• Stars
    star
    152
  • Rank 244,685 (Top 5 %)
  • Language Adblock Filter List
  • License
    GNU Lesser Genera...
  • Created almost 7 years ago
  • Updated almost 2 years ago

Reviews

There are no reviews yet. Be the first to send feedback to the community and the maintainers!

Repository Details

Known filters subscriptions transformed for better compatibility with AdGuard

AG Filters Registry

This repository contains the known filters subscriptions available to AdGuard users. We re-host these filters on filters.adtidy.org. 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:

  1. The filter should be oriented towards browser content blockers.
  2. The filter should be legal. If it has rules for paywall circumvention, we won't add such a filter.
  3. 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.
  4. 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
  5. The filter should be regularly updated with at least 10 updates per month.
  6. The filter should be compatible with AdGuard products. You can familiarize yourself with AdGuard syntax here: https://adguard.com/kb/general/ad-filtering/create-own-filters/.
  7. If the filter works only in some operating systems and satisfies all other criteria, it will be added but only for the supported platforms.
  8. 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.
  9. 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.
  10. If the filter is popular in a specific region and there are no alternatives to it, then it can be added as is.
  11. 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.
  12. 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.

Filters metadata

  • template.txt

    Template file is used by the filters compiler to prepare the final filter version.

  • exclude.txt

    A list of regular expressions. Rules that match these exclusions will not be included in the resulting filter.

  • metadata.json

    Filter metadata. Includes name, description, etc.

    • filterId — unique filter identifier (integer)
    • name — filter name; can be localized
    • description — filter description
    • timeAdded — time when this filter was added to the registry; milliseconds since January 1, 1970; you can exec new Date().getTime() in the browser console to get the current time
    • homepage — filter website/homepage
    • expires — filter's default expiration period; used as filter update interval if "Default" is chosen for according setting in AdGuard product
    • displayNumber — this number is used when AdGuard sorts available filters (GUI)
    • groupId — group identifier
    • subscriptionUrl — default filter subscription URL
    • tags — a list of tags
    • trustLevel — level of trust which describe allowed and permitted rules types; possible values:
      • low — only low-risk rule types are allowed; defaults to low if trust level is not configured at all
      • high — trusted third-party filter lists; some particular rules from there are still permitted
      • full — all types of filter rules are allowed; only AdGuard filter lists have full trust at the moment
    • platformsIncluded — the list of platforms to compile the filter for, e.g. ["mac", "windows", "android"]. If you need to compile the filter for all platforms remove this property
    • platformsExcluded — the list of platforms to skip while filter compiling, e.g. ["ios", "ext_safari"]. If you need to compile the filter for all platforms remove this property

    Note please that both platformsIncluded and platformsExcluded should not be set in filter's metadata simultaneously.

    Metadata example
    {
      "filterId": 2,
      "name": "AdGuard Base filter",
      "description": "EasyList + AdGuard English filter. This filter is necessary for quality ad blocking.",
      "timeAdded": 1404115015843,
      "homepage": "https://adguard.com/kb/general/ad-filtering/adguard-filters/",
      "expires": "4 days",
      "displayNumber": 1,
      "groupId": 1,
      "subscriptionUrl": "https://filters.adtidy.org/extension/chromium/filters/2.txt",
      "tags": [
        "purpose:ads",
        "reference:101",
        "recommended",
        "reference:2"
      ],
      "trustLevel": "full",
      "platformsIncluded": [
        "windows",
        "mac",
        "android",
        "ext_ublock"
      ]
    }
  • revision.json

    Filter version metadata, automatically filled and overwritten on each build.

  • filter.txt

    Resulting compiled filter.

  • diff.txt

    Build log that contains excluded and converted rules with an explanation.

Tags

Every filter can be marked by a number of tags. Every tag metadata listed in /tags/metadata.json.

Example
{
    "tagId": 1,
    "keyword": "purpose:ads"
  },

Possible tags:

  • lang:* — for language-specific filters; one or multiple lang-tags can be used. For instance, AdGuard Russian filter is marked with the lang:ru tag.

  • purpose:* — determines filters purposes; multiple purpose-tags can be used for one filter list. For instance, AdGuard DNS is marked with both purpose:ads and purpose:privacy.

  • recommended — for low-risk filter lists which are recommended to use in their category. The category is determined by the pair of the lang:* and purpose:* tags.

  • obsolete — for abandoned filter lists; filter's metadata with this tag will be excluded from filters.json and filters_i18n.json.

Groups

/groups/metadata.json — filters groups metadata. Each filter should belong to one of the groups.

Filters optimization

