{"id":28703148,"url":"https://github.com/adguardteam/deaddomainslinter","last_synced_at":"2026-03-03T22:01:36.025Z","repository":{"id":219627934,"uuid":"749519520","full_name":"AdguardTeam/DeadDomainsLinter","owner":"AdguardTeam","description":"Simple tool to check adblock filtering rules for dead domains.","archived":false,"fork":false,"pushed_at":"2025-09-01T07:01:56.000Z","size":234,"stargazers_count":32,"open_issues_count":16,"forks_count":2,"subscribers_count":8,"default_branch":"master","last_synced_at":"2026-01-26T13:54:56.955Z","etag":null,"topics":["adblock","adblock-list","adblock-plus","adguard","aglint","filter-list","linter","ublock-origin"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/AdguardTeam.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2024-01-28T20:05:24.000Z","updated_at":"2025-09-01T06:57:50.000Z","dependencies_parsed_at":"2024-04-07T09:28:28.228Z","dependency_job_id":"284daa03-0a1e-40a9-9878-088b5c8d2d33","html_url":"https://github.com/AdguardTeam/DeadDomainsLinter","commit_stats":null,"previous_names":["adguardteam/deaddomainslinter"],"tags_count":11,"template":false,"template_full_name":null,"purl":"pkg:github/AdguardTeam/DeadDomainsLinter","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AdguardTeam%2FDeadDomainsLinter","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AdguardTeam%2FDeadDomainsLinter/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AdguardTeam%2FDeadDomainsLinter/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AdguardTeam%2FDeadDomainsLinter/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/AdguardTeam","download_url":"https://codeload.github.com/AdguardTeam/DeadDomainsLinter/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AdguardTeam%2FDeadDomainsLinter/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30063356,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-03T18:21:05.932Z","status":"ssl_error","status_checked_at":"2026-03-03T18:20:59.341Z","response_time":61,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["adblock","adblock-list","adblock-plus","adguard","aglint","filter-list","linter","ublock-origin"],"created_at":"2025-06-14T13:07:09.237Z","updated_at":"2026-03-03T22:01:36.019Z","avatar_url":"https://github.com/AdguardTeam.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Dead Domains Linter\n\n[![npm-badge]][npm-url] [![license-badge]][license-url]\n\nThis is a simple tool that checks adblock filtering rules for dead domains.\n\nIn the future, it should be replaced with an [AGLint rule][aglintrule].\n\n[aglintrule]: https://github.com/AdguardTeam/AGLint/issues/194\n[npm-badge]: https://img.shields.io/npm/v/@adguard/dead-domains-linter\n[npm-url]: https://www.npmjs.com/package/@adguard/dead-domains-linter\n[license-badge]: https://img.shields.io/github/license/AdGuardTeam/DeadDomainsLinter\n[license-url]: https://github.com/AdguardTeam/DeadDomainsLinter/blob/master/LICENSE\n\n## How to use\n\n### Installation and update\n\nFirst of all, install the dead-domains-linter:\n\n```shell\nnpm i -g @adguard/dead-domains-linter\n```\n\n\u003e [!NOTE]\n\u003e If you have it installed and need to update to a newer version, run this\n\u003e command:\n\u003e\n\u003e ```shell\n\u003e npm update -g @adguard/dead-domains-linter\n\u003e ```\n\n### Interactive mode\n\nBy default it runs in interactive mode, scans the current directory and all its\nsubdirectories for `*.txt` files, and asks the user to apply suggested changes.\n\nJust run it in the directory with your filter lists to see how it works:\n\n```shell\ndead-domains-linter\n```\n\nHere's how the interactive mode looks like:\n![dead-domain-linter](https://cdn.adtidy.org/website/github.com/DeadDomainsLinter/default-config.png)\n\nYou can specify a custom glob expression to select files that the tool will\nscan:\n\n```shell\ndead-domains-linter -i filter.txt\n```\n\n### Automatic and show-only mode\n\nYou can allow it to automatically apply suggestions by passing the `--auto`\nflag:\n\n```shell\ndead-domains-linter --auto\n```\n\nAlternatively, you can run it in the \"show only\" mode:\n\n```shell\ndead-domains-linter --show\n```\n\n### Commenting rules out instead of removing them\n\nOne more useful feature would be to comment out filter rules that contain dead\ndomains instead of removing them. You can enable this feature by passing the\n`--commentout=true` flag:\n\n```shell\ndead-domains-linter --commentout\n```\n\n### Ignoring domains\n\nIf there are specific domains you want the tool to ignore and treat as valid,\nyou can use the --ignore flag and provide a file containing a list of domains to be excluded.\n\n### Exporting and using a pre-defined list of domains\n\nInstead of immediately modifying the filter list, you may opt to export the\nlist of dead domains so that you could carefully review it. For instance, the\ncommand below scans `filter.txt` for dead domains and exports this list to\n`domains.txt`.\n\n```shell\ndead-domains-linter -i filter.txt --export=domains.txt\n```\n\nWhen you finish the review and clean up the list, you can make the tool use it\nexclusively to modify filter lists. For instance, the command below scans\n`filter.txt` for all domains that are in `domains.txt` and removes them from\nthe filter list.\n\n```shell\ndead-domains-linter -i filter.txt --import=domains.txt --auto\n```\n\n### Disabling DNS check\n\n\u003e [!IMPORTANT]\n\u003e Please read this if you maintain a filter list with a large number of users.\n\nThe tool relies on AdGuard DNS snapshot of the Internet domains that represents\nall domains used by 100M+ AdGuard DNS users for the last 24 hours. Using this\nsnapshot is a good way to find dead domains, but it alone may not be 100%\naccurate and it can produce false positives for really rarely visited domains.\nThis is why the tool also double-checks dead domains with a DNS query.\n\nIf your filter list does not have a large number of dead domains, we recommend\ndisabling that double-check by running the tool with the `--dnscheck=false`\nflag:\n\n```shell\ndead-domains-linter --dnscheck=false\n```\n\n\u003e [!NOTE]\n\u003e Actually, AdGuard [filter policy][filterpolicy] requires that the website\n\u003e should be popular enough to be added to the filter list. So there's a great\n\u003e chance that even when the tool produced a false positive when running with\n\u003e `--dnscheck=false`, this domain anyways does not qualify for the filter list.\n\n[filterpolicy]: https://adguard.com/kb/general/ad-filtering/filter-policy/\n\n### Full usage info\n\n```shell\nUsage: dead-domains-linter [options]\n\nOptions:\n  -i, --input       glob expression that selects files that the tool will scan.\n                                                  [string] [default: \"**/*.txt\"]\n      --dnscheck    Double-check dead domains with a DNS query.\n                                                       [boolean] [default: true]\n      --commentout  Comment out rules instead of removing them.\n                                                      [boolean] [default: false]\n      --export      Export dead domains to the specified file instead of\n                    modifying the files.                                [string]\n      --import      Import dead domains from the specified file and skip other\n                    checks.                                             [string]\n      --ignore      File with domains to ignore.                        [string]\n  -a, --auto        Automatically apply suggested fixes without asking the user.\n                                                      [boolean] [default: false]\n  -s, --show        Show suggestions without applying them.\n                                                      [boolean] [default: false]\n  -v, --verbose     Run with verbose logging          [boolean] [default: false]\n      --version     Show version number                                [boolean]\n  -h, --help        Show help                                          [boolean]\n\nExamples:\n  dead-domains-linter -i **/*.txt       scan all .txt files in the current\n                                        directory and subdirectories in the\n                                        interactive mode\n  dead-domains-linter -a -i filter.txt  scan filter.txt and automatically apply\n                                        suggested fixes\n```\n\n## How to develop\n\nFirst, install [pnpm](https://pnpm.io/): `npm install -g pnpm`.\n\nThen you can use the following commands:\n\n* `pnpm install` - install dependencies.\n* `pnpm run lint` - lint the code.\n* `pnpm run test` - run the unit-tests.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fadguardteam%2Fdeaddomainslinter","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fadguardteam%2Fdeaddomainslinter","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fadguardteam%2Fdeaddomainslinter/lists"}