AdguardTeam / FiltersRegistry

AG Filters Registry • Introduction • What filters can be added to this repository • About filters • Metadata • Tags • Groups • Optimization • Compiler customization • Localization • Templates • How to build filters and patches • Use cases • Building *only AdGuard* filters and updating filters and patches • Building *all* filters and updating filters and patches • Working with locales • Expanding wildcard domains • Repository compression Introduction This repository contains the known filters subscriptions available to AdGuard users. We re-host these filters on . Also, these filters can be slightly modified in order to achieve better compatibility with AdGuard. What filters can be added to this repository We may add third-party filters to AdGuard Filters Registry. When making a decision about adding a third-party filter, we follow these rules: • The filter should be oriented towards browser content blockers. • The filter should be legal. If it has rules for paywall circumvention, we won't add such a filter. • The filter should have a place for receiving user complaints and holding discussions, such as a repository on github.com, or a website open to public. • The filter should be relatively popular, meaning: • if there is a repository on GitHub, the number of stars should be at least 50; • if there is no repository on GitHub, the number of analyzed issues and discussions is estimated at 10 per month on the filter's website; • the filter should be actively supported for at least 6 months. • The filter should be regularly updated with at least 10 updates per month. • The filter should be compatible with AdGuard products. You can familiarize yourself with AdGuard syntax in our [knowledge base][kb-rules-syntax]. • If the filter works only in some operating systems and satisfies all other criteria, it will be added but only for the supported platforms. • Previously added filters that haven't received any support for a year will be removed. We reserve the right to remove the filter earlier, depending on circumstances. • If the filter contains too many problematic rules, it will not be added. A rule is considered problematic if it causes false positives or otherwise displays unintended behavior. Decisions about filters with problematic rules are arbitrary and there may be exceptions (see items 9 and 10, for example). • If the filter intentionally blocks or restricts access to any services for no reason other than being a reflection of the filter author's opinion, the filter will not get added, or will get removed if already added. • If the filter is popular in a specific region and there are no alternatives to it, then it can be added as is. • If the filter gets added, it receives a so-called trustLevel (Low, High, Full), based on the number of problematic rules it contains and some other factors. Filters without "Full" trust level may have part of their rules disabled. • The trust level of a filter can be re-reviewed and raised if the author improves the filter over time. • If there are two or more similar filters that satisfy all other criteria, they all may be added if they don't duplicate each other and don't conflict with each other. If there is a large amount of conflicting or duplicate rules, the filter with more matches on such rules gets the priority. [kb-rules-syntax]: https://adguard.com/kb/general/ad-filtering/create-own-filters About filters Metadata • Template file is used by the filters compiler to prepare the final filter version. • A list of regular expressions. Rules that match these exclusions will not be included in the resulting filter. • Filter metadata. Includes name, description, etc. • — number, unique filter identifier. • — string, filter name; can be localized. • — string, filter description. • — number, time when this filter was added to the registry; milliseconds since January 1, 1970; you can exec in the browser console to get the current time. • — string, filter website or homepage. • — optional, boolean, filter is *deprecated* but still available and being built as usual, i.e. **not removed**. The flag shows that the filter list is no longer relevant and should not be used by the products. Final decision what to do with such filter is up to the product, e.g. simple hiding, disabling, or migration. • — optional, boolean, filter is disabled, i.e. *removed*, its building will be skipped and it will not be available to download. If used, the tag should be used as well. • — string, filter's default expiration period. used as filter update interval if "Default" is chosen for according setting in AdGuard product. • — number, this number is used when AdGuard sorts available filters (GUI). • — number, group identifier. • — optional, string, makes sense only for third-party lists that come from the registry. The idea is that these lists are re-hosted by the registry and downloaded not from the source url. • — string, main filter download url. • — string array, a list of tags. • — string, level of trust which describes [allowed and permitted rules types][gh-compiler-trust-levels]. Please note that the trust level can be ignored for same origin files, more details can be found in the [ directive documentation][gh-compiler-include-directive]. Possible values: • — only low-risk rule types are allowed; defaults to **low** if trust level is not configured at all; • — trusted third-party filter lists; some particular rules from there are still permitted; • — all types of filter rules are allowed; only AdGuard filter lists have full trust at the moment. • — string array, [the list of platforms][kb-hint-platforms] to compile the filter for, e.g. . If you need to compile the filter for all platforms remove this property. • — string array, [the list of platforms][kb-hint-platforms] to skip while filter compiling, e.g. . If you need to compile the filter for all platforms remove this property. > ⚠️ **Warning**: > > 1. Both and should not be set in…