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 quietly 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:
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.
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.
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.
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.
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:
Here's what nobody warns you about 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. 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.If your site takes card payments, CSP isn't optional any more. It's effectively mandated. PCI-DSS 4.0 (and the 4.0.1 revision) introduced two requirements aimed squarely at e-skimming, 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 a large part of this: the policy authorizes scripts, while the reports plus header monitoring provide the change detection.
Deploy a starting policy (default-src 'self' plus your obvious known sources) in report-only mode.
Collect violations across real traffic for 7–14 days. Filter the noise.
Add the legitimate sources you discover. Decide your inline-script strategy: nonces for dynamic, hashes for static, 'strict-dynamic' for complex apps.
Switch the refined policy to the enforcing header. Keep object-src 'none', base-uri 'self' and frame-ancestors locked down.
New violations after enforcement mean one of two things: someone shipped a change, or someone's attacking you. Both are things you want to know immediately.
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.A hardened starting point to adapt. Collect reports, refine, then switch Content-Security-Policy-Report-Only to Content-Security-Policy to enforce.
| 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 uses an LLM to turn your real data into a policy you can actually ship, with a plain-English explanation for every rule.
This guide is maintained by the team behind csplog. We tell you what your policy should be.