What Is the `$csp=` Option in uBlock Origin Filters? A Complete Technical Guide

The $csp= filter modifier injects custom Content-Security-Policy headers into HTTP responses, enabling fine-grained control over resource loading and script execution via static filtering rules.

The $csp= option is a network-filter modifier in uBlock Origin that lets you append Content-Security-Policy (CSP) directives to specific HTTP responses. According to the gorhill/uBlock source code, this feature parses CSP directives from filter rules and injects them during request processing, providing a mechanism to mitigate XSS attacks and restrict resource loading on matched domains.

How $csp= Works Under the Hood

Understanding the internal pipeline helps you write more effective rules. The implementation spans three main stages: parsing, storage, and injection.

Parsing and Modifier Recognition

When uBlock Origin compiles filter lists, the static-filtering parser scans each rule for net-options. Upon encountering $csp=, it recognizes the option name csp and creates a modifier of type MODIFIER_TYPE_CSP (value 4). This logic resides in src/js/static-net-filtering.js around lines 88-90, where the parser assigns the CSP bitmask (CSP_REALM) to identify these modifiers during subsequent processing.

Storage in the Static Filtering Engine

Once parsed, the modifier enters the compiled static filter database. The CompiledListReader and StaticNetFilteringEngine handle storage, ensuring that CSP directives remain associated with their target URL patterns. This compiled representation allows for efficient lookup during runtime without re-parsing the original filter text.

Runtime Header Injection

During request processing, uBlock Origin intercepts the response before it reaches the browser. In src/js/traffic.js, the injectCSP function performs the following steps (lines 59-66):

1. Collects built-in CSP policies (such as no-scripting blocks)
2. Calls staticNetFilteringEngine.matchAndFetchModifiers(fctxt, 'csp') to retrieve matching $csp= rules
3. Merges all directives into a comma-separated list
4. Adds the final Content-Security-Policy header to the HTTP response (lines 29-33)

Syntax and Practical Examples

The $csp= modifier accepts any valid CSP directive string. You can combine it with other modifiers to create sophisticated filtering logic.

Basic CSP Injection Rules

To block all resource loading on every request, use a global rule with a restrictive policy:

*$csp=default-src 'none'

This appends Content-Security-Policy: default-src 'none' to every matching HTTP response, effectively preventing scripts, images, and stylesheets from loading.

Combining Modifiers for Complex Rules

Chain $csp= with action modifiers like empty or redirect to both modify headers and block content:

*$csp=default-src 'none',empty,xhr

This rule applies only to XMLHttpRequest (xhr) connections, returns an empty response body, and injects the CSP header.

*$csp=default-src 'none',redirect=empty

Here, the request is redirected to an empty resource while simultaneously receiving the CSP header.

Resource-Type Targeting

You can restrict CSP injection to specific resource types. As noted in CHANGELOG.md (line 80), version 1.66.0 expanded support for $csp= when using resource-type options:

*$csp=script-src 'none',object

This injects the CSP header only for object-type resources (like Flash or Java applets), leaving other content unaffected.

Whitelisting and Allow Rules

Users can suppress CSP injection using allow rules. When an allow rule matches, it prevents the modifier from executing:

||example.com^$csp=default-src 'none',allow

Despite matching the $csp= condition, the allow modifier cancels the header injection for example.com requests.

Override and Exception Handling

The $csp= modifier respects uBlock Origin's dynamic filtering hierarchy. In src/js/traffic.js (lines 70-84 and 87-104), the code checks for allow rules before finalizing header injection. This means:

• Static allow rules ($allow) take precedence over $csp= directives
• Dynamic firewall rules created in the logger can whitelist requests and prevent CSP injection
• Built-in policies and filter-based CSPs merge additively unless explicitly blocked

The directive merging process (lines 29-33) combines multiple CSP sources into a single header value, ensuring that stricter policies accumulate while respecting any cancellation signals from allow rules.

Summary

• $csp= is a network-filter modifier that injects Content-Security-Policy headers into HTTP responses
• The parser creates a MODIFIER_TYPE_CSP modifier (value 4) stored in the compiled filter list
• Traffic.js handles runtime injection via injectCSP, merging directives from multiple sources
• Rules support resource-type targeting (script, xhr, object, etc.) and combine with other modifiers like empty or redirect
• Allow rules override $csp= directives, enabling site-specific whitelisting

Frequently Asked Questions

What does the $csp= modifier do in uBlock Origin?

The $csp= modifier allows filter authors to append custom Content-Security-Policy headers to HTTP responses. When a request matches a filter containing this option, uBlock Origin adds the specified CSP directive (such as script-src 'none') to the response headers before the browser processes the content, providing granular control over resource execution.

How do I whitelist a site to prevent CSP injection?

Append the allow modifier to your filter rule. For example, ||example.com^$csp=default-src 'none',allow creates an exception that matches the CSP rule but cancels the header injection. Alternatively, create a dynamic allow rule in the uBlock Origin logger, which overrides static CSP filters according to the precedence logic in src/js/traffic.js.

Can $csp= be combined with other filter modifiers?

Yes. $csp= works alongside modifiers like empty, redirect, important, and resource-type options (e.g., script, xhr, object). The parser processes these sequentially, allowing you to block a request entirely while simultaneously injecting security headers, or restrict the rule to specific resource types only.

What resource types support the $csp= option?

The modifier theoretically supports any resource type, but explicit support for object-type filters gained stability in version 1.66.0. You can target scripts, images, stylesheets, XHR requests, or objects specifically by adding the resource-type option after the CSP directive, ensuring the header only appears on relevant responses.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}