Content Security Policy: Control specification
CSP headers deploy through staged report-only and enforce modes with nonce or hash discipline, violation ingestion, rollback triggers, and environment-specific directive profiles so XSS containment does not break production on first publish.
Package status: AI-assisted reference package. Static package validation has passed; implementation scenarios remain not run and human domain review is required before stable adoption.
Decision
Content Security Policy rolls out per environment using explicit stages defined in the adoption profile. Script execution for dynamic pages uses per-request nonce discipline; HTML carrying a nonce must not be served from shared CDN cache with a stale header/body mismatch. Violation reports ingest to an unauthenticated, rate-limited collector treated as attacker-controlled input. They may contribute to rollback only after a trusted deployment signal corroborates them; raw report counts alone never authorize an automatic production change.
Scope
- CSP directive profiles, rollout stages, per-request nonce generation, HTML cache contract, violation report ingestion, and rollback automation for browser-facing applications.
Outside this block
- Subresource Integrity for static assets (complementary control, not specified here).
- Server-side HTML sanitization of user-generated content.
- Cookie security flags and CSRF tokens.
Contract
- Production enforce stage headers include default-src, script-src, and object-src directives at minimum; missing required directives fail deployment gate.
- Production enforce script-src includes per-request nonce or hash sources; forbidden_script_values remain absent unless break-glass exception exists in csp-rollout.yaml.
- csp_header_body_nonce_must_match requires inline script nonce to match the CSP header nonce for the same HTTP response.
- html_cache_policy_with_nonce private-no-store prevents shared caches from serving HTML whose nonce no longer matches a fresh CSP header.
- cdn_cache_key_includes_nonce when edge caching is unavoidable ensures cache keys vary with nonce.
- Report collectors are unauthenticated and rate-limited; report fields are never authorization or executable input.
- A rolling one-minute violation rate is evaluated throughout rollback_window_minutes. Crossing enforce_violation_rollback_threshold_per_minute opens a rollback candidate; automatic rollback additionally requires a trusted deployment-health signal, while an operator may approve a manual rollback from the candidate.
- Report-only stage runs for at least report_only_min_days before enforce promotion; promotion requires violation rate below threshold.
- Third-party script additions require catalog entry with owner and review date before appearing in script-src.
Implementation guidance
- Generate nonces per request at the layer that renders HTML; propagate to template context consistently.
- Treat report-uri and report-to collectors as unauthenticated, attacker-controlled ingestion endpoints: enforce strict content-type and body-size limits, rate-limit abuse, isolate storage, and never trust report fields as authorization or executable input.
- Store CSP artifacts in version control with digest pinned in deployment manifests.
- Test staging enforce mode against automated UI smoke suites before production promotion.
- Corroborate report-rate spikes with trusted signals such as synthetic browser failures, server-side release health, or an operator-confirmed incident. Deduplicate and abuse-filter reports before calculating the candidate rate.
Failure handling and safeguards
- CSP artifact parse errors block release rather than deploying malformed headers.
- Violation collector outage does not auto-promote to enforce; stage timers pause until reporting resumes or operators approve override.
- Spoofed or flooded reports may alert and open an investigation, but cannot by themselves trigger automated rollback.
- Break-glass unsafe-inline exceptions expire on calendar date in the profile and trigger CI warnings before expiry.
Verification and operations
- Automated checks assert header/body nonce alignment, cache-control headers, and forbidden directive absence on HTML responses.
- Dashboards chart violations per minute by directive and deploy version.
- Quarterly game-day exercises rollback CSP version under load.
Adoption assumptions
- Names and numeric values in example.yaml and csp-rollout.yaml are an adoption profile, not universal defaults.
- The adopting team owns third-party script inventory and maps MDN examples only as supplemental guidance to W3C CSP Level 3 normative text.