Static filter syntax

gwarser edited this page Sep 17, 2018 · 62 revisions

uBlock Origin ("uBO") supports Adblock Plus ("ABP") filter syntax, so you can refer to existing filter syntax documentation from Adblock Plus web site and ABP's filter cheatsheet.

However uBO does not support some very specific cases, and also adds its own extensions to ABP filter syntax (which at time of writing are not recognized by ABP).

Not supported

document for exception filters (those prefixed with @@):

Not supported. The purpose of the document option when used with an exception filter is to disable uBO completely. The purpose of the document option in static exception filters is mostly for the sake of "acceptable ads" support, which uBO does not support.

The reason it is not supported is to be sure that users explicitly disable uBO themselves if they wish (through whitelisting), not having some external filter list decide for them.

genericblock:

Not supported.

This option is meant to be used with an exception filter to disable generic network filters on target pages. Generic in this case means network filters without a domain= filter option. Filters such as ||example.com^ are still considered generic.

This option is not supported because using such filter option would cause large amount of filters to be silently disabled for a site where it's used.

For instance, when used for a specific site, the genericblock option would cause all the filters in hosts files to be disabled, including those from the malware lists. EasyPrivacy and other anti-tracking lists also contain countless so-called "generic" filters, and as a consequence these would also end up being disabled.

elemhide:

Translated internally to generichide. elemhide is used with exception filters to disable all cosmetic filtering on page, this can be achieved by "No cosmetic filtering" switch.

Keep in mind generichide is a cosmetic filtering-related option, and as such using it has no negative consequence with regard to privacy since cosmetic filtering has no privacy value.

Pre-parsing directives

uBO v1.16.0 and above supports pre-parsing directives. Pre-parsing directives are prefixed with !#, so this means older versions of uBO or other blockers will see the pre-parsing directives as comment and discard them.

The pre-parsing directives are executed before a list content is parsed, and influence the final content of a filter list.

!#include [file name]

The !#include directive allows to import another filter list in place where the directive appears. The purpose is to allow filter list maintainers to create filters which are specific to uBO, while keeping their list compatible with other blockers. Other blockers will ignore the !#include directive, because it will be seen as a comment and thus discarded. uBO will attempt to load the resource found at [file name] (the sub-list) and load its content into the current list.

The sub-list must be in the same directory as the main one, i.e. it is not allowed to load a sub-list which is located outside where the current one resides.

Correct usage:

  • !#include ublock-filters.txt
  • !#include ublock/filters.txt

Incorrect usage:

  • !#include https://github.com/uBlockOrigin/uAssets/blob/master/filters/filters.txt
  • !#include ../filters.txt

!#if [condition]

The !#if directive allows filter list maintainers to create areas in a filter list which will be parsed only if certain conditions are met (or not met). For example this can be used to create filters which are specific to a particular browser.

Example, to compile a block of filters only if uBO is being run as a Firefox extension:

!#if env_firefox
...
!#endif

Another example, compile a block of filters only if uBO is not being run as a Firefox extension:

!#if !env_firefox
...
!#endif

Support for pre-processor directives are the result of discussion with AdGuard developers, see https://github.com/AdguardTeam/AdguardBrowserExtension/issues/917.

For the time being, only a single token is supported in a !#if directive (can be negated using !), and uBO supports only the following tokens, anything else will be ignored:

ext_ublock
env_chromium
env_edge
env_firefox
env_mobile
env_safari
cap_html_filtering
cap_user_stylesheet

Tip: since ext_ublock is always true in uBO, you can use a !#if directive to disable a large block of your filters without having to remove them:

!#if !ext_ublock
...
!#endif

Extended syntax

uBO extends Adblock Plus filter syntax.

Static network filtering

HOSTS files

uBO can also parse HOSTS file-like resources. However, this creates an ambiguity with ABP filter syntax, which is pattern-based. For exemple, consider the following filter entry:

example.com

ABP filter syntax dictates that this is interpreted as "block network requests which URL contains example.com at any position". However if the entry comes from a HOSTS file, the interpretation must be "block network requests to the site example.com".

So in uBO, any entry which can be read as a valid hostname, will be assumed to be a HOSTS file entry. If ever you want such filter to be parsed as an ABP filter, just add a wildcard at the end:

