Guides · 2026-09-30 · By VSNARY | Emmanuel Orta · 2 views
CSP report-only: how to roll out a Content-Security-Policy without breaking your site
How to introduce a Content-Security-Policy without breaking the page: write it from what loads, ship it report-only with a sink that works, read the reports, then enforce.
Ship the Content-Security-Policy in report-only mode first, with a fresh nonce for inline scripts on every response and a report destination that really receives violations. Two mistakes make the reporting step silently useless: giving report-to a URL instead of the name of a group defined in Reporting-Endpoints, and pointing report-uri at your own site. Read the reports until they go quiet, then switch the header name from Content-Security-Policy-Report-Only to Content-Security-Policy to enforce it, and test signed in as well as signed out.
A Content-Security-Policy is the only response header that can break a page while returning 200. Every other security header either works or is ignored; this one, set too tightly, silently removes the scripts, styles and images a page was built on, and the visitor sees a broken layout with no error. That is why the header has a report-only mode, and why the sensible path is not to write the policy and switch it on, but to write it, watch what it would have blocked, fix those, and only then enforce. This guide describes that path as run on crawlcheck.io itself in September 2026, and the two reporting mistakes that make violation reports disappear without an error.
Two headers, one grammar #
Content-Security-Policy enforces. Content-Security-Policy-Report-Only evaluates the same policy, blocks nothing, and sends a report for every violation it would have blocked. The two can be sent together, with different policies, and browsers keep them separate. The grammar is directives separated by semicolons, each naming a resource class and the sources allowed for it: script-src, style-src, img-src, connect-src, frame-ancestors and so on, with default-src as the fallback for any class not named. A source can be a host, a scheme, the keyword 'self', a hash of the exact inline content, or a nonce.
Step one: write the policy from what the page loads #
Do not start from a template. Start from the network panel of the page, with the cache disabled, and list every third-party host it pulls from. Every host that serves a script, a style, a font, an image, a frame or an XHR target needs a directive that allows it. The inline scripts and styles are the hard part: a policy that permits 'unsafe-inline' for scripts permits every injected script too, which removes most of the protection. The alternative is a nonce, a random value generated per response, placed on the header and on every inline <script> the server writes. A script without the nonce does not run.
Step two: ship it as report-only with a working report sink #
This is the step most sites get wrong. A policy's report-uri directive takes a URL that will receive a POST per violation. The newer report-to directive takes the name of a reporting group, which must be defined in a separate Reporting-Endpoints or Report-To header. Give report-to a URL and the directive is invalid and ignored: the browser evaluates the policy and throws every report away. Broken reporting like this shows up on 0.3% of scanned sites, along with one more case: a report-uri pointing back at the site's own origin, which makes every violation an extra request to the page being reported on. Neither mistake shows up in a browser; the page loads, and the reports never arrive.
| Directive | Takes | Given a URL | Given a name |
|---|---|---|---|
report-uri | one or more URLs | works (deprecated, still honoured) | invalid |
report-to | a group name from Reporting-Endpoints | invalid — ignored silently | works |
Reporting-Endpoints header | name="url" pairs | — | defines the group |
Step three: read the reports, not the theory #
On crawlcheck.io the report-only policy went up on 24 September with a fresh nonce on every response. Over the following days the reports showed one real violation class, a script loaded from a third-party host, and nothing else. That is the outcome to wait for: a report stream that has gone quiet except for things you recognise. Serving that script from the site’s own domain let it carry the nonce, the violations stopped, and the policy was switched to enforced with 'strict-dynamic' so that scripts loaded by nonced scripts are trusted too. The public side of the change is on the trust center and the security page.
Step four: enforce, and keep report-only beside it #
Switching the header name from Content-Security-Policy-Report-Only to Content-Security-Policy is the enforcement. It is worth keeping a second, report-only header with a tighter draft policy beside the enforced one, so the next tightening can be measured the same way. Browsers apply both: the enforced one blocks, the report-only one reports. Do not send the same policy under both names; that only doubles the report volume.
The bug that only affected signed-in visitors #
A nonce policy has a failure mode that is invisible to a scanner and to most testing: the nonce must be swapped into every inline script on every response, and if any response path skips the swap, the header names a nonce the page does not carry and every inline script on that page is blocked. On crawlcheck.io one deploy skipped the swap for signed-in sessions. Anonymous responses were fine; signed-in responses carried a header naming a nonce that had never been written into the HTML. The report is in its own post. The lesson for a rollout is to test the enforced policy signed in and signed out, on a page that uses an inline script, before believing the report stream.
How to check a site from outside #
Fetch the homepage headers and read both CSP header names. If report-to appears, confirm its value is a bare token and that a Reporting-Endpoints header defines that token. If report-uri appears, confirm the host is not the site itself. Then load the page in a browser with the console open: an enforced policy that is too tight prints one console line per blocked resource, naming the directive. A scan on crawlcheck.io reports the reporting defects and lists the third-party hosts the page loads, which is the input the policy has to allow. What it cannot tell you is whether the policy is right; only the report stream, read for a few days, can.
The other directives and headers worth checking #
Rolling out script-src is the hard part. These are the smaller settings that sit next to it. Several of them do not fall back to default-src, so a policy that looks strict can still leave them open.
| Setting | What it does | How to check it | Reference |
|---|---|---|---|
CSP hash ('sha256-…') | Allows one inline script or style whose bytes match the hash, without allowing inline code in general | Hash the exact block, compare it with the policy, and watch the console for violations after every edit to that block | MDN |
form-action | Limits where forms on the page may submit | Submit each real form once; it does not inherit default-src, so leaving it out leaves forms unrestricted | MDN |
base-uri | Limits what a <base> element may set as the base for relative links | Look for a <base> tag and the directive; it does not inherit default-src either | MDN |
object-src | Controls plugin content loaded by <object> and <embed> | Set it to 'none' unless the site really embeds such content; it falls back to default-src | MDN |
upgrade-insecure-requests | Asks the browser to fetch http:// sub-resources over HTTPS | Useful during an HTTPS move; it does not make a resource that has no HTTPS version load, so check failed requests | MDN |
Subresource Integrity (integrity=) | Refuses a script or stylesheet whose bytes do not match the expected hash | Compare the hash with the file actually served; a stale hash blocks a legitimate update, and cross-origin files also need crossorigin | MDN |
Permissions-Policy | Turns off browser features (camera, location, payment) for the page and its embeds | List the features the site actually uses, deny the rest, and test any embedded form or map afterwards | MDN |
Referrer-Policy | Controls how much of the page address is sent to other sites | Check outgoing requests: paths and query strings can carry things a third party should not see | MDN |
Share this finding:LinkedInXEmailFollow Emmanuel on LinkedIn
Questions this post answers
What is the difference between Content-Security-Policy and Content-Security-Policy-Report-Only?
Both evaluate the same policy grammar. The enforced header blocks resources that violate it; the report-only header blocks nothing and sends a report per violation. Sending both, with different policies, is allowed and browsers keep them separate.
Why is report-to with a URL a problem?
The report-to directive takes the name of a reporting group defined in a Reporting-Endpoints or Report-To header. Given a URL it is invalid and the browser ignores it, so the policy is evaluated and every report is discarded. The page still loads, so nothing looks wrong.
Is report-uri deprecated?
It is marked deprecated in favour of report-to, but browsers still honour it, and a site can send both. The setup to avoid is a report-uri pointing at the site's own origin, because every violation then becomes an extra request to the page being reported on.
What does 'strict-dynamic' do?
It tells the browser to trust any script loaded by a script that already carries a valid nonce or hash, and to ignore host allowlists for scripts. It makes a nonce policy workable for pages whose scripts load further scripts.
How long should a policy stay in report-only?
Until the report stream goes quiet except for violations you recognise. On crawlcheck.io that took a few days of aggregated reports and one self-hosted script; the length depends on how many third-party resources the page loads.
Can a scanner tell me whether my CSP is correct?
It can tell you whether the reporting directives are valid and which third-party hosts the page loads, which is the input the policy must allow. Whether the policy blocks something the page needs only shows in a browser or in the violation reports.
Related findings
The main product
Found this on your own site? We fix it for $100.
Scan free to see where you stand. The fix is one site, every finding implemented and re-measured, with a sealed before and after.
Free browser extension
Check this on any site you open, without leaving the page.
CrawlCheck for Chrome grades every site you visit A–F and shows, from your own browser, what search engines and AI assistants are actually served. Free, no account.
Write for the library
Measured something yourself? Submit an article.
Send your finding, the data and the method. A person reads every submission and replies by email; accepted articles are published under your name with a link to your study. Free to submit. Articles are accepted on merit; no one can pay to have one published.
How it works · a reply within about a week
Spotted a mistake or a bug on this page? Report an error. Confirmed errors are fixed and logged on the corrections page.
Comments
Comments are read before they appear. Nothing is published automatically, and no account is needed. An AI agent with a published signing key can post without the queue: it signs the request and the signature is checked against its own domain (how). Those appear at once, marked verified.
Writing about this? Facts, live figures and marks — every number on that page is dated and traceable to a scan.