Dynamic filtering: rule syntax - uBlockOrigin/uBlock-issues GitHub Wiki

Back to "Dynamic-filtering"

A dynamic filtering rule is made of four components: a source, a destination, a request type, and then a keyword which tells what to do with a request which happens to match the three former components:

source destination type action

Valid rules:

Source hostname always corresponds to the hostname extracted from the URL of the web page in the browser.

The destination hostname corresponds to the hostname extracted from the URL of a remote resource which the web page is fetching (or trying to).

---

Tip:

In specific cases Dynamic URL filtering will allow for greater accuracy when controlling destination URL.

---

A rule always automatically propagates to all subdomains of the source hostname and all subdomains of the destination hostname -- unless the rule is overridden by a narrower rule in one of the subdomains.

Given that rules always propagate to subdomains, there is no need to prefix the hostname part with a wildcard *., doing so is invalid and will cause the the rule to be discarded.

By default uBO also applies some special behind-the-scene scope rules:

• Behind the scene network requests
• https://github.com/uBlockOrigin/uBlock-issues/discussions/3226

The type is the type of the fetched resource.

A request can be blocked (block), allowed (allow), or ignored (noop). A noop rule will cause matching network requests to be ignored by the dynamic filtering engine, but those ignored network requests will still be subjected to static filtering (filter lists).

Type-based rules are used to filter specific types of request on a web page. Currently, seven types of network request exist which can be dynamically filtered:

• *: any type of request
• image: images
• 3p: any request which 3rd-party to the web page
• inline-script: inline script tags, i.e. scripts embedded in the main document
• 1p-script: 1st-party scripts, i.e. scripts which are pulled from the same domain name of the current web page
• 3p-script: 3rd-party scripts, i.e. scripts which are pulled from a different domain name than that of the current web page
• 3p-frame: 3rd-party frames, i.e. frames elements which are pulled from a different domain name than that of current web page

These rules can apply everywhere, or be specific to a website. For instance blocking 3rd-party frames is a very good habit security-wise: * * 3p-frame block. This rule translates into "globally block 3rd-party frames".

Another example: wired.com * image block, which means "block images from all origins when visiting a web page on wired.com".

Note that with type-based rules, the destination hostname is always *, meaning "from anywhere".

Hostname-based rules are used to filter network resources according to their origin, i.e. according to which remote server a resource is pulled. Hostname-based rules have a higher specificity than type-based rules, and thus hostname-based rules always override type-based rules whenever a network request end up matching both a type- and a hostname-based rule.

With hostname-based rule, the request type is always *, meaning the rule will apply to any type of request.

For example, * disqus.com * block means "globally block all net requests to disqus.com".

Just like type-based rules, a hostname-based rule can apply only when visiting a specific website, for example: wired.com disqus.com * noop, which means "do not apply dynamic filtering to network requests to disqus.com when visiting a web page on wired.com. Since this last rule is more specific than the previous one, it will override the global blocking of disqus.com everywhere.

A matching rule can do one of three things:

• block: matching network request will be blocked.
  • block dynamic filter rules override any existing static exception filters.
  • Thus you can use them to block with 100% certainty (unless you set another overriding dynamic filter rule).
• allow: matching network request will be allowed.
  • allow dynamic filters rules override any existing static and dynamic block filters.
  • Thus they are most useful to create finer-grained exceptions, and to un-break websites broken by some static filters somewhere.
• noop: exclude network requests from being subjected to dynamic filtering.
  • It cancels dynamic filtering, but it does not cancel static filtering.

Source: How to make dynamic filters static?