Content Security Policy without breaking your site

What CSP does

Cross-site scripting (XSS) happens when an attacker gets their JavaScript to run in your page, for example through a comment field or a URL parameter that is echoed without escaping. The browser cannot tell that script apart from yours. Content Security Policy, specified by the W3C, lets you tell the browser which sources of script and other content are legitimate.

CSP is a second line of defence. Escaping output and sanitising input remain the primary fix for XSS; CSP limits the damage when a bug slips through. It also controls framing of your site, where forms may submit, and whether the page may load mixed content.

Directives that matter

frame-ancestors, sandbox and reporting directives only work in the HTTP header, not in a <meta http-equiv> tag. Use the header whenever you can. frame-ancestors also supersedes the older X-Frame-Options header in current browsers, although sending both is harmless.

Host allowlists versus nonces

Early CSP deployments listed allowed script hosts: script-src 'self' https://cdn.example.net https://analytics.example.org. Research by Google engineers showed that most such policies can be bypassed, because allowed CDNs and analytics hosts often serve scripts or JSONP endpoints an attacker can abuse. Long allowlists are also fragile: every new third-party script needs a policy change.

A nonce-based policy trusts scripts by a random value instead of by location. The server generates a new unguessable nonce for every response, adds it to the header and to each legitimate <script> tag. An injected script does not know the nonce, so it does not run.

Content-Security-Policy: script-src 'nonce-4AEemGb0xJptoIGFP3Nd' 'strict-dynamic'; object-src 'none'; base-uri 'none'

<script nonce="4AEemGb0xJptoIGFP3Nd" src="/assets/app.js"></script>
<script nonce="4AEemGb0xJptoIGFP3Nd">window.appConfig = { locale: "en" };</script>

'strict-dynamic' extends that trust to scripts loaded by a trusted script, such as a tag manager inserting other tags, without listing their hosts. Browsers that support 'strict-dynamic' ignore host allowlists and 'unsafe-inline' in the same directive, which lets you add those as fallbacks for very old browsers without weakening the policy for modern ones.

Content-Security-Policy:
  script-src 'nonce-{RANDOM}' 'strict-dynamic' https: 'unsafe-inline';
  object-src 'none';
  base-uri 'none';
  frame-ancestors 'self';
  report-to csp

Hashes for static pages

Static sites without server-side rendering cannot add a fresh nonce to each response. Instead, list the SHA-256 hash of each inline script's exact content, such as 'sha256-…', or move inline scripts into files served from your own origin. External scripts loaded from 'self' then need no nonce at all.

Rolling out without breaking anything

1. Inventory. List the scripts, styles, fonts, frames and API endpoints the site uses, including third parties such as analytics, chat widgets and payment forms.
2. Report-only. Send the policy as Content-Security-Policy-Report-Only. Browsers report violations but block nothing.
3. Collect reports. Configure a reporting endpoint and look at the browser console on key pages and flows.
4. Fix the page, not just the policy. Move inline event handlers (onclick=) into script files, add nonces to legitimate inline scripts, remove unused third parties.
5. Enforce. Switch to Content-Security-Policy once reports only show browser extensions and noise. Keep the report-only header with a stricter candidate policy if you want to tighten further.
6. Watch. Keep reporting on; new features and third-party changes will produce new violations.

Reporting-Endpoints: csp="https://example.com/csp-reports"
Content-Security-Policy-Report-Only: script-src 'nonce-{RANDOM}' 'strict-dynamic'; object-src 'none'; base-uri 'none'; report-to csp

report-to with the Reporting-Endpoints header is the current mechanism. The older report-uri directive is deprecated but still understood by browsers that do not support report-to, so many sites send both during the transition. Reports are JSON; expect noise from browser extensions that inject scripts, and filter by blocked-uri and source-file.

Common violations and fixes

Fix violations in order of risk: script violations first, then connections and frames, and styles last. Script sources decide whether injected code can run, while most style violations are cosmetic.

Resist adding 'unsafe-inline' to script-src without nonces or hashes. It allows exactly the injected inline scripts CSP is supposed to stop, and the HTTP Headers Checker reports it as a weak policy. 'unsafe-inline' in style-src is a smaller risk and a common compromise while inline styles are cleaned up.