For each filter, AdGuard compiles two versions: full and optimized. Optimized version is much more lightweight and does not contain rules which are not used at all or used rarely. Rules usage frequency comes from the collected filter rules statistics (thanks to the volunteers who enabled it in their AdGuard).

  • optimization_config.json - defines the target for the optimization process. AdGuard will try to compress the lists by removing the most rarely used rules until the compression goal (defined in percents) is met.

Filters compiler customization

custom_platforms.js customizes the way filters are compiled for certain platforms. We should use it if we need to temporary change rules for a platform. In all other cases, we should prefer the default configuration. Below is a example of the configuration for the platform AdGuard for Chrome with comments:

    "EXTENSION_CHROMIUM": {
        // Defines the platform for which the settings are specified.
        "platform": "ext_chromium",
        // Defines the path that can be used to access the settings or resources associated with this platform.
        "path": "extension/chromium",
        "configuration": {
            // Sets an array of regular expressions that will be used to remove certain rules.
            "removeRulePatterns": [
                "^((?!#%#).)*\\$\\$|\\$\\@\\$",
                "\\$(.*,)?replace=",
                "important,replace=",
                "\\$(.*,)?app",
                "\\$network",
                "\\$protobuf",
                "important,protobuf",
                "\\$extension",
                ",extension"
            ],
            // Sets an array of objects that will be used to replace certain values.
            "replacements": [ 
                {
                    "from": ":has\\(",
                    "to": ":-abp-has("
                }
            ],
            // Specifies whether to ignore hints for rules. A value of "false" means that hints will not be ignored.
            "ignoreRuleHints": false
        },
        "defines": {
            "adguard": true,
            "adguard_ext_chromium": true
        }
    },

Filters localization

If you want to help with filters translations, you can join us on Crowdin: https://crowdin.com/project/adguard-applications/en#/miscellaneous/filters-registry

Please learn more about translating our products: https://adguard.com/kb/miscellaneous/contribute/translate/program/

Filters templates

@include directive allows to include the content of specified file into the filter.

If you want to add a filter and keep all its rules during optimization, use the /notOptimized parameter.

Example:

@include "https://example.org/test-filter.txt" /notOptimized

How to build

yarn install

Run the following command:

node index.js

Build with white/black lists:

node index.js -i=1,2,3 -s=4,5,6

Validate filters.json and filters_i18n.json for platforms:

node validate ./platforms

For AdGuard filters all locales are required, it means 100% translated.

Validate locales:

yarn locales:validate

For third-party filters only REQUIRED_LOCALES should be 100% done.

More Repositories

1

AdGuardHome

Network-wide ads & trackers blocking DNS server
Go
18,381
star
2

AdguardBrowserExtension

AdGuard browser extension
JavaScript
2,427
star
3

AdguardFilters

AdGuard Content Blocking Filters
Adblock Filter List
2,331
star
4

dnsproxy

Simple DNS proxy with DoH, DoT, DoQ and DNSCrypt support
Go
1,791
star
5

AdguardForiOS

The most advanced ad blocker for iOS
JavaScript
1,289
star
6

AdguardForAndroid

Open bug tracker for Android version of AdGuard.
1,060
star
7

AdGuardForSafari

AdGuard for Safari app extension
JavaScript
875
star
8

AdGuardDNS

Public DNS resolver that protects you from ad trackers
Go
634
star
9

AdguardForWindows

AdGuard for Windows open bug tracker
568
star
10

AdGuardSDNSFilter

AdGuard Simplified Domain names filter
Adblock Filter List
491
star
11

ContentBlocker

Content blocking extension for Samsung Internet and Yandex Browser
Java
402
star
12

cname-trackers

This repository contains a list of popular CNAME trackers
JavaScript
334
star
13

AdGuardExtra

AdGuard Extra is designed to solve complicated cases when regular ad blocking rules aren't enough.
270
star
14

AdguardForMac

Open bug tracker for Mac version of AdGuard
269
star
15

PopupBlocker

Popup blocking userscript
TypeScript
220
star
16

gomitmproxy

Simple golang mitm proxy implementation
Go
155
star
17

AdguardKnowledgeBase

Adguard Knowledge Base
140
star
18

AdGuardMV3

AdGuard browser extension prototype based on the new Manifest V3
TypeScript
121
star
19

HostlistsRegistry

Known hosts blocklists that are made available to the users of AdGuard products
JavaScript
113
star
20

AdguardAssistant

Adguard Assistant userscript
JavaScript
110
star
21

Scriptlets

AdGuard scriptlets library
JavaScript
109
star
22

HostlistCompiler

