CSP Explained: Prevent XSS Without Breaking Your Site

Quickstart

If you want a CSP that improves security today without a week of firefighting, follow this sequence. Each step is designed to reduce risk while keeping the blast radius small.

Overview

A Content Security Policy tells the browser where your page is allowed to load code and content from. It’s an allowlist for scripts, styles, images, fonts, frames, and network requests. When you get XSS, the attacker’s goal is usually to run JavaScript that steals tokens, reads DOM data, or sends requests as the user. CSP can prevent those scripts from executing — even if the injection happens — by blocking sources that aren’t explicitly allowed.

CSP isn’t a substitute for fixing XSS (you still must validate/escape and avoid dangerous sinks). Think of it as a powerful “seatbelt” that reduces impact when something slips through.

Core concepts

To roll out a CSP without breaking your site, you need two things: (1) a mental model of what the browser is enforcing, and (2) a safe migration away from “anything goes” behaviors like inline scripts, dynamic code evaluation, and uncontrolled third-party embeds.

What CSP actually does

CSP is a response header (or a <meta http-equiv> tag, less ideal) that the browser reads before executing the page. Each directive is an allowlist. If a resource violates the policy, the browser blocks it (enforcing mode) or reports it (report-only). The most important directive for XSS is script-src.

Nonces vs hashes (and when to use which)

CSP blocks inline scripts by default, which is a good thing: many XSS payloads rely on inline execution. When you must run inline scripts (e.g., a tiny bootstrap snippet), you have two safe options: nonces or hashes.

Report-only vs enforcing mode

Report-only is your safety net: it tells you what would break without actually blocking. You should always start there unless you have a very simple static site with no third-party scripts. When you flip to enforcing mode, you keep a parallel report-only policy for a while to catch regressions.

“CSP is failing” often means connect-src is missing

Modern apps call many endpoints: APIs, telemetry, feature flags, auth, websockets. If your site loads but network requests fail, check connect-src. It controls fetch, XHR, EventSource, and WebSocket connections.

Step-by-step

This section is a rollout plan you can apply to most stacks (Node, Python, Rails, Go, .NET). The key is to treat CSP as a migration: you’re moving from implicit trust (any script can run) to explicit trust (only approved scripts run).

Step 1 — Capture your current resource graph

Before writing a strict policy, learn what your pages actually load. In Chrome/Edge DevTools, open Network and filter by “JS”, “CSS”, and “Fetch/XHR”. You’re looking for domains: your own origin, CDNs, analytics, ads, identity providers, widget embeds.

Step 2 — Add a Report-Only policy (safe baseline)

Start with a policy that is strict enough to be meaningful, but permissive enough that you can roll it out without breaking. A common baseline is default-src 'self' plus explicit allowances for known third-party domains. Don’t add 'unsafe-inline' in script-src unless you’re using report-only only as a discovery phase.

The following example is a production-friendly starting point for many sites. Replace the example domains with your real ones. Keep it in Report-Only first.

# Example: set CSP in report-only mode (reverse proxy / nginx style)
# Replace example domains with your real CDNs/APIs.

add_header Content-Security-Policy-Report-Only "
  default-src 'self';
  base-uri 'self';
  object-src 'none';
  frame-ancestors 'self';
  img-src 'self' data: https:;
  font-src 'self' https: data:;
  style-src 'self' https: 'unsafe-inline';
  script-src 'self' https: 'nonce-$request_id';
  connect-src 'self' https:;
  upgrade-insecure-requests;
  report-to csp-endpoint;
";

# Report-To header defines where reports go (example only).
# You can also use report-uri for legacy collectors.
add_header Report-To '{"group":"csp-endpoint","max_age":10886400,"endpoints":[{"url":"https://example.com/csp-report"}]}' ;

Step 3 — Collect and triage CSP violation reports

CSP reports can be noisy. The trick is to group them by “blocked directive + blocked URI + page”. Fix the highest-impact issues first: inline scripts, unexpected script domains, and missing connect-src entries.

Step 4 — Add nonces properly (server + templates)

A nonce must be random and per-response. The server sends the nonce in the CSP header, and any inline script that should execute includes nonce="...nonce...". If an attacker injects a script, they won’t know the nonce and the browser blocks execution.

Below is a simple Node/Express example that sets a nonce and renders it into HTML. The important part is: nonce is generated per request, included in the header, and used on script tags.

import crypto from "crypto";
import express from "express";

const app = express();

app.use((req, res, next) => {
  // Per-response nonce (base64 is common)
  const nonce = crypto.randomBytes(16).toString("base64");
  res.locals.cspNonce = nonce;

  // Minimal example CSP. Expand with your real hosts.
  res.setHeader(
    "Content-Security-Policy",
    [
      "default-src 'self'",
      "base-uri 'self'",
      "object-src 'none'",
      "frame-ancestors 'self'",
      `script-src 'self' 'nonce-${nonce}'`,
      "style-src 'self' https: 'unsafe-inline'",
      "img-src 'self' data: https:",
      "connect-src 'self' https:",
    ].join("; ")
  );

  next();
});

