Add $permissions modifier

ameshkov commented 6 years ago

It would be really useful for implementing stealth mode features.

More info: https://caniuse.com/permissions-policy https://www.w3.org/TR/permissions-policy-1/ https://developers.google.com/web/updates/2018/06/feature-policy https://w3c.github.io/webappsec-permissions-policy/

TODO: we need to come up with a better description of what we want. It could be used as a part of advanced tracking protection indeed, but we could also introduce a new filters modifier (just like $csp)

[ ] Once this feature is done, we should create a separate issue in the tsurlfilter repo
[ ] We should add a test for it to testcases.adguard.com
[ ] KnowledgeBase should be updated

sfionov commented 5 years ago

Link from #174: http://xhr.featurepolicy.rocks/

sxgunchenko commented 2 years ago

Here's the proposed spec:

`permissions`

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 security layer.

For the requests matching a $permissions rule, AdGuard will strengthen 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

Please note that there're a few characters forbidden in the $permissions value: ,, $;

$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.

It very similar to the $csp one.

ameshkov commented 1 year ago

@AdguardTeam/filters-maintainers could you please check this out?

AdamWr commented 1 year ago

I have a question regarding $permissions modifier - https://adguard.com/kb/general/ad-filtering/create-own-filters/#permissions-modifier

In knowledge base there is an example like this:

||example.org^$permissions=sync-xhr 'none'

but it looks like that adding such rule causes that there is an error displayed in the console:

Error with Permissions-Policy header: Parse of permissions policy failed because of errors reported by structured header parser.

I'm not familiar with this, but should not it be something like this:

||example.org^$permissions=sync-xhr=()

I have checked it out with permissions=fullscreen and it looks like that this rule:

*.*$permissions=fullscreen=()

works, but if I add:

*.*$permissions=fullscreen 'none'

it doesn't work

So I just wonder if I'm doing something wrong or maybe the example in knowledge base is not correct?

By the way, how can we use two permissions in one rule if , is forbidden?

Two characters are forbidden in the $permissions value: , and $;

And one more thing, if I'm not wrong this example:

$domain=example.org|example.com,permission=oversized-images 'none'; sync-script 'none'; unsized-media 'none';

is not correct, there is missed s in permission.

I'm checking it with AdGuard for Windows 7.13 nightly 2 (build 4183, CL 1.11.44)

sfionov commented 1 year ago

@AdamWr Yes, example is incorrect, they switched from CSP syntax to structured header syntax in final specification, and seems that CSP syntax is not supported anymore. We will fix examples, thanks.

AdamWr commented 1 year ago

Okay, thank you for your answer. By the way, I think that it would be nice to have ability to add two (or more) permissions in one rule, but I suppose that it would be necessary to remove this restriction:

Two characters are forbidden in the $permissions value: , and $;

to do that.

sxgunchenko commented 1 year ago

I think that it would be nice to have ability to add two (or more) permissions in one rule

Agree, will be done along with https://github.com/AdguardTeam/CoreLibs/issues/1748

dnmTX commented 1 year ago

Question: What about subframes? Like,for example,YAHOO doesn't allow fullscreen on embeded youtube videos. Can you guys give me example for the rule that i need. Thank you 👍

sxgunchenko commented 1 year ago

Question: What about subframes? Like,for example,YAHOO doesn't allow fullscreen on embeded youtube videos. Can you guys give me example for the rule that i need.

CoreLibs do not patch iframe html tags according to matched $permissions rules. This would weaken the user privacy, but the permissions modifier is intended to enhance it. So, you need a $replace rule, like ||yahoo.com^$replace=/(<iframe src=".*youtube.*\.com\/embed\/.*")(>)/\$1 allow="fullscreen *"$2/ (it adds allow="fullscreen *" permission to all the matching iframes on yahoo.com).

dnmTX commented 1 year ago

Sergei @sxgunchenko thanks for the explanation and trying to help but unfortunately it didn't work. Looks like Yahoo doesn't use the embeded link like any other site out there. Here is a link to one of the Yahoo's embeded videos. I'd appreciate if you can find me some solution. Thank you 👍 https://www.yahoo.com/news/22-years-jay-z-pleaded-115522884.html

sxgunchenko commented 1 year ago

Oops, just found a couple of mistakes in the rule. This one should work: ||yahoo.com^$replace=/(src=".*?youtube.*?\.com\/embed\/.*?")(>)/\$1 allow="fullscreen *"\$2/ (at least it does on my side).

dnmTX commented 1 year ago

Here is a List of features that can be used with the $permissions modifier (easier this way for everyone to see and decide). Probably more can be found throughout that repo and all of them to be mentioned in the knowledge base: https://github.com/w3c/webappsec-permissions-policy/blob/main/features.md 👍

https://source.chromium.org/chromium/chromium/src/+/main:out/Debug/gen/third_party/blink/renderer/core/permissions_policy/policy_helper.cc 👍

sxgunchenko commented 1 year ago

There is a link to the list in the KB article, although it leads to MDN

AdguardTeam / CoreLibs