This repository contains the known hosts blocklists that are made available to the users of AdGuard products (AdGuard DNS, AdGuard Home, etc).
Some of these blocklists are automatically converted to the rules format that AdGuard product understand better.
filters.json
contains all the blocklists added to the repo. downloadURL
is the location of the re-hosted blocklist.services.json
is the meta-data of "Web Services". This is a part of the parental control functionality of AdGuard Home and AdGuard DNS.The blocklist should be oriented towards DNS-level content blockers. There is a different repo for browser content blockers.
We prefer (mostly) original lists to compilations.
We prefer blocklists that are specifically made for AdGuard Home and use adblock-style syntax. Lists that use /etc/hosts
can also be added if there is no alternative.
The blocklist should have a clear purpose.
Examples:
The blocklist should have a place for receiving user complaints and holding discussions, such as a repository on github.com, or a public website/forum.
The blocklist should be relatively popular, meaning:
The blocklist should be regularly updated with at least 10 updates per month.
Previously added blocklists that haven't received any support for a year will be removed. We reserve the right to remove the blocklist earlier, depending on circumstances.
If the blocklist contains too many problematic rules, it will not be added. A rule is considered problematic if it causes false positives or otherwise displays unitended behavior. Decisions about blocklists with problematic rules are arbitrary and there may be exceptions.
If the blocklist intentionally blocks or restricts access to a service for no reason other than being a reflection of the filter author's opinion, the blocklist will not get added, or will get removed if already added.
If the blocklist is popular in a specific region and there are no alternatives to it, then it can be added as is even if it does not satisfy requirements above.
To add a new filter, you need to:
filter_(id)_(filter name)
.configuration.json
and metadata.json
. The contents of these files are described below.locales/en/filters.json
add an object with the name and description of the filter according to the example added above.The files /assets/filters.json
and /assets/filters-dev.json
must not be edited manually.
metadata.json
Filter metadata. Includes name, description, etc.
filterKey
— unique human-readable filter identifier (string)filterId
- unique internal filter identifier (integer)name
— filter name; can be localizeddescription
— filter descriptiontimeAdded
— 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 timehomepage
— filter website/homepageexpires
— filter's default expiration perioddisplayNumber
— this number is used when AdGuard sorts available filters (GUI)environment
- either dev
or prod
. Only prod
lists are available in AdGuard DNS.disabled
- if set to true
, the blocklist won't be updated.tags
— a list of tagsrevision.json
Filter version metadata, automatically filled and overwritten on each build.
filter.txt
Resulting compiled filter.
configuration.json
Configuration defines your filter list sources, and the transformations that are applied to the sources. See Hostlist compiler configuration for details
Every filter can be marked by a number of tags. Every tag metadata listed in /tags/metadata.json
.
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.
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
.
To add a new blocked service, a new .yml
file must be added to the services
directory, the contents of the directory and the resulting services.json
file are described in the next section.
The services.json
file combines information about services received from separate .yml
files located in the services
directory. The services.json
file is generated by a script, so there is no need to modify it manually.
Source .yml
files: Each .yml
file contains information about a specific service. The file name must match its id
.
File saving: .yml
files are stored in the services directory.
Updating information: In cases when it is necessary to change the configuration of a service, it is necessary to update the corresponding .yml
file in the services directory.
Adding a new service: to add a new service to services.json
it is necessary to add .yml
file to the services directory, after the script is run the file will be updated.
WARNING!
Deletion of files is strictly forbidden. If a service file is deleted, the script will restore it from a previous version of the services.json
file.
It is also forbidden to change service id
inside the .yml
file.
Service metadata includes id
, name
, rules
, icon_svg
:
id
— unique human-readable service identifier (string, as snake_case
)name
— service name (string)rules
— list of domain rules in Adblock syntax (list of strings)icon_svg
— svg icon (string)SVG icon requirements:
viewBox
attribute must be equal.fill="currentColor"
attribute. This is important for themes to work properly.width
and height
attributesengines_safe_search.txt
contains a set of rules to enforce Safe Search in the following searching engines:
youtube_safe_search.txt
contains a set of rules to enforce Safe Search and hide comments on YouTube.
yarn install
Run the following command:
yarn run compose
The build result can be found in the assets
directory.
Blocklist names, descriptions, and tags' names are translated via crowdin.
/locales
contains translations for filters, groups, and tags.
Base language strings:
locales/en/filters.json
locales/en/tags.json
In order to prepare these files run yarn run locales:prepare
.
This script will scan filters meta and add filters names, descriptions, and tags meta to the base language files.
yarn run locales:upload
yarn run locales:download