Brickmakers.AspSecurityHeaders.OrchardModule 2.5.1

The ID prefix of this package has been reserved for one of the owners of this package by NuGet.org. Prefix Reserved
dotnet add package Brickmakers.AspSecurityHeaders.OrchardModule --version 2.5.1
NuGet\Install-Package Brickmakers.AspSecurityHeaders.OrchardModule -Version 2.5.1
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package.
<PackageReference Include="Brickmakers.AspSecurityHeaders.OrchardModule" Version="2.5.1" />
For projects that support PackageReference, copy this XML node into the project file to reference the package.
paket add Brickmakers.AspSecurityHeaders.OrchardModule --version 2.5.1
#r "nuget: Brickmakers.AspSecurityHeaders.OrchardModule, 2.5.1"
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package.
// Install Brickmakers.AspSecurityHeaders.OrchardModule as a Cake Addin
#addin nuget:?package=Brickmakers.AspSecurityHeaders.OrchardModule&version=2.5.1

// Install Brickmakers.AspSecurityHeaders.OrchardModule as a Cake Tool
#tool nuget:?package=Brickmakers.AspSecurityHeaders.OrchardModule&version=2.5.1

BRICKMAKERS ASP.Net Security Headers

License CI-Pipeline Brickmakers.AspSecurityHeaders Nuget Version Brickmakers.AspSecurityHeaders.OrchardModule Nuget Version Brickmakers.AspSecurityHeaders.Generators Nuget Version

A small package for ASP.Net (Core) to automatically configure secure HTTP-Headers.

Table of Contents

<small><i><a href='https://ecotrust-canada.github.io/markdown-toc/'>Table of contents generated with markdown-toc</a></i></small>

IMPORTANT CHANGES in version 2.1.0

In 2.1.0, support for strict site isolation has been added and enabled. Check the release notes for more details.

Features

  • Secure defaults for HTTP-Headers, CSP, Cookies and more
  • Opt-Out mechanism for different security controls
  • Easily configurable via IApplicationBuilder.UseBmSecurityHeaders() extension
    • Or use IApplicationBuilder.UseBmApiSecurityHeaders() for API-Projects
  • Developed and Maintained by the BRICKMAKERS Security Advisory Team
  • Easy integration in any project and build pipelines
  • Provides additional generator package to create config files with security headers for:
    • IIS web.config files

Installation

This package is available on NuGet.org, you can simply add it to your C#-Project like any other dependency.

Usage

AspSecurityHeaders

For the standard features of the Security Headers you only need to install Brickmakers.AspSecurityHeaders.

To get started, all you have to to is to register the middleware in the Configure method. This should happen at the beginning of the method to ensure the headers are added to all responses, as different middlewares might end processing early, which would prevent the headers from being set:

public void Configure(IApplicationBuilder app)
{
    // ! Should be the first step in the Configure method

    // For "normal" Websites or combinations of Websites and APIs
    app.UseBmSecurityHeaders();

    // For pure APIs
    app.UseBmApiSecurityHeaders();

    // continue as usual with configuring the application
    // ...
}

This will add all security headers, as well as a strict CSP and cookie policy. To further configure it and opt out of certain security controls, you can use the configure parameter of the method. In the following example, scripts, styles and images are allowed to be loaded from the current origin and the minimum cookie same site requirements are reduced to be lax instead of strict.

public void Configure(IApplicationBuilder app)
{
    app.UseBmSecurityHeaders(collection => collection  // Or .UseBmApiSecurityHeaders for APIs
        .AddBmContentSecurityPolicy(builder =>
        {
            builder.AddScriptSrc().Self();
            builder.AddStyleSrc().Self();
            builder.AddImgSrc().Self();
        })
        .SetMinimumSameSitePolicy(SameSiteMode.Lax));

    // ...
}
Using the Built-In CSP Report Controller

The library includes a ready-made API-Controller to automatically report CSP-Violations. It will provide an endpoint to be used by the browser to report CSP errors and passes them to a customizable handler function. If you want to use the controller, there are a few steps that need to be taken.

