Umbraco.Community.CSPManager 2.0.2-alpha

Umbraco.Community.CSPManager

A comprehensive Content Security Policy (CSP) management package for Umbraco CMS that helps protect your website from XSS attacks and other code injection vulnerabilities. Manage CSP headers for both frontend and backend through an intuitive backoffice interface.

Features

• 🛡️ Frontend & Backend CSP Management - Configure different Content Security Policies for your website frontend and Umbraco backoffice
• 🎛️ Intuitive Backoffice Interface - Easy-to-use management screens within the Umbraco backoffice
• 🔍 CSP Evaluation Tools - Test and validate your Content Security Policies before deployment
• 🏷️ Nonce Support - Built-in tag helpers for script and style nonces
• ⚙️ Flexible Configuration - Customize CSP directives to match your website's requirements
• 📊 Real-time Testing - Evaluate CSP effectiveness with built-in testing tools

Table of Contents

• Requirements
• Installation
• Quick Start
• Policy Management
• Policy Settings
• Evaluation
• Configuration Options
• Nonce Tag Helper
• Advanced Usage
• Troubleshooting
• Contributing

Getting Started

dotnet add package Umbraco.Community.CSPManager

Quick Start

1. Install the package using the command above
2. Build and run your Umbraco application
3. Navigate to the CSP Management section in the Umbraco backoffice
4. Configure your Content Security Policies for frontend and/or backend
5. Test your configuration using the evaluation tools

Policy Management

Policy Settings

Evaluation

Configuration Options

You can configure CSP Manager behavior in your appsettings.json:

{
  "CspManager": {
    "DisableBackOfficeHeader": false
  }
}

DisableBackOfficeHeader - Emergency kill switch to disable CSP headers for the backoffice if needed (default: false)

Nonce Tag Helper

To use CSP nonce you can make use of the Tag Helper. To find out more about nonce see see nonce Guide.

First you will need to include the namespace in the ViewImports.cshtml

@addTagHelper *, Umbraco.Community.CSPManager

To use the nonce add csp-manager-add-nonce="true" to your <script> or <style> tags.

The nonce values shown are for demo purposes only.

<script csp-manager-add-nonce="true"></script>
<style csp-manager-add-nonce="true"></style>


<script nonce="scriptRAnd0m">
    doWhatever();
</script>
<style nonce="styleRAnd0m">
    .alert { color: red; }
</style>

When this is added it will include the nonce in the CSP header and output in the page.

If you need to access the nonce within a data attribute you can use csp-manager-add-nonce-data-attribute="true"

<script csp-manager-add-nonce-data-attribute="true"></script>
<style csp-manager-add-nonce-data-attribute="true"></style>


<script data-nonce="scriptRAnd0m">
    doWhatever();
</script>
<style data-nonce="styleRAnd0m">
    .alert { color: red; }
</style>

Advanced Usage

Notification Events

The CSP Manager provides notification events that allow you to extend functionality and integrate with your application logic.

CspWritingNotification

Triggered when building a CSP definition for an HTTP request. Use this to dynamically modify Content Security Policies based on request context.

using Umbraco.Cms.Core.Events;
using Umbraco.Community.CSPManager.Notifications;

public class CustomCspWritingHandler : INotificationHandler<CspWritingNotification>
{
    public void Handle(CspWritingNotification notification)
    {
        // Modify CSP definition based on request context
        if (notification.HttpContext.Request.Path.StartsWithSegments("/api"))
        {
            // Apply different CSP for API endpoints
            notification.CspDefinition?.Directives.Add("connect-src", "'self' api.example.com");
        }
    }
}

CspSavedNotification

Triggered when a CSP definition is saved through the backoffice. Use this for cache invalidation, logging, or integration with external systems.

public class CustomCspSavedHandler : INotificationHandler<CspSavedNotification>
{
    public void Handle(CspSavedNotification notification)
    {
        // Log CSP changes
        var csp = notification.CspDefinition;
        Logger.Information("CSP policy updated for {Area}", 
            csp.IsBackOffice ? "BackOffice" : "Frontend");
        
        // Integrate with external monitoring
        // NotifySecurityTeam(csp);
    }
}

Registering Notification Handlers

Register your custom handlers in your Startup.cs or Program.cs:

services.AddNotificationHandler<CspWritingNotification, CustomCspWritingHandler>();
services.AddNotificationHandler<CspSavedNotification, CustomCspSavedHandler>();

Getting Help

If you encounter issues not covered here:

1. Check the GitHub Issues page
2. Review the full documentation (link below)
3. Create a new issue with detailed information about your problem

Contributing

Contributions are welcome! Please read our Contributing Guidelines and feel free to submit issues and pull requests.

License

This project is licensed under the MIT License - see the LICENSE file for details.