Added "urlskip" and "ipaddress" network options.

2024-11-16 23:42:39 +01:00 · 2024-09-18 08:43:31 +00:00 · 2024-09-18 08:43:31 +00:00 · 520d96a9ba
commit 520d96a9ba
parent dc99890d82
1 changed files with 82 additions and 1 deletions
--- a/Static-filter-syntax.md
+++ b/Static-filter-syntax.md
@ -186,6 +186,7 @@ uBO extends ABP filter syntax.
 - [$important](#important)
 - [$inline-script](#inline-script)
 - [$inline-font](#inline-font)
+- [$ipaddress](#ipaddress)
 - [$match-case](#match-case)
 - [$media](https://help.adblockplus.org/hc/en-us/articles/360062733293#options)
 - [$method](#method)
@ -211,6 +212,7 @@ uBO extends ABP filter syntax.
 - [$removeparam](#removeparam)
 - [$replace](#replace) (only from a trusted-source origin)
 - [$uritransform](#uritransform) (only from a trusted-source origin)
+- [$urlskip](#urlskip) (only from a trusted-source origin)

 ## Static network filtering

@ -435,7 +437,7 @@ Related discussion: [uBlockOrigin/uBlock-issues#2234](https://github.com/uBlockO
 Regex-based domain values can be negated just like plain or entity-based values:
 `*$domain=~/regex.../`

-See also: [`to`](#to)
+See also: [`ipaddress`](#ipaddress) and [`to`](#to).

 ***

@ -569,6 +571,36 @@ 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). Further stabilized, improved and bugs fixed in: [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).
+
+Similar to [`domain`](#domain), but the purpose is to block according to the IP address of a network request. 
+
+In the current implementation, the filter option can only be enforced at _onHeadersReceived_ time, which means the new filter option cannot be enforced in Chromium-based browsers since the IP address of network requests is available only at _onResponseStarted_ time, which is not blocking.
+
+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. `::*` for anything starting with `::`, and `::` for exact match (since [1.59.1rc4](https://github.com/uBlockOrigin/uBlock-issues/issues/3381), related issue: [`ipaddress=::` unexpectedly matches IPv4-mapped IPv6 addresses](https://github.com/uBlockOrigin/uBlock-issues/issues/3381)). Examples:
+
+```adb
+*$script,ipaddress=93.184.215.14
+||xyz/|$xhr,3p,method=head,ipaddress=/^139\.45\.19[5-7]\.\d{1,3}/
+*$all,ipaddress=::,domain=~0.0.0.0|~127.0.0.1|~[::1]|~[::]|~local|~localhost
+```
+
+The `ipaddress` option can only be enforced when the extension framework does provide a valid IP address in a _onHeadersReceived_ listener. For instance, cached resources do not have a valid IP address and thus can't be a match to `ipaddress` option.
+
+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()_.
+
+***
+
 #### `match-case`

 New in [1.31.1b8](https://github.com/gorhill/uBlock/commit/eae7cd58fe679d6765d62bb6c01e296d5301433a).
@ -939,6 +971,55 @@ 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).  
+
+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 `urlskip=` option ...
+- ... is valid only when used in a trusted filter list
+- ... is enforced only on top documents
+- ... is enforced on both blocked and non-blocked documents
+- ... 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 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:
+
+```adb
+||example.com/path/to/tracker$urlskip=?url
+```
+
+The above filter will cause navigation to `https://example.com/path/to/tracker?url=https://example.org/` to automatically bypass navigation to `example.com` and navigate directly to `https://example.org/`.
+
+It is possible to recursively extract URL parameters by using
+more than one directive, example:
+
+```adb
+||example.com/path/to/tracker$urlskip=?url ?to
+```
+
+The above filter will cause navigation to `https://example.com/path/to/tracker?url=https%3A%2F%2Fexample.org%2Fpath%2Fto%2Ftracker%3Fto%3Dhttps%253A%252F%252Fgithub.com%252F` to automatically bypass navigation to `example.com` & `example.org`and navigate directly to `https://github.com/`.
+
+_Note:_ No skip will occur if not all extraction directives can be fulfilled in URL, example URL: 
+`https://example.com/path/to/tracker?url=https%3A%2F%2Fexample.org%2Fpath%2Fto%2Ftracker`.
+
+<br>More extraction capabilities may be added in the future. In the future we might want to add base64-decoding or regex extraction (`=?url base64`), so a separator is needed for the sake of extending the syntax in the future, a space is a good choice since it's never meant to appear in a URL.
+  
+Related issues:
+- [Add queryjump to redirect url](https://github.com/uBlockOrigin/uBlock-issues/issues/3206)
+- [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)
+
 ***

 ## Static extended filtering