Skip to content
This repository was 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