Content-Security-Policy: the browser-enforced second line

The xss unit was about keeping attacker text out of HTML and script sinks. Content-Security-Policy (CSP) is the second line: a response header that tells the browser which scripts, styles, images and connections this page is allowed to use. If an injected payload slips through, the browser refuses to run it. MDN calls it "a backup in case the other defenses fail" — the server still sends the bad HTML; the browser just won't execute what the policy doesn't allow.

A policy is a list of directives separated by semicolons. Each directive is a name followed by the sources it allows:

Content-Security-Policy: default-src 'self'; script-src 'self' 'nonce-r4nd0m' https://js.stripe.com; object-src 'none'; base-uri 'none'; frame-ancestors 'none'

Two spelling rules: keywords are quoted ('self', 'none', 'nonce-…'), and hosts and schemes are not (https://js.stripe.com, https:). self without quotes would mean a host called "self".

What this buys you against XSS: once a policy has script-src (or default-src) without 'unsafe-inline', the browser blocks inline <script> blocks that don't carry the nonce, inline event handlers like onerror="…" and onclick="…", and javascript: URLs; eval() and its relatives are blocked too. The <img src=x onerror=…> payload from the previous unit lands in the page and does nothing.

A plain Node server that sends a nonce-based policy. Run it and request the page twice: the two responses carry different nonces.

import { createServer } from "node:http";
import { randomBytes } from "node:crypto";

createServer((req, res) => {
  const nonce = randomBytes(16).toString("base64"); // 128 bits, fresh for this response
  const csp = [
    `script-src 'nonce-${nonce}' 'strict-dynamic'`,
    "object-src 'none'",
    "base-uri 'none'",
  ].join("; ");

  res.setHeader("Content-Security-Policy", csp);
  res.setHeader("Content-Type", "text/html; charset=utf-8");
  res.end(`<!doctype html><script nonce="${nonce}" src="/app.js"></script>`);
}).listen(3000);

$ curl -si localhost:3000 | grep -i content-security-policy
Content-Security-Policy: script-src 'nonce-bfiayeQQooD+DrlcufrbdA==' 'strict-dynamic'; object-src 'none'; base-uri 'none'
$ curl -si localhost:3000 | grep -i content-security-policy
Content-Security-Policy: script-src 'nonce-DFsSSeZaNYL/9GSWRxdKMg==' 'strict-dynamic'; object-src 'none'; base-uri 'none'

Why each piece is there:

• randomBytes(16) inside the handler. The nonce is a per-response secret. Generated once at start-up, it would be printed in every page anyone loads — including the attacker's — and they'd simply put it on their injected script. 16 bytes is the spec's recommended 128-bit minimum, from a cryptographically secure source (Math.random() is not one).
• The same nonce in the header and on our tag, and only on tags we wrote. MDN warns against templating that adds the nonce to every <script> in the output: an injected tag would get one too.
• 'strict-dynamic'. app.js is trusted because its tag has the nonce. Scripts it adds with document.createElement("script") inherit that trust, so a bundler's chunk loader or a tag manager works without listing every host. The next reading covers the catch.
• object-src 'none'. Plugin content (<object>, <embed>) is an old route around script restrictions; nothing modern needs it.
• base-uri 'none'. An injected <base href="https://evil.example"> would make the relative /app.js load from the attacker's host — with our valid nonce on the tag. The spec uses exactly this example. base-uri closes it, and it has to be stated explicitly because it doesn't fall back to default-src.

This is a strict CSP. MDN's version is a nonce- or hash-based script-src plus object-src 'none' and base-uri 'none'; the CSP Level 3 draft's version is nonces or hashes with 'strict-dynamic', plus base-uri 'self' or 'none'. Notice what both leave out: a list of allowed hosts. Host allow-lists are, in MDN's words, "hard to get right" and "can be very large and hard to maintain".

An enforced policy that's wrong breaks the site: a blocked analytics loader, a payment iframe that never appears, a chunk that won't load. The way in is to report first, enforce second.

Report-Only. The same policy sent under a different header name is evaluated but not enforced — MDN: "The policy is not enforced, but any violations are sent to the reporting endpoint specified in the policy."

Reporting-Endpoints: csp-endpoint="https://example.com/csp-reports"
Content-Security-Policy-Report-Only: script-src 'nonce-R' 'strict-dynamic'; object-src 'none'; base-uri 'none'; report-to csp-endpoint

Reporting-Endpoints names an endpoint; report-to in the policy points at it. Browsers POST reports as application/reports+json with "type": "csp-violation". The older report-uri directive is deprecated, but MDN advises declaring both until report-to works everywhere — browsers that support report-to ignore report-uri. (MDN's compat data lists report-to support in Firefox only from version 149.)

Both headers can be sent at once, and both are honoured: keep enforcing the policy you trust while the stricter one only reports. Fix or allow each legitimate violation the reports show; when only violations you intend to block are left, move the strict policy to the enforcing header.

More than one policy only ever tightens. If a response carries two enforced CSP headers, a resource must pass both. MDN: adding policies "can only further restrict the capabilities of the protected resource". A CDN or platform that adds its own CSP header on top of yours can block what your policy allows.

The <meta> tag is a partial substitute. The CSP spec: Report-Only isn't supported in a meta element, and "Neither are the report-uri, frame-ancestors, and sandbox directives". A frame-ancestors 'none' in a meta tag protects against nothing.

Test the policy where it actually runs. The most common way to ship a broken policy is to set it only in production:

if (process.env.NODE_ENV === "production") res.setHeader("Content-Security-Policy", csp);

Every page then works in development, because no policy exists there; the inline script someone added last week is only blocked for real users. Frameworks also differ between modes — Next.js's development server needs 'unsafe-eval' (React uses eval for debugging information) while its production build doesn't. Run the policy in development too (adding only what dev genuinely needs), and click through a local production build with the policy on before you ship it.