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

Dynamic filtering: rule syntax

Zearin edited this page Jul 18, 2015 · 35 revisions

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