First, you have to add the controller to your controllers by extending the CspReportControllerBase:

[ApiController]
[Route("[controller]")]
public class CspReportController : CspReportControllerBase
{
    protected override Task HandleCspReport(CspReport cspReport)
    {
        // Implement logging or other handling here
        // IMPORTANT: If you log the report values, you should sanitized them to prevent log forgery attacks
        // See: https://owasp.org/www-community/attacks/Log_Injection
        
        return Task.CompletedTask;
    }
}

If you are using the standard Microsoft.Extensions.Logging.ILogger for logging, you can use a handy extension method on the logger that automatically handles formatting and also logs the properties of the report in case you are using a structured logging backend like App Insights.

[ApiController]
[Route("[controller]")]
public class CspReportController : CspReportControllerBase
{
    protected override Task HandleCspReport(CspReport cspReport)
    {
        _logger.LogCspReport(cspReport); // default log level ist "Error", but can be adjusted
        return Task.CompletedTask;
    }
}

Next, you have to add the controller to the MVC instance inside of the ConfigureServices method. Typically, the AddMvc method is used, but you can also use any other of the MVC initializers, like for example AddControllers in case of a pure API. In addition to registering controllers, you also need to add the CSP-Report content type. You can simply use the AddCspMediaType method for that:

public void ConfigureServices(IServiceCollection services)
{
    services.AddMvc() // works on .AddRazorPages() and .AddControllers() as well
        .AddCspMediaType();
}

In the case that this is the first controller you add to your project, you also need to ensure that controllers are correctly mapped to endpoints. You can do so via the UseEndpoints method at the end of Configure:

public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
{
    // do your normal setup
    // ...

    // at the end, UseEndpoints should already exist
    app.UseEndpoints(endpoints =>
    {
        // this one must be present
        endpoints.MapControllers();
        
        // other mappings, e.g. MapRazorPages, depends on your application
        // ...
    });
}

Finally, you need to actually set the report URI in the CSP. This can be done by adding it inside the CSP builder of the UseBmSecurityHeaders by adding AddReportUri to the CSP. There you should set the path to the previously defined CSP controller. In this example, the controller path was defined as CspReport.

public void Configure(IApplicationBuilder app)
{
    app.UseBmSecurityHeaders(collection => collection  // Or .UseBmApiSecurityHeaders for APIs
        .AddBmContentSecurityPolicy(builder =>
        {
            // setup your CSP
            // ...
            
            builder.AddReportUri().To("/CspReport");
        }));
    // ...
}

In case you also have additional projects that should also report to this controller, or in case you separate API and web project, the controller will always be accessible via https://<host>/CspReport. You can use it as any other CSP reporting endpoint.

Orchard Module

If you are working with Orchard Core, then instead of using the Security Headers package directly, you should instead use the Brickmakers.AspSecurityHeaders.OrchardModule package, which itself is an orchard module that automatically configures the security headers for you. To use it, follow the standard Steps to add an Orchard module as dependency:

  1. Add the NuGet package reference
  2. Update your Manifest.cs and add Brickmakers.AspSecurityHeaders.OrchardModule as dependency
  3. Enable MVC in your application Startup.cs: services.AddOrchardCore().AddMvc();
  4. For Orchard CMS installations: Enter the "Features" Admin Menu and manually enable the module

With the, the module is automatically loaded and activated. It will:

  1. Enable all standard security headers, including a customized CSP
  2. Register the CSP report controller under /CspReport

To customize the security headers, you can basically follow the standard instructions of the normal Security headers package, with 2 exceptions: Use UseOrchardBmSecurityHeaders and AddOrchardBmContentSecurityPolicy instead of their " normal" counterparts:

public void Configure(IApplicationBuilder app)
{
    // ! Should be the first step in the Configure method

    // Only needed if customization is required
    app.UseOrchardBmSecurityHeaders(config => config
        .AddOrchardBmContentSecurityPolicy(/* ... */) // csp config
        // ... other configuration, just like with the normal security headers
    );
}

