CSP Levels and Evolution

Trace CSP from level 1 through level 3 and understand nonce-based and hash-based policies

Introduction: The Evolution of Content Security Policy

Have you ever wondered why your carefully crafted web application can still fall victim to malicious scripts, even when you've sanitized every input? The harsh reality is that Cross-Site Scripting (XSS) attacks have plagued the web for decades, exploiting the fundamental trust relationship between browsers and web servers. Just when developers thought they had input validation figured out, attackers found new vectors. This cat-and-mouse game drove the creation of Content Security Policy (CSP), a revolutionary security mechanism that fundamentally changed how browsers handle potentially dangerous content. Master these free flashcards we've embedded throughout this lesson to solidify your understanding of how CSP evolved to become one of the web's most powerful defenses.

The story of CSP's evolution mirrors the story of the modern web itself. In the early 2010s, XSS attacks were rampant—studies showed that over 80% of web applications contained at least one XSS vulnerability. Traditional approaches relied on server-side input sanitization, but this placed an enormous burden on developers to anticipate every possible attack vector. One missed encoding, one overlooked context, and an application became vulnerable. The web community needed a different approach: instead of trying to catch every bad input, why not tell the browser what good content looks like?

🎯 Key Principle: CSP shifts security from "blocking the bad" to "allowing only the good"—a fundamental change in defensive philosophy that makes attacks exponentially harder.

The Security Crisis That Demanded Evolution

The initial version of CSP, now known as CSP Level 1, emerged from this crisis in 2012. It introduced the concept of directives—declarative policies that instructed browsers about which sources of content were legitimate. Instead of executing any script found on a page, browsers could now consult a policy and reject unauthorized content before it ever ran. This was revolutionary, but it had limitations that quickly became apparent in real-world deployments.

💡 Real-World Example: Google deployed CSP Level 1 across their properties and immediately discovered a problem: their inline event handlers (onclick="...") were blocked by their own security policy. The choice was stark—rewrite millions of lines of code or compromise security. This tension drove the creation of CSP Level 2.

The evolution from CSP Level 1 to CSP Level 2 (finalized in 2016) and then CSP Level 3 (still in development) wasn't arbitrary feature creep. Each level addressed critical gaps discovered through massive-scale deployments. Level 1 established the foundation: directive-based policies that controlled script sources, style sources, and other content types. But it struggled with modern web development patterns that relied heavily on inline scripts and styles.

CSP Evolution Timeline:

2012          2016          2020+
  |             |             |
  v             v             v
Level 1 ───> Level 2 ───> Level 3
  │             │             │
  │             │             └─> Worker support
  │             │                 Trusted Types
  │             │                 Embedded enforcement
  │             │
  │             └───────────────> Nonces & hashes
  │                               strict-dynamic
  │                               Improved reporting
  │
  └─────────────────────────────> Source whitelists
                                   Basic directives
                                   Report-only mode

Why Multiple Levels Matter for Modern Defense

Understanding the relationship between CSP levels isn't just academic—it's essential for practical security implementation. Each level represents both a specification version and a browser capability tier. A browser that supports CSP Level 2 can process all Level 1 directives plus the new Level 2 features like nonces, hashes, and strict-dynamic. This creates a fascinating challenge: how do you write a policy that protects users on modern browsers while maintaining some security for users on older ones?

🤔 Did you know? According to the 2023 Web Almanac, only 8% of websites implement any CSP at all, and among those that do, 40% have policies so permissive they provide almost no protection. Understanding CSP levels helps avoid this trap.

The concept of backwards compatibility and progressive enhancement becomes critical here. A well-crafted CSP policy should provide baseline protection to all browsers while taking advantage of advanced features where available. This isn't just theoretical—the difference in protection levels is measurable and significant.

📋 Quick Reference Card: CSP Levels at a Glance

🏷️ Level	📅 Year	🔑 Key Innovation	🎯 Primary Use Case
Level 1	2012	Source whitelisting	🔒 Basic resource control
Level 2	2016	Nonces, hashes, strict-dynamic	🛡️ Modern app protection
Level 3	2020+	Trusted Types, worker support	🚀 Advanced injection defense

Measuring Real Impact: The XSS Prevention Data

