the Chromium logo

The Chromium Projects

URL Blocklist filter format

The format of filters for the URLBlocklist and URLAllowlist policies, as of Chrome 52, is:

[scheme://][.]host[:port][/path][@query]

The format is very similar to the URL format, with some exceptions:

The filter selected for a URL is the most specific match found:

  1. First, the filters with the longest host match will be selected;
  2. Among these, filters with a non-matching scheme or port are discarded;
  3. Among these, the filter with the longest matching path is selected;
  4. Among these, the filter with the longest set of query tokens are selected;
  5. If no valid filter is left at step 3, the host is reduced by removing the left-most subdomain, and trying again from step 1;
  6. If a filter is available at step 3, its decision (block or allow) is enforced. If no filter ever matches, the default is to allow the request.

The special '*' host will be the last searched, and matches all hosts. When both a blocklist and allowlist filter apply at step 4 (with the same path length and number of query tokens), the allowlist filter takes precedence. If a filter has a '.' (dot) prefixing the host, only exact host matches will be filtered:

The scheme can be either a standard or a custom one. Supported standard schemes are: about, blob, content, chrome, cid, data, file, filesystem, ftp, gopher, http, https, javascript, mailto, ws, wss. All other schemes are treated as custom schemes. As of Chrome 52, custom schemes are supported, but only the patterns scheme:* and scheme://* are allowed. They match all URLs with that scheme.

The scheme and as of Chrome 52 the host are case insensitive, while path and query are case sensitive.

Example of searching for a match for "http://mail.example.com/mail/inbox":

  1. First find filters for "mail.example.com", and go to step 2. If that fails, then try again with "example.com", "com" and finally "".
  2. Among the current filters, remove those that have a scheme which is not http.
  3. Among the current filters, remove those that have an exact port number and it not 80;
  4. Among the current filters, remove those that don't have "/mail/inbox" as a prefix of the path;
  5. Pick the filter with the longest path prefix, and apply it. If no such filter exists, go back to step 1 and try the next subdomain.

Some examples:

Example: allowing only a small set of sites:

Example: block all access to a domain, except to the mail server using HTTPS and to the main page:

Example: block all access to youtube, except for selected videos.