Content Security Policy (CSP) Complete Guide: From Basics to Production

Content Security Policy (CSP) is one of the most effective defenses against Cross-Site Scripting (XSS) attacks. By telling the browser exactly which resources are allowed to load, CSP can prevent malicious code injection even when your application has vulnerabilities.

What is CSP and Why Does It Matter?

CSP is an HTTP response header that controls which resources the browser is allowed to load for a given page. Without CSP, a single XSS vulnerability could allow attackers to inject scripts, steal cookies, redirect users, or deface your site.

How CSP Works

When a browser receives a CSP header, it enforces the policy by blocking any resource that violates the rules:

Browser receives HTTP response:
  Content-Security-Policy: default-src 'self'; script-src 'self' https://cdn.example.com

Browser allows:
  ✅ <script src="/app.js">              (same origin = 'self')
  ✅ <script src="https://cdn.example.com/lib.js">

Browser blocks:
  ❌ <script src="https://evil.com/steal.js">
  ❌ <script>alert('XSS')</script>       (inline = not allowed)

All CSP Directives

Source Values Explained

Step-by-Step Implementation

Step 1: Start with Report-Only Mode

Deploy CSP in report-only mode first to identify violations without breaking your site:

Content-Security-Policy-Report-Only: default-src 'self'; report-uri /csp-report

Step 3: Build Your Policy

Create a policy based on your findings. Start strict and relax as needed:

Content-Security-Policy:
  default-src 'self';
  script-src 'self' https://cdn.example.com;
  style-src 'self' 'unsafe-inline';
  img-src 'self' data: https:;
  font-src 'self' https://fonts.gstatic.com;
  connect-src 'self' https://api.example.com;
  frame-ancestors 'self';
  base-uri 'self';
  form-action 'self';
  object-src 'none';
  upgrade-insecure-requests

Common CSP Configurations

Strict Policy (Maximum Security)

Content-Security-Policy:
  default-src 'none';
  script-src 'self';
  style-src 'self';
  img-src 'self';
  font-src 'self';
  connect-src 'self';
  base-uri 'self';
  form-action 'self';
  frame-ancestors 'none';
  object-src 'none';
  upgrade-insecure-requests

Moderate (Typical SPA)

Content-Security-Policy:
  default-src 'self';
  script-src 'self' 'unsafe-inline' 'unsafe-eval';
  style-src 'self' 'unsafe-inline';
  img-src 'self' data: blob: https:;
  font-src 'self' https://fonts.gstatic.com;
  connect-src 'self' https://api.example.com wss://ws.example.com;
  frame-ancestors 'self'

With Google Analytics

Content-Security-Policy:
  default-src 'self';
  script-src 'self' https://www.googletagmanager.com https://www.google-analytics.com;
  img-src 'self' https://www.google-analytics.com https://www.googletagmanager.com;
  connect-src 'self' https://www.google-analytics.com https://analytics.google.com

Implementation Methods

Nginx

add_header Content-Security-Policy "default-src 'self'; script-src 'self'" always;

Apache

Header set Content-Security-Policy "default-src 'self'; script-src 'self'"

Express.js

// Using helmet middleware (recommended)
const helmet = require('helmet');
app.use(helmet.contentSecurityPolicy({
  directives: {
    defaultSrc: ["'self'"],
    scriptSrc: ["'self'", "https://cdn.example.com"],
    styleSrc: ["'self'", "'unsafe-inline'"],
    imgSrc: ["'self'", "data:", "https:"],
  }
}));

// Or manually
app.use((req, res, next) => {
  res.setHeader('Content-Security-Policy',
    "default-src 'self'; script-src 'self'");
  next();
});

HTML Meta Tag

<meta http-equiv="Content-Security-Policy"
  content="default-src 'self'; script-src 'self'">

Common CSP Mistakes

FAQ