Dynamic filtering: rule syntax

Back to "Dynamic-filtering"

---

Rule syntax

A dynamic filtering rule consists of four components:

1. Source hostname
2. Destination hostname
3. Request type
4. Action

source-hostname destination-hostname request-type action

The source hostname always corresponds to the hostname extracted from the URL of the web page in the browser. The destination hostname corresponds to the hostname extracted from the URL of a remote resource which the web page is fetching (or trying to). The request type is the type of the fetched resource; a request can be blocked, allowed, or ignored. The action specifies what to do with a request that matches the other 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 can 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".

Another example: wired.com * image block, which 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, i.e. according to which remote server a resource is pulled. Hostname-based rules have a higher specificity than type-based rules, and thus hostname-based rules always override type-based rules whenever a network request end up matching 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".

Just like type-based rules, a hostname-based rule can apply only when visiting a specific web site, for example: 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 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 to create fine-grain exceptions and to un-break web sites broken by static filters.
3. noop: prevent dynamic filters from being applied to matching requests.
   • Cancels dynamic filtering, but does not cancel static filtering.