Note: Orchard core is not the most security aware framework. The default CSP that is required to make it work includes unsafe-inline unsafe-eval. Be aware that for a security sensitive application, it should be carefully evaluated if orchard core is the right choice, or whether critical components should be provided in a pure ASP.net application that allows for tighter security controls and a better CSP.

Overwriting the Orchard CSP

When customizing the Orchard CSP, you can simply add new rules to the existing ones. This will not overwrite the standard orchard rules anymore. If you need to disable the standard rules, you can use the optional clear parameter. For example, if a script source should be added but the image sources should be cleared and replaced, it would look like the following:

public void Configure(IApplicationBuilder app)
{
    app.UseOrchardBmSecurityHeaders(config => config
        .AddOrchardBmContentSecurityPolicy(builder => 
        {
            builder.AddScriptSrc() // Adds new diretives
                .From("https://example.com");
            builder.AddImgSrc(clear: true) // Replaces directives (usually not needed)
                .Self()
                .From("https://example.com");
        })
    );
}
Support for Login with Microsoft/Azure AD

If you want to allow a login with Microsoft in your orchard application, special cookie policy rules need to be added so that azure can pass the authentication result back to the orchard application. Additionally, some CSP rules need to be adjusted, as otherwise your page cannot redirect to microsoft. You can either manually configure the rules via the AddCookieOption and the CSP builder, or use the helper methods that do that for you:

public void Configure(IApplicationBuilder app)
{
    app.UseOrchardBmSecurityHeaders(config => config
        .AddMicrosoftLoginCookieWhitelist()
        .AddOrchardBmContentSecurityPolicy(cspBuilder => {
            cspBuilder.AddFormAction()
                .MicrosoftLogin();
        })
    );
}

Generators

To use the generators, you have to install the Brickmakers.AspSecurityHeaders.Generators package. The you can use the various writers to generate your configuration.

IIS web.config

To generate a web.config file with security headers, you can use the IISWebConfigWriter class:

await IISWebConfigWriter.Create() // or .CreateApi()
    .SetBmSecurityHeadersConfig(config => config
        .AddBmContentSecurityPolicy(builder =>
        {
            builder.AddScriptSrc().Self();
            builder.AddStyleSrc().Self();
            builder.AddImgSrc().Self();
        }))
    .EnforceHttps(false)
    .Run("web.config");

With the SetBmSecurityHeadersConfig, you can configure your security headers in exactly the same way as with the standard security headers package. In addition to that, there are also some extra configuration options that are only available with web.config files. These are:

  • XML Writer configuration for controlling how the generated XML is formatted
  • Advanced removal of server identifying headers
  • Enforce HTTPS
  • Flags to control if the generated headers should be for HTTP / TLS

Attributions and Background

This project is heavily based on NetEscapades.AspNetCore.SecurityHeaders, thanks to everyone involved on that project.

The reason this package exists is because it enforces even stricter defaults than the original package and adds additional features. It has not been integrated into the original security headers, as some of these feature would be breaking changes and too strict for some users.

However, we at BRICKMAKERS prefer to use tight secure defaults, which is why we created this package. It will always set everything to no by default and may add new, even more restricting headers in the future.

Product Compatible and additional computed target framework versions.
.NET net6.0 is compatible.  net6.0-android was computed.  net6.0-ios was computed.  net6.0-maccatalyst was computed.  net6.0-macos was computed.  net6.0-tvos was computed.  net6.0-windows was computed.  net7.0 is compatible.  net7.0-android was computed.  net7.0-ios was computed.  net7.0-maccatalyst was computed.  net7.0-macos was computed.  net7.0-tvos was computed.  net7.0-windows was computed.  net8.0 was computed.  net8.0-android was computed.  net8.0-browser was computed.  net8.0-ios was computed.  net8.0-maccatalyst was computed.  net8.0-macos was computed.  net8.0-tvos was computed.  net8.0-windows was computed. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.

NuGet packages

This package is not used by any NuGet packages.

GitHub repositories

This package is not used by any popular GitHub repositories.

Version Downloads Last updated
2.5.1 3,348 9/12/2023
2.5.0 104 9/12/2023
2.4.0 1,777 6/22/2023
2.3.0 246 6/13/2023
2.2.1 2,960 12/15/2022
2.2.0 299 12/8/2022

# Changelog

All notable changes to this project will be documented in this file.

The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), and this project adheres
to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

## 2.5.1 - 2023-09-12

### Fixed

- Fixed a bug the prevented the `BmFeaturePolicy` from being configured correctly, when the feature policy generation
 is enabled.

## 2.5.0 - 2023-09-12

### Changed

- Updated Orchard Core Module to use Orchard Core Version 1.7.0

## 2.4.0 - 2023-06-26

### Changed

- Deprecated `CspReport.AsAttributes` and replaced with `.ToDictionary`
- Added `ILogger.LogCspReport` extension for easy logging of a `CspReport` when using `ILogger`
- Improved logging format of csp reports in the Orchard module

## 2.3.0 - 2023-06-13

### Added

- Explicit support for .Net 7.0
- `UnconfigureCacheControl` method to allow to exclude cache control from being configured with the security headers

### Changed

- Replaced default CSP builder with custom wrapper that allows for directives to be updated
- Simplified CSP for orchard module

### Deprecated

### Removed

- Support for .Net Core 3.1

### Fixed

- Updated dependencies

### Security

- Escape csp report values for logger in orchard module endpoint

## 2.2.1 - 2022-12-15

### AspSecurityHeaders.OrchardModule

- Improved handling of microsoft logins
   - Renamed `AddAzureLoginCookieWhitelist` to `AddMicrosoftLoginCookieWhitelist`
   - Added CSP form action builder extension

## 2.2.0 - 2022-12-08

### Added

- New orchard core MVC module that enables the security headers for any orchard project
   - Includes adjusted CSP that works out of the box for a standard orchard project
   - Automatically adds the CSP report controller
   - Customized `UseOrchardBmSecurityHeaders` method to configure the headers for orchard projects
   - Includes `AddAzureLoginCookieWhitelist` that automatically configures the cookie policy for an Azure AD login

## 2.1.0 - 2022-12-05

### Added

- Enabled strict site isolation by enabling the COEP, COOP and CORP headers
   - Read https://web.dev/why-coop-coep/ for mor details, on why they are needed and what they do
   - Should you encounter problems, you can use overwrite their usage to only report errors via
     the `AddCrossOriginXXXPolicy` methods
- The `X-Powered-By` header now gets automatically removed as well

## 2.0.0 - 2022-03-22

This release contains breaking changes. See README for more details.

### Added

- New `CspReportControllerBase` controller base class that can be extended
   - Replaces the old, built-in CSP controller, as the automatic registration was problematic
   - Example on how to use it
- `AddCspMediaType`-Method to add the CSP media type to an `IMvcBuilder`

### Removed

- Built-In CSP-Controller, as the automatic registration was problematic
   - You can use the `CspReportControllerBase` instead, see README

## 1.3.1 - 2022-02-03

### Added

- Added XML-Documentation of all public members
- Added symbols packages

## 1.3.0 - 2022-02-02

### Added

- Created the new `Brickmakers.AspSecurityHeaders.Generators` package
   - Can generate an IIS `web.config` from the security headers config

## 1.2.2 - 2022-01-26

### Added

- Added package icon

## 1.2.1 - 2022-01-26

### Changed

- First public release on GitHub and NuGet.org

## 1.2.0 - 2021-12-21

### Added

- `CspReportController`: Easily report CSP violations via the built-in controller
- Integration Tests
- Support for .Net 6

## 1.1.0 - 2021-10-21

### Added

- `UseBmApiSecurityHeaders`: Add Configuration method for pure APIs

## 1.0.2 - 2021-10-12

### Security

- Disable HSTS preload by default

## 1.0.1 - 2021-10-11

### Added

- Initial Release