Guardy 1.1.0

Guardy 🛡️

A lightweight, fluent security headers middleware for ASP.NET Core applications. Guardy makes it easy to add HTTP security headers to your responses using either a code-first builder API or configuration-based approach.

Features

• Fluent Builder API – Configure security headers with a clean, chainable syntax
• Configuration-based – Load header values from appsettings.json or any IConfiguration source
• Supports all major security headers:
  • Content-Security-Policy
  • Strict-Transport-Security
  • X-Content-Type-Options
  • X-Frame-Options
  • X-XSS-Protection
  • Referrer-Policy

License

This project is licensed under the MIT License.

Installation

Add the Guardy project reference or NuGet package to your ASP.NET Core application:

dotnet add package Guardy

Quick Start

Option 1 – Fluent Builder API (Code-First)

Configure security headers directly in code using the builder pattern:

using Guardy.Extensions;
using Guardy.Constants.Sources;

var builder = WebApplication.CreateBuilder(args);
var app = builder.Build();

app.UseSecurityHeaders(headers =>
{
    headers
        .AddContentSecurityPolicy()
            .AddDefaultSrc(ContentSecurityPolicySources.Self)
            .AddScriptSrc(ContentSecurityPolicySources.Self, ContentSecurityPolicySources.UnsafeInline)
            .AddStyleSrc(ContentSecurityPolicySources.Self, ContentSecurityPolicySources.UnsafeInline)
            .AddImgSrc(ContentSecurityPolicySources.Self, ContentSecurityPolicySources.Data);

    headers
        .AddStrictTransportSecurity()
            .SetMaxAgeInYears(1)
            .IncludeSubDomains()
            .EnablePreload();

    headers
        .AddXContentTypeOptions()
            .SetNoSniff();

    headers
        .AddXFrameOptions()
            .SetDeny();

    headers
        .AddXSSProtection()
            .Enable()
            .SetModeBlock();

    headers
        .AddReferrerPolicy()
            .SetNoReferrer();
});

app.MapGet("/", () => "Hello World!");

app.Run();

Option 2 – Configuration-Based (appsettings.json)

Load security header values from your configuration:

1. Add headers to appsettings.json:

{
  "SecurityHeaders": {
    "ContentSecurityPolicy": "default-src 'self'; script-src 'self' 'unsafe-inline'; style-src 'self' 'unsafe-inline'",
    "StrictTransportSecurity": "max-age=31536000; includeSubDomains; preload",
    "XContentTypeOptions": "nosniff",
    "XFrameOptions": "DENY",
    "XSSProtection": "1; mode=block",
    "ReferrerPolicy": "no-referrer"
  }
}

2. Register services and use the middleware:

using Guardy.Extensions;

var builder = WebApplication.CreateBuilder(args);

// Register Guardy services and bind configuration
builder.Services.AddGuardy(builder.Configuration);

var app = builder.Build();

// Use security headers from configuration
app.UseSecurityHeadersFromConfiguration(headers =>
{
    headers
        .AddContentSecurityPolicy()
        .AddStrictTransportSecurity()
        .AddXContentTypeOptions()
        .AddXFrameOptions()
        .AddXSSProtection()
        .AddReferrerPolicy();
});

app.MapGet("/", () => "Hello World!");

app.Run();

API Reference

Security Headers

Content-Security-Policy

headers.AddContentSecurityPolicy()
    .AddDefaultSrc(sources)
    .AddScriptSrc(sources)
    .AddStyleSrc(sources)
    .AddImgSrc(sources)
    .AddFontSrc(sources)
    .AddConnectSrc(sources)
    .AddMediaSrc(sources)
    .AddObjectSrc(sources)
    .AddFrameSrc(sources)
    .AddChildSrc(sources)
    .AddWorkerSrc(sources)
    .AddManifestSrc(sources);

Use the built-in ContentSecurityPolicySources constants for source values:

Strict-Transport-Security

headers.AddStrictTransportSecurity()
    .SetMaxAge(seconds)          // Set max-age in seconds
    .SetMaxAgeInDays(days)       // Set max-age in days
    .SetMaxAgeInYears(years)     // Set max-age in years
    .IncludeSubDomains()         // Add includeSubDomains directive
    .EnablePreload();            // Add preload directive

Note: SetMaxAge, SetMaxAgeInDays, or SetMaxAgeInYears is required. An InvalidOperationException is thrown if not set.

X-Content-Type-Options

headers.AddXContentTypeOptions()
    .SetNoSniff();               // Set value to "nosniff"

X-Frame-Options

headers.AddXFrameOptions()
    .SetDeny()                   // Set value to "DENY"
    .SetSameOrigin();            // Set value to "SAMEORIGIN"

X-XSS-Protection

headers.AddXSSProtection()
    .Enable()                    // Enable XSS protection (1)
    .SetModeBlock()              // Enable with mode=block (1; mode=block)
    .Disable();                  // Disable XSS protection (0)

Referrer-Policy

headers.AddReferrerPolicy()
    .SetNoReferrer()
    .SetNoReferrerWhenDowngrade()
    .SetOrigin()
    .SetOriginWhenCrossOrigin()
    .SetSameOrigin();