Rolling Out a Script Policy in Report-Only Mode

Part of Unified Script Policy Architecture, this page covers how to get a strict script policy into production without a breakage window: two headers on every response, a staged sequence with written exit criteria, and a rollback lever you can pull in seconds.

Quick Reference

Rollout order: report-only wide, triage, tighten, enforce on a canary, enforce everywhere.

The mental model: two policies, one page load

A response may carry both header fields at once, and they are evaluated independently. Every policy listed in Content-Security-Policy is enforced — a violation blocks the load or the sink write and emits a report. Every policy listed in Content-Security-Policy-Report-Only is monitored — a violation changes nothing about page behaviour and emits a report. The two streams are distinguishable at the collector because each report carries a disposition field whose value is enforce or report.

That gives you a safe way to run an experiment in production. The enforcing header keeps whatever guarantees you already ship, typically a loose policy inherited from an earlier project. The report-only header carries the policy you actually want: nonce-based script-src with 'strict-dynamic', no 'unsafe-inline', no wildcard hosts, object-src 'none', base-uri 'none', and Trusted Types on top. Real users, on real devices, with real extensions installed, tell you exactly which of those rules would have broken the site. You are not guessing from a staging environment that nobody visits with a password manager installed.

The trap is treating the report-only header as a permanent fixture. A policy that reports for eighteen months protects nobody. The discipline that makes this work is committing, up front, to a fixed number of stages, each with an exit criterion written down before the stage starts, and keeping the report-only header always one notch stricter than the enforcing one so there is a candidate policy in flight at all times.

Canonical example: both headers on one response

This Express middleware emits the enforcing policy, the candidate report-only policy, and the Reporting-Endpoints header that both refer to. The per-request nonce is generated once and reused in both policies and in the templates, which is the pattern described in Generating Per-Request CSP Nonces.

// middleware/script-policy.js
import { randomBytes } from 'node:crypto';

const REPORT_HOST = 'https://reports.example.com';

// Flip these two constants to move a stage forward or to roll back.
const ENFORCED_STAGE = 'legacy';   // 'legacy' | 'strict'
const CANARY_PERCENT = 0;          // 0-100, share of traffic enforcing 'strict'

const legacyPolicy = (nonce) => [
  "default-src 'self'",
  `script-src 'self' 'unsafe-inline' https://cdn.example.com`,
  "object-src 'none'",
  'report-uri /csp/enforce',
  'report-to csp-enforce',
].join('; ');

const strictPolicy = (nonce) => [
  "default-src 'self'",
  `script-src 'nonce-${nonce}' 'strict-dynamic' https:`,
  "object-src 'none'",
  "base-uri 'none'",
  "frame-ancestors 'none'",
  "require-trusted-types-for 'script'",
  'trusted-types default dompurify',
].join('; ');

export function scriptPolicy(req, res, next) {
  const nonce = randomBytes(16).toString('base64');
  res.locals.nonce = nonce;

  const enforceStrict =
    ENFORCED_STAGE === 'strict' ||
    (CANARY_PERCENT > 0 && hashBucket(req) < CANARY_PERCENT);

  res.setHeader(
    'Reporting-Endpoints',
    `csp-enforce="${REPORT_HOST}/csp/enforce", ` +
      `csp-report-only="${REPORT_HOST}/csp/report-only"`,
  );

  const enforced = enforceStrict
    ? `${strictPolicy(nonce)}; report-uri /csp/enforce; report-to csp-enforce`
    : legacyPolicy(nonce);
  res.setHeader('Content-Security-Policy', enforced);

  // Always keep a candidate one notch ahead of what is enforced.
  if (!enforceStrict) {
    res.setHeader(
      'Content-Security-Policy-Report-Only',
      `${strictPolicy(nonce)}; report-uri /csp/report-only; report-to csp-report-only`,
    );
  }

  next();
}

function hashBucket(req) {
  const id = req.cookies?.visitor_id ?? req.ip ?? '';
  let h = 0;
  for (let i = 0; i < id.length; i += 1) h = (h * 31 + id.charCodeAt(i)) % 100;
  return h;
}

On the wire, a mid-rollout response looks like this. Both header fields are present, each names its own endpoint, and each carries its own report-uri fallback for browsers that do not implement the Reporting API.

HTTP/2 200
content-type: text/html; charset=utf-8
reporting-endpoints: csp-enforce="https://reports.example.com/csp/enforce", csp-report-only="https://reports.example.com/csp/report-only"
content-security-policy: default-src 'self'; script-src 'self' 'unsafe-inline' https://cdn.example.com; object-src 'none'; report-uri /csp/enforce; report-to csp-enforce
content-security-policy-report-only: default-src 'self'; script-src 'nonce-r4Kd9vQm2Xp7' 'strict-dynamic' https:; object-src 'none'; base-uri 'none'; frame-ancestors 'none'; require-trusted-types-for 'script'; trusted-types default dompurify; report-uri /csp/report-only; report-to csp-report-only

The markup the strict policy is designed to accept keeps its nonce, and any third-party script keeps both an integrity attribute and the crossorigin attribute that makes the integrity check possible:

