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

> Learn how the unique $csp= option in uBlock Origin lets you inject custom Content-Security-Policy headers for server-side control of website resources and scripts.

- Repository: [Raymond Hill/uBlock](https://github.com/gorhill/uBlock)
- Tags: deep-dive
- Published: 2026-03-05

---

**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`](https://github.com/gorhill/uBlock/blob/main/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`](https://github.com/gorhill/uBlock/blob/main/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:

```text
*$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:

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

```

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

```text
*$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:

```text
*$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:

```text
||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`](https://github.com/gorhill/uBlock/blob/main/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`](https://github.com/gorhill/uBlock/blob/main/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.