Content Security Policy (CSP): Implementation Guide

TL;DR

• Bottom line: Deploy a strict nonce-based CSP with strict-dynamic to prevent inline script injection (XSS) -- start in report-only mode, then enforce after validating no breakage.
• Key tool/command: Content-Security-Policy: script-src 'nonce-{RANDOM}' 'strict-dynamic'; object-src 'none'; base-uri 'none';
• Watch out for: Using 'unsafe-inline' in script-src defeats CSP's entire XSS protection -- use nonces or hashes instead.
• Works with: All modern browsers. CSP Level 3 (strict-dynamic) supported in Chrome 59+, Firefox 58+, Safari 15.4+, Edge 79+.

Constraints

• ALWAYS start with Content-Security-Policy-Report-Only before enforcing -- deploying CSP in enforcement mode without testing WILL break site functionality
• NEVER use 'unsafe-inline' for script-src in production -- it defeats CSP's primary XSS protection
• NEVER use wildcard (*) as a source for script-src or default-src -- it allows loading scripts from any origin
• Nonces MUST be cryptographically random (at least 128 bits) and regenerated on every page load -- reusing nonces defeats their purpose
• CSP is defense-in-depth, NOT a replacement for output encoding -- always combine CSP with proper input validation and output encoding
• frame-ancestors directive CANNOT be set via <meta> tag -- it must be sent as an HTTP header

Quick Reference

CSP Directives by Category

Source Expression Keywords

Decision Tree

START: What is your CSP deployment scenario?
├── New application (no existing inline scripts)?
│   ├── YES → Deploy strict nonce-based CSP immediately (see Step 1)
│   └── NO ↓
├── Existing app with inline scripts you control?
│   ├── YES → Add nonces to all inline scripts, then deploy strict CSP (see Step 2)
│   └── NO ↓
├── Existing app with third-party inline scripts?
│   ├── YES → Use hash-based CSP for static scripts + nonces for dynamic (see Step 3)
│   └── NO ↓
├── Legacy app that cannot be modified?
│   ├── YES → Deploy allowlist-based CSP as interim measure, plan migration to strict CSP
│   └── NO ↓
├── Need to prevent clickjacking only?
│   ├── YES → Use frame-ancestors 'none' or 'self' (Step 5)
│   └── NO ↓
└── DEFAULT → Start with report-only mode to audit current resource loading (Step 1)

Step-by-Step Guide

1. Deploy CSP in report-only mode

Start by deploying a strict policy in report-only mode to discover what would break without actually blocking anything. [src6]

Content-Security-Policy-Report-Only:
  default-src 'self';
  script-src 'self';
  style-src 'self';
  img-src 'self';
  object-src 'none';
  base-uri 'none';
  report-to csp-endpoint;

Verify: Open browser DevTools > Console -- CSP violations appear as warnings with [Report Only] prefix.

2. Add nonces to all inline scripts

Generate a cryptographically random nonce per request and add it to every inline <script> tag. [src5]

Content-Security-Policy: script-src 'nonce-dGhpcyBpcyBhIG5vbmNl' 'strict-dynamic'

Verify: Inline scripts without a nonce should be blocked. Check console for Refused to execute inline script errors.

3. Build a strict CSP policy

Combine the essential directives for a production-ready strict CSP. [src3]

Content-Security-Policy:
  default-src 'self';
  script-src 'nonce-{RANDOM}' 'strict-dynamic';
  style-src 'self' 'nonce-{RANDOM}';
  img-src 'self' https:;
  font-src 'self';
  connect-src 'self' https://api.example.com;
  frame-src 'none';
  object-src 'none';
  base-uri 'none';
  form-action 'self';
  frame-ancestors 'none';
  upgrade-insecure-requests;
  report-to csp-endpoint;

Verify: Run your CSP through Google's CSP Evaluator at https://csp-evaluator.withgoogle.com/.

4. Switch from report-only to enforcement

After monitoring report-only mode for at least 1-2 weeks with no unexpected violations, switch to enforcement. [src6]

curl -sI https://your-site.com | grep -i content-security-policy

Verify: Should return the enforced policy (not report-only).

5. Configure frame-ancestors for clickjacking protection

Replace the legacy X-Frame-Options header with CSP frame-ancestors. [src1]

# Prevent all framing
Content-Security-Policy: frame-ancestors 'none';

# Allow same-origin framing only
Content-Security-Policy: frame-ancestors 'self';