<script nonce="r4Kd9vQm2Xp7"
        src="https://cdn.example.com/app.9f2c.js"
        integrity="sha384-oqVuAfXRKap7fdgcCY5uykM6+R9GqQ8K/uxy9rx7HNQlGYl1kPzQho1wx4JwY8wC"
        crossorigin="anonymous"></script>

The staged sequence

Five stages, in order, each ending on a written criterion rather than on a calendar date. The point of the sequence is that every stage removes one class of unknown before the next stage takes a risk.

The stage table below is the version to paste into a rollout ticket. Durations are typical for a site with a weekly release train; substitute your own cycle length, but keep the ordering and keep the exit criteria as evidence rather than dates.

Stage 3 is where most of the calendar goes, and that is correct. Each fix — a moved inline handler, a removed eval, a third-party tag replaced with a self-hosted copy — is a code change that has to ship through your normal release process. Narrow the report-only policy only after the fix is live, never in the same deploy, so a regression is attributable.

Triaging the report stream

The first day of stage 1 will produce more reports than the rest of the rollout combined, and the overwhelming majority are worthless. Browser extensions inject scripts and inline styles into every page they touch, and those injections violate your policy exactly as a real attacker’s would. Ad blockers, password managers, translation add-ons, coupon tools, accessibility overlays and enterprise device agents all show up. You cannot fix any of them from the server, so the only correct action is to identify them and drop them before they reach a dashboard.

The reliable discriminator is the scheme in sourceFile and blockedURL: chrome-extension:, moz-extension: and safari-web-extension: are unambiguous. After that filter, a second, larger class remains — inline event handlers such as onclick baked into legacy server-rendered templates. These are genuine first-party violations, they report with effectiveDirective set to script-src-attr, and clearing them is the substance of stage 3. The mechanics of moving them out of markup are covered in Migrating from unsafe-inline to Hash-Based CSP.

Once reports are landing in a table, triage is a grouping query rather than a reading exercise. This one collapses a week of raw rows into the short list of distinct problems worth assigning, with the extension noise excluded and the report-only stream separated from the enforcing stream:

SELECT
  effective_directive,
  COALESCE(NULLIF(blocked_url, ''), 'inline') AS blocked,
  regexp_replace(source_file, '\?.*$', '')     AS source,
  substr(sample, 1, 40)                        AS first_sample,
  count(*)                                     AS hits,
  count(DISTINCT session_id)                   AS sessions
FROM csp_reports
WHERE received_at > now() - interval '7 days'
  AND disposition = 'report'
  AND source_file NOT LIKE 'chrome-extension:%'
  AND source_file NOT LIKE 'moz-extension:%'
  AND source_file NOT LIKE 'safari-web-extension:%'
  AND blocked_url NOT LIKE '%-extension:%'
GROUP BY 1, 2, 3, 4
HAVING count(DISTINCT session_id) > 5
ORDER BY sessions DESC
LIMIT 50;

The count(DISTINCT session_id) column is what makes the output actionable. A violation seen five thousand times in six sessions is one user with an unusual extension; a violation seen six hundred times across six hundred sessions is a template you ship. Sorting by sessions rather than raw hits puts the real work at the top. Details of endpoint schema, retention and ingest belong to Collecting CSP Violation Reports with the Reporting API.

Variants

Trusted Types in report-only mode

Trusted Types has no separate report-only header of its own — it rides the same Content-Security-Policy-Report-Only field. Put require-trusted-types-for 'script' there and every assignment to a guarded DOM sink produces a report while still executing normally, so a legacy innerHTML call keeps working during the observation window. Reports arrive with effectiveDirective set to require-trusted-types-for, blockedURL set to trusted-types-sink, and sample set to the sink name followed by the first forty characters of the assigned value, which is usually enough to locate the call site. Adding the trusted-types directive additionally reports every attempt to create a policy whose name is not on the list, which is how you discover that a vendor bundle quietly creates its own. Enforcement details are in Enforcing require-trusted-types-for script, and the sanitizer policy those sinks route through is covered in Writing a Trusted Types Policy with DOMPurify.

Static origins with nginx

If a nonce is not available because the HTML is static, run the report-only stage with a hash-based or host-based policy instead. The dual-header pattern is identical:

map $rollout_enforce $strict_enforced {
    default "";
    "1"     "default-src 'self'; script-src 'self'; object-src 'none'; base-uri 'none'; report-uri /csp/enforce";
}

add_header Reporting-Endpoints 'csp-report-only="https://reports.example.com/csp/report-only"' always;
add_header Content-Security-Policy-Report-Only "default-src 'self'; script-src 'self'; object-src 'none'; base-uri 'none'; require-trusted-types-for 'script'; report-uri /csp/report-only; report-to csp-report-only" always;

Remember that add_header in nginx is not inherited into a location block that defines its own add_header directives — repeat them or use include to avoid losing the policy on a subset of routes.

The rollback lever

