OwaspHeaders.Core

An ASP.NET Core middleware designed to increase web application security by adopting the OWASP Secure Headers project recommended HTTP headers and values.

Build Status	Release Status	License used	OpenSSF

Please note: this middleware DOES NOT SUPPORT BLAZOR OR WEBASSEMBLY APPLICATIONS. This is because setting up secure HTTP headers in a WebAssembly context is a non-trivial task.

Tools Required to Build This Repo

• .NET SDKs vLatest
  • 8.0
  • 9.0
• an IDE (VS Code, Rider, or Visual Studio)
• dotnet-format global tool.

That's it.

Documentation

The latest documentation for OwaspHeaders.Core can be found at https://gaprogman.github.io/OwaspHeaders.Core/.

Attestations

As of PR 148, OwaspHeaders.Core uses the GitHub provided process for creating attestations per build. This document talks through how to verify those attestations using the gh CLI.

See the Attestations page of the documentation to read about how you can verify the attestations for builds from 9.5.0 onward.

Pull Requests

Pull requests are welcome, but please take a moment to read the Code of Conduct before submitting them or commenting on any work in this repo.

We have comprehensive documentation for contributing to this project which you are encouraged to reach. This documentation can be found at: https://gaprogman.github.io/OwaspHeaders.Core/Contributing/.

Getting Started

Assuming that you have an ASP .NET Core project, add the NuGet package:

dotnet add package OwaspHeaders.Core

Alter the program.cs file to include the following:

app.UseSecureHeadersMiddleware();

This will add a number of default HTTP headers to all responses from your server component.

The following is an example of the response headers from version 9.0.0 (taken on November 19th, 2024)

 cache-control: max-age=31536000,private 
 content-security-policy: script-src 'self';object-src 'self';block-all-mixed-content;upgrade-insecure-requests; 
 cross-origin-resource-policy: same-origin 
 referrer-policy: no-referrer 
 strict-transport-security: max-age=31536000;includeSubDomains 
 x-content-type-options: nosniff 
 x-frame-options: DENY 
 x-permitted-cross-domain-policies: none; 
 x-xss-protection: 0 

Please note: The above example contains only the headers added by the Middleware.

Secure Headers

The SecureHeadersMiddleware is used to inject the HTTP headers recommended by the OWASP Secure Headers project into all responses generated by the ASP.NET Core pipeline.

Listing and commenting on the default values that this middleware provides is out of scope for this readme—but can be found in the official documentation—. Please note that you will need to read through the above link to the Secure Headers Project in order to understand what these headers do, and the affect their presence will have on your applications when running in a web browser.

Configuration

This Middleware uses the builder pattern to set up the header information, which is a compile time dependency.

In your Program.cs file:

OwaspHeaders.Core/example/Program.cs

Line 26 in 433cbb7

app.UseSecureHeadersMiddleware(RealisticContentSecurityPolicyGenerators.GenerateOwaspHomePageCsp());

This will use the default configuration for the OwaspHeaders.Core middleware. The method (found in /src/Extensions/SecureHeadersMiddlewareExtensions.cs) looks like this:

OwaspHeaders.Core/src/Extensions/SecureHeadersMiddlewareExtensions.cs

Lines 23 to 38 in 433cbb7

	public static SecureHeadersMiddlewareConfiguration BuildDefaultConfiguration()
	{
	return SecureHeadersMiddlewareBuilder
	.CreateBuilder()
	.UseHsts()
	.UseXFrameOptions()
	.UseContentTypeOptions()
	.UseContentDefaultSecurityPolicy()
	.UsePermittedCrossDomainPolicies()
	.UseReferrerPolicy()
	.UseCacheControl()
	.RemovePoweredByHeader()
	.UseXssProtection()
	.UseCrossOriginResourcePolicy()
	.Build();
	}

Custom Configuration

In order to use a custom configuration, follow the same pattern (perhaps creating your own extension method to encapsulate it):

public static SecureHeadersMiddlewareConfiguration CustomConfiguration()
{
    return SecureHeadersMiddlewareBuilder
        .CreateBuilder()
        .UseHsts(1200, false)
        .UseContentDefaultSecurityPolicy()
        .UsePermittedCrossDomainPolicy
            (XPermittedCrossDomainOptionValue.masterOnly)
        .UseReferrerPolicy(ReferrerPolicyOptions.sameOrigin)
        .Build();
}

Then consume it in the following manner:

app.UseSecureHeadersMiddleware(
    CustomSecureHeaderExtensions.CustomConfiguration()
);

Testing the Middleware

An example ASP .NET Core application - with the middleware installed - is provided as part of this repo (see the code in the OwaspHeaders.Core.Example directory). As such, you can run this example application to see the middleware in use via a provided OpenAPI endpoint - located at /swagger.

Or you could add the middleware to an existing application and run through the following Run the application, request one of the pages that it serves and view the headers for the page.

This can be done in Google Chrome, using the Dev tools and checking the network tab.

Shown above in the Response Headers section of the Values response.

Server Header: A Warning

The default configuration for this middleware removes the X-Powered-By header, as this can help malicious users to use targeted attacks for specific server infrastructure. However, since the Server header is added by the reverse proxy used when hosting an ASP .NET Core application, removing this header is out of scope for this middleware.

In order to remove this header, a web.config file is required, and the following should be added to it:

<?xml version="1.0" encoding="UTF-8"?>
<configuration>
    <system.webServer>
        <security>
            <requestFiltering removeServerHeader="true" />
        </security>
    </system.webServer>
</configuration>

The above XML is taken from this answer on ServerFault.

The web.config file will need to be copied to the server when the application is deployed.