Web Security Headers: A Practical CSP Implementation Guide

Strict-Transport-Security (HSTS) forces browsers to use HTTPS for your domain and prevents protocol downgrade attacks. Set Strict-Transport-Security: max-age=31536000; includeSubDomains; preload once you are confident every endpoint on every subdomain serves HTTPS. Content-Security-Policy (CSP) controls which sources the browser is allowed to load resources from and which inline code is allowed to execute; it is the only header that meaningfully mitigates XSS once it has occurred. X-Content-Type-Options: nosniff disables MIME type sniffing, preventing the browser from interpreting a text response as JavaScript or HTML based on content inspection. Referrer-Policy controls how much of the current URL is sent in the Referer header on outbound requests; strict-origin-when-cross-origin is a sensible default that sends only the origin on cross-origin requests. Permissions-Policy (formerly Feature-Policy) controls which browser features (camera, microphone, geolocation, payment, USB) the page can use, defaulting to deny everything not explicitly needed. X-Frame-Options is the legacy header for clickjacking protection; it is superseded by CSP frame-ancestors which is more expressive (supports multiple sources, supports paths). Other headers (X-XSS-Protection, X-Permitted-Cross-Domain-Policies, Expect-CT, Cross-Origin-Resource-Policy, Cross-Origin-Embedder-Policy, Cross-Origin-Opener-Policy) range from deprecated (X-XSS-Protection) to situationally valuable (the cross-origin isolation headers if you need SharedArrayBuffer). Focus on the six above first.

HSTS deployment has three phases. First, set Strict-Transport-Security: max-age=300 to begin enforcement with a short TTL while you verify nothing breaks. Second, raise the max-age to 31536000 (one year) and add includeSubDomains. Third, add preload and submit to the HSTS preload list at hstspreload.org. Preload bakes your domain into the browser binary so that the very first request to your domain is forced to HTTPS, eliminating the trust-on-first-use window where HSTS without preload is bypassable by an attacker controlling the initial DNS response. The preload list is shipped with Chrome, Firefox, Safari, and Edge. The commitment is significant: includeSubDomains means every current and future subdomain must serve valid HTTPS, including subdomains you do not currently use. If you have a marketing team that occasionally spins up campaign subdomains on HTTP, preload will break them and removal from the preload list takes weeks at minimum. Audit every subdomain (including those behind firewalls, on internal DNS) before submitting. The maximum supported max-age for preload is unbounded; the minimum to qualify for the list is 31536000 (one year). Once preloaded, treat HSTS as a one-way commitment.

CSP works by allowlisting sources for each resource type. The directive hierarchy: default-src is the fallback for any fetch directive not explicitly set. script-src controls JavaScript sources, including inline scripts; this is the most security-critical directive. style-src controls CSS sources. img-src controls image sources. connect-src controls XHR, fetch, WebSocket, and EventSource targets. font-src controls web font sources. frame-src controls iframe sources. frame-ancestors controls who can frame this page (clickjacking protection, supersedes X-Frame-Options). form-action controls form submission targets. base-uri restricts the <base> element to prevent attackers from rewriting relative URL resolution. object-src 'none' disables Flash, Java applets, and PDF embeds. report-uri (legacy) or report-to (modern) specifies an endpoint to receive violation reports. A reasonable starting policy: default-src 'self'; script-src 'self' 'nonce-{random}'; style-src 'self' 'unsafe-inline'; img-src 'self' data: https:; connect-src 'self'; frame-ancestors 'none'; form-action 'self'; base-uri 'self'; object-src 'none'; report-uri /csp-report. The 'nonce-{random}' value must be a fresh cryptographically random value generated per response and included in the nonce attribute of every legitimate inline script: <script nonce='abc123'>. Inline scripts without the matching nonce are blocked; injected XSS payloads cannot guess the nonce.

Deploying a strict CSP straight into enforcement will break your site. Every legitimate inline script, every third-party widget, every analytics snippet will be blocked, and your users will see broken pages. The disciplined rollout is two-phase. Phase one: deploy with Content-Security-Policy-Report-Only header instead of Content-Security-Policy. Report-Only does not block anything; it only sends violation reports to your report-uri endpoint. Set up a violation collector (Sentry, Datadog, or a simple JSON endpoint that logs to your SIEM) and collect violations for at least two weeks across all user populations, including mobile, internationalized users, and users with browser extensions. Analyze the violations: distinguish legitimate sources you forgot (your CDN, your analytics provider, your error tracker) from extension noise (chrome-extension://, moz-extension://, safari-extension://) which you can usually filter out from reports. Add legitimate sources to your policy. Iterate until the violation rate drops to a manageable level dominated by extension noise. Phase two: switch the header name from Content-Security-Policy-Report-Only to Content-Security-Policy and keep monitoring. Keep the report-uri active in enforcement mode so you catch any new sources introduced by feature work. For new applications, you can skip Report-Only by building with CSP discipline from day one, but for any existing application with more than trivial JavaScript, Report-Only first is the only safe path.

The default impulse when CSP breaks something is to add 'unsafe-inline' to script-src, which silently disables most of the XSS protection CSP provides. The disciplined alternative is nonces or hashes. Nonces: generate a fresh random value per response (at least 128 bits of entropy, base64-encoded), include it in the CSP header as 'nonce-{value}' in script-src, and emit it on every legitimate inline script tag. The application framework (Next.js, Rails, Django) typically has middleware or template helpers for this. Hashes: for static inline scripts whose content does not change, compute the SHA-256 hash of the script content and include 'sha256-{base64hash}' in script-src; the browser allows only inline scripts whose content matches the hash. Hashes work for build-time constants but not for dynamic content. For 'unsafe-eval', which permits eval, new Function, and similar dynamic code generation, the answer is to remove eval from your code; modern frameworks rarely require it, and the libraries that do (some templating engines, some JSON parsers) usually have safe alternatives. Common breakage scenarios: CDNs like Cloudflare Rocket Loader inject inline scripts that need either disabling at the CDN level or whitelisting via hash, analytics platforms (Google Tag Manager, Segment) sometimes load secondary scripts from domains not in your initial allowlist, third-party widgets (chat, support, comment systems) often require 'unsafe-inline' or specific domains; isolate these in dedicated iframes with their own permissive CSP rather than weakening your main page policy. Grade your final configuration on securityheaders.com and observatory.mozilla.org, but treat the grade as a sanity check rather than a goal; an A+ grade with 'unsafe-inline' is worse than a B grade with a strict nonce-based policy.