Web Request and Declarative Net Request: Explaining the impact on Extensions in Manifest V3

June 12th, 2019

The Story So Far

As part of an effort to increase user security and privacy, Chrome is planning a number of changes to the extensions platform. We announced some of these changes last October, and have provided additional context on them today. These changes to the platform are being implemented as part of Manifest V3 – the next version of the Chrome Extensions platform.

One of these changes is to move away from the blocking version of the Web Request API towards a new API, called Declarative Net Request. There’s been a lot of confusion and misconception around both the motivations and implications of this change, including speculation that these changes were designed to prevent or weaken ad blockers. This is absolutely not the goal. In fact, this change is meant to give developers a way to create safer and more performant ad blockers.

In order to improve the security and privacy guarantees of the extensions platform, we are rethinking some of the extension platform’s core APIs. That’s why we’re planning to replace the blocking Web Request API with the Declarative Net Request API.

How Web Request Works

With Web Request, Chrome sends all the data in a network request to the listening extension – including any sensitive data contained in that request like personal photos or emails. The extension has a chance to evaluate the request, and then tells Chrome what to do with the request: allow it, block it, or send it with some modifications. As a result, extensions that leverage the Web Request API typically have access to read and manipulate everything a user does on the web.

Web Request and Declarative Net Request: Explaining the impact on Extensions in Manifest V3

While this API is used by good actors to implement powerful features like content blockers, it can also be – and has been – abused. Because all of the request data is exposed to the extension, it makes it very easy for a malicious developer to abuse that access to a user’s credentials, accounts, or personal information. Since January 2018, 42% of malicious extensions use the Web Request API.

In addition to these safety concerns, there are also significant performance costs. In most cases, these costs are not from the evaluation of the extension script processing events, but rather from everything else coordinating the script. That overall performance impact can be very large, even for an extension written as performantly as possible where the JavaScript execution time is negligible.

As it’s designed today, the blocking version of the Web Request API requires a persistent, long-running process, and is fundamentally incompatible with “lazy” processes – processes that can be set up or torn down as-needed, conserving valuable system resources. There are also significant costs associated with the serialization of the request data, the inter-process communication needed to send that data to the extensions, and the processing of extension responses.

Enter Declarative Net Request

The Declarative Net Request API works differently than the Web Request API. Instead of Chrome sending all the information about a request to the listening extensions at the time of the request, extensions register rules that tell Chrome what to do if certain types of requests are seen.

Web Request and Declarative Net Request: Explaining the impact on Extensions in Manifest V3

This approach has advantages for both user security and privacy, as well as performance. With a declarative approach, Chrome does not need to expose any sensitive data to the extension. The browser can perform the action requested by the extension without sending it all the data associated with the network request, because the extension already specified the conditions under which different actions are taken. This enables the extension to perform content blocking without needing access to all of a user’s personal information.

This has significant performance implications. Most importantly, a persistent, long-running process is no longer necessary because rules are registered before requests are made rather than needing to process them at runtime. This also cuts down on the cost of serializing all the request data and shuttling the inter-process messages to the listening extensions.

These performance improvements will make extensions significantly more viable on resource-constrained platforms.

Why Not Both?

In addition to the performance concerns raised above, the Chrome team strongly believes that users should not have to expose their emails, photos, social media, or any other sensitive data to an extension if the extension doesn’t actually need that access to perform its function. And historically, when extension developers are given the choice between capability and security, the vast majority of developers choose capability. We’ve seen this repeatedly on the extensions platform with event pages, optional permissions, and activeTab.


Enterprises, schools, and businesses often require different network and software controls to comply with corporate policies. Additionally, these organizations typically have administrators whose role it is to understand and set up their environments.

Chrome provides enterprise controls through its administrator policies. The blocking version of the Web Request API remains available for managed extensions because of the deep integrations that enterprises may have between their software suites and Chrome. System administrators can continue to manage Chrome in enterprise environments for free using OS-provided mechanisms to deploy Chrome policies.

Moving Forward

Declarative Net Request, and the whole of Manifest V3, is still very much in design and development. We are continuing to iterate on it, responding to community feedback and working with developers to help support different use cases.

Since the original announcement of the Declarative Net Request API, we have added significant functionality to the API as a result of these discussions. The Declarative Net Request API now allows for the registration and removal of dynamic rules – specified at runtime rather than statically in the manifest. We’ve also added the capability to remove common tracking headers, such as Referer, Cookie, and Set-Cookie.

We are actively exploring other ways to expand this API, including adding methods to get feedback about matched rules, and support for richer redirects leveraging URL manipulation and regular expressions. Additionally, we are currently planning to change the rule limit from maximum of 30k rules per extension to a global maximum of 150k rules.

We will continue working with the developer community moving forward. We understand that adopting Manifest V3 will require developers to update their extensions and we will continue to support them through this transition.

Posted by Simeon Vincent, Developer Advocate for Chrome Extensions