-
Notifications
You must be signed in to change notification settings - Fork 435
Dynamic filtering: rule syntax
A dynamic filtering rule consists of four components:
source-hostname destination-hostname request-type action
-
source-hostname
corresponds to the hostname of the URL of the web page in the browser -
destination-hostname
corresponds to the hostname from the URL of a remote resource which the web page is fetching (or trying to) -
request-type
is the type of the fetched resource-
*
,image
,3p
,inline-script
,1p-script
,3p-script
, or3p-frame
(see below for descriptions)
-
-
action
specifies what to do when a request matches the previous three components-
block
,allow
, ornoop
(see below for descriptions)
-
Type-based rules are used to filter specific types of request on a web page. These rules may apply everywhere, or be specific to a web site. All type-based rules have a destination-hostname
of *
, meaning "from anywhere".
There are seven types of requests which can be dynamically filtered:
-
*
: any type of request -
image
: images -
3p
: any requests that are 3rd-party to the web page -
inline-script
: inline script tags (scripts embedded in the main document) -
1p-script
: 1st-party scripts (scripts from the same domain name of the current web page) -
3p-script
: 3rd-party scripts (scripts from a different domain name than that of the current web page) -
3p-frame
: 3rd-party frames (frame elements from a different domain name than that of current web page)
For example, blocking 3rd-party frames is a very good habit security-wise:
-
* * 3p-frame block
. This rule translates to "globally block 3rd-party frames". -
wired.com * image block
means "block images from all origins when visiting a web page on wired.com".
Hostname-based rules filter network resources according to their origin (i.e. according to which remote server a resource is pulled from). Hostname-based rules only apply when visiting a specific web site. All hostname-based rules have a request-type
of *
, meaning the rule will apply to all types of requests.
Hostname-based rules are more specific than type-based rules. Thus, hostname-based rules always override type-based rules when a network request matches both a type- and a hostname- based rule.
For example, consider the following rules:
-
* disqus.com * block
(which means "globally block all net requests todisqus.com
"), and -
wired.com disqus.com * noop
(which means "do not apply dynamic filtering to net requests todisqus.com
when visiting a page onwired.com
").
Since the second rule is more specific, it will override the global blocking of disqus.com
everywhere.
A matching rule can do one of three things:
-
block
: block matching requests-
block
dynamic filter rules override any existing static exception filters - Use them to block with 100% certainty (unless you set another overriding dynamic filter rule).
-
-
allow
: allow matching requests-
allow
dynamic filters rules override static and dynamicblock
filters - Useful for creating fine-grained exceptions (and to un-break web sites broken by static filters)
-
-
noop
: disable dynamic filters on matching requests- Cancels dynamic filtering
- Static filtering continues as normal