Skip to content

README.md

Latest commit

 

History

History
111 lines (83 loc) · 6.16 KB

README.md

File metadata and controls

111 lines (83 loc) · 6.16 KB
Raw

SafeWebCore Documentation

Welcome to the SafeWebCore documentation. SafeWebCore is a .NET 10 middleware library that adds security headers to ASP.NET Core applications, targeting an A+ rating on securityheaders.com out of the box.

📖 Table of Contents

Getting Started

  • Getting Started — Installation, minimal setup (v1.1.0+), verifying headers, using nonces

Core Guides

  • Security Headers — Every header explained, defaults vs strict A+, header comparison table
  • CSP Configuration — Full CSP Level 3 & Level 4 reference, builder, nonces, performance optimizations (v1.1.0+)
  • Presets — All five presets (StrictAPlus, Api, Mvc, Blazor, SpaReverseProxy), comparison, decision guide
  • Advanced Configuration — Path policies, report-only, CSP reporting, custom sinks, endpoint overrides, testing, troubleshooting

Examples & Patterns

  • Examples — Three runnable projects (MinimalApi, MvcApp, ApiService) with feature matrix

Performance & Reference

  • Benchmarks — Running BenchmarkDotNet suites, result interpretation, creating new benchmarks
  • Recipes — Practical guides for common scenarios (MVC+CDN, Swagger, Blazor, Report-Only, Reverse Proxy, etc.)
  • Roadmap — Planned work for v1.4 through v1.6, focused on DX, diagnostics, tooling, and observability
  • Backward Compatibility Policy — Rules for additive-only changes, stable defaults, and supported upgrade paths

Repository, packages & release

Archived

  • Archive — Obsolete v1.2 planning documents (implementation plan, roadmap)

📋 Quick Reference

I want to... Go to
Get A+ in one line Getting Started
Run a working example Examples
Configure everything custom Getting Started
Access CSP nonce Getting Started
Understand what each header does Security Headers
Configure CSP with advanced directives CSP Configuration
Choose the right preset Presets
Use path-based policies Advanced Configuration
Set up CSP violation reporting Advanced Configuration
Debug CSP violations Advanced Configuration
Create custom headers Advanced Configuration
Add endpoint overrides Advanced Configuration
Preview effective headers and path-policy behavior Advanced Configuration
Test security headers Advanced Configuration
Use testing helpers SafeWebCore.Testing package (preview)
Understand planned roadmap work Roadmap
Review compatibility rules before contributing Backward Compatibility Policy
See all projects in the repo Project Catalog
Understand NuGet candidates NuGet Packages & Candidates
Check if ready to release Release Readiness

🚀 Latest Features (v1.1.0+)

Feature Link
Per-request nonce access via HttpContext.GetCspNonce() Getting Started
Zero-allocation nonce generation TryWriteNonce(Span<char>) Getting Started
Pre-built CSP template (startup-only computation) CSP Configuration
TagHelper nonce auto-injection Getting Started
All v1.2 features now shipped Presets and Advanced Configuration

📚 API Reference

Generated from XML documentation comments. Key classes:

Class Purpose
SecurePresets Pre-configured security option sets
NetSecureHeadersOptions Root configuration for all headers
CspOptions CSP directive configuration (C# record)
CspBuilder Fluent API for CSP configuration
ReferrerPolicyBuilder Typed builder for Referrer-Policy
PermissionsPolicyBuilder Typed builder for Permissions-Policy
CrossOriginPolicyBuilder Typed builder for COEP/COOP/CORP
NonceService Nonce generation (GenerateNonce(), TryWriteNonce())
ICspReportSink Custom CSP violation handling
IHeaderPolicy Custom header implementations

🔗 Important Links