The evolution of CSP levels has produced measurable security improvements. Research from Google's security team showed that properly implemented CSP Level 2 policies with nonces reduced successful XSS exploitation by 95% compared to no CSP. Even more impressive, the addition of strict-dynamic in Level 2 eliminated entire classes of bypass techniques that plagued Level 1 implementations.

💡 Pro Tip: The most common mistake isn't choosing the wrong CSP level—it's implementing any level incorrectly. A CSP Level 1 policy with proper source restrictions outperforms a permissive Level 2 policy every time.

However, CSP Level 1 alone showed more modest improvements—typically 30-50% reduction in successful attacks—because attackers could still exploit inline scripts on sites that needed them for functionality. This is where Level 2's innovations became game-changing. By introducing cryptographic nonces (random values that change with each page load) and content hashes (cryptographic fingerprints of legitimate scripts), Level 2 enabled developers to allow specific inline code while blocking everything else.

⚠️ Common Mistake: Assuming a higher CSP level is always better. Mistake 1: Deploying Level 2/3 features without understanding browser support for your user base can leave some users with no protection at all. Always implement fallback mechanisms. ⚠️

❌ Wrong thinking: "I'll just use CSP Level 3 for maximum security." ✅ Correct thinking: "I'll analyze my browser support needs and implement the highest CSP level that serves 95%+ of my users, with graceful degradation."

As we move through this lesson, you'll gain the practical knowledge to implement CSP at each level, understand when to use specific features, and avoid the pitfalls that have trapped even experienced developers. The evolution of CSP represents one of the web's greatest security success stories—but only if you understand how to harness it effectively.

CSP Level 1: Foundation and Core Directives

When Content Security Policy Level 1 emerged in 2012, it represented a paradigm shift in web security. Instead of trying to detect and filter malicious content after it arrived, CSP Level 1 introduced a whitelist-based security model that told browsers exactly which sources of content to trust. This proactive approach fundamentally changed how we defend against cross-site scripting (XSS) and injection attacks.

The Core Directive Architecture

CSP Level 1 introduced a directive structure that remains the foundation of all modern CSP implementations. Each directive controls a specific type of resource, creating granular control over what content can load and execute on your page.

🎯 Key Principle: Every CSP directive follows the pattern directive-name source-list, where the source list defines the allowed origins for that resource type.

The core directives introduced in Level 1 include:

🔒 default-src – The fallback directive that applies to any resource type not explicitly specified 🔒 script-src – Controls JavaScript sources, including inline scripts and eval() 🔒 style-src – Governs CSS stylesheets and inline styles 🔒 img-src – Restricts image sources 🔒 connect-src – Limits origins for XMLHttpRequest, WebSocket, and EventSource connections 🔒 font-src – Controls font file sources 🔒 object-src – Restricts plugins like Flash 🔒 media-src – Governs <audio> and <video> sources

Browser Request Flow with CSP Level 1:

1. Browser receives page with CSP header:
   Content-Security-Policy: default-src 'self'; script-src 'self' cdn.example.com

2. Page attempts to load <script src="https://evil.com/malware.js">
   |
   v
3. Browser checks script-src directive
   Allowed: 'self', cdn.example.com
   Requested: evil.com
   |
   v
4. ❌ BLOCKED – Request never sent
   Console warning logged

💡 Mental Model: Think of CSP Level 1 as a bouncer at a club with an explicit guest list. If your name isn't on the list, you're not getting in—no exceptions, no negotiations.

Source List Syntax: Building Your Whitelist

The source list syntax in Level 1 provides several ways to specify trusted sources:

Special keywords (always wrapped in single quotes):

'none' – Block all sources of this type
'self' – Allow resources from the same origin (protocol + domain + port)
'unsafe-inline' – Allow inline scripts/styles (dangerous!)
'unsafe-eval' – Allow eval() and similar dynamic code execution

Origin-based sources:

https://example.com – Specific domain with HTTPS
*.example.com – All subdomains
https: – Any HTTPS source
data: – Data URIs

💡 Real-World Example: A typical e-commerce site might use:

Content-Security-Policy: 
  default-src 'self'; 
  script-src 'self' https://cdn.jsdelivr.net; 
  style-src 'self' 'unsafe-inline'; 
  img-src 'self' https://*.cloudinary.com data:; 
  connect-src 'self' https://api.stripe.com

