Baike.dev
All toolsOnline toolsAI codingTrendingOpen sourceNewsSubmit
Log in
< Back to tools
H

HostlistsRegistry

> 编程语言
Open source

Known hosts blocklists that are made available to the users of AdGuard products

382 stars0 likes2 views
WebsiteGitHub

About

Known hosts blocklists that are made available to the users of AdGuard products

AdGuard Host Lists Registry

  • What Blocklists Can Be Added Here
  • Where Blocklists Are Published
  • Filters Metadata
  • Services Metadata
  • Safe Search Filters
  • Typosquatting Allowlist
  • How to Build
  • How to Compress
  • Localizations

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.

Where Blocklists Are Published

  • filters.json contains all the blocklists added to the repo. downloadURL is the location of the re-hosted blocklist.
  • filters_apps.json contains a minimal hand-picked subset of the blocklists that is used by AdGuard apps. Unlike AdGuard Home and AdGuard DNS, apps do not handle huge blocklists well, so only the lists marked with includeInApps in their metadata.json are included here. Its localizations are published in filters_apps_i18n.json.
  • services.json is the meta-data of "Web Services". This is a part of the parental control functionality of AdGuard Home and AdGuard DNS.

What Blocklists Can Be Added Here

  • 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:

    • good: "blocks TV ads".
    • bad: "John Doe's personal blocklist"
  • 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:

    • 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 reported issues and discussions should be at least 10 per month.
    • the blocklist should be actively supported for at least 6 months.
  • 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.

How to add a filter list

To add a new filter, you need to:

  1. Go to the filters folder.
  2. Go to the category to which the new filter will belong.
  3. Create a new folder with the name filter_(id)_(filter name).
  4. Create two files in this folder: configuration.json and metadata.json. The contents of these files are described below.
  5. In the file 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, /assets/filters-dev.json, /assets/filters_apps.json, and /assets/filters_apps_i18n.json must not be edited manually.

Filters Metadata

  • 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 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

    • deprecated — optional, boolean, filter is deprecated and should not be used by the products, but filter is still available, i.e. not removed

    • expires — filter's default expiration period

    • displayNumber — this number is used when AdGuard sorts available filters (GUI)

    • environment - either dev or prod. Only prod lists are available in AdGuard DNS.

    • includeInApps - optional, boolean. If set to true, the list is included in filters_apps.json and filters_apps_i18n.json, the minimal hand-picked index used by AdGuard apps. Only a few moderately-sized, non-problematic lists should be marked with this flag as apps do not handle huge blocklists well.

    • disabled - if set to true, the blocklist won't be updated.

    • tags — a list of tags

    • trusted - a flag that allows using $dnsrewrite rules for this filter. If the filter is not trusted, $dnsrewrite rules will be removed from the compiled filter.

      Metadata example

    json
    {
      "filterKey": "adguard_dns_filter",
      "filterId": 1,
      "name": "AdGuard DNS filter",
      "description": "Filter composed of several other filters (AdGuard Base filter, Social Media filter, Tracking Protection filter, Mobile Ads filter, EasyList and EasyPrivacy) and simplified specifically to be better compatible with DNS-level ad blocking.",
      "timeAdded": 1404115015843,
      "homepage": "https://kb.adguard.com/general/adguard-ad-filters",
      "expires": "4 days",
      "displayNumber": 3,
      "environment": "prod",
      "tags": [],
      "trusted": true
    }
  • revision.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

Tags

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

Example

json
{
  "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.

  • 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.

How to add a blockable service

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.

Services Metadata

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, group:

  • 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)
  • group - semantic group for service. Possible values:
Full Name Key Definition
Artificial intelligence ai Provides AI-powered tools and intelligent solutions for automation, analysis, and content-making.
Content delivery networks (CDN) cdn Optimizes content delivery for websites through caching, load balancing, and strategic distribution.
Dating services dating Connects individuals seeking romantic relationships based on shared interests and preferences.
Gambling and betting gambling Offers online gaming and betting experiences with the chance to win prizes through casino games and sports wagering.
Gaming gaming Provides a diverse range of video and online games for entertainment purposes.
Web hosting hosting Offers server space and resources for hosting websites, applications, and digital content.
Messaging services messenger Facilitates instant communication through text, voice, and video messaging.
Privacy tools privacy Prioritizes user data protection and privacy through encryption and strict security measures.
Shopping shopping Enables online commerce with secure payment options, order tracking, and personalized shopping experiences.
Social networks social_network Connects individuals for interactions, community-building, and sharing personal and professional information.
Software development software Provides tools, platforms, and frameworks for software development, coding, and project management.
Streaming services streaming Delivers real-time audio, video, and other digital content for immediate access and entertainment.

Service examples

services.json - wechat object

json
{
  "id": "wechat",
  "name": "WeChat",
  "rules": ["||wechat.com^", "||weixin.qq.com^", "||wx.qq.com^"],
  "icon_svg": "",
  "group": "social_network"
}

wechat.yml

yaml
id: wechat
name: WeChat
rules:
  - '||wechat.com^'
  - '||weixin.qq.com^'
  - '

Issues· 0 open

View all issuesOpen on GitHub

No open issues yet, or sync has not completed.

> Tags

JavaScriptadguardadguard-dnsadguard-home

No comments yet. Be the first to share.

> Details

PublishedAug 1, 2026
UpdatedSep 17, 2026
Category编程语言
PricingOpen source

> Related tools

T
TypeScript
JavaScript 的超集,为前端与全栈提供静态类型
P
Python
通用编程语言,广泛用于 Web、数据与 AI
G
Go
Google 推出的简洁高效系统语言