Content-Security-Policy-Report-Only

The HTTP Content-Security-Policy-Report-Only response header applies a Content Security Policy in observation mode, generating violation reports without blocking any resources.

Usage

The Content-Security-Policy-Report-Only header accepts the same directives as Content-Security-Policy (CSP) but does not enforce them. When a resource or behavior violates the declared policy, the browser generates a violation report and sends the report to the endpoint specified in the report-to directive. The resource loads normally.

This report-only approach allows operators to measure the impact of a CSP policy before committing to enforcement. A new policy deployed directly in the enforcing header risks breaking legitimate page functionality. Deploying the same policy in Content-Security-Policy-Report-Only first reveals which resources and inline scripts trigger violations, giving time to adjust the policy or update the page before switching to enforcement.

Both headers are active simultaneously when present in the same response. The enforcing header blocks violations. The report-only header monitors a stricter or experimental policy alongside the enforcing one. This allows progressive tightening of the security policy.

Content-Security-Policy: script-src 'self'
Content-Security-Policy-Report-Only: script-src 'self';
  report-to csp
Reporting-Endpoints: csp="https://reports.example.re/csp"

The report-to directive names the reporting endpoint group. The endpoint URL is declared in the Reporting-Endpoints response header. The legacy report-uri directive sends reports directly to a URL and is still supported but deprecated in favor of report-to.

Directives

All directives defined for Content-Security-Policy are valid in Content-Security-Policy-Report-Only. Fetch directives (script-src, style-src, img-src, connect-src, font-src, media-src, object-src, frame-src, child-src, worker-src), document directives (base-uri), navigation directives (form-action, frame-ancestors), and reporting directives (report-to, report-uri) all function identically in report-only mode, producing reports instead of blocking.

report-to

The report-to directive specifies the reporting endpoint group name receiving CSP violation reports. The name maps to a URL declared in the Reporting-Endpoints response header. This is the modern replacement for report-uri.

report-uri

The report-uri directive specifies a URL receiving CSP violation reports directly. Deprecated in favor of report-to. When both report-to and report-uri are present, report-to takes precedence in browsers supporting the Reporting API.

Violation reports

The browser sends violation reports as JSON to the designated endpoint. Each report contains fields describing the violation.

• document-uri: the URL of the document where the violation occurred.
• blocked-uri: the URL of the resource blocked by the policy. Cross-origin URIs are truncated to scheme, host, and port.
• violated-directive: the name of the policy directive violated.
• effective-directive: the directive whose enforcement led to the violation.
• original-policy: the full policy string as declared in the header.
• disposition: either report for report-only mode or enforce for the enforcing header.
• status-code: the HTTP status code of the document.
• script-sample: the first 40 characters of the inline script or event handler causing the violation.
• referrer: the referrer of the document.

{
  "csp-report": {
    "document-uri": "https://example.re/page",
    "blocked-uri": "https://ads.example.re/track.js",
    "violated-directive": "script-src",
    "effective-directive": "script-src",
    "original-policy": "script-src 'self'; report-uri /csp",
    "disposition": "report",
    "status-code": 200
  }
}

Example

A report-only policy monitoring script sources. The browser reports any script loaded from outside the current origin but does not block the script.

Content-Security-Policy-Report-Only: script-src 'self';
  report-to csp
Reporting-Endpoints: csp="https://reports.example.re/csp"

A stricter report-only policy running alongside an enforcing policy. The enforcing header allows scripts from the current origin and a CDN. The report-only header tests a tighter policy removing the CDN to see how many violations occur before committing.

Content-Security-Policy: script-src 'self'
  https://cdn.example.re
Content-Security-Policy-Report-Only: script-src 'self';
  report-to csp-strict
Reporting-Endpoints:
  csp-strict="https://reports.example.re/strict"

A report-only policy using the legacy report-uri directive. The browser sends violation reports to the specified URL as a POST request with a JSON body.

Content-Security-Policy-Report-Only: default-src 'self';
  report-uri /csp-reports

Takeaway

The Content-Security-Policy-Report-Only header monitors a CSP policy without enforcement, sending violation reports to a designated endpoint. This enables safe testing and progressive rollout of content security policies alongside the enforcing Content-Security-Policy header.

See also

• Content Security Policy Level 3 (W3C)
• Content-Security-Policy
• Reporting-Endpoints
• Report-To
• HTTP headers