Technical

Content Security Policy

Content Security Policy (CSP): HTTP header telling the browser which sources may load scripts, styles, images and iframes. The main defense against XSS.

Plaque de verre dressée percée de trois fentes verticales, trois petits cubes bordeaux translucides passant à travers, tandis que des cubes noirs plus gros s'entassent bloqués derrière, sur un sol sombre réfléchissant
Content Security Policy — Image générée par IA (Qwen-Image 2.1, ComfyUI local)

Content Security Policy (CSP) is an HTTP header that lets a server tell the browser which sources are allowed to provide executable or displayable content in a page: JavaScript, stylesheets, images, iframes, fonts, network connections. It is one of the most powerful defenses against XSS attacks, provided it is configured rigorously. It is also one of the hardest to roll out without breaking anything, because it enforces strict discipline over everything the browser loads.

Technical definition

Structure of a CSP policy

A CSP is a list of directives separated by semicolons. Each directive controls one category of resources. For example:

Content-Security-Policy:
  default-src 'self';
  script-src 'self' 'nonce-abc123';
  style-src 'self' 'unsafe-inline';
  img-src 'self' data: https:;
  connect-src 'self' https://api.example.com;
  frame-ancestors 'none';

By default, this policy only allows resources from the same domain, with explicit exceptions: scripts must come from the same domain or carry a valid nonce, inline styles are tolerated (a concession to WordPress), images may come from data: or HTTPS, AJAX connections are restricted to one specific domain, and the page cannot be displayed in any iframe.

The most important directives

  • default-src: default value for every directive not specified. Starting with 'self' is a good baseline.
  • script-src: controls JavaScript, the most security-critical directive.
  • style-src: controls stylesheets.
  • img-src: controls images.
  • frame-ancestors: replaces the old X-Frame-Options and controls who can embed the page in an iframe.
  • form-action: restricts where forms can be submitted (protection against formjacking).
  • upgrade-insecure-requests: forces the browser to load over HTTPS every resource declared over HTTP.
  • report-uri / report-to: tells the browser where to send violation reports.

Current challenges

The difficulty of deploying in production

Applying a strict CSP to an existing application is a delicate exercise. WordPress, for example, injects large amounts of inline JavaScript through its plugins and the Gutenberg editor, which makes it incompatible with a CSP that forbids 'unsafe-inline'. The recommended strategy is to start in Content-Security-Policy-Report-Only mode, analyze the violations reported by browsers, identify the legitimate sources and add them to the policy, then switch to blocking mode once you have proof that nothing breaks.

Nonces and hashes to allow inline code

When inline JavaScript cannot be eliminated completely, CSP offers two precise exception mechanisms:

  1. Nonce: a random string generated by the server for each request, included both in the CSP header and in every allowed <script> tag. The browser only runs scripts carrying the right nonce. An attacker who injects a script does not know the current nonce, so the script is blocked.
  2. Hash: a SHA-256 hash of the exact content of the inline script. This method is better suited to static sites where the inline content is known in advance and does not change.

CSP and the supply chain

Beyond XSS protection, CSP is a safeguard against front-end supply chain attacks. If an attacker compromises a third-party CDN or an analytics tool, a strict CSP prevents malicious scripts from being injected because the new script violates the policy. Recent incidents (British Airways, Ticketmaster) have shown that the front-end supply chain is a significant attack vector, and a well-configured CSP would have limited the exposure.

Practical applications

On WordPress, CSP is typically handled by a security plugin, which brings the usual plugin problems (attack surface, unversioned configuration, performance). An alternative approach is to manage the CSP through an infrastructure configuration file, with several modes driven by an environment variable (off, permissive, report-only, strict) to allow a gradual rollout. I describe this approach in detail in my article on securing WordPress without plugins.

Frequently Asked Questions

What exactly does CSP protect against?

CSP is designed primarily to neutralize XSS (Cross-Site Scripting) attacks: even if an attacker manages to inject JavaScript into a page, CSP stops the browser from running that script unless it comes from an authorized source. It also protects against clickjacking (through the frame-ancestors directive), unauthorized third-party resource injection (CDN typosquatting, supply chain attacks) and formjacking (forms redirected to malicious servers, blocked with form-action).

What is the difference between Content-Security-Policy and Content-Security-Policy-Report-Only?

The standard Content-Security-Policy header blocks anything that violates the policy. The Content-Security-Policy-Report-Only header reports violations (to a reporting endpoint) but blocks nothing. It is the recommended way to roll out a CSP gradually: start in observation mode on a staging environment, analyze the reported violations, fix the false positives, then switch to blocking mode in production once you are sure the user experience will not break.

What is a CSP nonce and what is it for?

A nonce (number used once) is a random string generated by the server for each request. The server includes it both in the CSP header (script-src 'nonce-abc123') and in every <script> tag it wants to allow (<script nonce="abc123">). The browser only runs scripts carrying the right nonce. This technique precisely allows legitimate inline code while blocking any script injected by an attacker, who cannot know the nonce of the current request.

Resources and Documentation