mdn / mdn/content

CSP: Testing your policy instructions improvement

Open
#45,262 2 comments 0 reactions 1 assignee Claimed by @Radhikarathi04 View on GitHub
Content:HTTP Content:WebAPI
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

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.