URL blocklist filter format

The format of filters for the URLBlocklist and URLAllowlist policies is:

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

Schemes you can use

You can use either a standard or a custom scheme. Supported standard schemes are:

• about
• blob
• content
• chrome (not recommended, use Block sensitive internal Chrome URLs instead)
• cid
• data
• file
• filesystem
• gopher
• http
• https
• javascript
• mailto
• ws
• wss

All other schemes are treated as custom schemes. Custom schemes are supported, but only the patterns scheme:* and scheme://* are allowed. They match all URLs with that scheme. The scheme and the host are case insensitive, but path and query are case sensitive. 

Example scheme formats

• Supported standard schemes
  • http://example.com matches HTTP://Example.com, http://example.COM and http://example.com.
  • http://example.com/path?query=1 doesn't match http://example.com/path?Query=1 or http://example.com/Path?query=1 but does match http://Example.com/path?query=1.
• Custom schemes
  • The patterns custom://* or custom:* are valid and match custom:app.
  • The patterns custom:app or custom://app are invalid.

Exceptions to URL format

The filters format is very similar to the URL format. The following exceptions apply:

• You can include user:pass fields but they will be ignored. For example, instead of entering http://user:pass@example.com/pub/bigfile.iso, enter http://example.com/pub/bigfile.iso.
• If you include a reference separator #, it is ignored along with everything that appears after it.
• The host can be *. It can also have . (dot) as a prefix.
• The host can have / or . (dot) as a suffix. If it is the case, that suffix is ignored.

Filter selection

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

Considerations

• Wildcards (*) are the last searched, and match all hosts. You cannot use a wildcard at the end of a URL, such as https://www.example.com/* and https://example.com/*.
• When both a block and allow filter apply at step 4 below, with the same path length and number of query tokens, the allow filter takes precedence.
• If a filter has . (dot) prefixing the host, only exact host matches are filtered. For example:
  • example.com matches example.com, www.example.com and sub.www.example.com.
  • .www.example.com only matches exactly www.example.com.

Filter selection process

1. The filters with the longest host match are selected. Filters with a non-matching scheme or port are discarded.
2. From these filters, the filters with the longest matching path are selected.
3. From these filters, the filters with the longest set of query tokens are selected.
4. If no valid filter is left at this stage, the host is reduced by removing the left-most subdomain, and starting again from step 1.
5. If a filter is still available, the filter decision, to block or allow, is enforced. If no filter ever matches, the default is to allow the request.