This policy allows scripts from the site itself and jsDelivr CDN, styles from the same origin plus inline styles, images from the origin, Cloudinary CDN, and data URIs, and API connections to the origin and Stripe.

The Dangerous Keywords: unsafe-inline and unsafe-eval

Two keywords in CSP Level 1 stand out for their security implications: 'unsafe-inline' and 'unsafe-eval'. These keywords exist as escape hatches, but their names reveal their danger.

'unsafe-inline' permits inline JavaScript and CSS:

<!-- Allowed only with 'unsafe-inline' -->
<script>alert('inline code')</script>
<div onclick="doSomething()">Click me</div>
<style>body { background: red; }</style>

'unsafe-eval' permits dynamic code execution:

// Allowed only with 'unsafe-eval'
eval('alert("dynamic code")');
setTimeout('doSomething()', 1000);
new Function('return true')();

⚠️ Common Mistake: Developers often add 'unsafe-inline' to "fix" CSP errors without understanding they're defeating the primary XSS protection CSP provides. If attackers inject <script> tags, 'unsafe-inline' allows them to execute!

❌ Wrong thinking: "CSP is blocking my inline scripts, so I'll just add 'unsafe-inline' to make it work."

✅ Correct thinking: "CSP is blocking inline scripts because they're a primary XSS vector. I should refactor my code to use external script files or wait for CSP Level 2's nonce/hash approach."

🤔 Did you know? The explicit 'unsafe-' prefix was a deliberate design choice. The CSP working group wanted developers to feel uncomfortable writing these keywords, serving as a constant reminder of the security trade-off.

Critical Limitations of Level 1

While revolutionary, CSP Level 1 had significant limitations that drove the development of subsequent versions:

1. The Inline Code Problem Level 1 offered only a binary choice: block all inline code (script-src 'self') or allow all inline code (script-src 'self' 'unsafe-inline'). There was no middle ground to allow legitimate inline scripts while blocking injected ones. This forced developers to choose between security and compatibility.

2. CDN Whitelist Weakness Whitelisting a CDN domain meant trusting every script on that CDN:

Content-Security-Policy: script-src 'self' https://cdn.example.com

<!-- Both allowed with same directive -->
<script src="https://cdn.example.com/trusted-library-v1.2.3.js"></script>
<script src="https://cdn.example.com/anything-else.js"></script>

If an attacker discovered any script on the whitelisted CDN they could exploit, they could bypass CSP entirely.

3. No Hash or Nonce Support Level 1 couldn't distinguish between different inline scripts or styles, making it impossible to selectively allow specific inline code blocks.

4. Report-Only Mode Challenges While Content-Security-Policy-Report-Only existed for testing, the reporting mechanism was basic and sometimes unreliable.

Browser Adoption Timeline

CSP Level 1 adoption faced a gradual rollout:

📋 Quick Reference Card:

🌐 Browser	📅 Initial Support	🔧 Notes
Chrome 25+	Feb 2013	Full support
Firefox 23+	Aug 2013	Full support
Safari 7+	Oct 2013	Partial initially
IE/Edge 10+	2012	Prefixed, limited
Opera 15+	May 2013	Full support

⚠️ Important: Internet Explorer used a non-standard X-Content-Security-Policy header and supported only a subset of directives. This fragmentation created adoption challenges for sites requiring broad compatibility.

💡 Pro Tip: When implementing CSP Level 1 today, you're essentially implementing the baseline that all modern browsers support. However, you'll want to leverage Level 2 and 3 features for optimal security. Use CSP Level 1 as your compatibility floor, not your ceiling.

The foundation laid by CSP Level 1—the directive architecture, source list syntax, and whitelist model—remains central to all CSP implementations. Understanding these fundamentals is essential because every CSP policy you write, regardless of which advanced features you use, builds upon this original specification. The limitations we've explored directly motivated the powerful enhancements that came in CSP Levels 2 and 3, which we'll examine next.

CSP Level 2 and 3: Advanced Features and Modern Enhancements