# Allow specific origins
Content-Security-Policy: frame-ancestors 'self' https://trusted-partner.com;

Verify: Try embedding your page in an <iframe> on a different origin -- it should be blocked.

Code Examples

Express.js/Node.js: Helmet CSP with Per-Request Nonces

const express = require('express');     // ^4.18.0
const helmet = require('helmet');       // ^8.0.0
const crypto = require('crypto');
const app = express();

// Generate per-request nonce middleware
app.use((req, res, next) => {
  res.locals.cspNonce = crypto.randomBytes(16).toString('base64');
  next();
});

// Configure CSP via Helmet
app.use(helmet({
  contentSecurityPolicy: {
    directives: {
      defaultSrc: ["'self'"],
      scriptSrc: [
        (req, res) => `'nonce-${res.locals.cspNonce}'`,
        "'strict-dynamic'"
      ],
      styleSrc: ["'self'", (req, res) => `'nonce-${res.locals.cspNonce}'`],
      imgSrc: ["'self'", "https:"],
      connectSrc: ["'self'"],
      fontSrc: ["'self'"],
      objectSrc: ["'none'"],
      baseUri: ["'none'"],
      formAction: ["'self'"],
      frameAncestors: ["'none'"],
      upgradeInsecureRequests: []
    }
  }
}));
// In templates: <script nonce="<%= cspNonce %>">...</script>

Django: django-csp Configuration

# settings.py -- using django-csp >= 4.0
# pip install django-csp
MIDDLEWARE = ["csp.middleware.CSPMiddleware", ...]

CONTENT_SECURITY_POLICY = {
    "DIRECTIVES": {
        "default-src": ["'self'"],
        "script-src": ["'strict-dynamic'"],  # nonces added automatically
        "style-src": ["'self'"],
        "img-src": ["'self'", "https:"],
        "connect-src": ["'self'"],
        "font-src": ["'self'"],
        "object-src": ["'none'"],
        "base-uri": ["'none'"],
        "form-action": ["'self'"],
        "frame-ancestors": ["'none'"],
        "upgrade-insecure-requests": True,
    }
}
# In templates: {% load csp %} <script nonce="{% csp_nonce %}">...</script>

Nginx: CSP Header Configuration

# /etc/nginx/snippets/csp-headers.conf
# Hash-based CSP for static sites (Nginx cannot generate nonces natively)
add_header Content-Security-Policy "
  default-src 'self';
  script-src 'self' 'sha256-{HASH_OF_INLINE_SCRIPT}';
  style-src 'self';
  img-src 'self' https:;
  font-src 'self';
  connect-src 'self';
  object-src 'none';
  base-uri 'none';
  form-action 'self';
  frame-ancestors 'none';
  upgrade-insecure-requests;
" always;

Apache: CSP Header Configuration

# .htaccess or httpd.conf
Header always set Content-Security-Policy "\
  default-src 'self'; \
  script-src 'self' 'sha256-{HASH_OF_INLINE_SCRIPT}'; \
  style-src 'self'; \
  img-src 'self' https:; \
  font-src 'self'; \
  connect-src 'self'; \
  object-src 'none'; \
  base-uri 'none'; \
  form-action 'self'; \
  frame-ancestors 'none'; \
  upgrade-insecure-requests"

Anti-Patterns

Wrong: Using unsafe-inline with script-src

# BAD -- unsafe-inline completely negates CSP's XSS protection
Content-Security-Policy: default-src 'self'; script-src 'self' 'unsafe-inline'
# Any XSS payload can execute inline scripts freely

Correct: Nonce-based script-src

# GOOD -- only scripts with the correct nonce execute
Content-Security-Policy: script-src 'nonce-abc123def456' 'strict-dynamic'
# XSS payloads cannot guess the per-request nonce

Wrong: Wildcard sources in script-src

# BAD -- allows scripts from ANY origin
Content-Security-Policy: default-src *; script-src *

Correct: Explicit origin allowlist or nonces

# GOOD -- use nonce-based CSP with strict-dynamic
Content-Security-Policy: script-src 'nonce-{RANDOM}' 'strict-dynamic'; object-src 'none'; base-uri 'none'

Wrong: Overly permissive default-src

# BAD -- default-src https: allows loading from ANY HTTPS origin
Content-Security-Policy: default-src https:
# Attackers can host payloads on any HTTPS domain they control

