CSP: Testing your policy instructions improvement

[Radhikarathi04]

MDN URL

https://developer.mozilla.org/en-US/docs/Web/HTTP/Guides/CSP

What specific section or headline is this issue about?

Testing your policy

What information was incorrect, unhelpful, or incomplete?

The "Testing your policy" section explains the mechanics of
Content-Security-Policy-Report-Only — how to set the header, that both
headers are honoured when sent together, and that report-only cannot be
delivered via <meta>.

It doesn't cover the deployment process that report-only mode exists to
support. In practice, the hard part of adopting CSP on an existing site
isn't writing the header; it's interpreting what comes back and deciding
when it's safe to enforce.

In particular the guide doesn't mention that a large share of violation
reports on a real site are not caused by the site's own resources.
Browser extensions, injected third-party scripts, and intermediaries such
as CDNs and proxies (which may add to or rewrite the CSP header in transit)
all generate reports. Without knowing this, a reader's reasonable
conclusion from a noisy report endpoint is that their policy is wrong.

What did you expect to see?

A short subsection under "Testing your policy" covering the rollout path
from report-only to enforcement. Something like:

• Why to run report-only for a period before enforcing, and what you're
  looking for during it
• Common sources of violation reports that are not policy failures:
  browser extensions, third-party embeds, and CDNs or proxies that modify
  the CSP header in transit
• How to distinguish those from genuine violations, using the fields in
  the violation report
• Iterating on the policy while still in report-only
• What to check before switching to the enforced header
• Handling third-party embeds that need ongoing directive exceptions

Do you have any supporting links, references, or citations?

• Content-Security-Policy-Report-Only:
  https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/Content-Security-Policy-Report-Only
• CSPViolationReportBody:
  https://developer.mozilla.org/en-US/docs/Web/API/CSPViolationReportBody
• CSP Level 3 § reporting: https://w3c.github.io/webappsec-csp/#reporting

Do you have anything more you want to share?

Happy to draft this if it's in scope. I've deployed CSP on a large
production site, including the report-only period, triaging the report
volume, and the move to enforcement, so I can write it from experience
rather than theory.

Understood if the guide is meant to stay reference-focused and this
belongs elsewhere.

[hamishwillee]

@Radhikarathi04 Thanks very much.

Yes, the docs are very much descriptive of the mechanics of setting up testing.
Yes they are hand wavy around the practical problems you might run into: probably because the authors (i.e. me and people like me) haven't had to do a large scale deployment.

IMO such docs are very much in-scope and welcome.

It is hard to say exactly how this should integrate without knowing what/how would be written. I propose a PR to add Testing a CSP Guide below https://developer.mozilla.org/en-US/docs/Web/HTTP/Guides/CSP.
Once written we could then decide how much to pull out of the parent document or whether to add highlights from it.

I've assigned you to this task.

[Radhikarathi04]

@hamishwillee Thanks, that's really helpful, and I'm happy to take it on.

I'll draft Web/HTTP/Guides/CSP/Testing covering the practical side: starting in report-only mode, setting up reporting endpoints, separating genuine violations from noise, staging a rollout, and the signals that tell you it's safe to enforce. I'll also cover constraints that only show up at scale, such as header size limits and CDN behaviour.

I'll keep it self-contained for the first pass so we can decide afterwards what's worth pulling out of the parent page. I'll open a PR with an outline first if that's easier to review than a finished draft.