example.com/*

* aka "all URLs"

The wildcard character * can be used to apply a filter to all URLs. This is not recommended though, unless you further narrow the filter using filter options. Examples:

  • *$third-party: block all 3rd-party network requests.
  • *$script,domain=example.com: block all network requests to fetch script resources from example.com.

Usually, it is far more convenient to use dynamic filtering rules in lieu of such generic static filters.

badfilter

To disable an existing filter. Sometimes, disabling an existing blocking filter is better than creating an exception filter. Just for example sake, let's say that a mind-absent filter list maintainer added the following filter in his list:

*$image

Now all images from everywhere are blocked on your side. An exception filter (@@*$image) is not a good solution because it would also cause images which should be legitimately blocked from no longer being blocked. In such case, the badfilter option is best:

*$image,badfilter

This will cause the *$image filter to be discarded. Just appending ,badfilter to any instance of static network filter will prevent the loading of that filter.

document

For block filters only. This is type option (like image or script) which specifies main frame (a.k.a. the root document) of a web page. Usually not necessary, because uBO implies it for filters specifying only host part of the URL. This will cause web pages which match the filter to be subjected to strict blocking.

first-party

This is equivalent to ~third-party. Provided strictly for convenience (0.9.9.0).

important

The filter option important means to ignore all exception filters (those prefixed with @@).

It applies only to network block filters. The important option will allow you to block with 100% certainty specific network requests.

Example: ||google-analytics.com^$important,third-party will block all network requests to google-analytics.com, disregarding any existing network exception filters. Another example: ||twitter.com^$important,third-party. Etc.

inline-script

To specifically disable inline script tags in a main page: ||example.com^$inline-script.

popunder

To block "popunders" windows/tabs. To be used in the same manner as the popup filter option, except that it will block popunders.

redirect

To cause a blocked network request to be redirected to a local "neutered" version of the resource. The "neutered" resource must be referenced using a resource token. The resources are defined in uAssets/filters/resources.txt.

The filter syntax for redirect= filter option is a subset of ABP-compatible filtering syntax, and is as follow:

||example.com^$script,redirect=noopjs,domain=github.com
||example.com/path/to/image$image,redirect=2x2-transparent.png,domain=github.com
||example.com/$script,redirect=noopjs,first-party

Specifically, notice that the filter must start with || or *, otherwise no redirection directive will be created, although a blocking filter will be created. Essentially, a redirection filter must always have a destination hostname specified, or * if the filter is to apply to all destinations*.

A source hostname should always be specified, so the domain= option is strongly recommended. It is allowed to use first-party instead of domain=[...], in which case the source hostname will be that of the destination hostname.

* redirections applied to all destinations (starting with *) cannot be narrowed by first-party or ~third-party option #3590

Static extended filtering

Static extended filters are all of the form:

[hostname(s)]##[expression]
[hostname(s)]#@#[expression]

The most common type of static extended filters are cosmetic filters, also known as "element hiding filters" in Adblock Plus.

Entity

All static extended filters can be declared to apply to a specific entity. For example:

google.*###tads.c

An entity is defined as follow: a formal domain name with the Public Suffix part replaced by a wildcard.

Examples: google.* will apply to all similar Google domain names: google.com, google.com.br, google.ca, google.co.uk, etc. Another example: facebook.* will apply to all similar Facebook domain names: facebook.com, facebook.net.

Since the base domain name is used to derive the name of the "entity", google.evil.biz would not match google.*.

Cosmetic filters

Procedural cosmetic filters

:has(...), :has-text(...), :if(...), :if-not(...), :matches-css(...), :matches-css-before(...), :matches-css-after(...), :xpath(...).

See detailed documentation.

:style()

Related issue: Support cosmetic filters with explicit style properties.

By default, the implicit purpose of cosmetic filters is to hide unwanted DOM elements. However sometimes it may be useful to re-style a specific DOM element on a page rather than hide it. Here is an recent example of such cases. This is the purpose of the new :style-based selector. The syntax is as follow:

example.com##h1:style(background-color: blue !important)

So mainly it's exactly the same syntax of plain cosmetic filters (i.e. must be a valid CSS selector), except that the :style(...) suffix is appended at the end. The content in the parentheses must be one or more CSS property declarations (separated by the standard ;). It is not allowed to use property values with url(...), such style:-based cosmetic filters will be discarded.

As with the other new cosmetic filtering selectors, the :style can be used only for specific cosmetic filters, i.e. there must be a hostname or entity specified for the filter.

AdGuard already support such feature, although using a different syntax. However uBO is able to transparently convert and make use of the AdGuard's "CSS injection rules" if ever you use an AdGuard filter list in uBO (well, this essentially means you can use AdGuard's syntax in uBO if you prefer).

For example, AdGuard English filter contains ~50 styling filters, AdGuard Russian filter list contains ~250 styling filters, etc. Note that often styling filters are used to foil anti-blocker mechanism on web pages. Given this, you may want to benefit from AdGuard's filter lists, which can be enabled from the 3rd-party filters pane.

HTML filters

Supported by uBO 1.14.23b3+ in Firefox 57+.

READ VERY CAREFULLY: HTML filtering acts on the response data (before browser parsing). Do not use the browser inspector from developer tools to create HTML filters. You must use view-source:[URL of page] instead to look at the response data and find out relevant information to create relevant HTML filters.

The purpose of HTML filters is to remove elements from a document before it is parsed by the browser.

The syntax is similar to that of cosmetic filters, except that you must prefix your selector (CSS or procedural) with the character ^:

example.com##^.badstuff
example.com##^script:has-text(7c9e3a5d51cdacfc)

These HTML filters will cause the elements matching the selectors to be removed from the streamed response data, such that the browser will never know of their existence once it parses the modified response data. This makes it a powerful tool in uBO's arsenal.

With the introduction of HTML filtering, the script:contains(...) is now deprecated and internally converted into an equivalent ##^script:has-text(...) HTML filter. The result is essentially the same: to prevent the execution of specific inline script tags in a main HTML document. See "Inline script tag filtering" for further documentation.

Scriptlet injection

script:inject(...)

Starting from 1.15.12 uBO supports new shorter syntax:

+js(...)

This allows the injection of specific javascript code into pages. The ... part is a token identifying a javascript resource from the resource library. Keep in mind the resource library is completely under control of the uBO project, hence only javascript code vouched by uBO can be inserted into web pages, through the use of a valid resource token.

Generic script:inject filters are ignored: those filters must be specific, i.e. they must apply to specific hostnames, e.g. example.com##script:inject(yavli-defuser.js).

Clone this wiki locally
You can’t perform that action at this time.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.
Press h to open a hovercard with more details.