# OwaspHeaders.Core - Complete Documentation

> ASP.NET Core middleware for injecting OWASP-recommended HTTP security headers into all responses with a single line of code

## Overview

OwaspHeaders.Core is an open-source ASP.NET Core middleware library designed to increase web application security by adopting the OWASP-recommended values for HTTP headers as per the OWASP Secure Headers project. The middleware automatically injects secure HTTP headers into all responses generated by the ASP.NET Core pipeline.

**Project Details:**
- **Maintainer:** Jamie Taylor
- **Company:** RJJ Software Ltd
- **License:** MIT
- **Current Version:** 10.4.1
- **Repository:** https://github.com/GaProgMan/OwaspHeaders.Core
- **Documentation:** https://gaprogman.github.io/OwaspHeaders.Core/
- **NuGet Package:** https://www.nuget.org/packages/OwaspHeaders.Core/
- **OpenSSF Best Practices:** Certified (https://www.bestpractices.dev/projects/9723)

## Supported .NET Versions

OwaspHeaders.Core aims to keep in step with the official Microsoft .NET support lifecycle. As of November 19th, 2024, the supported versions are:
- .NET 8 (LTS)
- .NET 9
- .NET 10

**Important Note:** Backporting features and fixes to older versions is not provided. Versions earlier than 8.0.0, and the .NET Framework release, are no longer supported.

## Quick Start

### Installation

```bash
dotnet add package OwaspHeaders.Core
```

### Basic Usage

In your `Program.cs` file, add a single line:

```csharp
app.UseSecureHeadersMiddleware();
```

This will add 11 OWASP-recommended HTTP headers to all responses from your server component with their secure default values.

### Example Response Headers (v9.9.0)

```
strict-transport-security: max-age=31536000;includesubdomains
x-frame-options: deny
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
cache-control: max-age=0,no-store
cross-origin-opener-policy: same-origin
cross-origin-embedder-policy: same-require-corp
x-xss-protection: 0
```

## Included HTTP Security Headers

OwaspHeaders.Core implements the following OWASP-recommended security headers:

### 1. Strict-Transport-Security (HSTS)
Forces browsers to use HTTPS connections only. Default: `max-age=31536000;includesubdomains` (1 year, including all subdomains).

### 2. X-Frame-Options
Prevents clickjacking attacks by controlling whether the page can be displayed in frames. Default: `deny` (no framing allowed).

### 3. X-Content-Type-Options
Prevents MIME-sniffing attacks by forcing browsers to respect the Content-Type header. Default: `nosniff`.

### 4. Content-Security-Policy (CSP)
Controls which resources the browser is allowed to load. Default: `script-src 'self';object-src 'self';block-all-mixed-content;upgrade-insecure-requests;`

### 5. X-Permitted-Cross-Domain-Policies
Controls cross-domain policy files (used by Flash and PDF readers). Default: `none`.

### 6. Referrer-Policy
Controls how much referrer information is included with requests. Default: `no-referrer` (no referrer information sent).

### 7. Cross-Origin-Resource-Policy (CORP)
Protects against cross-origin resource embedding attacks. Default: `same-origin`.

### 8. Cache-Control
Controls browser and proxy caching behavior. Default: `max-age=0,no-store` (no caching).

### 9. Clear-Site-Data
Instructs browsers to clear client-side data (cache, cookies, storage) for specific paths. Not included in default configuration; must be explicitly configured for logout endpoints.

### 10. Reporting-Endpoints (Experimental)
Allows website administrators to specify endpoints where browsers can send violation reports from security policies like Content Security Policy (CSP). Not included in default configuration; marked as EXPERIMENTAL on MDN and must be explicitly configured.

### 11. Cross-Origin-Opener-Policy (COOP)
Isolates browsing context from other windows. Default: `same-origin`.

### 12. Cross-Origin-Embedder-Policy (COEP)
Prevents documents from loading cross-origin resources that don't explicitly grant permission. Default: `same-require-corp`.

### 13. X-XSS-Protection
Legacy header for older browsers. Default: `0` (disabled, as modern CSP is more effective).

**Note:** Permissions-Policy header is not yet implemented.

## Configuration

### Default Configuration

The middleware uses secure defaults based on OWASP recommendations. Simply call:

```csharp
app.UseSecureHeadersMiddleware();
```

### Custom Configuration

Use the fluent builder pattern to customize header values:

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

Then consume it:

```csharp
app.UseSecureHeadersMiddleware(
    CustomSecureHeaderExtensions.CustomConfiguration()
);
```

### Clear-Site-Data Configuration

The Clear-Site-Data header is particularly useful for logout endpoints:

```csharp
var config = SecureHeadersMiddlewareBuilder
    .CreateBuilder()
    .UseClearSiteData(
        new Dictionary<string, ClearSiteDataOptions>
        {
            { "/logout", ClearSiteDataOptions.Cache | ClearSiteDataOptions.Cookies | ClearSiteDataOptions.Storage }
        }
    )
    .Build();

app.UseSecureHeadersMiddleware(config);
```

### Reporting-Endpoints Configuration

The Reporting-Endpoints header is experimental and allows specifying endpoints for browser violation reports:

```csharp
var reportingEndpoints = new Dictionary<string, Uri> {
    { "standard", new Uri("https://localhost:5000/reporting-endpoint") }
};
var config = SecureHeadersMiddlewareBuilder.CreateBuilder()
    .UseReportingEndpointsPolicy(reportingEndpoints)
    .Build();
app.UseSecureHeadersMiddleware(config);
```

## Logging

OwaspHeaders.Core includes comprehensive logging functionality via `ILogger<SecureHeadersMiddleware>`, following Andrew Lock's high-performance logging best practices. To see logging output, ensure your application has logging configured in `appsettings.json`:

```json
{
  "Logging": {
    "LogLevel": {
      "OwaspHeaders.Core.SecureHeadersMiddleware": "Information"
    }
  }
}
```

## Important Limitations

### Blazor and WebAssembly
**This middleware DOES NOT SUPPORT BLAZOR OR WEBASSEMBLY APPLICATIONS.** Setting up secure HTTP headers in a WebAssembly context is a non-trivial task that requires different approaches.

### Server Header
The middleware removes the `X-Powered-By` header, but the `Server` header is added by the reverse proxy and is out of scope for this middleware. To remove the Server header, you need a `web.config` file:

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

## Version History Highlights

### Version 10 (Current)
- Library now supports .NET 10 (by updating the TFM to include `net10.0`)
- Added support for the EXPERIMENTAL Reporting-Endpoints header (version 10.1.x)
- Fixed model properties in OwaspHeaders.Core.Models namespace that were incorrectly set to private (version 10.2.x)
- New ReportingEndpointsPolicy model for configuring endpoint name-to-URI mappings
- UseReportingEndpointsPolicy builder method for middleware configuration
- Support for the modern `report-to` directive in Content Security Policy
- All model properties now properly accessible for serialization scenarios

### Version 9
- Removed support for .NET 6 and .NET 7 (no longer supported by Microsoft)
- Added support for .NET 9
- Added Clear-Site-Data header support with path-specific configuration
- Added Cross-Origin-Opener-Policy (COOP) header
- Added Cross-Origin-Embedder-Policy (COEP) header
- Comprehensive logging support
- Optimizations to middleware Invoke method

### Version 8
- Removed support for ASP.NET Core on .NET Framework
- Re-architected test classes
- Added OwaspHeaders.Core prefix to example and test projects

### Version 7
- Added Cross-Origin-Resource-Policy header to defaults
- Simplified middleware usage in Program.cs

### Version 6
- Removed deprecated Expect-CT header from defaults

### Version 5
- XSS Protection hard-coded to return "0" if enabled

### Version 4
- Introduced builder pattern for configuration
- Uses .NET Standard 2.0
- Removed XSS Protection header from defaults

## Contributing

OwaspHeaders.Core is completely open-source and welcomes community contributions. The project prioritizes:
1. Implementing missing OWASP-recommended headers
2. Bug fixes
3. Documentation improvements

### Contribution Process
1. Fork the project on GitHub
2. Clone your forked version
3. Create a branch under `feature/` directory
4. Commit changes with tests
5. Run `dotnet-format fix` to ensure formatting compliance
6. Push to your fork
7. Create a Pull Request with detailed description

### Contribution Requirements
- Add tests to OwaspHeaders.Core.Tests project
- Run `dotnet-format` and fix any .editorconfig issues
- Ensure code coverage stays above 65%
- Increase version number in OwaspHeaders.Core.csproj (for code changes)
- Document new features in the docs directory

### Tools Required to Build
- .NET SDK 8.0, 9.0, and 10.0
- An IDE (VS Code, Rider, or Visual Studio)
- dotnet-format global tool

## Security Policy

OwaspHeaders.Core minimizes security risk by:
- Making all source code publicly available
- Using only official Microsoft-backed NuGet dependencies
- Carefully reviewing all code contributions
- Building and publishing packages with GitHub Actions
- Using deterministic builds and SourceLink for all NuGet packages

### Supported Versions

Support is scoped by .NET runtime, not by package version: any release of OwaspHeaders.Core running on a .NET version that Microsoft still supports is supported. A release targeting a .NET version that has reached end of support is unsupported, regardless of its version number.

- 10.x.x (targets .NET 8, 9, 10): ✅ Supported until November 14, 2028
- 9.x.x (targets .NET 8, 9): ✅ Supported until November 10, 2026
- 8.x.x (targets .NET 6, 7, 8): ✅ Supported until November 10, 2026, on .NET 8 only. Consuming 8.x.x on .NET 6 or .NET 7 is unsupported today, as Microsoft has retired both runtimes.
- < 8.0.0 (targets .NET 6 and earlier): ❌ Not supported
- .NET Framework version (targets .NET Framework, ASP .NET Core 2.2): ❌ Not supported

.NET 8 and .NET 9 both reach end of support on November 10, 2026, so 8.x.x and 9.x.x become unsupported on the same date, leaving 10.x.x supported by way of its .NET 10 target.

Backporting features and fixes to unsupported releases is not provided.

### Vulnerability Reporting
Report vulnerabilities using GitHub's Private Vulnerability Reporting: https://docs.github.com/en/code-security/how-tos/report-and-fix-vulnerabilities/report-privately

The maintainers aim to acknowledge any vulnerabilities within 72 hours, and fix them as soon as practicable, with severity-dependent timelines.

## Community Guidelines

All community members must adhere to the Code of Conduct, which essentially boils down to: **be nice**.

Violations of the code of conduct are taken very seriously.

## Testing

An example ASP.NET Core application with the middleware installed is provided in the `OwaspHeaders.Core.Example` directory. Run the example application and access the OpenAPI endpoint at `/swagger` to test the middleware.

To verify headers in production applications:
1. Run the application
2. Request a page
3. View headers in browser dev tools (Network tab)
4. Check the Response Headers section

## Additional Documentation

### Detailed Configuration Guides
- Strict-Transport-Security: https://gaprogman.github.io/OwaspHeaders.Core/configuration/Strict-Transport-Security/
- X-Frame-Options: https://gaprogman.github.io/OwaspHeaders.Core/configuration/X-Frame-Options/
- X-Content-Type-Options: https://gaprogman.github.io/OwaspHeaders.Core/configuration/X-Content-Type-Options/
- Content-Security-Policy: https://gaprogman.github.io/OwaspHeaders.Core/configuration/Content-Security-Policy/
- X-Permitted-Cross-Domain-Policies: https://gaprogman.github.io/OwaspHeaders.Core/configuration/X-Permitted-Cross-Domain-Policies/
- Referrer-Policy: https://gaprogman.github.io/OwaspHeaders.Core/configuration/Referrer-Policy/
- Cross-Origin-Resource-Policy: https://gaprogman.github.io/OwaspHeaders.Core/configuration/Cross-Origin-Resource-Policy/
- Cache-Control: https://gaprogman.github.io/OwaspHeaders.Core/configuration/Cache-Control/
- Clear-Site-Data: https://gaprogman.github.io/OwaspHeaders.Core/configuration/Clear-Site-Data/
- Reporting-Endpoints: https://gaprogman.github.io/OwaspHeaders.Core/configuration/Reporting-Endpoints/
- Cross-Origin-Opener-Policy: https://gaprogman.github.io/OwaspHeaders.Core/configuration/Cross-Origin-Opener-Policy/
- Cross-Origin-Embedder-Policy: https://gaprogman.github.io/OwaspHeaders.Core/configuration/Cross-Origin-Embedder-Policy/
- X-XSS-Protection: https://gaprogman.github.io/OwaspHeaders.Core/configuration/X-XSS-Protection/

### Other Resources
- Home/Quick Start: https://gaprogman.github.io/OwaspHeaders.Core/
- Logging Configuration: https://gaprogman.github.io/OwaspHeaders.Core/logging
- Troubleshooting: https://gaprogman.github.io/OwaspHeaders.Core/troubleshooting
- Minimal Code Sample: https://gaprogman.github.io/OwaspHeaders.Core/Minimal-Code-Sample
- Changelog: https://gaprogman.github.io/OwaspHeaders.Core/changelog
- Contributing Guide: https://gaprogman.github.io/OwaspHeaders.Core/Contributing
- Code of Conduct: https://gaprogman.github.io/OwaspHeaders.Core/Code-of-Conduct
- Attestations: https://gaprogman.github.io/OwaspHeaders.Core/attestations

## External References
- OWASP Secure Headers Project: https://owasp.org/www-project-secure-headers/
- OWASP Main Page: https://www.owasp.org/
- .NET Support Lifecycle: https://dotnet.microsoft.com/en-us/platform/support/policy/dotnet-core#lifecycle
- GitHub Repository: https://github.com/GaProgMan/OwaspHeaders.Core
- Build Status: https://github.com/GaProgMan/OwaspHeaders.Core/actions/workflows/dotnet.yml
- Release Workflow: https://github.com/GaProgMan/OwaspHeaders.Core/actions/workflows/release.yml