app.get("/", (req, res) => {
  // Example HTML output. In a real app use your template engine.
  res.type("html").send(`
    <!doctype html>
    <html>
      <head><meta charset="utf-8"></head>
      <body>
        <h1>Hello</h1>
        <script nonce="${res.locals.cspNonce}">
          window.__BOOT__ = { ok: true };
        </script>
        <script src="/app.js"></script>
      </body>
    </html>
  `);
});

app.listen(3000);

Step 5 — Reduce “breakage risk” by removing inline scripts

The most stable CSP is one where you don’t need inline scripts at all. Move inline JS to bundled files, replace DOM event attributes (onclick="...") with event listeners, and avoid dynamic code evaluation.

Step 6 — Enforce CSP and add a regression gate

Once Report-Only reports look clean on your highest-traffic pages, switch to enforcing mode. Keep Report-Only in parallel for a bit (with the same policy) to catch new third-party additions or build changes. Finally, add a CI gate so CSP doesn’t silently drift.

Here’s a small “CSP sanity check” script you can run in CI to detect inline scripts and event handler attributes. It’s not perfect, but it catches most regressions early.

import re
import sys
from pathlib import Path

INLINE_SCRIPT = re.compile(r"<script(?![^>]*\\bsrc=)[^>]*>", re.IGNORECASE)
INLINE_HANDLER = re.compile(r"\\son\\w+\\s*=\\s*['\\\"]", re.IGNORECASE)

def scan_file(p: Path) -> list[str]:
  txt = p.read_text(encoding="utf-8", errors="ignore")
  issues = []
  if INLINE_SCRIPT.search(txt):
    issues.append("inline <script> without src")
  if INLINE_HANDLER.search(txt):
    issues.append("inline event handler attribute (onclick/onload/...)")
  return issues

def main(root: str) -> int:
  root_path = Path(root)
  bad = 0
  for p in root_path.rglob("*.html"):
    issues = scan_file(p)
    if issues:
      bad += 1
      print(f"[CSP] {p}: " + ", ".join(issues))
  return 1 if bad else 0

if __name__ == "__main__":
  target = sys.argv[1] if len(sys.argv) > 1 else "."
  raise SystemExit(main(target))

Step 7 — Tighten policy over time

After you enforce a stable baseline, you can tighten CSP to increase protection: remove broad https: allowances, reduce third-party domains, lock down frames, and constrain connections. The best CSP is usually the one that matches your architecture: few script hosts, explicit API hosts, and minimal inline code.

Common mistakes

CSP failures are usually not mysterious: they come from a handful of predictable patterns. Here are the most common CSP rollout pitfalls, and how to fix them without weakening the policy.

FAQ

What is CSP and how does it prevent XSS?

CSP is a browser-enforced allowlist for resources. It tells the browser which script sources are allowed and whether inline scripts can run. If an attacker injects a script tag or inline JS, CSP can block execution unless it matches an allowed origin or has a valid nonce/hash. It reduces the impact of XSS, but you still need to fix the underlying injection bug.

Should I use <meta http-equiv="Content-Security-Policy"> or headers?

Use headers whenever possible. Headers are more robust, apply earlier, and are easier to manage consistently across routes. Meta CSP can be useful for static hosting without header control, but it’s more limited and easier to misconfigure.

What’s the safest CSP starting policy?

Start in Report-Only with a strict script-src plan. A common baseline is default-src 'self', object-src 'none', base-uri 'self', and a script-src that allows only your origin and known vendor domains. Then add nonces for any unavoidable inline scripts.

Why does CSP break my API calls and telemetry?

Because connect-src controls network destinations. If your frontend calls an API on a different domain, uses WebSockets, or sends telemetry to a collector, those hosts must be listed in connect-src. Without it, the browser blocks the requests.

Is 'unsafe-eval' ever OK?

In production, avoid it. Some dev tooling or older libraries require eval-like behavior, but it weakens protections and can enable certain injection chains. Keep 'unsafe-eval' only in development policies if you absolutely must, and ensure production builds don’t depend on it.

Nonce or hash: which should I choose?

Choose nonces for dynamic apps and hashes for static pages. Nonces are generated per response and scale well with templates/SSR. Hashes work when the inline script is stable and rarely changes. Both are far better than allowing all inline scripts.

Cheatsheet

A compact CSP checklist you can use during rollout, code review, and incident response.

Wrap-up

CSP is one of the most practical browser security controls: it changes XSS from “one injection = full compromise” into “injection that can’t easily execute or exfiltrate.” The key is to roll it out like a migration: report-only → fix → nonces/hashes → enforce → regressions.

Next up: threat modeling your frontend surface, reviewing third-party scripts, and securing API endpoints against abuse. The related posts below cover those angles.

Related posts

• OWASP Top 10 in Real Life: How Apps Actually Get Hacked
• Threat Modeling in 45 Minutes: A Lightweight Template
• Passkeys, MFA, Sessions: Modern Authentication Done Right
• API Security Checklist: Auth, Rate Limits, and Abuse Cases
• DevSecOps Basics: Add Security to CI/CD Without Chaos
• Dependency Attacks: How One Package Can Burn Your App