Understanding the Content-Security-Policy-Report-Only Header

Key Benefit: Test CSP rules without breaking your site by monitoring violations while allowing all content to load.

Security-conscious organizations recognize the critical role that HTTP response headers play in safeguarding websites and applications. Among these, Content-Security-Policy-Report-Only stands out as a powerful tool for monitoring how well your site adheres to Content Security Policy (CSP) rules—without actually blocking any content that violates them.

What Is Content-Security-Policy-Report-Only?

Content-Security-Policy-Report-Only is an HTTP response header designed to test and track potential CSP violations in a live environment. Unlike the standard Content-Security-Policy header—which actively blocks resources that do not meet the specified policy—this header only logs violations.

Identify Issues

Identify places where your site loads resources from unexpected origins.

Safe Testing

Test new or evolving CSP directives without risking breakage on production environments.

Security Insights

Gather insights into possible cross-site scripting (XSS) or injection threats.

How It Works

Monitoring Without Enforcement

When you configure Content-Security-Policy-Report-Only, the browser checks each loaded resource against your declared CSP rules. If anything is disallowed by these rules, the browser will generate a report but will not block the content from being rendered.

report-to

Modern directive that indicates the endpoint name that receives violation reports using the Reporting API.

report-uri

Legacy directive that points directly to a reporting URL (still widely supported).

Server Implementation

<IfModule mod_headers.c>
    Header set Reporting-Endpoints "csp-endpoint=\"https://example.com/csp-reports\""
    Header set Content-Security-Policy-Report-Only "default-src 'self'; report-to csp-endpoint"
</IfModule>

server {
    add_header Reporting-Endpoints "csp-endpoint=\"https://example.com/csp-reports\"";
    add_header Content-Security-Policy-Report-Only "default-src 'self'; report-to csp-endpoint";
}

<configuration>
  <system.webServer>
    <httpProtocol>
      <customHeaders>
        <add name="Reporting-Endpoints" 
             value="csp-endpoint="https://example.com/csp-reports"" />
        <add name="Content-Security-Policy-Report-Only" 
             value="default-src 'self'; report-to csp-endpoint" />
      </customHeaders>
    </httpProtocol>
  </system.webServer>
</configuration>

Implementation Guidelines

Define a Basic Policy:
Identify which sources are permitted for scripts, styles, images, etc.
Choose a Reporting Method:
Decide between report-to or report-uri directives (or use both for compatibility).
Set Up an Endpoint:
Configure the Reporting-Endpoints header to map endpoint names to URLs.
Monitor and Adjust:
Review violation logs and refine your policy based on findings.

Additional Resources

MDN Web Docs

Complete documentation on Content-Security-Policy-Report-Only header

W3C CSP Specification

Official Content Security Policy Level 3 specification

Report URI

CSP violation reporting and monitoring service

web.dev CSP Guide

Google's comprehensive guide to Content Security Policy

Related Security Headers

Learn about other HTTP security headers to strengthen your website's security: