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; a request can be blocked, allowed, or ignored
4. action specifies what to do when a request matches the previous three components

Type-based rules

Type-based rules are used to filter specific types of request on a web page. There are seven types of requests which can be dynamically filtered:

• *: any type of request
• image: images
• 3p: any request which is a 3rd-party to the web page
• inline-script: inline script tags, i.e. scripts embedded in the main document
• 1p-script: 1st-party scripts, i.e. scripts which are pulled from the same domain name of the current web page
• 3p-script: 3rd-party scripts, i.e. scripts which are pulled from a different domain name than that of the current web page
• 3p-frame: 3rd-party frames, i.e. frames elements which are pulled from a different domain name than that of current web page

These rules may apply everywhere, or be specific to a web site. 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".

NOTE: With type-based rules, the destination hostname is always *, meaning "from anywhere".

Hostname-based rules

Hostname-based rules are used to filter network resources according to their origin; that is, according to which remote server a resource is pulled.

Hostname-based rules have a higher specificity 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.

With hostname-based rules, the type is always *, meaning the rule will apply to all types of requests.

For example, * disqus.com * block means "globally block all net requests to disqus.com".

As with type-based rules, hostname-based rules only apply when visiting a specific web site. For example, wired.com disqus.com * noop means "do not apply dynamic filtering to net requests to disqus.com when visiting a page on wired.com." Since this last rule is more specific than the previous one, 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