The rollback lever must not be a deploy. Keep the enforcing policy behind a runtime flag read on every request — the ENFORCED_STAGE and CANARY_PERCENT constants above become a config lookup — so an on-call engineer can move all traffic back to the legacy policy in one edit. Two things make this fail in practice: HTML cached at the CDN with the strict header baked in, and a service worker serving a cached HTML shell. Verify before stage 4 that your HTML responses carry Cache-Control: no-store or private, or that a purge is part of the documented rollback runbook, and confirm the rollback path end to end with a curl check rather than assuming it.

Gotchas and Edge Cases

• Chrome ignores report-uri when report-to is present. Per CSP Level 3, a user agent that supports report-to must ignore report-uri in the same policy. Chromium honours this, so the moment you add report-to your legacy collector stops receiving Chrome traffic while Firefox and Safari keep using report-uri. Keep both directives, but make the collector accept both application/csp-report and application/reports+json, and never compute a browser-share metric from a single format.

• A report-to endpoint name with no Reporting-Endpoints entry fails silently. There is no console warning and no fallback. A typo, or the Reporting-Endpoints header being stripped by a proxy, produces the same symptom as a working rollout with zero violations, which is the most dangerous failure mode this process has. Stage 1’s exit criterion exists precisely to rule it out — you must see a deliberately triggered report arrive before you trust an empty dashboard.

• Two Content-Security-Policy headers both enforce. If a framework and a reverse proxy each add one, the browser applies both, and the effective result is their intersection — the strictest of each directive wins. That is a common way to accidentally enforce a policy you believed was report-only. Check with curl -I at the edge, not in local development.

• An integrity attribute without crossorigin="anonymous" blocks the load outright. A cross-origin script with integrity but no crossorigin attribute is fetched in no-cors mode, yielding an opaque response the browser cannot hash, so it fails the integrity check and never executes. During a report-only rollout this looks like a policy regression but is entirely independent of CSP: no report is emitted, only a console error. Add crossorigin="anonymous" to every tag that carries integrity, and make sure the origin serves Access-Control-Allow-Origin.

• Cross-origin report endpoints need a CORS preflight. Reporting API deliveries are POST requests with Content-Type: application/reports+json, which is not a simple content type, so a collector on a different origin must answer the OPTIONS preflight with Access-Control-Allow-Origin and Access-Control-Allow-Headers: Content-Type. Same-origin paths such as /csp/report-only avoid the problem entirely and are the safer default.

• Report bodies are deliberately lossy. Cross-origin blockedURL values are truncated to the origin, sample is capped at forty characters, and browsers deduplicate identical reports within a document. Do not build a rollout gate that requires reproducing an exact URL or a full script body from a report; use the report to identify a class of problem and reproduce it locally.

Verification Steps

1. Confirm both headers reach the browser

curl -sI https://www.example.com/ | grep -i -E 'content-security-policy|reporting-endpoints'

Expected output during stages 1-3: three lines — a content-security-policy, a content-security-policy-report-only, and a reporting-endpoints line whose endpoint names exactly match the names used in both report-to directives.

2. Force a violation and confirm the report lands

Load a page and run this in the console. It triggers the report-only policy without changing anything a user sees:

// Violates script-src in the report-only policy; nothing is blocked.
document.head.appendChild(
  Object.assign(document.createElement('script'), {
    src: 'https://example.invalid/probe.js',
  }),
);

Then check the collector. Reporting API deliveries are batched and can lag by up to a minute, so poll rather than expecting an instant row:

curl -s "https://reports.example.com/api/recent?minutes=5" | jq '.[] | {disposition: .body.disposition, directive: .body.effectiveDirective, blocked: .body.blockedURL}'

Expected output:

{
  "disposition": "report",
  "directive": "script-src-elem",
  "blocked": "https://example.invalid"
}

A disposition of report proves the report-only header is the one that fired. If you see enforce, the strict policy is already in the enforcing header and you are further along the rollout than you thought.

3. Check the first-party violation count before promoting

psql -qtAX -d telemetry -c "SELECT count(DISTINCT session_id) FROM csp_reports WHERE received_at > now() - interval '7 days' AND disposition = 'report' AND source_file NOT LIKE '%-extension:%'"

Expected output for a stage-3 exit: 0. Any non-zero value names sessions where the candidate policy would have broken the page, so the stage continues.

4. Prove the rollback lever works

# Flip the runtime flag back to the legacy policy, then re-check the edge.
curl -sI https://www.example.com/ | grep -ci "unsafe-inline"

Expected output: 1, within one cache TTL of the flag change. If it stays 0, your HTML is cached with the strict header and rollback requires a purge — fix that before stage 4, not during an incident. Once the full policy is enforced everywhere, keep the pipeline pointed forward: the same report stream drives Auditing a Script Policy for Gaps, and the layered design the candidate policy is converging on is described in Layering CSP Nonces, SRI and Trusted Types.

Frequently Asked Questions

Related

• Deploying Defense-in-Depth Script Controls — how the enforcing policy this rollout lands fits with integrity checks and sanitizers
• Alerting on SRI Failures from CSP Reports — turning the collected report stream into paging alerts once the rollout is finished
• Combining require-sri-for with CSP — where the require-sri-for directive stands and what to use instead today