# Brave Ad-Blocking Engine: How adblock-rust Powers Network and Cosmetic Filtering

> Discover Brave ad-blocking engine adblock-rust. Learn how this native Rust library implements Adblock Plus and uBlock Origin filter syntax powering network and cosmetic filtering in Brave Browser.

- Repository: [Brave Software/brave-browser](https://github.com/brave/brave-browser)
- Tags: internals
- Published: 2026-02-16

---

**Brave's ad-blocking engine is adblock-rust, a native Rust library that implements Adblock Plus/uBlock Origin filter syntax with Brave-specific extensions, exposed to Chromium via a C FFI layer called adblock_rust_ffi.**

The `brave/brave-browser` repository integrates this engine to provide high-performance content blocking across all platforms. Unlike JavaScript-based blockers, adblock-rust compiles to native code, enabling Brave to parse and match filter lists with minimal memory overhead while supporting advanced features like procedural selectors and CNAME decloaking.

## What Is Brave’s Ad-Blocking Engine?

Brave’s ad-blocking capability centers on **adblock-rust**, an open-source Rust crate maintained in the separate `brave/adblock-rust` repository. This engine implements the full Adblock Plus and uBlock Origin filter syntax, including network request blocking, cosmetic filtering, and scriptlet injection.

The library extends standard filter capabilities with Brave-specific features:

- **Procedural selectors** (`:-abp-has()`, `:has-text()`)
- **$removeparam** option for stripping tracking parameters from URLs
- **CNAME decloaking** to uncover trackers hidden behind canonical name records
- **Binary filter list format** for faster startup and lower memory usage

## Architecture of adblock-rust: From C++ to Rust

Brave’s browser code is primarily C++ built on Chromium. To integrate the Rust-based engine without rewriting the browser, Brave uses a three-layer architecture:

```

+---------------------------+      +---------------------------+
|  Chromium/Brave C++ code  | <--> |   adblock_rust_ffi (C)   |
+---------------------------+      +---------------------------+
                                      |
                                      v
                           +---------------------------+
                           |   adblock-rust (Rust)     |
                           +---------------------------+

```

### The FFI Bridge (adblock_rust_ffi)

The `adblock_rust_ffi` layer lives inside `brave-core` at [`components/adblock_rust_ffi/src/lib.rs`](https://github.com/brave/brave-browser/blob/main/components/adblock_rust_ffi/src/lib.rs). This crate provides a stable C API that wraps the Rust engine, handling:

- **Memory safety**: Rust ownership rules prevent use-after-free errors when C++ destroys engine instances
- **Thread safety**: Public FFI functions use `Mutex` and `RwLock` to protect mutable state across threads
- **Data translation**: Converting between C++ `std::string` and Rust `String` types

Key FFI functions exposed to the browser include:

- `Engine_Create()` – Initializes a new blocking engine
- `Engine_Match()` – Checks if a URL should be blocked
- `Engine_AddFilterList()` – Ingests filter list text or binary data
- `Engine_Update()` – Refreshes filter lists from the component updater
- `Engine_Destroy()` – Frees engine memory

### The Rust Core (adblock-rust)

The `adblock-rust` crate contains the actual blocking logic. When the FFI layer calls into Rust, it delegates to several specialized modules:

- **[`src/engine.rs`](https://github.com/brave/brave-browser/blob/main/src/engine.rs)** – Core matching engine that coordinates network and cosmetic filtering
- **[`src/parser.rs`](https://github.com/brave/brave-browser/blob/main/src/parser.rs)** – Parses raw filter list text into `FilterSet` structures, handling `!` comments, `$` options, and procedural selectors
- **[`src/cosmetic.rs`](https://github.com/brave/brave-browser/blob/main/src/cosmetic.rs)** – Generates CSS hiding rules and JavaScript scriptlets for cosmetic filtering
- **[`src/procedural.rs`](https://github.com/brave/brave-browser/blob/main/src/procedural.rs)** – Implements Brave-specific extensions like `:-abp-has()` and CNAME decloaking logic

The engine supports multiple input formats: plain text (EasyList, EasyPrivacy), binary protobuf for compressed storage, and gzip-compressed lists for network transfer.

## Implementation Examples

### Initializing the Engine from C++

Brave’s C++ code initializes the blocking engine through the FFI layer:

```cpp
#include "adblock_rust_ffi.h"

// Create a new engine instance
AdblockEngine* engine = Engine_Create();

// Load a filter list from URL or local storage
Engine_AddFilterList(engine, "https://easylist.to/easylist/easylist.txt");

// Check if a request should be blocked
bool is_blocked = Engine_Match(
    engine,
    "https://ads.example.com/banner.jpg",
    "document",           // resource type
    "GET"                 // HTTP method
);

// Update filter lists from component updater
Engine_Update(engine);

// Cleanup when done
Engine_Destroy(engine);

```

### Direct Rust API Usage

For developers working directly with the `adblock-rust` crate, the API looks like this:

```rust
use adblock_rust::{Engine, Request, EngineOptions};

// Initialize with default options
let mut engine = Engine::new(EngineOptions::default());

// Add filter lists
engine.add_filter_list("https://easylist.to/easylist/easylist.txt")
    .expect("Failed to load filter list");

// Create a request to check
let request = Request::new(
    "https://ads.example.com/banner.jpg",
    "document",
    "GET"
);

// Check match result
let result = engine.matches(&request);
if result.is_blocked() {
    println!("Request blocked by filter: {:?}", result.filter);
}

```

## Brave-Specific Extensions

Beyond standard Adblock Plus syntax, `adblock-rust` implements several Brave-specific features in [`src/procedural.rs`](https://github.com/brave/brave-browser/blob/main/src/procedural.rs):

- **$removeparam**: Strips tracking parameters from URLs before they are requested
- **CNAME decloaking**: Resolves canonical DNS names to reveal trackers hiding behind first-party domains
- **Procedural selectors**: Supports `:has()`, `:has-text()`, and other complex DOM-matching rules for cosmetic filtering

These extensions are exposed through the same FFI interface, allowing the C++ layer to request advanced filtering operations without knowing the underlying implementation language.

## Summary

- **adblock-rust** is Brave’s native Rust library implementing Adblock Plus/uBlock Origin filter syntax with proprietary extensions
- The engine integrates into Brave via **adblock_rust_ffi**, a C FFI layer in [`brave-core/components/adblock_rust_ffi/src/lib.rs`](https://github.com/brave/brave-browser/blob/main/brave-core/components/adblock_rust_ffi/src/lib.rs)
- Key FFI functions include `Engine_Create`, `Engine_Match`, and `Engine_AddFilterList`, wrapping Rust implementations in [`src/engine.rs`](https://github.com/brave/brave-browser/blob/main/src/engine.rs) and [`src/parser.rs`](https://github.com/brave/brave-browser/blob/main/src/parser.rs)
- The architecture provides memory-safe, thread-safe, high-performance blocking across Windows, macOS, Linux, Android, and iOS
- Brave-specific features like `$removeparam`, CNAME decloaking, and procedural selectors are implemented in [`src/procedural.rs`](https://github.com/brave/brave-browser/blob/main/src/procedural.rs)

## Frequently Asked Questions

### What programming language is Brave’s ad-blocking engine written in?

Brave’s ad-blocking engine is written in **Rust**. The core library, `adblock-rust`, is maintained as a separate open-source repository and compiled to native code for performance and memory safety. It connects to Brave’s C++ codebase through a thin FFI layer.

### How does Brave’s adblock-rust differ from uBlock Origin?

While both implement the same filter syntax (EasyList, EasyPrivacy), **adblock-rust** is a native library compiled into the browser, whereas uBlock Origin is a JavaScript extension. This gives Brave lower-level access to network requests and CNAME resolution, enabling features like CNAME decloaking that JavaScript extensions cannot perform. Additionally, adblock-rust supports Brave-specific options like `$removeparam` and binary filter list formats for faster startup.

### Where is the FFI layer located in the Brave source code?

The FFI layer is located at **[`components/adblock_rust_ffi/src/lib.rs`](https://github.com/brave/brave-browser/blob/main/components/adblock_rust_ffi/src/lib.rs)** inside the `brave-core` repository. This file defines the C-compatible functions (like `Engine_Create` and `Engine_Match`) that bridge Brave’s C++ code with the Rust `adblock-rust` engine. The layer handles memory management, thread safety via `Mutex` and `RwLock`, and data structure translation between C++ and Rust.

### Can adblock-rust be used outside of Brave?

Yes. The **`adblock-rust`** crate is published as open source and can be integrated into any Rust project or exposed via FFI to other languages. While the `adblock_rust_ffi` layer is specific to Brave’s Chromium integration, the underlying Rust library is generic and implements standard filter list parsing and matching that works independently of the Brave browser.