OOmnistu

Blog / Engineering Playbooks

Engineering Playbooks

Content Security Policy (CSP) explained for site owners

Understand how Content Security Policy restricts browser behavior, where it helps and why it does not replace secure application code.

OOmnistu
Reviewed 2026-11-16 · 3 min read

A Content Security Policy is a set of instructions your website sends to the browser, limiting what the code on the page may do. MDN's guide (https://developer.mozilla.org/en-US/docs/Web/HTTP/Guides/CSP) says it helps prevent or minimize certain security threats. Its main use is controlling which resources, especially JavaScript, a document may load, as a defence against cross-site scripting (XSS), where an attacker injects malicious code into your site. It can also help against clickjacking and help ensure pages load over HTTPS.

How it is delivered

Per MDN, a CSP should be sent in the Content-Security-Policy response header, on all responses, not only the main page. It can also be set with a meta tag, useful for some static single-page apps, but that option does not support all CSP features. A policy is a list of directives separated by semicolons, for example: default-src 'self'; img-src 'self' example.com.

Four jobs, independent of each other

MDN says there is no dependency between the use cases, so you can add only the directives you need:

  1. Control what loads, to protect against XSS.
  2. Restrict embedding, to protect against clickjacking.
  3. Upgrade insecure requests, to help serve everything over HTTPS.
  4. Require trusted types, to help defend against client-side XSS.

Strict CSP beats long allowlists

For scripts, MDN recommends a "strict CSP" using nonces or hashes instead of allowlisting domains. It gives two reasons: allowlist policies are hard to get right and often permit unsafe domains by accident, and they can grow very large, especially when third-party scripts load more scripts. The exact requirements depend on current vendor behavior; no fixed domain count is asserted here.

MDN's nonce-based example:

Content-Security-Policy: script-src 'nonce-{RANDOM}'; object-src 'none'; base-uri 'none';

Here {RANDOM} is a placeholder, not a reusable value. Generate an unpredictable nonce for each response and put that value only on intended trusted script elements as well as in the policy. Nonces suit sites that generate pages dynamically. Hash-based policies suit static content, but the hash must be recalculated whenever the script changes.

Clickjacking

The frame-ancestors directive controls which sites may embed your page. MDN says to set it to 'none' unless your site must be embeddable, and calls it a more flexible replacement for the X-Frame-Options header.

Mixed content

If an HTTPS page loads resources over HTTP, the protection of HTTPS is weakened. Browsers upgrade some of these requests and block others, which can break a page. The upgrade-insecure-requests directive is MDN's tool for that migration (we read its overview only).

Rolling it out safely

MDN recommends testing in report-only mode first: the Content-Security-Policy-Report-Only header does not enforce the policy but sends violation reports. A report-only policy cannot be set in a meta tag. For reporting, MDN recommends the Reporting API (a Reporting-Endpoints header plus the report-to directive) and describes the older report-uri as deprecated, though both are declared until support is complete.

Why this matters for sites with analytics or ads

Every third-party script you add, such as analytics or an ad network, must be allowed by your policy. We did not research any particular vendor's CSP requirements; check each vendor's current documentation and test in report-only mode before enforcing.

Limits

CSP reduces risk and does not replace secure coding such as escaping user input. We did not read MDN's sections on Trusted Types in detail or the individual fetch directives.

By Omnistu.

Sources

Previous
Cloud cost control for startups: five principles from the AWS Well-Architected Framework