Skip to content
This repository has been archived by the owner on Sep 9, 2022. It is now read-only.

Dynamic filtering: rule syntax

Jump to bottom
Zearin edited this page Jul 18, 2015 · 35 revisions

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 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
Clone this wiki locally