From 9279008508ec6247018c4f9dacf5df6b626511b2 Mon Sep 17 00:00:00 2001 From: Sergei Gunchenko <26045362+sxgunchenko@users.noreply.github.com> Date: Fri, 11 Nov 2022 16:10:22 +0300 Subject: [PATCH 1/7] Introduce modifier description --- .../ad-filtering/create-own-filters.md | 31 +++++++++++++++++++ 1 file changed, 31 insertions(+) diff --git a/docs/general/ad-filtering/create-own-filters.md b/docs/general/ad-filtering/create-own-filters.md index 7bd194596a9..aeb043b1588 100644 --- a/docs/general/ad-filtering/create-own-filters.md +++ b/docs/general/ad-filtering/create-own-filters.md @@ -756,6 +756,37 @@ For the requests matching a `$csp` rule, we will strengthen response security po > > Rules with `$csp` modifier are not supported by AdGuard Content Blocker, AdGuard for iOS and Safari. +#### **`$permissions`** {#permissions-modifier} + +This modifier completely changes the rule behavior. If it is applied to a rule, it will not block the matching request. The response headers are going to be modified instead. + +> In order to use this type of rules, it is required to have the basic understanding of the [Feature Policy](https://developer.mozilla.org/en-US/docs/Web/HTTP/Feature_Policy) security layer. + +For the requests matching a `$permissions` rule, AdGuard strengthens response's feature policy by adding additional feature policy equal to the `$permissions` modifier contents. `$permissions` rules are applied independently from any other rule type. Other basic rules have no influence on it **save for document-level exceptions** (see the examples section). + +> **Multiple rules matching a single request.** +> +> In case if multiple `$permissions` rules match a single request, AdGuard will apply each of them. + +**Syntax** + +`$permissions` value syntax is similar to the `Permissions-Policy` (or `Feature-Policy`) header syntax. + +`$permissions` value can be empty in the case of exception rules. See examples section for further information. + +> **Limitations** +> +> 1. Please note that there are a few characters forbidden in the `$permissions` value: `,`, `$`; +> 2. `$permissions` is compatible with the limited list of modifiers: `$domain`, `$important`, `$subdocument`. + +**Examples** + +* `||example.org^$permissions=sync-xhr 'none'` disallows synchronous `XMLHttpRequest` requests across `example.org`. +* `@@||example.org/page/*$permissions=sync-xhr 'none'` disables all rules with the `$permissions` modifier exactly matching `sync-xhr 'none'` on all the pages matching the rule pattern. For instance, the rule above. +* `@@||example.org/page/*$permissions` disables all the `$permissions` rules on all the pages matching the rule pattern. +* `$domain=example.org|example.com,permission=oversized-images 'none'; sync-script 'none'; unsized-media 'none';` disallows oversized images, synchronous scripts and unsized media features across `example.org` and `example.com`. +* `@@||example.org^$document` or `@@||example.org^$urlblock` disables all the `$permission` rules on all the pages matching the rule pattern. + ##### **`$all`** `$all` modifier is made of [`$document`](#document-modifier), [`$popup`](#popup-modifier), [`$csp`](#csp-modifier) modifiers. E.g. rule `||example.org^$all` is converting into such set of rules: From 12eee87e424b3fc5427dec79dba0f4a445f8a3e3 Mon Sep 17 00:00:00 2001 From: Sergei Gunchenko <26045362+sxgunchenko@users.noreply.github.com> Date: Fri, 11 Nov 2022 16:16:14 +0300 Subject: [PATCH 2/7] Add a compatibility note --- docs/general/ad-filtering/create-own-filters.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/docs/general/ad-filtering/create-own-filters.md b/docs/general/ad-filtering/create-own-filters.md index aeb043b1588..81b3066248d 100644 --- a/docs/general/ad-filtering/create-own-filters.md +++ b/docs/general/ad-filtering/create-own-filters.md @@ -787,6 +787,10 @@ For the requests matching a `$permissions` rule, AdGuard strengthens response's * `$domain=example.org|example.com,permission=oversized-images 'none'; sync-script 'none'; unsized-media 'none';` disallows oversized images, synchronous scripts and unsized media features across `example.org` and `example.com`. * `@@||example.org^$document` or `@@||example.org^$urlblock` disables all the `$permission` rules on all the pages matching the rule pattern. +> **Compatibility with different versions of AdGuard** +> +> Rules with the `$permissions` modifier are supported by AdGuard for Windows, Mac, and Android, **running CoreLibs version 1.11 or later**. + ##### **`$all`** `$all` modifier is made of [`$document`](#document-modifier), [`$popup`](#popup-modifier), [`$csp`](#csp-modifier) modifiers. E.g. rule `||example.org^$all` is converting into such set of rules: From fd9a5586608457c43512d319dfa291c745a757b4 Mon Sep 17 00:00:00 2001 From: Sergei Gunchenko <26045362+sxgunchenko@users.noreply.github.com> Date: Tue, 24 Jan 2023 09:59:17 +0300 Subject: [PATCH 3/7] add more links --- docs/general/ad-filtering/create-own-filters.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/general/ad-filtering/create-own-filters.md b/docs/general/ad-filtering/create-own-filters.md index 60c61687755..96a0620adcf 100644 --- a/docs/general/ad-filtering/create-own-filters.md +++ b/docs/general/ad-filtering/create-own-filters.md @@ -837,7 +837,8 @@ For the requests matching a `$permissions` rule, AdGuard strengthens response's **Syntax** -`$permissions` value syntax is similar to the `Permissions-Policy` (or `Feature-Policy`) header syntax. +`$permissions` value syntax is similar to the `Permissions-Policy` (or `Feature-Policy`) header [syntax](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Permissions-Policy). +See [here](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Permissions-Policy#directives) for the list of the available directives. `$permissions` value can be empty in the case of exception rules. See examples section for further information. From 74a1d57e4d67aa2e435a1560d525d571e072ae82 Mon Sep 17 00:00:00 2001 From: Sergei Gunchenko <26045362+sxgunchenko@users.noreply.github.com> Date: Wed, 25 Jan 2023 12:26:12 +0300 Subject: [PATCH 4/7] apply suggestion Co-authored-by: Helen <58733007+el-termikael@users.noreply.github.com> --- docs/general/ad-filtering/create-own-filters.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/general/ad-filtering/create-own-filters.md b/docs/general/ad-filtering/create-own-filters.md index 96a0620adcf..adbd1ce2809 100644 --- a/docs/general/ad-filtering/create-own-filters.md +++ b/docs/general/ad-filtering/create-own-filters.md @@ -838,7 +838,7 @@ For the requests matching a `$permissions` rule, AdGuard strengthens response's **Syntax** `$permissions` value syntax is similar to the `Permissions-Policy` (or `Feature-Policy`) header [syntax](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Permissions-Policy). -See [here](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Permissions-Policy#directives) for the list of the available directives. +The list of the available directives is available [here](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Permissions-Policy#directives). `$permissions` value can be empty in the case of exception rules. See examples section for further information. From 44cfe69b86de1308ac5f52327b532fbcfa4746ef Mon Sep 17 00:00:00 2001 From: Sergei Gunchenko <26045362+sxgunchenko@users.noreply.github.com> Date: Wed, 25 Jan 2023 12:27:24 +0300 Subject: [PATCH 5/7] accept suggestion Co-authored-by: Helen <58733007+el-termikael@users.noreply.github.com> --- docs/general/ad-filtering/create-own-filters.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/general/ad-filtering/create-own-filters.md b/docs/general/ad-filtering/create-own-filters.md index adbd1ce2809..0e714733dc6 100644 --- a/docs/general/ad-filtering/create-own-filters.md +++ b/docs/general/ad-filtering/create-own-filters.md @@ -840,7 +840,7 @@ For the requests matching a `$permissions` rule, AdGuard strengthens response's `$permissions` value syntax is similar to the `Permissions-Policy` (or `Feature-Policy`) header [syntax](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Permissions-Policy). The list of the available directives is available [here](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Permissions-Policy#directives). -`$permissions` value can be empty in the case of exception rules. See examples section for further information. +`$permissions` value can be empty in the case of exception rules — see examples below. > **Limitations** > From 5e62456eaf09672baf9d5e446e5d3aaeaf28f374 Mon Sep 17 00:00:00 2001 From: Sergei Gunchenko <26045362+sxgunchenko@users.noreply.github.com> Date: Wed, 25 Jan 2023 12:27:56 +0300 Subject: [PATCH 6/7] accept suggestion Co-authored-by: Helen <58733007+el-termikael@users.noreply.github.com> --- docs/general/ad-filtering/create-own-filters.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/general/ad-filtering/create-own-filters.md b/docs/general/ad-filtering/create-own-filters.md index 0e714733dc6..8b1c830d45d 100644 --- a/docs/general/ad-filtering/create-own-filters.md +++ b/docs/general/ad-filtering/create-own-filters.md @@ -844,7 +844,7 @@ The list of the available directives is available [here](https://developer.mozil > **Limitations** > -> 1. Please note that there are a few characters forbidden in the `$permissions` value: `,`, `$`; +> 1. Two characters are forbidden in the `$permissions` value: `,` and `$`; > 2. `$permissions` is compatible with the limited list of modifiers: `$domain`, `$important`, `$subdocument`. **Examples** From f9702b26e44eb411f61d09d94562d789d84f72c6 Mon Sep 17 00:00:00 2001 From: Sergei Gunchenko <26045362+sxgunchenko@users.noreply.github.com> Date: Wed, 25 Jan 2023 12:28:26 +0300 Subject: [PATCH 7/7] accept suggestion Co-authored-by: Helen <58733007+el-termikael@users.noreply.github.com> --- docs/general/ad-filtering/create-own-filters.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/general/ad-filtering/create-own-filters.md b/docs/general/ad-filtering/create-own-filters.md index 8b1c830d45d..c75f0979026 100644 --- a/docs/general/ad-filtering/create-own-filters.md +++ b/docs/general/ad-filtering/create-own-filters.md @@ -845,7 +845,7 @@ The list of the available directives is available [here](https://developer.mozil > **Limitations** > > 1. Two characters are forbidden in the `$permissions` value: `,` and `$`; -> 2. `$permissions` is compatible with the limited list of modifiers: `$domain`, `$important`, `$subdocument`. +> 2. `$permissions` is compatible with the limited list of modifiers: `$domain`, `$important`, and `$subdocument`. **Examples**