While CSP Level 1 established the foundation for content security policies, it struggled with a critical limitation: it forced developers to either allow all inline scripts with 'unsafe-inline' (eliminating much of CSP's protection) or completely refactor their applications to remove inline code. CSP Levels 2 and 3 introduced sophisticated mechanisms that addressed these practical challenges while significantly strengthening security postures.

Level 2: Nonce-Based and Hash-Based Whitelisting

CSP Level 2's most transformative addition was nonce-based whitelisting, which allows specific inline scripts to execute without enabling all inline code. A nonce (number used once) is a cryptographically random string generated by the server for each page load. When you include this nonce in both your CSP header and the nonce attribute of approved inline scripts, the browser will execute only those specific scripts.

Here's how the nonce mechanism works:

Content-Security-Policy: script-src 'nonce-r4nd0m123xyz'

<!-- This script executes -->
<script nonce="r4nd0m123xyz">
  console.log('Approved inline code');
</script>

<!-- This injected script is blocked -->
<script>
  maliciousCode();
</script>

🎯 Key Principle: Nonces must be unpredictable, unique per page load, and never reused. An attacker who can predict your nonce defeats the entire mechanism.

Alternatively, hash-based whitelisting allows you to specify the cryptographic hash of approved inline script content. The browser computes the hash of each inline script and only executes those matching your whitelist:

Content-Security-Policy: script-src 'sha256-xzi4zkCjuC8lZcD2UmnqDG0vurmq12W/XKM5Vd0+MlQ='

<!-- This specific script executes if its hash matches -->
<script>
  console.log('Approved inline code');
</script>

💡 Pro Tip: Hash-based CSP works excellently for static content that doesn't change between deployments, while nonce-based CSP is better for dynamic applications where script content varies.

⚠️ Common Mistake: Mistake 1: Including whitespace or comments in your hash calculation. The hash must match the script content exactly as the browser sees it, including all formatting. ⚠️

The 'strict-dynamic' Keyword: A Modern Architecture

CSP Level 2 also introduced 'strict-dynamic', which fundamentally changes how script trust propagates. With traditional CSP, every script source must be explicitly whitelisted. This becomes unwieldy when trusted scripts dynamically load other scripts (a common pattern in modern applications).

When you use 'strict-dynamic', scripts loaded by already-trusted scripts inherit that trust:

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

<script nonce="abc123">
  // This script is trusted via nonce
  var s = document.createElement('script');
  s.src = 'https://example.com/library.js';
  document.body.appendChild(s);
  // library.js is now trusted because a trusted script loaded it
</script>

The architectural flow looks like this:

┌─────────────────────────────────────────┐
│  CSP: script-src 'nonce-xyz'           │
│       'strict-dynamic'                  │
└─────────────────────────────────────────┘
                  |
                  v
┌─────────────────────────────────────────┐
│  <script nonce="xyz">                  │
│    (Root trusted script)                │
└─────────────────────────────────────────┘
          |                    |
          v                    v
  ┌──────────────┐     ┌──────────────┐
  │ Dynamically  │     │ Dynamically  │
  │ loaded lib A │     │ loaded lib B │
  │ (TRUSTED)    │     │ (TRUSTED)    │
  └──────────────┘     └──────────────┘

🤔 Did you know? When 'strict-dynamic' is present, the browser ignores most allowlist entries including 'self' and https: sources. This prevents attackers from exploiting JSONP endpoints or other whitelisted-but-vulnerable sources.

💡 Mental Model: Think of 'strict-dynamic' as a "trust chain" where the initial nonce or hash is the anchor, and trust flows through script-initiated script loads.

Level 3 Enhancements: Refining the Model

CSP Level 3 continued the evolution with several targeted improvements. The 'unsafe-hashes' keyword addresses a specific gap: allowing inline event handlers when their hash is whitelisted. Without this, you couldn't use hashes for onclick attributes:

Content-Security-Policy: script-src 'unsafe-hashes' 
                          'sha256-hash-of-handler'

<!-- This can now be allowed via hash -->
<button onclick="doSomething()">Click</button>

Level 3 also introduced the worker-src directive specifically for controlling Web Workers and Service Workers, which previously fell under the broader script-src or child-src directives:

Content-Security-Policy: worker-src 'self'; script-src 'strict-dynamic' 'nonce-xyz'

📋 Quick Reference Card: CSP Level Comparison

Feature	🔵 Level 1	🟢 Level 2	🟣 Level 3
🎯 Inline scripts	Only 'unsafe-inline'	Nonces, hashes	+'unsafe-hashes'
🔗 Dynamic loading	Manual whitelist	'strict-dynamic'	Same
👷 Worker control	child-src	Same	worker-src
📊 Reporting	report-uri	+report-to	Enhanced report-to
🛡️ XSS protection	Basic	Strong	Strongest

Migration Strategies: Moving to Modern CSP

Transitioning from Level 1 to modern CSP implementations requires careful planning. The most effective strategy uses a phased approach:

Phase 1: Report-Only Assessment

Deploy a Level 2/3 policy in report-only mode to identify violations without breaking functionality:

Content-Security-Policy-Report-Only: script-src 'strict-dynamic' 'nonce-xyz'; 
                                      report-uri /csp-violations

Phase 2: Hybrid Policy

For browser compatibility, serve both old and new syntax. Modern browsers automatically ignore incompatible keywords:

Content-Security-Policy: script-src 'strict-dynamic' 'nonce-xyz' 
                          https: 'unsafe-inline'

In this configuration, browsers supporting 'strict-dynamic' ignore https: and 'unsafe-inline', while older browsers fall back to the allowlist approach.

Phase 3: Full Migration

Once analytics show sufficient modern browser adoption, remove legacy fallbacks and deploy strict Level 2/3 policies.

⚠️ Common Mistake: Mistake 2: Forgetting that 'strict-dynamic' changes the entire trust model. Don't expect domain allowlists to work alongside it—that's the entire point of the keyword. ⚠️

❌ Wrong thinking: "I'll add 'strict-dynamic' to my existing allowlist-based policy for extra security."

✅ Correct thinking: "'strict-dynamic' represents a different security architecture. I need to rethink my script loading strategy around nonces or hashes as trust roots."

The evolution from CSP Level 1 to Levels 2 and 3 represents a maturation from basic allowlisting to cryptographically-anchored trust models. Modern CSP implementations using nonces with 'strict-dynamic' provide robust XSS protection while remaining practical for complex applications. Understanding these mechanisms enables you to deploy defenses that are both secure and maintainable at scale.

Practical Implementation Across CSP Levels

Understanding CSP theory is one thing; implementing it effectively in real applications is another. Let's walk through practical examples that demonstrate how to build, upgrade, and deploy CSP policies across different levels, making strategic decisions based on your application's needs and browser support requirements.

Building a Level 1 Policy: The Foundation

Imagine you're securing a simple blog application that loads resources from your own domain and a CDN. A Level 1 CSP policy uses whitelisting to define trusted sources for each resource type.

Here's how you build it step-by-step:

Content-Security-Policy: default-src 'self'; 
                         script-src 'self' https://cdn.example.com; 
                         style-src 'self' https://fonts.googleapis.com; 
                         img-src 'self' https://images.example.com data:; 
                         font-src https://fonts.gstatic.com;

This policy establishes that by default (default-src 'self'), all resources must come from your own origin. Then we create specific exceptions: scripts from your domain and a trusted CDN, styles from your domain and Google Fonts, images from your domain and an image CDN (plus data URIs for inline images), and fonts exclusively from Google's font service.

┌─────────────────────────────────────────┐
│  Browser Resource Loading Decision      │
├─────────────────────────────────────────┤
│                                         │
│  Script from cdn.example.com? ✅        │
│  Script from evil.com?        ❌        │
│  Inline <script>?             ❌        │
│  Font from fonts.gstatic.com? ✅        │
│  Style from self?             ✅        │
│                                         │
└─────────────────────────────────────────┘

⚠️ Common Mistake 1: Including 'unsafe-inline' in your Level 1 policy to "make things work." This defeats the primary purpose of CSP by allowing the exact attack vector (inline scripts) that XSS exploits use. ⚠️

💡 Pro Tip: Start with default-src 'none' and explicitly add each directive you need. This deny-by-default approach is more secure than starting permissive and trying to restrict.

Upgrading to Level 2: Nonces and Hashes

Your blog now needs interactive features requiring inline scripts. Level 1 would force you to choose between security and functionality. Level 2 introduces cryptographic nonces and hashes as the solution.

Implementation with nonces requires server-side generation of a unique random value for each request:

// Server-side (Node.js/Express example)
const crypto = require('crypto');

app.use((req, res, next) => {
  res.locals.nonce = crypto.randomBytes(16).toString('base64');
  res.setHeader(
    'Content-Security-Policy',
    `script-src 'self' 'nonce-${res.locals.nonce}'`
  );
  next();
});

<!-- In your template -->
<script nonce="<%= nonce %>">
  // This inline script is now allowed
  document.getElementById('interactive').addEventListener('click', handleClick);
</script>

The nonce acts like a secret handshake: only scripts with the matching nonce attribute execute, while injected scripts without it are blocked.

Hashes provide an alternative for static inline scripts that don't change:

<script>
  console.log('This script never changes');
</script>

Generate the SHA-256 hash of the script content (including whitespace!), then add it to your policy:

Content-Security-Policy: script-src 'self' 'sha256-xyz123abc...'

🎯 Key Principle: Nonces are dynamic and require server-side support; hashes are static and work for unchanging content. Choose based on your architecture.

Real-World Case Study: Strict Level 3 Policy

A financial services application requires maximum security. They deploy a strict CSP using Level 3's 'strict-dynamic' keyword:

Content-Security-Policy: 
  script-src 'nonce-r@nd0m' 'strict-dynamic' https:; 
  object-src 'none'; 
  base-uri 'none';

Here's what makes this powerful: 'strict-dynamic' allows scripts loaded by trusted scripts (those with the correct nonce) to load additional scripts, even from non-whitelisted sources. This solves the third-party library problem where CDN-hosted scripts need to load their own dependencies.

Trust Propagation with 'strict-dynamic':

  [HTML with nonce]  ──trusted──>  [Main Script] 
                                         │
                                         ├──creates──> [Dynamic Script 1] ✅
                                         │
                                         └──creates──> [Dynamic Script 2] ✅

  [Injected Script] ──no nonce──> ❌ BLOCKED

💡 Real-World Example: Google uses strict CSP with 'strict-dynamic' across many of its properties. They found it reduced XSS vulnerabilities by over 95% while maintaining compatibility with modern JavaScript frameworks.

Testing CSP Policies: Developer Tools

Before enforcing any policy, test thoroughly using browser developer tools. Modern browsers provide detailed CSP violation reports in the Console:

🔒 CSP Violation:
   Blocked script from 'https://evil.com/inject.js'
   Violated directive: script-src 'self'
   Document: https://yoursite.com/page.html

The testing workflow:

🔧 Step 1: Deploy using Content-Security-Policy-Report-Only header 🔧 Step 2: Monitor violation reports (browser console or reporting endpoint) 🔧 Step 3: Adjust policy based on legitimate violations 🔧 Step 4: Switch to enforcing mode with Content-Security-Policy

Report-Only Mode: Your Safety Net

Report-only mode lets you validate CSP compatibility without breaking your application:

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

Violations generate reports but don't block resources. You can collect these reports server-side:

// Express endpoint for CSP reports
app.post('/csp-violation-report', express.json({type: 'application/csp-report'}), (req, res) => {
  console.log('CSP Violation:', req.body);
  // Log to your monitoring system
  res.status(204).end();
});

⚠️ Common Mistake 2: Skipping report-only mode and deploying directly to enforcement. You'll inevitably break legitimate functionality that you didn't account for in testing. ⚠️

📋 Quick Reference Card: Choosing Your CSP Level

🎯 Scenario	📊 Recommended Level	🔑 Key Directive
🌐 Legacy browser support	Level 1	`script-src` whitelist
🔧 Modern app with inline scripts	Level 2	`'nonce-xxx'` or `'sha256-xxx'`
🔒 Maximum security, modern browsers	Level 3	`'strict-dynamic'`
🧪 Testing new policy	Any + Report-Only	`Content-Security-Policy-Report-Only`

💡 Remember: You can run both enforcing and report-only policies simultaneously to test stricter rules while maintaining current protection.

By following these implementation patterns, you'll deploy CSP policies that balance security, functionality, and browser compatibility—protecting your users while keeping your application working smoothly across different environments.

Common Pitfalls and Best Practices

Implementing Content Security Policy across different levels and browsers presents numerous challenges that can undermine your security posture or break application functionality. Understanding these common pitfalls and following established best practices will help you deploy CSP effectively while maintaining compatibility.

Misconception: Universal Browser Support for Latest CSP Features

❌ Wrong thinking: "I'll just use CSP Level 3 features everywhere since the spec is published."

✅ Correct thinking: "I need to check browser support data and implement progressive enhancement with fallbacks."

One of the most pervasive misconceptions is assuming that all browsers support the latest CSP level uniformly. The reality is far more complex. Browser support is fragmented across CSP levels, with some browsers implementing Level 3 features before fully supporting all Level 2 directives. For example, Safari lagged significantly in supporting strict-dynamic, while Chrome implemented it early. Some browsers may silently ignore unsupported directives, while others might reject the entire policy.

💡 Pro Tip: Always check caniuse.com for current CSP feature support before deploying specific directives. Use tools like report-uri.com or csper.io to monitor policy violations across different browser versions in production.

🎯 Key Principle: Implement progressive enhancement by providing a baseline CSP Level 1 policy with Level 2/3 enhancements that gracefully degrade. For instance:

Content-Security-Policy: 
  script-src 'nonce-abc123' 'strict-dynamic' https: 'unsafe-inline';

This policy works across CSP levels: Level 3 browsers use nonce + strict-dynamic, Level 2 uses nonce (ignoring strict-dynamic), and Level 1 falls back to https: (with unsafe-inline ignored in modern browsers but present for ancient ones).

Mistake 1: Over-Relying on 'unsafe-inline' During Migration ⚠️

When migrating from no CSP to CSP Level 1, developers often include 'unsafe-inline' as a temporary measure to avoid breaking existing inline scripts. The critical mistake is leaving it there permanently.

⚠️ Common Mistake: Adding 'unsafe-inline' "just to be safe" even when using nonces or hashes in Level 2+. This completely negates your CSP protection against XSS attacks.

The proper migration path follows this progression:

Phase 1 (Report-Only):  script-src 'unsafe-inline' https:
Phase 2 (Enforcement):  script-src 'unsafe-inline' https:
Phase 3 (Transition):   script-src 'nonce-...' 'unsafe-inline' https:
Phase 4 (Secure):       script-src 'nonce-...' https:
Phase 5 (Modern):       script-src 'nonce-...' 'strict-dynamic'

🤔 Did you know? When nonces or hashes are present in CSP Level 2+ browsers, 'unsafe-inline' is automatically ignored for scripts. However, it still weakens protection in older browsers, so remove it once you've verified compatibility.

Pitfall: Incorrect Nonce Implementation

Nonce implementation errors are among the most common CSP failures. Three critical mistakes stand out:

1. Reusing nonces across requests

<!-- ❌ WRONG: Static nonce defeats the purpose -->
<script nonce="always-the-same-value">
  doSomething();
</script>

Nonces must be cryptographically random and unique per request. Reusing nonces makes them predictable, allowing attackers to inject scripts with the known nonce value.

2. Breaking HTTP caching with nonces

A subtle but devastating mistake is applying nonces to cacheable resources:

<!-- ❌ WRONG: External scripts can't have dynamic nonces -->
<script src="/static/app.js" nonce="random-per-request"></script>

This breaks caching because the HTML references a nonce that changes with each request, but the cached script has a different nonce. The solution: use hashes for static content and nonces only for inline scripts.

3. Single-Page Application (SPA) nonce problems

In SPAs, dynamically injected scripts often fail because they lack the proper nonce:

// ❌ WRONG: Dynamically created script without nonce
const script = document.createElement('script');
script.textContent = 'console.log("Hello")';
document.body.appendChild(script); // CSP violation!

💡 Real-World Example: For SPAs, use 'strict-dynamic' to allow dynamically created scripts from trusted sources, or implement a system to propagate nonces to framework-generated scripts. Frameworks like React and Angular have specific CSP integration patterns.

Browser-Specific Quirks and Vendor Prefixes

Different browsers have historically implemented CSP with variations:

Vendor prefix handling:

Older browsers required X-WebKit-CSP (Safari, Chrome) or X-Content-Security-Policy (Firefox, IE)
Modern approach: Always use standard Content-Security-Policy header
For legacy support (pre-2016 browsers), send multiple headers:

Content-Security-Policy: default-src 'self'
X-WebKit-CSP: default-src 'self'
X-Content-Security-Policy: default-src 'self'

Safari-specific issues:

Safari 15.4 finally added strict-dynamic support (years after other browsers)
Safari treats data: URIs differently in certain contexts
Older Safari versions had issues with hash algorithms

Internet Explorer quirks:

IE 10-11 only support CSP Level 1 (no nonces/hashes)
IE uses X-Content-Security-Policy header with limited directive support
sandbox directive works differently in IE

Best Practices for Feature Detection and Graceful Degradation

🎯 Key Principle: Always implement defense in depth by combining CSP levels rather than relying on a single approach.

1. Use report-uri and report-to together

Content-Security-Policy: 
  default-src 'self';
  report-uri /csp-report;
  report-to csp-endpoint

Level 3's report-to isn't universally supported, so include Level 2's report-uri as fallback.

2. Implement layered script protection

script-src 
  'nonce-{random}'          /* Level 2: Inline scripts */
  'strict-dynamic'          /* Level 3: Allow dynamic loads */
  https:                    /* Level 1: Fallback whitelist */
  'unsafe-inline'           /* Ancient browser fallback */

3. Monitor policy effectiveness

Don't deploy CSP blindly. Use Report-Only mode extensively:

Content-Security-Policy-Report-Only: ...

Analyze violation reports for at least two weeks across different browsers before switching to enforcement mode.

4. Test across browser versions

Create a testing matrix:

Browser	Version	CSP Level	Test Status
🦊 Firefox	Latest, ESR	Level 3	✅ Tested
🔵 Chrome	Latest, -2	Level 3	✅ Tested
🧭 Safari	Latest, -1	Level 2/3*	⚠️ Partial
📘 Edge	Latest	Level 3	✅ Tested

💡 Pro Tip: Use automated CSP testing tools like csp-evaluator.withgoogle.com to identify policy weaknesses before deployment.

📋 Quick Reference Card: CSP Pitfall Checklist

⚠️ Pitfall	🔧 Solution	🎯 Priority
Static/reused nonces	Generate cryptographically random nonces per request	🔴 Critical
Nonces on cached resources	Use hashes for static files, nonces for inline only	🔴 Critical
Missing fallback directives	Layer Level 1/2/3 features for progressive enhancement	🟡 Important
Assuming universal support	Check caniuse.com and test across browser versions	🟡 Important
Permanent 'unsafe-inline'	Remove after migration to nonces/hashes	🔴 Critical
No violation monitoring	Implement report-uri/report-to with analysis	🟡 Important
SPA dynamic script blocking	Use 'strict-dynamic' or framework-specific CSP integration	🟢 Recommended

Summary

You now understand the critical implementation challenges that can undermine CSP security or break application functionality. Before reading this section, you might have assumed CSP implementation was straightforward—just add a header and you're protected. Now you recognize that effective CSP requires careful attention to browser compatibility, proper nonce/hash implementation, and progressive enhancement strategies.

Key insights you've gained:

🧠 Browser support is fragmented across CSP levels, requiring feature detection and graceful degradation rather than assuming uniform support

🔒 Nonce implementation has three critical failure modes: reuse across requests, breaking caching, and SPA compatibility issues—each requiring specific solutions

📊 Layered security combining multiple CSP levels provides the best protection while maintaining backward compatibility

⚠️ Critical points to remember:

Never reuse nonces—they must be cryptographically random per request
Use hashes for static cached content, nonces only for inline scripts
Always test CSP in Report-Only mode before enforcement
Remove 'unsafe-inline' once you've verified nonce/hash implementation

Practical Next Steps

1. Audit your current CSP implementation using Google's CSP Evaluator and your violation reports to identify gaps and browser-specific issues

2. Implement a CSP testing pipeline that validates your policy across major browser versions before deployment, particularly testing nonce generation and SPA dynamic script loading

3. Develop a migration roadmap if you're currently using 'unsafe-inline', planning the transition through progressive tightening of your policy while monitoring violation reports

With this knowledge of common pitfalls and best practices, you're equipped to implement CSP that provides real security benefits while maintaining application functionality across diverse browser environments.

📝

Ready to practice?

This lesson has 15 questions to help you learn