Mirrors/uBlock
1
0
Fork 0
mirror of https://github.com/gorhill/uBlock.git synced 2024-09-28 21:57:12 +02:00
Code Issues Releases Wiki Activity

Updated Static filter syntax (markdown)

Raymond Hill 2024-09-20 08:50:39 -04:00
parent 6857d6a303
commit 75e1633b1e
1 changed files with 37 additions and 15 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

52
Static-filter-syntax.md

@ -573,13 +573,22 @@ Disable inline font tags in the main page via CSP: `||example.com^$inline-font`.
#### `ipaddress`
New in [1.59.1b15](https://github.com/gorhill/uBlock/commit/c6dedd253f). Related commit: [1.59.1b17](https://github.com/gorhill/uBlock/commit/030d7334e4), [1.59.1b19](https://github.com/gorhill/uBlock/commit/6acf97bf51), [1.59.1rc1](https://github.com/gorhill/uBlock/commit/6a042f152b513bbf5b3c8623ea3fbe2574ac0e24), [1.59.1rc4*](https://github.com/uBlockOrigin/uBlock-issues/issues/3381).
New in 1.60.0.
The purpose is to block according to the IP address of a network request.
Firefox-based browsers: full support. Chromium-based browsers: only when the IP address is used directly in the URL in lieu of a hostname.
The value assigned to `ipaddress` can either be a plain string which must match exactly a given IP address, or a regex which will be matched against the IP address. Also a wildcard can be used at the end, i.e. `192.168.*` for any IPv4 address starting with `192.168.`.
The value assigned to `ipaddress` can be ...
- ... a plain string which must match exactly a given IP address<br>
e.g. `ipaddress=192.168.1.1` to match exactly IP address `192.168.1.1`
- ... a plain string followed by a wildcard to match IP addresses starting with the pattern<br>
e.g. `ipaddress=192.168.*` to match IP addresses starting with `192.168.`
- ... a regex which will be matched against the IP address<br>
e.g. `ipaddress=/^192.168.1.\d{1-2}/` to match IP address between `192.168.1.0` and `192.168.1.99`.
- ... `lan` to match [IP addresses reserved for private networks](https://en.wikipedia.org/wiki/Reserved_IP_addresses)<br>
- ... `loopback` to match [IP addresses reserved for loopback](https://en.wikipedia.org/wiki/Loopback#Virtual_loopback_interface)
Examples:
@ -593,15 +602,16 @@ Examples:
Cached resources do not have a valid IP address and thus can't be a match to `ipaddress` option.
<details><summary>Technical notes</summary>
First commit in [1.59.1b15](https://github.com/gorhill/uBlock/commit/c6dedd253f). Related commit: [1.59.1b17](https://github.com/gorhill/uBlock/commit/030d7334e4), [1.59.1b19](https://github.com/gorhill/uBlock/commit/6acf97bf51), [1.59.1rc1](https://github.com/gorhill/uBlock/commit/6a042f152b513bbf5b3c8623ea3fbe2574ac0e24), [1.59.1rc4*](https://github.com/uBlockOrigin/uBlock-issues/issues/3381).
Lan/loopback values are supported (since [1.59.1b17](https://github.com/gorhill/uBlock/commit/030d7334e4)), related issue: [Possibility of Blocking Requests to localhost and Reserved IP Addresses by websockets?](https://github.com/uBlockOrigin/uBlock-issues/issues/1070).
Browser-provided `0.0.0.0` IP address will be ignored when DNS is proxied (since [1.59.1rc1](https://github.com/gorhill/uBlock/commit/6a042f152b513bbf5b3c8623ea3fbe2574ac0e24)), related issue: [Some rules may break websites that use socks proxy in Firefox](https://github.com/uBlockOrigin/uBlock-issues/issues/3379).
Cname uncloaking code has been rewritten to account for the `ipaddress` option (since [1.59.1b19](https://github.com/gorhill/uBlock/commit/6acf97bf51)), related issue: [Add AdGuard's $network support on Firefox](https://github.com/uBlockOrigin/uBlock-issues/issues/2792). This commit makes the DNS resolution code better suited for both filtering on cname and IP address. The change allows early availability of IP address so that `ipaddress` option can be matched at _onBeforeRequest_ time. As a result, it is now possible to block root document using `ipaddress` option -- so long as an IP address can be extracted before first _onBeforeRequest()_ call.
Caveat: the IP address used is the first one among the list of IP addresses returned by _dns.resolve()_ method. There is no way for uBO to know which exact IP address will be used by the browser when sending the request, so this is at most a best guess. The exact IP address used by the browser is available at _onHeadersReceived_ time, and uBO will also filter according to this value, but by then the network request has already been sent to the remote server.
Possibly a future improvement would make available the whole list of ip addresses to the filtering engine, but even then it's impossible to know with certainty which IP address will ultimately be used by the browser -- it is entirely possible that the IP address used by the browser might not be in the list received through _dns.resolve()_.
</details>
***
@ -952,6 +962,8 @@ Cosmetically added params cannot be removed via `removeparam` (see related comme
See also: [Filter Performance](./Filter-Performance#removeparam-modifier)
***
#### `replace`
New in [1.53.1b3](https://github.com/gorhill/uBlock/commit/7c3e060c01).
@ -962,6 +974,8 @@ See <https://adguard.com/kb/general/ad-filtering/create-own-filters/#replace-mod
[Documentation to be completed]
***
#### `uritransform`
New in [1.52.3b12](https://github.com/gorhill/uBlock/commit/2e4525fe3c509a636fc67776cd728819f54a7de6) as `urltransform`.
@ -975,14 +989,15 @@ See <https://adguard.com/kb/general/ad-filtering/create-own-filters/#urltransfor
[Documentation to be completed]
***
#### `urlskip`
New in [1.59.1b22](https://github.com/gorhill/uBlock/commit/266ec4894b).
New in 1.60.0.
Can only be used in a trusted-source origin.
The main purpose is to bypass URLs designed to track whether a user
visited a specific URL, typically used in click-tracking links.
The main purpose is to bypass URLs designed to track whether a user visited a specific URL, typically used in click-tracking links.
The `urlskip=` option ...
- ... is valid only when used in a trusted filter list
@ -991,13 +1006,15 @@ The `urlskip=` option ...
- ... is a modifier, i.e. it cannot be used along with other
modifier options in a single filter
The syntax is `urlskip=[steps]`, where steps is a space-separated
list of extraction directives detailing what action to perform on
the current URL.
The syntax is `urlskip=[steps]`, where steps is a space-separated list of extraction directives detailing what action to perform on the current URL.
The only supported directive in this first commit is `?name`,
which purpose is to extract the value of a named URL parameter
and use the result as the new URL. Example:
Valid directives:
- `?name`: the value of parameter named `name` will be extracted and replace the current URL as the new URL
- `+https`: the protocol of the current URL will be forced to `https:`<br>
This directive will succeed only if the protocol of the current URL is either absent or matches `http:` or `https:`
The final computed URL must be a valid URL as per [URL API](https://developer.mozilla.org/en-US/docs/Web/API/URL_API), otherwise the filter will be ignored.
```adb
||example.com/path/to/tracker$urlskip=?url
@ -1024,6 +1041,11 @@ Related issues:
- [Implement `$queryjump` for static network filter](https://github.com/uBlockOrigin/uBlock-issues/issues/2693)
- [[Enhancement] Add option to *automatically* visit embedded URLs w/o tracker](https://github.com/uBlockOrigin/uBlock-issues/issues/1784)
<details><summary>Technical notes</summary>
First commit in [1.59.1b22](https://github.com/gorhill/uBlock/commit/266ec4894b).
</details>
***
## Static extended filtering