Correct: Restrictive default-src with explicit overrides

# GOOD -- lock down default, open specific directives as needed
Content-Security-Policy: default-src 'none'; script-src 'nonce-{RANDOM}' 'strict-dynamic'; style-src 'self'; img-src 'self' https:; font-src 'self'; connect-src 'self'

Wrong: CSP via meta tag for frame-ancestors

<!-- BAD -- frame-ancestors, report-uri, report-to, and sandbox
     are IGNORED in meta tags -->
<meta http-equiv="Content-Security-Policy"
      content="frame-ancestors 'none'; report-uri /csp-report">

Correct: CSP via HTTP header

# GOOD -- all directives work via HTTP header
Content-Security-Policy: frame-ancestors 'none'; report-to csp-endpoint

Wrong: Using unsafe-eval for convenience

# BAD -- allows eval(), new Function(), setTimeout(string)
Content-Security-Policy: script-src 'self' 'unsafe-eval'

Correct: Refactoring to avoid eval

// GOOD -- replace eval() with safe alternatives
// Instead of: setTimeout('doSomething()', 1000)
setTimeout(doSomething, 1000);  // pass function reference
// Instead of: new Function('return ' + userInput)
JSON.parse(userInput);  // for data parsing

Common Pitfalls

• Forgetting report-only first: Deploying CSP in enforcement mode immediately breaks inline scripts, third-party widgets, and analytics. Fix: Always deploy with Content-Security-Policy-Report-Only first and monitor for 1-2 weeks. [src6]
• Nonce reuse across requests: Serving the same nonce for all requests allows attackers who discover it to bypass CSP. Fix: Generate a new cryptographically random nonce for every HTTP response using crypto.randomBytes(16). [src5]
• Missing object-src and base-uri: Omitting object-src allows plugin injection; omitting base-uri allows <base> tag hijacking. Fix: Always include object-src 'none'; base-uri 'none'. [src3]
• Allowlist bypasses via JSONP/Angular: Allowlisting a CDN that hosts JSONP endpoints lets attackers load script gadgets that bypass CSP. Fix: Use nonce-based CSP with strict-dynamic instead of domain allowlists. [src5]
• CSP on meta tag limitations: Using <meta http-equiv="Content-Security-Policy"> ignores frame-ancestors, report-uri, report-to, and sandbox. Fix: Set CSP via HTTP response headers. [src2]
• Mixed content after upgrade-insecure-requests: The directive does not upgrade WebSocket (ws://) connections. Fix: Explicitly use wss:// for WebSocket connections. [src1]
• Breaking service workers: Restrictive worker-src or script-src without accounting for service worker scope blocks SW registration. Fix: Include worker-src 'self' if you use service workers. [src2]
• report-uri deprecation: report-uri is deprecated in CSP Level 3 in favor of report-to. Fix: Include both during the transition period. [src4]

Diagnostic Commands

# Check current CSP headers of a live site
curl -sI https://your-site.com | grep -i content-security-policy

# Check CSP with full headers
curl -sI https://your-site.com | grep -iE '(content-security|report)'

# Generate SHA-256 hash of an inline script for hash-based CSP
echo -n 'console.log("hello")' | openssl dgst -sha256 -binary | openssl base64

# Validate CSP: visit https://csp-evaluator.withgoogle.com/

# Scan for inline scripts that need nonces
grep -rn '<script>' --include="*.html" --include="*.ejs" .

# Scan for inline event handlers that CSP will block
grep -rn 'onclick=\|onload=\|onerror=\|onsubmit=' --include="*.html" .

Version History & Compatibility

When to Use / When Not to Use

Important Caveats

• strict-dynamic trusts scripts loaded by nonce-approved scripts -- if a trusted script has a gadget vulnerability (e.g., JSONP endpoint, prototype pollution), it can be exploited to bypass CSP
• CSP via <meta> tag does not support frame-ancestors, report-uri, report-to, or sandbox -- use HTTP headers for full protection
• Internet Explorer does not support Content-Security-Policy -- only the non-standard X-Content-Security-Policy (IE 10-11, limited support)
• upgrade-insecure-requests does not upgrade WebSocket connections (ws:// to wss://) -- handle this explicitly in application code
• Hash-based CSP requires recalculating hashes whenever inline script content changes -- prefer nonces for dynamic applications
• Multiple CSP headers are intersected (most restrictive wins), not merged -- adding a second header can only restrict, never relax, the policy