CSP: Testing your policy instructions improvement
- Dominant language
- Markdown
- Stars
- 11k
- Forks
- 23.2k
- Avg merge
- 2d 9h
- Merged PRs (30d)
- 331
Description
### 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 ``.
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.
Contributor guide
Assessment
This issue has not been assessed yet.