SimpleOwaspHeaders.Cookies 1.0.2

SimpleOwaspHeaders

Target framework: net10.0 · Language: C# · Test runner: xUnit

Route-aware OWASP security headers for ASP.NET Core 10, configured with IOptions<T> and appsettings.json.

Install

dotnet add package SimpleOwaspHeaders
# optional cookie hardening
dotnet add package SimpleOwaspHeaders.Cookies

Quick start

builder.Services.AddSimpleOwaspHeaders(options =>
{
    options.DefaultPolicy = SecurityHeaderPolicy.OwaspRecommended;

    options.AddNamedPolicy("Admin", policy => policy
        .WithContentSecurityPolicy(csp => csp
            .ScriptSources("'self'")
            .ImageSources("'self'", "data:")));

    options.ForPath("/admin", "Admin");
    options.ForPathRegex(@"^/api/public/.*", policy => policy
        .WithContentSecurityPolicy(csp => csp.DefaultSources("'none'")));

    options.IgnorePath("/health");
});

app.UseSimpleOwaspHeaders();
app.MapSimpleOwaspHeadersDiagnostics(); // optional — dev diagnostics when EnableDiagnosticsEndpoint = true
await app.RunOrExportSecurityReportAsync();

appsettings.json

{
  "SimpleOwaspHeaders": {
    "DefaultPreset": "OwaspRecommended",
    "EnableDiagnosticsEndpoint": true
  }
}

builder.Services.AddSimpleOwaspHeaders(builder.Configuration.GetSection("SimpleOwaspHeaders"));

How it works

1. AddSimpleOwaspHeaders — register options, presets, and path policies
2. ValidateOnStart — fail fast on invalid configuration
3. UseSimpleOwaspHeaders — middleware runs on each request
4. Policy resolver — match path, merge policies, pick effective headers
5. Response — security header values written to the HTTP response

Each request passes through the middleware. The resolver picks the effective policy for that path, merges it onto the default, and the middleware writes the header values to the response.

See docs/POLICY_MERGE.md for merge order and path-matching rules.

Features

• Options-first — AddSimpleOwaspHeaders() + startup validation
• Per-route CSP — prefix, regex, and [SecureHeaders("Name")] endpoint policies; CSP directives merge individually
• Presets — OwaspRecommended, Strict, ApiOnly, SpaWithCdn(cdnUrl)
• Full CSP builder — all major directives, data:, nonces, Report-Only, report-to
• Clear-Site-Data — path-specific (logout flows)
• Permission-Policy — experimental, opt-in
• Reporting-Endpoints — pairs with CSP report-to
• SimpleOwaspHeaders.Cookies — HttpOnly, Secure, SameSite on Set-Cookie
• Roslyn analyzers — compile-time checks for common misconfiguration (docs/ANALYZERS.md)
• Diagnostics — HTML reports with per-directive CSP breakdown (dev only)

Diagnostics (development)

Enable with EnableDiagnosticsEndpoint = true in configuration (development environment only).

HTTP endpoints (via MapSimpleOwaspHeadersDiagnostics):

Build-time / CI export (via RunOrExportSecurityReportAsync, CLI flags, env vars, or MSBuild):

Export the configuration matrix without starting the web server:

dotnet run -- --export-security-report ./artifacts/security-headers-report.html
dotnet run -- --export-security-report ./report.html --export-security-report-format=json

Environment variables:

• SIMPLE_OWASP_HEADERS_REPORT_PATH — output path
• SIMPLE_OWASP_HEADERS_REPORT_FORMAT — html, json, or both (default)

MSBuild (web projects referencing the package):

<PropertyGroup>
  <ExportSimpleOwaspHeadersReport>true</ExportSimpleOwaspHeadersReport>
  <SimpleOwaspHeadersReportOutputPath>$(OutputPath)security-headers-report.html</SimpleOwaspHeadersReportOutputPath>
</PropertyGroup>

AddSimpleOwaspHeaders() registers a startup export hook, so MSBuild export works without RunOrExportSecurityReportAsync() — export flags or SIMPLE_OWASP_HEADERS_REPORT_PATH exit the process after writing the report.

Sample app

cd samples/SimpleOwaspHeaders.Sample
dotnet run

Contributing

Contributions are welcome. See CONTRIBUTING.md for setup, project layout, and how to add presets, policies, or analyzers.

Please read our Code of Conduct before participating.

Quick start for contributors:

git clone https://github.com/kearns2000/SimpleOwaspHeaders.git
cd SimpleOwaspHeaders
dotnet build -c Release
dotnet test -c Release

Open a pull request with tests for any behaviour change. CI runs build and test on every PR.

License

MIT