IM.ContentSecurityPolicy 2.0.2

IM.ContentSecurityPolicy

Content Security Policy (CSP) headers and per-request nonces for ASP.NET Core and Umbraco CMS 13 to 18.

The package:

• generates a random nonce for each request;
• writes a Content-Security-Policy or Content-Security-Policy-Report-Only header built from CspOptions;
• adds the nonce to <script>, <style> and <link> tags through a tag helper, HTML helpers or view components.

It targets net8.0 and runs on .NET 8, 9 and 10. It references Umbraco.Cms.Core 13 to 18 so that the Umbraco Marketplace lists it. The code does not call Umbraco, so it also works in plain ASP.NET Core apps.

Source availability: the source repository is private. The package is distributed through NuGet.org. Report bugs and request features in the issue tracker and ask questions in Discussions.

For Umbraco 10 to 12 use version 1.0.2.

Installation

dotnet add package IM.ContentSecurityPolicy

Setup

using IM.ContentSecurityPolicy.Extensions;
using IM.ContentSecurityPolicy.Middleware;

builder.Services.AddNonceServices();

var app = builder.Build();

app.UseNonceGeneration();
app.UseContentSecurityPolicy();

Call UseNonceGeneration before UseContentSecurityPolicy. In the other order the header and the page get different nonces.

Register the tag helpers and the HTML helper namespace in Views/_ViewImports.cshtml:

@addTagHelper *, IM.ContentSecurityPolicy
@using IM.ContentSecurityPolicy.Extensions

Adding the nonce to tags

Tag helper

Add asp-nonce="true" to a <script>, <style> or <link> element:

<script src="~/js/site.js" asp-nonce="true"></script>

<script asp-nonce="true">
    console.log('inline script');
</script>

<link rel="stylesheet" href="~/css/site.css" asp-nonce="true" />

The nonce attribute is written only when the request already has a nonce, so the nonce middleware must run first.

HTML helpers

attributes is an anonymous object such as new { defer = "defer" }. Property names are written in lower case.

The helpers do not HTML-encode their arguments. Pass only trusted values.

View components

The view components put the nonce into a view model and render a view. The package does not include the views, so add one per component you use, for example Views/Shared/Components/NonceScript/Default.cshtml:

@model IM.ContentSecurityPolicy.ViewComponents.NonceScriptViewModel
<script src="@Url.Content(Model.Src)" type="@Model.Type" nonce="@Model.Nonce"></script>

@await Component.InvokeAsync("NonceScript", new { src = "~/js/site.js" })

The models are in the IM.ContentSecurityPolicy.ViewComponents namespace and are named after the component, for example NonceInlineStyleViewModel.

Nonce service

Inject INonceService from IM.ContentSecurityPolicy.Services to read the nonce in your own code.

A nonce is 32 bytes from RandomNumberGenerator, Base64-encoded.

Configuration

AddNonceServices takes an optional Action<CspOptions>. The source 'nonce-{nonce}' in any list is replaced with the request nonce.

builder.Services.AddNonceServices(options =>
{
    options.ScriptSrc = new[] { "'self'", "'nonce-{nonce}'", "https://cdn.example.com" };
    options.ImgSrc = new[] { "'self'", "data:", "https:" };
    options.ReportOnly = true;
    options.ReportUri = "https://example.com/csp-report";
});

An empty array leaves the directive out of the header.

Builder

CspOptionsBuilder sets the same properties with With... methods. Pass it the options instance to change it in place:

using IM.ContentSecurityPolicy.Options;

builder.Services.AddNonceServices(options => new CspOptionsBuilder(options)
    .WithScriptSrc("'self'", "'nonce-{nonce}'", "https://cdn.example.com")
    .WithConnectSrc("'self'", "https://api.example.com")
    .WithCustomDirective("worker-src", "'self'"));

There are two presets:

• CspOptionsBuilder.CreateStrict() is the default policy with frame-src 'none'.
• CspOptionsBuilder.CreateDevelopment() adds 'unsafe-inline' and 'unsafe-eval' to scripts, 'unsafe-inline' to styles, data: to fonts, https: to images and ws: wss: to connections, and turns off upgrade-insecure-requests.

A preset returns a new builder, so copy the values you need:

builder.Services.AddNonceServices(options =>
{
    if (builder.Environment.IsDevelopment())
    {
        var dev = CspOptionsBuilder.CreateDevelopment().Build();
        options.ScriptSrc = dev.ScriptSrc;
        options.StyleSrc = dev.StyleSrc;
        options.ConnectSrc = dev.ConnectSrc;
        options.UpgradeInsecureRequests = false;
    }
});

Options on the middleware

app.UseContentSecurityPolicy(options => { ... }) starts from the defaults and ignores the options registered with AddNonceServices.

Umbraco

The default policy blocks the inline scripts of the Umbraco backoffice. Apply the middleware to front-end requests only, before app.UseUmbraco():

app.UseWhen(
    context => !context.Request.Path.StartsWithSegments("/umbraco"),
    branch => branch.UseNonceGeneration().UseContentSecurityPolicy());

Security notes

• Start with ReportOnly = true and a ReportUri. Enforce the policy once the reports are clean.
• Nonces cover <script>, <style> and stylesheet <link> elements. They do not cover inline event handlers such as onclick, or javascript: URLs.
• Do not put a nonce on a script that contains user input.
• Cached markup keeps the nonce it was rendered with. Do not use output caching or Umbraco cached partials for markup that contains a nonce.

License

MIT. See LICENSE.