Dynamic filtering: rule syntax

Back to "Dynamic-filtering"

---

Rule syntax

A dynamic filtering rule consists of four components:

source-hostname destination-hostname request-type action

1. source-hostname corresponds to the hostname of the URL of the web page in the browser
2. destination-hostname corresponds to the hostname from the URL of a remote resource which the web page is fetching (or trying to)
3. request-type is the type of the fetched resource
   • *, image, 3p, inline-script, 1p-script, 3p-script, or 3p-frame (see below for descriptions)
4. action specifies what to do when a request matches the previous three components
   • block, allow, or noop (see below for descriptions)

Type-based rules

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

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 to disqus.com"), and
• wired.com disqus.com * noop (which means "do not apply dynamic filtering to net requests to disqus.com when visiting a page on wired.com").

Since the second rule is more specific, it will override the global blocking of disqus.com everywhere.

Actions

A matching rule can do one of three things:

1. 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).
2. allow: allow matching requests
   • allow dynamic filters rules override static and dynamic block filters
   • Useful for creating fine-grained exceptions (and to un-break web sites broken by static filters)
3. noop: disable dynamic filters on matching requests
   • Cancels dynamic filtering
   • Static filtering continues as normal