Agent view · Guides · 2026-09-30
CSP report-only: how to roll out a Content-Security-Policy without breaking your site
This is the response this server returns to a client that asks for Accept: text/markdown at https://crawlcheck.io/guides/content-security-policy-rollout-report-only-to-enforced: fetched when you opened this page, shown byte for byte. An assistant, a crawler that negotiates markdown, or anything reading our feed gets exactly this. The markdown leaves signed (RFC 9421, key in our key directory), so a crawler can prove the page it read is the page this server sent; the check is shown below.
| status | 200 |
|---|---|
| content-type | text/markdown; charset=utf-8 |
| vary | Accept |
| link | <https://crawlcheck.io/llms.txt>; rel="describedby"; type="text/plain", <https://crawlcheck.io/.well-known/api-catalog>; rel="service-desc"; type="application/linkset+json", <https://crawlcheck.io/guides/content-security-policy-rollout-report-only-to-enforced>; rel="cite-as", <https://crawlcheck.io/.well-known/http-message-signatures-directory>; rel="http-message-signatures-directory" |
| cache-control | public, max-age=900, stale-while-revalidate=2400 |
| bytes | 19,157 |
| words | 2,706 |
| sha-256 | fd22f645b3e6ef97f51b34720cbb94a8d2b9362b9198e9340f5ff729ff32bfb9 |
| repr-digest | sha-256=:/SL2RbPm75f1GzRyDLuUqNK5NiuRmOk0D1/3Kf8yv7k=: ← matches the body shown |
| signature-input | sig1=("@authority";req "@path";req "repr-digest" "content-type");created=1795182062;expires=1795185662;keyid="1hHmE3fo1rg5Ig70wuFtJ5wBc7G-sUTgUJkxyPWFRps";alg="ed25519";nonce="cX_An51-We2SyFfMQB8GZQ";tag="crawlcheck-page" |
| signature | sig1=:DKJGUl8q3rt3jzwU5IgVCCGu3ppK1Ujx10JWwRJW+r1W49TN4i+DN3nu1UPievRNmCefcrLSQbqp46ztqNiTBw==: |
| verified | yes — signature by key 1hHmE3fo1rg5Ig70… from https://crawlcheck.io/.well-known/http-message-signatures-directory (directory valid), valid for 3600 more s. Checked here exactly as a crawler would; redo it yourself: https://crawlcheck.io/api/tool/wba |
Guides · 2026-09-30 · By [VSNARY | Emmanuel Orta](/author) · 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. Check your own site free Check my site About a minute. First scan free with your email, nothing installed. On this page - Two headers, one grammar - Step one: write the policy from what the page loads - Step two: ship it as report-only with a working report sink - Step three: read the reports, not the theory - Step four: enforce, and keep report-only beside it - The bug that only affected signed-in visitors - How to check a site from outside - The other directives and headers worth checking A [Content-Security-Policy](/glossary/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](/glossary/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](/trust) and the [security page](/security). ## 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](/blog/our-security-headers-skipped-every-signed-in-session). 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](/glossary/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](/glossary/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](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/Content-Security-Policy/script-src) | | `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](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/Content-Security-Policy/form-action) | | `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](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/Content-Security-Policy) | | `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](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/Content-Security-Policy) | | `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](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/Content-Security-Policy/upgrade-insecure-requests) | | [Subresource Integrity](/glossary/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](https://developer.mozilla.org/en-US/docs/Web/Security/Defenses/Subresource_Integrity) | | `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](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/Permissions-Policy) | | `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](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/Referrer-Policy) | Read live from the same counters the dataset page uses, at the moment this page was served. Bars are scaled to the largest value shown, not to 100%. Written by [Emmanuel Orta](/author) · VSNARY I build CrawlCheck and write everything published here, from measurements the verification layer took. Where a post got something wrong, the correction stays in the post. [Every post, and where I got it wrong →](/author) · [Follow on LinkedIn →](https://www.linkedin.com/in/emmanuelorta) Share this finding: [LinkedIn](https://www.linkedin.com/sharing/share-offsite/?url=https%3A%2F%2Fcrawlcheck.io%2Fguides%2Fcontent-security-policy-rollout-report-only-to-enforced%3Futm_source%3Dlinkedin%26utm_medium%3Dsocial%26utm_campaign%3Dshare)[X](https://twitter.com/intent/tweet?url=https%3A%2F%2Fcrawlcheck.io%2Fguides%2Fcontent-security-policy-rollout-report-only-to-enforced%3Futm_source%3Dx%26utm_medium%3Dsocial%26utm_campaign%3Dshare&text=CSP%20report-only%3A%20how%20to%20roll%20out%20a%20Content-Security-Policy%20without%20breaking%20your%20site)[Email](mailto:?subject=CSP%20report-only%3A%20how%20to%20roll%20out%20a%20Content-Security-Policy%20without%20breaking%20your%20site&body=https%3A%2F%2Fcrawlcheck.io%2Fguides%2Fcontent-security-policy-rollout-report-only-to-enforced)[Follow Emmanuel on LinkedIn](https://www.linkedin.com/in/emmanuelorta) ## 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 [2026-09-16 HTTP status codes for crawlers: what a 200 can hide A 200 can carry a bot challenge and a 403 can be a wall on every path. How to read status codes the way crawlers get them, with cu](/guides/http-status-codes-what-a-crawler-actually-gets)[2026-10-18 How to check if your website supports HTTP/3 A site advertises HTTP/3 in its Alt-Svc header and its DNS HTTPS record. How to check both, what google.com and others show, and w](/guides/http-3-how-to-check-whether-your-site-offers-it)[2026-10-09 MCP servers that ask for a login: what 1,366 request first Of 1,366 login-gated MCP servers, 597 had a finding: 244 default to every scope including write, 152 publish no metadata, 39 reque](/blog/mcp-servers-that-ask-for-a-login-what-they-request-by-default) 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. [Fix it all — $100](https://buy.stripe.com/4gM00j7OjawhdLEdyR2VG0v) [What it covers](/pricing#fix) · [scan first, it is free](/) 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. [Add to Chrome — free](https://chromewebstore.google.com/detail/plgjengobhbdmbgckiiaaflgiepdbcpi?utm_source=crawlcheck.io&utm_medium=post) [What it does](/extension) 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. [Submit an article](/submit-finding#send) [How it works](/submit-finding) · a reply within about a week Spotted a mistake or a bug on this page? [Report an error](/report-error?k=article). Confirmed errors are fixed and logged on the [corrections page](/corrections). ## 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](/api/comment/signed)). Those appear at once, marked *verified*. Send for review Writing about this? [Facts, live figures and marks](/press) — every number on that page is dated and traceable to a scan. [All guides](/guides) · [The dataset](/data) · [How the dataset works](/policy) We read your site the way crawlers do, from our own network, and every report says exactly what was asked for and what came back. [Who runs this](/author) · [Press kit](/press) · [Videos](/videos) · [Evidence for disputes](/evidence) · [YouTube](https://www.youtube.com/@crawlcheck) · [hello@crawlcheck.io](mailto:hello@crawlcheck.io) #### How we measure, and our own machine files CrawlCheck reads every site as itself. Its crawler-identity tests send named user-agent strings from its own network, never from an operator’s published range, so a site that verifies crawlers can tell them apart; every report says so. Results reflect what an anonymous non-browser client receives. [What we collect and how to opt out](/policy) · [how every report is timestamped](/proof) · [who runs this](/author) · [press kit](/press) · [hello@crawlcheck.io](mailto:hello@crawlcheck.io). **Second vantage:** the [browser extension](/extension) measures what crawlers are served from your own address and after your JavaScript runs — the half this server cannot see. From 1.0.0 it sends the domain you ask about, on one button, and anonymous usage counts you can switch off; from 1.0.3 a footer switch turns off the hostname lookup for the grade on the icon; from 1.0.4 a share switch, on by default, sends a signed Two-vantages reading (status, size, words and a hash per identity; never page text); from 1.0.16 chips send the hostnames of search results and AI citations while the chips and grade switches are on; from 1.0.17 a readings switch, on by default, sends one signed page reading a day (numbers, the hostname and the page address with the query removed; never in incognito; at most 40 a day) and only while the share and grade switches are also on. Earlier versions send nothing. **Our own machine layer for the agentic web:** [llms.txt](/llms.txt) · [llms-full.txt](/llms-full.txt) · [agents.md](/agents.md) · [SKILL.md](/SKILL.md) · [entitymap.json](/entitymap.json) · [media kit](/.well-known/media-kit.json) · [MCP server card](/.well-known/mcp/server-card.json) · [API catalog](/.well-known/api-catalog) · [OpenAPI](/openapi.json) · [robots.txt](/robots.txt) · [sitemap.xml](/sitemap.xml) · [security.txt](/.well-known/security.txt) — every one named in robots.txt, which is exactly what we check for on yours. **Registry:** [MCP: Operator](/registry/mcp/operator) · [MCP](/registry/mcp) · [AI policy](/registry/aipolicy) · [auxologico.it](/registry/auxologico.it) · [deobeautyusa.com](/registry/deobeautyusa.com) · [hustonchevrolet.com](/registry/hustonchevrolet.com) · [newsisout.com](/registry/newsisout.com) · [triplinkintl.com](/registry/triplinkintl.com) · [Place: Boston](/registry/place/ma/boston) | **Pages:** [IP ranges](/data/ip-ranges) | **Datasets:** [Iowa](/datasets/state/iowa) · [Technologies: Vue](/datasets/technologies/vue) [Contact](/contact) · [Partnerships](/partnerships) · [Terms of service](/terms) · [Refund policy](/refunds) · [Trust center](/trust) · [Subprocessors](/subprocessors) · [Changelog](/changelog) · [Report an error](/report-error)
Same body as a file: /guides/content-security-policy-rollout-report-only-to-enforced.md · as data: /feed.json · what we tell agents site-wide: /llms.txt, /agents.md. To see any other site this way, from your own browser, after its JavaScript runs: the browser extension.