SecureHeaders.AspNetCore 1.0.0

SecureHeaders.AspNetCore

Lightweight, high-performance, security-focused HTTP headers middleware for ASP.NET Core.

One line secures your application against the most common browser-based attacks:

app.UseSecureHeaders();

Features

• Zero heavy dependencies — only standard Microsoft.AspNetCore.App framework references
• Multi-targeting — supports .NET 8 and .NET 10 (future-compatible)
• Presets — Basic, ApiOnly, Spa, Strict for common scenarios
• Fluent CSP builder — strongly-typed Content-Security-Policy construction
• Minimal allocations — header values are pre-computed and cached at startup
• Thread-safe — safe for high-concurrency workloads
• HSTS Production Guard — HSTS is only sent in Production by default
• Non-destructive — existing response headers are preserved unless you opt in to override

Headers managed

Installation

dotnet add package SecureHeaders.AspNetCore

Quick Start

Minimal (defaults)

// Program.cs
builder.Services.AddSecureHeaders();

app.UseSecureHeaders();

Inline configuration

app.UseSecureHeaders(options =>
{
    options.EnableHsts = true;
    options.HstsMaxAge = TimeSpan.FromDays(365);
    options.EnableCsp = true;
    options.CspPolicy = "default-src 'self'; object-src 'none';";
});

Preset usage

// Safe production defaults
app.UseSecureHeaders(SecurityHeaderPreset.Basic);

// Optimised for REST APIs
app.UseSecureHeaders(SecurityHeaderPreset.ApiOnly);

// React / Angular / Vue SPA backend
app.UseSecureHeaders(SecurityHeaderPreset.Spa);

// Maximum isolation
app.UseSecureHeaders(SecurityHeaderPreset.Strict);

Preset + override

app.UseSecureHeaders(SecurityHeaderPreset.Strict, options =>
{
    // Relax CSP for a specific third-party analytics script
    options.CspPolicy = "default-src 'self'; script-src 'self' https://analytics.example.com;";
});

CSP Fluent Builder

Use CspBuilder to construct type-safe Content-Security-Policy strings:

using SecureHeaders.AspNetCore.Builders;

var policy = new CspBuilder()
    .AddDefaultSrcSelf()
    .AddScriptSrcSelf()
    .AddStyleSrcSelf()
    .AddImgSrcSelf()
    .AddImgSrcData()          // allow inline SVG data URIs
    .AddFontSrcSelf()
    .AddConnectSrcSelf()
    .AddObjectSrcNone()
    .AddBaseUriSelf()
    .AddFormActionSelf()
    .AddFrameAncestorsNone()
    .AddUpgradeInsecureRequests()
    .Build();

app.UseSecureHeaders(options =>
{
    options.EnableCsp = true;
    options.CspPolicy = policy;
});

Nonce & hash support

// Nonce-based inline script allowance
var policy = new CspBuilder()
    .AddDefaultSrcSelf()
    .AddNonce("script-src", nonceBase64Value)
    .AddObjectSrcNone()
    .Build();

// Hash-based inline script allowance
var policy = new CspBuilder()
    .AddDefaultSrcSelf()
    .AddHash("script-src", "sha256", scriptHashBase64)
    .Build();

CSP Report-Only mode

app.UseSecureHeaders(options =>
{
    options.EnableCsp = true;
    options.EnableCspReportOnly = true;        // sends Content-Security-Policy-Report-Only
    options.CspPolicy = "default-src 'self'";
    options.CspReportUri = "/security/csp-report";
});

SPA Configuration

For React, Angular, or Vue applications:

app.UseSecureHeaders(SecurityHeaderPreset.Spa);

The Spa preset configures:

• Cross-Origin-Opener-Policy: same-origin-allow-popups (allows OAuth pop-ups)
• Cross-Origin-Embedder-Policy: unsafe-none (avoids breaking CDN asset loading)
• Cross-Origin-Resource-Policy: same-site
• Referrer-Policy: same-origin
• HSTS enabled in Production

API-Only Configuration

For JSON REST APIs that serve no browser-rendered HTML:

app.UseSecureHeaders(SecurityHeaderPreset.ApiOnly);

The ApiOnly preset:

• Omits X-Frame-Options (browser-only concept for APIs)
• Sets Referrer-Policy: no-referrer
• Enables COOP same-origin
• Leaves CSP disabled

Configuration Reference

SecureHeadersOptions

Custom headers

app.UseSecureHeaders(options =>
{
    // Add a custom header
    options.CustomHeaders.Add(new CustomHeader("X-Tenant", "acme-corp"));

    // Override an existing header (if the response already has it)
    options.CustomHeaders.Add(new CustomHeader("X-Frame-Options", "DENY", overrideExisting: true));

    // Remove a header
    options.RemoveHeaders.Add("X-AspNet-Version");
});

DI registration (AddSecureHeaders)

Calling AddSecureHeaders() is optional when you pass a configure delegate or a preset directly to UseSecureHeaders(). It is required when calling app.UseSecureHeaders() with no arguments (so that IOptions<SecureHeadersOptions> is available in the DI container).

// Required when using UseSecureHeaders() with no arguments:
builder.Services.AddSecureHeaders();

// Also supports configuring via DI (e.g. appsettings.json binding):
builder.Services.AddSecureHeaders(options =>
{
    options.EnableCsp = true;
    options.CspPolicy = builder.Configuration["Security:CspPolicy"];
});

Performance

The middleware pre-computes all header values into a HeaderValueCache at startup. Per-request work is limited to:

• Iterating a small fixed list of header names
• Calling IHeaderDictionary[name] = value for each enabled header
• No allocations for pre-computed header values

Version Compatibility

The package uses only stable IApplicationBuilder, HttpContext, and IHeaderDictionary abstractions, making it forward-compatible with future .NET versions.

Security Considerations

• HSTS preload: enabling HstsPreload = true registers your domain permanently with browser HSTS preload lists. This cannot be easily undone. Only enable once you are fully committed to HTTPS on all subdomains.
• CSP: CSP requires careful tuning per application. Start with report-only mode and monitor reports before switching to enforcing mode.
• COEP: require-corp may break pages that load cross-origin resources (CDN images, fonts) that do not return Cross-Origin-Resource-Policy headers.

Contributing

Pull requests are welcome at github.com/DNVerma88/secure-headers-aspnetcore. Please ensure:

• All tests pass on both net8.0 and net10.0
• New public API surface includes XML documentation
• No new runtime dependencies are introduced
• TreatWarningsAsErrors remains satisfied

License

MIT