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

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. 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 – Core matching engine that coordinates network and cosmetic filtering
• src/parser.rs – Parses raw filter list text into FilterSet structures, handling ! comments, $ options, and procedural selectors
• src/cosmetic.rs – Generates CSS hiding rules and JavaScript scriptlets for cosmetic filtering
• 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:

#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:

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:

• $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
• Key FFI functions include Engine_Create, Engine_Match, and Engine_AddFilterList, wrapping Rust implementations in src/engine.rs and 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

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 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.

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