A simple tool that compiles hosts blocklists from multiple sources
JavaScript
95
star
23

BlockYouTubeAdsShortcut

This repo contains the code for blocking YouTube ads that is supposed to be run by an iOS shortcut
JavaScript
85
star
24

AdGuardVPNForAndroid

AdGuard VPN Android app open bug tracker
81
star
25

DisableAMP

Disable AMP userscript
JavaScript
76
star
26

DnsLibs

DNS filtering library
C++
75
star
27

urlfilter

AdGuard content blocking library in golang
Go
71
star
28

AdGuardVPNExtension

AdGuard VPN Chrome and Firefox extension
TypeScript
57
star
29

AnonymousRedirect

Very simple HTML page that is used for anonymous redirect
HTML
55
star
30

ExtendedCss

A TypeScript library for non-standard element selecting — :contains(), :matches-css(), etc., and applying CSS styles with extended properties.
TypeScript
54
star
31

HttpsExclusions

Centralized repo for HTTPS exclusions
JavaScript
48
star
32

KnowledgeBaseDNS

AdGuard DNS knowledge base
JavaScript
47
star
33

StealthMode

JavaScript
46
star
34

Userscripts

Userscripts made by our team
JavaScript
42
star
35

AdGuardVPNForWindows

AdGuard VPN Windows app open bug tracker
39
star
36

VscodeAdblockSyntax

TM language plugin with ad blocking rules syntax
37
star
37

FiltersCompiler

A tool that compiles & validates filters
JavaScript
36
star
38

tsurlfilter

AdGuard content blocking library
TypeScript
35
star
39

CoreLibs

Core Adguard libraries
33
star
40

BrowserAssistant

AdGuard Browser Assistant
JavaScript
33
star
41

AGLint

Universal adblock filter list parser, linter and converter
TypeScript
28
star
42

KnowledgeBase

AdGuard knowledge base
JavaScript
26
star
43

AdGuardVPNForiOS

AdGuard VPN iOS app open bug tracker
25
star
44

SafariConverterLib

Swift library that converts AdGuard rules to Safari content blocking rules
Swift
21
star
45

AdGuardVPNForMac

AdGuard VPN Mac app open bug tracker
21
star
46

AdguardTeam.github.io

HTML
17
star
47

companiesdb

This is a companies DB that we use in AdGuard Home and AdGuard DNS.
JavaScript
16
star
48

ProxiesSetup

A simple script that sets up an HTTP and a SOCKS5 proxy (squid and danted)
Shell
16
star
49

WebBatteryTester

This application allows you to test how quick is your battery drained by web-browsing.
Java
14
star
50

golibs

Small helper Go libraries
Go
13
star
51

SafariConverter

Converter: ad blocking rules -> safari content blocker
JavaScript
12
star
52

deep-override

TypeScript
10
star
53

VerificationLibrary

Certificates verification library
C
9
star
54

go-webext

Automation for working with extension stores
Go
9
star
55

FiltersDownloader

Pre-processing library for filters subscriptions
JavaScript
9
star
56

translate

Simple internationalization library with react integration
TypeScript
8
star
57

AdGuardFiltersStats

The repo where we collect AdguardFilters statistics
JavaScript
8
star
58

ecsstree

Adblock Extended CSS supplement for CSSTree
JavaScript
7
star
59

ReportsWebApp

Allows users to report a problem with Adguard filters
JavaScript
7
star
60

NativeLibsCommon

Native libs common
C++
6
star
61

Recovery

JavaScript
5
star
62

VpnLibs

Open bug tracker for AdGuard VPN core library
5
star
63

KnowledgeBaseVPN

AdGuard VPN knowledge base
JavaScript
5
star
64

AdGuardVpnKnowledgeBase

AdGuard VPN Knowledge Base
5
star
65

LegalDocs

AdGuard's legal documents
4
star
66

SafariContentBlockerTester

Utility Safari extension for content blocker format testing.
JavaScript
4
star
67

TestCases

Used for testing puproses
JavaScript
3
star
68

SafariContentBlockerConverterCompiler

Utility scripts for building safari content blocker converter.
JavaScript
3
star
69

github-stats

Tool for calculating AdguardFilters contributors statistics
JavaScript
3
star
70

DeadDomainsLinter

Simple tool to check adblock filtering rules for dead domains.
JavaScript
2
star
71

AdGuardVPNCLI

AdGuard VPN command-line version
2
star
72

AdGuardDNSClient

Client tool for AdGuard DNS
Go
2
star
73

closure-tools-helper

TypeScript
1
star
74

dns-sde-extension

Proof-of-concept browser extension for Structured DNS errors
1
star