How to Use the Content-Security-Policy-Report-Only Header

CSP report-only deployment and validation checklist

Use this sequence to turn a candidate header and its CSP violation reports into reviewable evidence. A quiet collector is not a pass unless reporting itself and the required application states were tested.

1. Define the pages, roles, consent states, actions, and supported browsers in the test matrix.
2. Capture the exact final response headers, including duplicate report-only or enforced policies added by the application, proxy, CDN, or host.
3. Connect a bounded collector you control, version the candidate policy, and trigger one deliberate violation to prove the reporting path works.
4. Exercise representative success, failure, login, checkout, upload, and third-party integration flows; reproduce each relevant signal before changing policy.
5. Classify each signal, make the narrowest justified code or directive change, and retest both required flows and negative controls in a clean browser profile.
6. Move to bounded enforcement only when the tested coverage is documented, required-flow violations are understood, and rollback is ready; keep monitoring after release.

What is a CSP report, and how do I interpret it?

A CSP report describes an action that violated a page's Content Security Policy. It can identify the page, the applicable directive, the blocked source, and whether the policy was reporting or enforcing. A report is a lead to investigate, not proof of an attack or a reason to allow the reported source.

1. Identify the format: modern reports use an array of entries with type: "csp-violation" and a body; legacy reports use a csp-report object. Field names differ between these formats.
2. Match the page and policy: compare documentURL / document-uri and originalPolicy / original-policy with the response you are testing. Delayed reports may describe an older policy.
3. Read the disposition: report identifies report-only evaluation; enforce identifies an enforcing policy. Do not infer which policy fired only from whether the page appeared to work.
4. Locate the restriction: read effectiveDirective / effective-directive and blockedURL / blocked-uri. For example, script-src-elem with inline points to an inline script element; it is not a domain to add to an allowlist.
5. Reproduce and decide: trace the signal to owned code or a required dependency in a clean browser profile. Fix unnecessary code or apply the narrowest justified policy change, then retest the flow and a deliberate violation.

For the inline-script case, the controlled walkthrough demonstrates moving the statement into a same-origin script file. Other cases may need a nonce or exact hash. Avoid adding 'unsafe-inline' simply to silence reports.

Treat received fields as untrusted input, and do not interpret missing reports as proof of safety. This guide explains report interpretation and collection; Script Sentinel does not offer a hosted public CSP report collector.

Trace one inline-script violation from detection to correction

Scope: This is a controlled teaching lab, not a customer result. Run it only on a staging origin you control. The same-origin /csp-report path represents a bounded collector you operate; Script Sentinel does not host that endpoint.

Observed lab result: In a clean headless Chrome 152.0.7977.64 loopback run, the starting statement executed and produced both a matching violation event and collector POST. After the same statement moved to /static/lab.js under the unchanged header, it executed without that matching inline event or POST during a 500 ms post-load observation within a 2.5-second virtual-time run. This validates the minimal fixture, not other browsers or application flows.

1. Configure the staging server to send the lab response header below on /lab.html, save the starting HTML as that file, and make POST /csp-report return a small success response after bounded processing.
2. Open /lab.html in a clean browser profile. Lab script ran confirms that the statement executed; that page result alone does not prove the browser received the header or emitted a report.
3. Confirm a matching console message, securitypolicyviolation event, or collector request with the field values documented below. Execution plus that matching signal shows the report-only policy observed the statement without blocking it.
4. Verify that the inline code is owned and required, replace /lab.html with the corrected HTML, save the moved statement as /static/lab.js, and repeat the test. Then temporarily restore the starting /lab.html; the matching inline signal must return before you count the quiet corrected pass as meaningful.

How the observed violation becomes a policy decision

For this starting file, use only the matching observation: disposition = report, effectiveDirective / effective-directive = script-src-elem, blockedURL / blockedURI / blocked-uri = inline, and originalPolicy / original-policy matching the exact policy value in the lab response header.

This closes one reproduced finding only. If externalizing is impractical, evaluate a per-response nonce or an exact hash. Do not add 'unsafe-inline' reflexively, and do not treat this lab as proof that untested routes, states, or browsers are ready for enforcement.

Treat every CSP report as attacker-controlled input

This is design guidance for a collector you operate. Script Sentinel does not currently provide a hosted public CSP violation collector.

Privacy and retention

Report URLs, referrers, source locations, policy text, and code samples can expose account paths, query tokens, personal data, or application details. Collect only what the review workflow needs.

• Strip URL user information, query strings, and fragments unless a documented use case requires a safer derived value.
• Redact or omit code samples and other high-risk fields before storage, logging, analytics, or alert delivery.
• Restrict access to stored reports, define a short retention window, aggregate older data when useful, and delete expired raw records.
• Document the collector, processors, retention period, and deletion path in the applicable privacy notice.

For protocol details, consult the W3C Content Security Policy reporting specification and Reporting API specification.

Why am I not receiving useful CSP reports?

Debug the delivery path, active headers, browser behavior, collector response, and exercised application state separately. A quiet collector is not proof that an enforced policy is ready.

Reporting API delivery can be delayed, batched, rate-limited, disabled, or dropped. During the compatibility period, accept both report media types and use deprecated report-uri alongside report-to when your browser support requirements justify it.