From ea81c23a293e68ea0a305445b7a30cdaaea4aae3 Mon Sep 17 00:00:00 2001 From: Jamie Taylor Date: Wed, 27 Nov 2024 23:39:35 +0000 Subject: [PATCH 01/49] Re-arranged basic docs, added configuration page --- docs/Configutation.md | 70 ++++++++++++++++++++++++++++++++++++++++ docs/_config.yml | 14 +++----- docs/index.md | 74 ++++++++++--------------------------------- 3 files changed, 91 insertions(+), 67 deletions(-) create mode 100644 docs/Configutation.md diff --git a/docs/Configutation.md b/docs/Configutation.md new file mode 100644 index 0000000..5d01a76 --- /dev/null +++ b/docs/Configutation.md @@ -0,0 +1,70 @@ +--- +title: Configuration +layout: page +--- + +This Middleware uses the builder pattern to set up the header information, which is a compile time dependency. If you need to change the configuration, you will need to rebuild your application. + +## Basic Configuration + +Adding the default configuration by adding the following to your `Program.cs` somewhere in the Middleware pipeline: + +```csharp +app.UseSecureHeadersMiddleware(); +``` + +This will use the default configuration for the OwaspHeaders.Core middleware. The method (found in `/src/Extensions/SecureHeadersMiddlewareExtensions.cs`) looks like this: + +```csharp +public static SecureHeadersMiddlewareConfiguration BuildDefaultConfiguration() +{ + return SecureHeadersMiddlewareBuilder + .CreateBuilder() + .UseHsts() + .UseXFrameOptions() + .UseContentTypeOptions() + .UseContentDefaultSecurityPolicy() + .UsePermittedCrossDomainPolicies() + .UseReferrerPolicy() + .UseCacheControl() + .RemovePoweredByHeader() + .UseXssProtection() + .UseCrossOriginResourcePolicy() + .Build(); +} +``` + +{: .warning } +The default configuration is INCREDIBLY restrictive. + +### Custom Configuration + +In order to use a custom configuration, follow the same pattern (perhaps creating your own extension method to encapsulate it). In the following example, we've created a static method called `CustomConfiguration` within a helpers class (called `CustomSecureHeaderExtensions`) which returns a completely custom configuration: + +``` csharp +public static CustomSecureHeaderExtensions +{ + public static SecureHeadersMiddlewareConfiguration CustomConfiguration() + { + return SecureHeadersMiddlewareBuilder + .CreateBuilder() + .UseHsts(1200, false) + .UseContentDefaultSecurityPolicy() + .UsePermittedCrossDomainPolicy + (XPermittedCrossDomainOptionValue.masterOnly) + .UseReferrerPolicy(ReferrerPolicyOptions.sameOrigin) + .Build(); + } +} +``` + +{: .note } +This is an example configuration + +Then consume it in the following manner, within your `Program.cs`'s Middleware pipeline: + +```csharp +app.UseSecureHeadersMiddleware( + CustomSecureHeaderExtensions.CustomConfiguration() +); +``` diff --git a/docs/_config.yml b/docs/_config.yml index fb3e9c8..82994a7 100644 --- a/docs/_config.yml +++ b/docs/_config.yml @@ -12,14 +12,6 @@ permalink: pretty # URL for the built GitHub pages root; ensures that all generated absolute URLs are correct url: https://gaprogman.github.io/OwaspHeaders.Core -# Aux links for the upper right navigation -aux_links: - Repository: https://github.com/gaprogman/OwaspHeaders.Core - NuGet: https://www.nuget.org/packages/OwaspHeaders.Core/ - -# Makes Aux links open in a new tab. Default is false -aux_links_new_tab: true - # For copy button on code enable_copy_code_button: true @@ -48,8 +40,10 @@ nav_sort: case_sensitive # Capital letters sorted before lowercase # External navigation links nav_external_links: - - title: Just the Docs on GitHub - url: https://github.com/just-the-docs/just-the-docs + - title: Source code repository + url: https://github.com/gaprogman/OwaspHeaders.Core + - title: NuGet + url: https://www.nuget.org/packages/OwaspHeaders.Core/ # Show navigation error report nav_error_report: true # default is false/nil. diff --git a/docs/index.md b/docs/index.md index 25c2836..b11ac25 100644 --- a/docs/index.md +++ b/docs/index.md @@ -3,15 +3,18 @@ title: Home layout: home --- -An ASP.NET Core middleware designed to increase web application security by adopting the recommended [OWASP] settings. +An ASP.NET Core middleware designed to increase web application security by adopting the recommended [OWASP] recommended values for HTTP headers as per 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. 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. | Build Status | Release Status | License used | | -------------|----------------|-----------| | [![Build status](https://github.com/GaProgMan/OwaspHeaders.Core/actions/workflows/dotnet.yml/badge.svg)](https://github.com/GaProgMan/OwaspHeaders.Core/actions/workflows/dotnet.yml) | [![Release](https://github.com/GaProgMan/OwaspHeaders.Core/actions/workflows/release.yml/badge.svg)](https://github.com/GaProgMan/OwaspHeaders.Core/actions/workflows/release.yml) | [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) | -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. +{: .warning } +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. -## Getting Started +## Quick Start Assuming that you have an ASP .NET Core project, add the NuGet package: @@ -30,62 +33,19 @@ This will add a number of default HTTP headers to all responses from your server The following is an example of the response headers from version 9.0.0 (taken on November 19th, 2024) ```plaintext - 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=63072000;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. 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: - -https://github.com/GaProgMan/OwaspHeaders.Core/blob/433cbb764956e86b80b598c5d0760bdfdef28161/example/Program.cs#L26 - -This will use the default configuration for the OwaspHeaders.Core middleware. The method (found in `/src/Extensions/SecureHeadersMiddlewareExtensions.cs`) looks like this: - -https://github.com/GaProgMan/OwaspHeaders.Core/blob/433cbb764956e86b80b598c5d0760bdfdef28161/src/Extensions/SecureHeadersMiddlewareExtensions.cs#L23-L38 - -### Custom Configuration - -In order to use a custom configuration, follow the same pattern (perhaps creating your own extension method to encapsulate it): - -``` csharp -public static SecureHeadersMiddlewareConfiguration CustomConfiguration() -{ - return SecureHeadersMiddlewareBuilder - .CreateBuilder() - .UseHsts(1200, false) - .UseContentDefaultSecurityPolicy() - .UsePermittedCrossDomainPolicy - (XPermittedCrossDomainOptionValue.masterOnly) - .UseReferrerPolicy(ReferrerPolicyOptions.sameOrigin) - .Build(); -} +Cache-Control: max-age=31536000;private +Strict-Transport-Security: max-age=63072000;includeSubDomains +X-Frame-Options: DENY +X-XSS-Protection: 0 +X-Content-Type-Options: nosniff +Content-Security-Policy: script-src 'self';object-src 'self';block-all-mixed-content;upgrade-insecure-requests; +X-Permitted-Cross-Domain-Policies: none; +Referrer-Policy: no-referrer +Cross-Origin-Resource-Policy: same-origin ``` -Then consume it in the following manner: - -```csharp -app.UseSecureHeadersMiddleware( - CustomSecureHeaderExtensions.CustomConfiguration() -); -``` +{: .note } +The above example contains only the headers added by the Middleware. ## Server Header: A Warning From 7cf5d6d5e1bae82d63f536021289e2fede6d9e85 Mon Sep 17 00:00:00 2001 From: Jamie Taylor Date: Wed, 27 Nov 2024 23:46:51 +0000 Subject: [PATCH 02/49] Altered ordering of pages --- docs/Configutation.md | 1 + docs/_config.yml | 4 ---- docs/index.md | 1 + 3 files changed, 2 insertions(+), 4 deletions(-) diff --git a/docs/Configutation.md b/docs/Configutation.md index 5d01a76..55e05c3 100644 --- a/docs/Configutation.md +++ b/docs/Configutation.md @@ -1,6 +1,7 @@ --- title: Configuration layout: page +nav_order: 2 --- This Middleware uses the builder pattern to set up the header information, which is a compile time dependency. If you need to change the configuration, you will need to rebuild your application. diff --git a/docs/_config.yml b/docs/_config.yml index 82994a7..fc9a74d 100644 --- a/docs/_config.yml +++ b/docs/_config.yml @@ -34,10 +34,6 @@ gh_edit_view_mode: "tree" # "tree" or "edit" if you want the user to jump into t # Nav menu can also be selectively enabled or disabled using page variables or the minimal layout nav_enabled: true -# Sort order for navigation links -# nav_sort: case_insensitive # default, equivalent to nil -nav_sort: case_sensitive # Capital letters sorted before lowercase - # External navigation links nav_external_links: - title: Source code repository diff --git a/docs/index.md b/docs/index.md index b11ac25..0d7013d 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,6 +1,7 @@ --- title: Home layout: home +nav_order: 1 --- An ASP.NET Core middleware designed to increase web application security by adopting the recommended [OWASP] recommended values for HTTP headers as per the [OWASP Secure Headers] project into all responses generated by the ASP.NET Core pipeline. From 0fac4a4a8499fb76428b03f6e4f9066aa0c82eee Mon Sep 17 00:00:00 2001 From: Jamie Taylor Date: Thu, 28 Nov 2024 15:10:30 +0000 Subject: [PATCH 03/49] Added changelog to docs --- changelog.md | 20 ++-- docs/changelog.md | 258 ++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 268 insertions(+), 10 deletions(-) create mode 100644 docs/changelog.md diff --git a/changelog.md b/changelog.md index d7b7407..aada714 100644 --- a/changelog.md +++ b/changelog.md @@ -4,17 +4,17 @@ This changelog represents all of the major (i.e. breaking) changes made to the O ## TL;DR -| Major Version Number | Changes | -|----------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| 9 | Removed support for both .NET 6 and .NET 7 as these are no longer supported by Microsoft. It also adds support for .NET 9. | -| 8 | Removed support for ASP .NET Core on .NET Framework workflows; example and test projects now have OwaspHeaders.Core prefix, re-architected some of the test classes | -| 7 | Added Cross-Origin-Resource-Policy header to list of defaults; simplfied the use of the middleware in Composite Root/Program.cs | -| 6 | Removes Expect-CT Header from the list of default headers | -| 5 | XSS Protection is now hard-coded to return "0" if enabled | +| Major Version Number | Changes | +|----------------------|-------------------------------------------------------------------------| +| 9 | Removed support for both .NET 6 and .NET 7 as these are no longer supported by Microsoft. It also adds support for .NET 9. | +| 8 | Removed support for ASP .NET Core on .NET Framework workflows; example and test projects now have OwaspHeaders.Core prefix, re-architected some of the test classes | +| 7 | Added Cross-Origin-Resource-Policy header to list of defaults; simplified the use of the middleware in Composite Root/Program.cs | +| 6 | Removes Expect-CT Header from the list of default headers | +| 5 | XSS Protection is now hard-coded to return "0" if enabled | | 4 | Uses builder pattern to create instances of `SecureHeadersMiddlewareConfiguration` class
uses .NET Standard 2.0
Removed XSS Protection header from defaults | -| 3 | Uses builder pattern to create instances of `SecureHeadersMiddlewareConfiguration` class
also uses .NET Standard 2.0 | -| 2 | Uses `secureHeaderSettings.json` and default config loader to create instances of `SecureHeadersMiddlewareConfiguration` class
also uses .NET Core 2.0 | -| 1 | Uses `secureHeaderSettings.json` and default config loader to create instances of `SecureHeadersMiddlewareConfiguration` class
also uses .NET Standard 1.4 | +| 3 | Uses builder pattern to create instances of `SecureHeadersMiddlewareConfiguration` class
also uses .NET Standard 2.0 | +| 2 | Uses `secureHeaderSettings.json` and default config loader to create instances of `SecureHeadersMiddlewareConfiguration` class
also uses .NET Core 2.0 | +| 1 | Uses `secureHeaderSettings.json` and default config loader to create instances of `SecureHeadersMiddlewareConfiguration` class
also uses .NET Standard 1.4 | ### Version 9 diff --git a/docs/changelog.md b/docs/changelog.md new file mode 100644 index 0000000..f6768e4 --- /dev/null +++ b/docs/changelog.md @@ -0,0 +1,258 @@ +--- +title: Changelog +layout: page +nav_order: 3 +--- + +# Changelog + +This changelog represents all of the major (i.e. breaking) changes made to the OwaspHeaders.Core project since it's inception. Early in the repo's development, GitHub's "releases" where used to release builds of the code repo. However shortly after it's inception, builds and releases where moved to [AppVeyor](https://ci.appveyor.com/project/GaProgMan/owaspheaders-core). Because of this, the releases on the GitHub repo became stale. + +## TL;DR + +| Major Version Number | Changes | +|----------------------|-------------------------------------------------------------------------| +| 9 | Removed support for both .NET 6 and .NET 7 as these are no longer supported by Microsoft. It also adds support for .NET 9. | +| 8 | Removed support for ASP .NET Core on .NET Framework workflows; example and test projects now have OwaspHeaders.Core prefix, re-architected some of the test classes | +| 7 | Added Cross-Origin-Resource-Policy header to list of defaults; simplified the use of the middleware in Composite Root/Program.cs | +| 6 | Removes Expect-CT Header from the list of default headers | +| 5 | XSS Protection is now hard-coded to return "0" if enabled | +| 4 | Uses builder pattern to create instances of `SecureHeadersMiddlewareConfiguration` class
uses .NET Standard 2.0
Removed XSS Protection header from defaults | +| 3 | Uses builder pattern to create instances of `SecureHeadersMiddlewareConfiguration` class
also uses .NET Standard 2.0 | +| 2 | Uses `secureHeaderSettings.json` and default config loader to create instances of `SecureHeadersMiddlewareConfiguration` class
also uses .NET Core 2.0 | +| 1 | Uses `secureHeaderSettings.json` and default config loader to create instances of `SecureHeadersMiddlewareConfiguration` class
also uses .NET Standard 1.4 | + +### Version 9 + +This version dropped support for .NET 6 and .NET 7, as they are no longer supported by Microsoft. It also added support for .NET 9. + +All projects in the [GitHub repo](https://github.com/GaProgMan/OwaspHeaders.Core) now build and run with either .NET 8 or .NET 9, whichever is present (deferring to the highest version number if both are present). As of November 19th, 2024 there are no new features in Version 9, so if you still need to use the NuGet package with .NET 6 or 7 please use Version 8 of the package. + +### Version 8 + +This version dropped support for support for ASP .NET Core on .NET Framework workflows. This means that, from version 8 onwards, this package will no longer with with .NET Framework workloads. This decision was made as Microsoft have dropped support for ASP .NET Core on .NET Framework workloads. This can be seen in the ASP .NET Core support documentation [here](https://dotnet.microsoft.com/en-us/platform/support/policy/aspnet#dotnet-core) + +{: .note } +> To help facilitate migrating applications to ASP.NET Core on .NET Core, the specified ASP.NET Core 2.1 packages (latest patched version only) will be supported on the .NET Framework and follow the support cycle for those .NET Framework versions. ASP.NET Core 2.1 is defined as "Tools" in the Microsoft Support Lifecycle Policy +> +> Source: https://dotnet.microsoft.com/en-us/platform/support/policy/aspnet#dotnet-core, obtained Oct 19th, 2024. + +The Example and Tests csproj files (and directories) have been renamed to make the standard `OwaspHeaders.Core.{x}` where `{x}` is either `Example` (for the ASP .NET Core application which provides an example implementation) or `Tests` for the unit tests project. + +#### Community Contributions + +[swharden](https://github.com/swharden) created [PR #96](https://github.com/GaProgMan/OwaspHeaders.Core/pull/96) which greatly simplified and improved the NuGet package metadata and created a wonderful logo for the project. + +--- + +### Version 7.5 + +This version makes it simpler to get started with the NuGet package by simplifying the use of it in Program.cs/Composite Root. This, effectively, changes the composite root from: + +```csharp +app.UseSecureHeadersMiddleware( + SecureHeadersMiddlewareExtensions + .BuildDefaultConfiguration() + ); +``` + +to: + +```csharp +app.UseSecureHeadersMiddleware(); +``` + +--- + +### Version 7 + +This version adds the Cross-Origin-Resource-Policy header with the OWASP recommended value "same-origin" to the list of default headers in the `BuildDefaultConfiguration()` extension method. This was requested via [issue #76](https://github.com/GaProgMan/OwaspHeaders.Core/issues/76). + +--- + +### Version 6 + +This version removes Expect-CT Header from the list of default headers in the `BuildDefaultConfiguration()` extension method. This is related to [issue #72](https://github.com/GaProgMan/OwaspHeaders.Core/issues/72). + +All code which generates the header and it's value are still present, but it is removed from the defaults. Please see the above referenced issue for details. + +--- + +### Version 5 + +This version of the repo ensure that the XSS Protection header (which was removed from the list of defaults in Version 4) is simplified down to the only recommended value (i.e. "0"), so that if a consumer enables XSS Protection they will only get the one possible value. + +This is related to [guidance by MDN](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/X-XSS-Protection) and by OWASP: + +> Warning: The X-XSS-Protection header has been deprecated by modern browsers and its use can introduce additional security issues on the client side. As such, it is recommended to set the header as X-XSS-Protection: 0 in order to disable the XSS Auditor, and not allow it to take the default behavior of the browser handling the response. Please use Content-Security-Policy instead. + +--- + +### Version 4 + +This version of the repo removed the XSS Protection Header from the list of default headers in the `BuildDefaultConfiguration()` extension method. This is related to [issue #44](https://github.com/GaProgMan/OwaspHeaders.Core/issues/44). + +#### Version 4.0.1 Specific Changes + +It was noticed that the `server:` header was not removed (this is defaulted to `server: kestrel` when running locally). Removal of this header was added when the `RemovePoweredByHeader` option (in the `SecureHeadersMiddlewareBuilder`) was chosen. + +#### Version 4.2.0 Specific Changes + +It was [requested](https://github.com/GaProgMan/OwaspHeaders.Core/issues/60) that a `Content-Security-Policy-Report-Only` header could be added. This header was added in version 4.0.2 of the library. + +#### Version 4.4.0 Specific Changes + +The beginnings of the Cache-Control header were added via a [PR](https://github.com/GaProgMan/OwaspHeaders.Core/pull/63). This PR was sent in via GitHub user [mkokabi](https://github.com/mkokabi). + +#### Version 4.5.0 Specific Changes + +It was pointed out that the Cache-Control header PR was incomplete, and caused production systems to begin caching responses which should not have been cached. This version brings in a configuration for the Cache-Control header which allows the user to add the following directives: + +- `no-cache` +- `no-store` +- `must-revalidate` + +These directives are added when building the configuration: + +```c# +return SecureHeadersMiddlewareBuilder + .CreateBuilder() + .UseHsts() + .UseXFrameOptions() + .UseContentTypeOptions() + .UseContentDefaultSecurityPolicy() + .UsePermittedCrossDomainPolicies() + .UseReferrerPolicy() + .UseCacheControl() // <- this line + .UseExpectCt(string.Empty, enforce: true) + .RemovePoweredByHeader() + .Build(); +``` + +The above directives are added via `bool`s. For example, in order to add the `no-cache` header, you need to alter the call to `UseCacheControl()` to look like `UseCacheControl(noCache: true)`. + +### Version 3 + +This version of the repo removed the dependency on .NET Core 2.0, and replaced it with a dependency on .NET Standard 2.0 (via the `netstandard2.0` Target Framework Moniker), and the version of the [Microsoft.AspNetCore.Http.Abstractions](https://www.nuget.org/packages/Microsoft.AspNetCore.Http.Abstractions/) was upped to version 2.1.1 + +This version of the repo was also changed to use the [Builder Pattern](https://en.wikipedia.org/wiki/Builder_pattern) for creating an instance of the `SecureHeadersMiddlewareConfiguration` class. This decision was taken because the configuration should be a build-time decision, rather than a runtime one. As such, a default builder was created for the `SecureHeadersMiddlewareConfiguration` class, which could be generated by calling the following: + +``` csharp +app.UseSecureHeadersMiddleware(SecureHeadersMiddlewareExtensions.BuildDefaultConfiguration()); +``` + +within the Startup class. This would call the following method: + +``` csharp +public static SecureHeadersMiddlewareConfiguration BuildDefaultConfiguration() +{ + return SecureHeadersMiddlewareBuilder + .CreateBuilder() + .UseHsts() + .UseXFrameOptions() + .UseXSSProtection() + .UseContentTypeOptions() + .UseContentDefaultSecurityPolicy() + .UsePermittedCrossDomainPolicies() + .UseReferrerPolicy() + .Build(); +} +``` + +#### Version 3.0.0.0-2 Specific Changes + +The `CspCommandType` enum was added, and consumed when creating Content Security Policy directives. This greatly simplifies the creation of Content Security policy directives, as the previous versions of the library used hard coded rules to decide whether a CSP rule was a directive (e.g. 'self') or a URL. + +Also included where various changes in the placement of semi-colon characters (i.e. ';') within the hard coded string values for certain headers. These are replaced with a single semi-colon which is appended to the header at the very end of rendering it's value. + +#### Version 3.0.0.3 Specific Changes + +This version fixed casing based typos to the `XFrameOptions` enum. It also fixed case based typos in the rendered values for the X-Frame-Options header value (i.e. `sameorigin` was replaced with `SOMEORIGIN`) + +#### Version 3.1.0.0 Specific Changes + +Added support for removing the `X-Powered-By` header value. This required the creation of an extension method called `TryRemoveHeader`, which would return true/false based on whether the header was present and could be removed. This was also added to the default configuration by adding a call to `RemovePoweredByHeader()` to the default config builder. + +#### Version 3.1.0.1 Specific Changes + +This version fixed a typo-based issue which was created during the 3.0.0.3 changes: namely `XFrameOptions.Sameorigin` was rendering as `SOMEORIGIN`. This was changed to `SAMEORIGIN` in this version. + +#### Version 3.1.1 Specific Changes + +An SVG logo was added to the project, ready to be consumed in the NuSpec file. + +#### Version 3.2.0 Specific Changes + +Support for the `Expect-CT` header was added - as per [this issue](https://github.com/GaProgMan/OwaspHeaders.Core/issues/19). The addition of this header was exposed via an extension method called `UseExpectCt()` which can be called when building the configuration object. + +#### Version 3.2.2 Specific Changes + +Removed the explicit dependency on the Microsoft.AspNetcore.All metapackage - as per [this issue](https://github.com/GaProgMan/OwaspHeaders.Core/issues/28). This change required taking a direct dependency on the Microsoft.AspNetCore.Http.Abstractions package (which is what the metapackage was supplying). + +--- + +### Version 2 + +This version of the repo continued to use the `secureHeaderSettings.json`, which was consumed in the Startup class. However, this version of the repo has an explicit dependency on .NET Core 2.0 (it uses the `netcoreapp2.0` Target Framework Moniker), and [Microsoft.AspNetCore.Http.Abstractions version 2.0.0](https://www.nuget.org/packages/Microsoft.AspNetCore.Http.Abstractions/2.0.0). + +### Version 1 + +The initial version of the repo relied on the presence of .NET Standard 1.0 and [Microsoft.AspNetCore.Http.Abstractions version 1.1.1](https://www.nuget.org/packages/Microsoft.AspNetCore.Http.Abstractions/1.1.1). + +The initial version of the repo used a file called `secureHeaderSettings.json` which took the following format: + +``` json +{ + "SecureHeadersMiddlewareConfiguration": { + "UseHsts": "true", + "HstsConfiguration": { + "MaxAge": 42, + "IncludeSubDomains": "true" + }, + "UseHpkp": "true", + "HPKPConfiguration" :{ + "PinSha256" : [ + "e927fad33f9eb96126896413502a1034be0ca379dec377fb891feb9ebc720e47" + ], + "MaxAge": 3, + "IncludeSubDomains": "true", + "ReportUri": "https://github.com/GaProgMan/OwaspHeaders.Core" + }, + "UseXFrameOptions": "true", + "XFrameOptionsConfiguration": { + "OptionValue": "allowfrom", + "AllowFromDomain": "com.gaprogman.dotnetcore" + }, + "UseXssProtection": "true", + "XssConfiguration": { + "XssSetting": "oneReport", + "ReportUri": "https://github.com/GaProgMan/OwaspHeaders.Core" + }, + "UseXContentTypeOptions": "true", + "UseContentSecurityPolicy": "true", + "ContentSecurityPolicyConfiguration": { + "BlockAllMixedContent": "true", + "UpgradeInsecureRequests": "true" + } + } +} +``` + +This was read and used to construct an instance of the `SecureHeadersMiddlewareConfiguration` class (which represented the values used to render the secure headers) at runtime. + +The json file containing the configuration was loaded in the Startup class in the following manner: + +``` csharp +public Startup(IHostingEnvironment env) +{ + var builder = new ConfigurationBuilder() + .SetBasePath(env.ContentRootPath) + .AddJsonFile("appsettings.json", optional: true, reloadOnChange: true) + .AddJsonFile($"appsettings.{env.EnvironmentName}.json", optional: true) + .AddJsonFile("secureHeaderSettings.json", optional:true, reloadOnChange: true) + .AddEnvironmentVariables(); + Configuration = builder.Build(); +} +``` + +As the code used the default configuration builder, changing the contents of the `secureHeaderSettings.json` would force the consuming application to reboot. This would mean that requests which were being dealt with _could_ be destroyed, and responses never generated for them. From de7ec2fc2f8300654dc5c59ec8b778b374e81027 Mon Sep 17 00:00:00 2001 From: Jamie Taylor Date: Thu, 28 Nov 2024 15:15:12 +0000 Subject: [PATCH 04/49] Added about header to index --- docs/index.md | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/docs/index.md b/docs/index.md index 0d7013d..5e53413 100644 --- a/docs/index.md +++ b/docs/index.md @@ -4,7 +4,9 @@ layout: home nav_order: 1 --- -An ASP.NET Core middleware designed to increase web application security by adopting the recommended [OWASP] recommended values for HTTP headers as per the [OWASP Secure Headers] project into all responses generated by the ASP.NET Core pipeline. +## About + +OwaspHeaders.Core is an ASP.NET Core middleware designed to increase web application security by adopting the recommended [OWASP] recommended values for HTTP headers as per 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. 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. @@ -48,6 +50,8 @@ Cross-Origin-Resource-Policy: same-origin {: .note } The above example contains only the headers added by the Middleware. +For a more detailed explanation of how to use the middleware, including how to configure it, see [Using the Middleware](). + ## 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. From 3c07ed73f8e6362638f43e2e9132a2495ab464d6 Mon Sep 17 00:00:00 2001 From: Jamie Taylor Date: Thu, 28 Nov 2024 15:15:25 +0000 Subject: [PATCH 05/49] Removed reference to code base --- docs/Configutation.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/Configutation.md b/docs/Configutation.md index 55e05c3..05ec752 100644 --- a/docs/Configutation.md +++ b/docs/Configutation.md @@ -14,7 +14,7 @@ Adding the default configuration by adding the following to your `Program.cs` so app.UseSecureHeadersMiddleware(); ``` -This will use the default configuration for the OwaspHeaders.Core middleware. The method (found in `/src/Extensions/SecureHeadersMiddlewareExtensions.cs`) looks like this: +This will use the default configuration for the OwaspHeaders.Core middleware. The method looks like this: ```csharp public static SecureHeadersMiddlewareConfiguration BuildDefaultConfiguration() From ad341fe2254bab25b6043143a5ac61c6b428948a Mon Sep 17 00:00:00 2001 From: Jamie Taylor Date: Thu, 28 Nov 2024 16:01:16 +0000 Subject: [PATCH 06/49] Added quote type to docs config --- docs/_config.yml | 3 +++ 1 file changed, 3 insertions(+) diff --git a/docs/_config.yml b/docs/_config.yml index fc9a74d..898266c 100644 --- a/docs/_config.yml +++ b/docs/_config.yml @@ -71,6 +71,9 @@ callouts: warning: title: Warning color: red + quote: + titles: Quote + color: yellow plugins: - jekyll-seo-tag From f3c6ac3b57be1497f3f8e4cbad29cfddec92e401 Mon Sep 17 00:00:00 2001 From: Jamie Taylor Date: Thu, 28 Nov 2024 16:01:58 +0000 Subject: [PATCH 07/49] Made configuration docs into a directory --- docs/{Configutation.md => configuration/index.md} | 1 - 1 file changed, 1 deletion(-) rename docs/{Configutation.md => configuration/index.md} (99%) diff --git a/docs/Configutation.md b/docs/configuration/index.md similarity index 99% rename from docs/Configutation.md rename to docs/configuration/index.md index 05ec752..ed0764e 100644 --- a/docs/Configutation.md +++ b/docs/configuration/index.md @@ -1,6 +1,5 @@ --- title: Configuration -layout: page nav_order: 2 --- From 4c96d6f570522fe378335608b4712b1e750bd233 Mon Sep 17 00:00:00 2001 From: Jamie Taylor Date: Thu, 28 Nov 2024 16:02:11 +0000 Subject: [PATCH 08/49] Added HSTS and X-Frame-Options docs --- .../Strict-Transport-Security.md | 53 +++++++++++++++++++ docs/configuration/X-Frame-Options.md | 51 ++++++++++++++++++ 2 files changed, 104 insertions(+) create mode 100644 docs/configuration/Strict-Transport-Security.md create mode 100644 docs/configuration/X-Frame-Options.md diff --git a/docs/configuration/Strict-Transport-Security.md b/docs/configuration/Strict-Transport-Security.md new file mode 100644 index 0000000..a895654 --- /dev/null +++ b/docs/configuration/Strict-Transport-Security.md @@ -0,0 +1,53 @@ +--- +title: Strict-Transport-Security (HSTS) +nav_order: 1 +--- + +The Mozilla Developer Network describes the Strict-Transport-Security header like this: + +{: .quote } +> The HTTP Strict Transport Security header informs the browser that it should never load a site using HTTP and should automatically convert all attempts to access the site using HTTP to HTTPS requests instead. +> +> source: https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Strict-Transport-Security#description + +An HSTS header can be added in one of two ways, either using the default middleware options: + +```csharp +app.UseSecureHeadersMiddleware(); +``` + +The above adds the HSTS header with the following values: + +| Directive | Value | +|-----------|----------| +| max-age | 31536000 | +| includeSubDomains | (no value needed) | + +Or by creating an instance of the `SecureHeadersMiddlewareBuilder` class using the following code: + +```csharp +var customHstsConfig = SecureHeadersMiddlewareBuilder + .CreateBuilder() + .UseHsts(1200, false) + .Build(); + +app.UseSecureHeadersMiddleware(customHstsConfig); +``` + +The above adds the HSTS header with the following values: + +| Directive | Value | +|-----------|----------| +| max-age | 1200 | + +{: .note } +The above example does not enforce the inclusion of subdomains; as such the HSTS header will only be applied at the domain level. + +## Full Options + +The HSTS header object (known internally as `HstsConfiguration`) has the following options: + +- int: `maxAge` +- bool: `includeSubdomains` + +These values can be set when creating a new instance of the `HstsConfiguration` object, or by calling the `UseHsts` extension method on the `SecureHeadersMiddlewareConfiguration` class. diff --git a/docs/configuration/X-Frame-Options.md b/docs/configuration/X-Frame-Options.md new file mode 100644 index 0000000..3830f00 --- /dev/null +++ b/docs/configuration/X-Frame-Options.md @@ -0,0 +1,51 @@ +--- +title: X-Frame-Options (XFO) +nav_order: 2 +--- + +The Mozilla Developer Network describes the X-Frame-Options header like this: + +{: .quote } +> The X-Frame-Options HTTP response header can be used to indicate whether a browser should be allowed to render a page in a ,