A worked example: tightening a real policy

Consider a marketing site at example.com that has grown a policy over the years. It works, but the HTTP Headers Checker marks it as weak because script-src contains 'unsafe-inline' and a wildcard. Here is the starting point and the policy it can reach in a few iterations.

Content-Security-Policy: default-src 'self' https:; script-src 'self' 'unsafe-inline' https://*.example.net https://analytics.example.org; style-src 'self' 'unsafe-inline'; img-src * data:

The problems are easy to name. 'unsafe-inline' lets any injected inline script run, https://*.example.net trusts every host under a shared CDN domain, default-src https: allows any HTTPS origin for everything not listed, and img-src * allows images from anywhere, which can leak data through image URLs. There is also no object-src, base-uri or frame-ancestors.

Content-Security-Policy:
  default-src 'self';
  script-src 'nonce-{RANDOM}' 'strict-dynamic' https: 'unsafe-inline';
  style-src 'self' 'unsafe-inline';
  img-src 'self' data: https://analytics.example.org;
  connect-src 'self' https://analytics.example.org;
  object-src 'none';
  base-uri 'none';
  form-action 'self';
  frame-ancestors 'self';
  report-to csp

Getting there took three changes to the site rather than to the policy: inline onclick handlers moved into the main script, the analytics loader got the nonce, and a legacy widget that needed eval was replaced. 'unsafe-inline' in style-src stays for now as a documented compromise. In browsers that support nonces, the https: and 'unsafe-inline' entries in script-src are ignored, so they only keep very old browsers working.

Beyond scripts

Clickjacking

frame-ancestors 'none' prevents any site from framing yours; 'self' allows only your own pages. It replaces X-Frame-Options: DENY and SAMEORIGIN in modern browsers.

Mixed content

upgrade-insecure-requests makes the browser fetch http:// images, scripts and styles over HTTPS. It helps during migrations of old content, together with HSTS for the page itself.

Trusted Types

require-trusted-types-for 'script' makes supporting browsers reject strings passed to dangerous DOM sinks such as innerHTML unless they come from an approved policy. It targets DOM-based XSS that nonces cannot catch. It needs code changes and is best added after the main policy is stable.

Keeping the policy healthy

A CSP is not a one-time project. Every new feature, marketing tool or embedded widget can need a policy change, and a policy nobody owns tends to accumulate exceptions until it no longer protects anything. Give the policy an owner, keep it in version control next to the application, and review changes to it like code changes.

Two habits keep it tight. First, when adding a source, prefer the narrowest form: an exact origin in connect-src rather than a wildcard, and a nonce rather than a new script host. Second, review violation reports monthly: a sudden rise often means a new third-party script was added without telling anyone, or that an injection attempt is being blocked, and both are worth knowing about.

Finally, test the policy as part of deployment. A simple check that fetches key pages and fails the pipeline when the Content-Security-Policy header is missing or contains 'unsafe-inline' without a nonce catches accidental regressions, such as a proxy configuration change that drops the header.

CSP with frameworks, CDNs and tag managers

Server-rendered frameworks usually have a way to inject a nonce into every script tag they render; look for CSP or nonce support in the framework's documentation. Single-page applications built into static files work well with a policy that allows scripts from 'self' and has no inline scripts at all. Build tools can often be configured to avoid inline bootstrap scripts.

CDNs and edge platforms can add or rewrite headers, which is convenient but can also leave two different policies in effect. When two CSP headers are present, the browser enforces both, and a resource must be allowed by every policy. Check the final response with the HTTP Headers Checker after each deployment.

Tag managers are the hardest case, because marketing teams add scripts without code changes. With 'strict-dynamic', scripts inserted by a nonce-trusted tag manager are allowed, which keeps things working but also means anyone with access to the tag manager can run code on your site. Protect that access like production deploy rights.

FAQ

Sources

• W3C: Content Security Policy Level 3
• MDN: Content Security Policy (CSP)
• W3C: Reporting API
• W3C: Trusted Types
• OWASP Cheat Sheet: Content Security Policy