How Chromium's declarativeNetRequest Protects Browsing Data

This article explains how the Chromium web browser's declarativeNetRequest (DNR) API evaluates network blocking rules while preserving user privacy. By shifting the rule evaluation process from the extension's background environment directly into the browser's native code, Chromium allows extensions to block, redirect, and modify network requests without ever exposing the user's browsing history or sensitive request data. Below, we examine the core mechanisms of this API, including upfront rule registration, native browser compilation, and isolated runtime execution.

The Shift from Imperative to Declarative Filtering

To understand how the declarativeNetRequest API protects privacy, it is necessary to look at how network filtering worked previously. Under the older webRequest API, filtering was imperative. For every single network request a user made, the browser had to pause the request, send the full URL and headers to the extension, wait for the extension's JavaScript to analyze the data, and then execute the extension's return command. This meant the extension had full visibility into every website the user visited.

The declarativeNetRequest API reverses this model. Instead of the browser sending user data to the extension for evaluation, the extension sends its rules to the browser in advance. The browser then handles all the evaluation internally, acting as a secure firewall between the user's network traffic and the extension.

Upfront Rule Registration

With the DNR API, extensions do not write dynamic code to inspect live traffic. Instead, they provide the browser with static or dynamic rulesets formatted in JSON. Each rule consists of two main parts:

  1. Conditions: Criteria that trigger the rule, such as a specific URL pattern, domain name, or resource type (like an image, script, or stylesheet).
  2. Actions: What the browser should do when the conditions are met, such as blocking the request, upgrading the scheme to HTTPS, redirecting to a different URL, or modifying request and response headers.

Once the extension hands these JSON files over to Chromium, its direct involvement in the filtering process ends.

Browser-Side Compilation and Indexing

When an extension is installed, updated, or registers new dynamic rules, Chromium ingests the JSON rulesets. Because parsing JSON for every single network request would be too slow, the browser compiles these rules into a highly optimized, indexed binary format known as FlatBuffers.

This compiled data structure is stored locally within the browser's internal memory space. By indexing the rules by domain fragments and URL patterns, Chromium prepares them for near-instantaneous lookup using its native C++ code.

Native Network Stack Evaluation

When a user navigates to a webpage, the browser's network stack generates dozens of requests to fetch HTML, scripts, and media. Here is how Chromium evaluates these requests privately:

  • In-Process Interception: As a request is initiated, the Chromium network process intercepts it before it leaves the device.
  • Native Matching: The browser checks the request's URL, initiator domain, and resource type directly against the compiled FlatBuffers index. This happens entirely within Chromium's native C++ engine.
  • Action Execution: If a match is found, the browser immediately applies the specified action (e.g., dropping the connection for a block rule). If multiple extensions have matching rules, the browser resolves the conflict based on a strict priority system—for example, block rules always override redirect rules.

Throughout this entire lifecycle, the extension's background service worker remains completely dormant. No data is passed to the extension's JavaScript runtime, making it impossible for the extension to log, read, or exfiltrate the URLs the user is visiting.

Strict Permission Isolation

A critical feature of the DNR architecture is that extensions do not need broad host permissions (the ability to read and change data on all websites) to perform basic network blocking or HTTPS upgrades.

If an extension wants to know if its rules are working, it cannot ask the browser for a list of blocked URLs. By default, the browser only allows the extension to display an aggregate count of matched rules on its toolbar badge—a process also handled natively by the browser so the extension doesn't even know when a rule was triggered. The extension is completely blind to the user's activity, ensuring that network filtering is both high-performance and private by design.