{"id":23789923,"url":"https://github.com/blackglory/fcdns","last_synced_at":"2025-09-08T17:32:57.866Z","repository":{"id":45281712,"uuid":"357292678","full_name":"BlackGlory/fcdns","owner":"BlackGlory","description":"🌳 DNS relay server with fact-checking.","archived":false,"fork":false,"pushed_at":"2024-12-28T01:58:26.000Z","size":2841,"stargazers_count":3,"open_issues_count":0,"forks_count":0,"subscribers_count":3,"default_branch":"main","last_synced_at":"2024-12-28T01:59:10.587Z","etag":null,"topics":["cli","esm","npm-package","typescript"],"latest_commit_sha":null,"homepage":"https://www.npmjs.com/package/fcdns","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/BlackGlory.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}},"created_at":"2021-04-12T18:07:21.000Z","updated_at":"2024-12-28T01:58:29.000Z","dependencies_parsed_at":"2024-12-16T23:51:08.293Z","dependency_job_id":"d1873eef-87d6-40ec-934d-9f370325bd66","html_url":"https://github.com/BlackGlory/fcdns","commit_stats":{"total_commits":173,"total_committers":2,"mean_commits":86.5,"dds":"0.028901734104046284","last_synced_commit":"866b36e6e26f80524bcebb969d237d4bb6c7e7af"},"previous_names":[],"tags_count":52,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/BlackGlory%2Ffcdns","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/BlackGlory%2Ffcdns/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/BlackGlory%2Ffcdns/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/BlackGlory%2Ffcdns/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/BlackGlory","download_url":"https://codeload.github.com/BlackGlory/fcdns/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":232333522,"owners_count":18507048,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","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":["cli","esm","npm-package","typescript"],"created_at":"2025-01-01T17:17:42.628Z","updated_at":"2025-09-08T17:32:57.782Z","avatar_url":"https://github.com/BlackGlory.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# fcdns\nDNS relay server with fact-checking.\n\n## Install\n```sh\nnpm install --global fcdns\n# or\nyarn global add fcdns\n```\n\n## Usage\n```sh\nUsage: fcdns [options]\n\nDNS relay server with fact-checking.\n\nOptions:\n  -V, --version                    output the version number\n  --test-server \u003cserver\u003e\n  --untrusted-server \u003cserver\u003e\n  --trusted-server \u003cserver\u003e\n  --port \u003cport\u003e                     (default: \"53\")\n  --timeout \u003cseconds\u003e               (default: \"30\")\n  --ip-whitelist \u003cfilename\u003e         (default: \"ip-whitelist.txt\")\n  --hostname-whitelist \u003cfilename\u003e   (default: \"hostname-whitelist.txt\")\n  --hostname-blacklist \u003cfilename\u003e   (default: \"hostname-blacklist.txt\")\n  --cache \u003cfilename\u003e                (default: \"cache.db\")\n  --test-timeout \u003cmilliseconds\u003e     (default: \"200\")\n  --log \u003clevel\u003e                     (default: \"info\")\n  -h, --help                       display help for command\n```\n\nExample:\n```sh\nfcdns \\\n  --test-server=162.125.7.1 \\\n  --untrusted-server=127.0.0.1:5301 \\\n  --trusted-server=127.0.0.1:5302\n```\n\n## 原理\n![流程图](./res/flow-chart.svg)\n\n## 必要条件\n使用fcdns需要指定3个服务器地址, 1份IP地址白名单, 1份主机名白名单.\n\n### 投毒测试服务器(test server)\n投毒测试服务器是一台非DNS服务器,\n当客户端向该远程主机的53端口发送DNS查询(question)时, 查询将会超时或被拒绝.\n当网络内存在DNS污染时, 向该远程主机发送DNS查询时, 将得到查询结果(answer).\n基于这两个事实, fcdns通过查询A记录的方式以判断相关主机名是否被投毒.\n\n通常, 在存在DNS污染的网络里, 任意不提供DNS服务器功能的在线主机都可以作为投毒测试服务器使用.\n由于投毒测试可能由于网络原因导致失败, 为了能够区分网络原因导致的失败,\nfcdns会在发出DNS查询的同时发出ping, 因此投毒测试服务器必须能够被ping通.\n\nfcdns会持久化缓存投毒测试的结果, 同一个主机名只在第一次查询时会经历投毒测试.\n\n### 不可信DNS服务器(untrusted server)\n不可信DNS服务器是一台DNS服务器, 客户端与该服务器的连接是被污染的, 或该服务器可能返回被污染的结果.\n从该服务器返回的结果虽然并不总是可信, 但借助投毒测试, 可以从中筛选出大量的可信结果.\n\n之所以需要依赖不可信DNS服务器, 是因为不可信DNS服务器通常比可信DNS服务器更快响应, 且返回的结果更准确.\n\n由于fcdns只提供DNS转发功能, 建议使用CoreDNS等程序建立本地DNS服务器作为背后的代理.\n\n### 可信DNS服务器(trusted server)\n可信DNS服务器是一台DNS服务器, 客户端与该服务器的连接是不被污染的, 且该服务器不会返回被污染的结果.\n\n之所以需要可信DNS服务器, 是为了能够查询那些被投毒的主机名的正确记录.\n可信DNS服务器返回的结果可能并不总是最准确, 但至少是具备可用性的.\n\n由于fcdns只提供DNS转发功能, 建议使用CoreDNS等程序建立本地DNS服务器作为背后的代理.\n\n### IP地址白名单(ip whitelist)\nIP地址白名单用于指定允许用\"不可信DNS服务器\"返回的IP地址或IP地址范围,\n所有不在白名单内的IP地址都会转用\"可信DNS服务器\"进行二次查询.\n\n如果DNS查询返回了多条A记录, 则只要有一条A记录的IP地址与白名单匹配, 就算作命中.\n\nfcdns会持久化缓存查询最终选择的服务器, 同一个主机名只在第一次查询时会被IP地址白名单影响.\n\n之所以使用白名单而不是黑名单, 是因为通常情况下白名单所需记录的内容条数较少.\n\n#### 文件格式\n白名单是一个文本文件, 以行为分隔符储存地址或地址范围.\n地址范围由起点IP和终点IP组成, 以`-`相连.\n\nIPv4地址示例:\n```\n1.1.1.1\n```\n\nIPv6地址示例:\n```\n2606:4700:4700::1111\n```\n\nIPv4地址范围示例:\n```\n1.0.1.0-1.0.3.255\n```\n\nIPv6地址范围示例:\n```\n2001:250::-2001:252:ffff:ffff:ffff:ffff:ffff:ffff\n```\n\n如果不需要此功能, 则只需要将白名单设置为:\n```\n0.0.0.0-255.255.255.255\n::-ffff:ffff:ffff:ffff:ffff:ffff:ffff:ffff\n```\n\n### 主机名白名单(hostname whitelist)\n主机名白名单用于强制使某些主机名在解析时使用不可信DNS服务器, 其优先级高于fcdns里的其他规则.\n\n### 主机名黑名单(hostname blacklist)\n主机名白名单用于强制使某些主机名在解析时使用可信DNS服务器, 其优先级低于白名单, 高于fcdns里的其他规则.\n\n#### 文件格式\n白名单是一个文本文件, 以行为分隔符存储主机名模式.\n主机名模式使用`*`作为通配符, 可以匹配任意个字符.\nfcdns认为的合法主机名模式只能由数字, 字母, 连字符(`-`), 点(`.`), 通配符(`*`)组成.\n\n主机名模式示例:\n```\nwikipedia.org\n*.wikipedia.org\n```\n\n## 针对fcdns的攻击\n### 以黑名单/白名单形式污染DNS服务器\n禁止向非DNS服务器发送DNS数据包将会破坏fcdns的投毒测试功能.\n\n### 无差别污染主机名\n劫持所有DNS响应将会破坏fcdns的投毒测试功能.\n\n### 随机投毒\n随机投毒将会使fcdns生成错误的缓存记录.\n\n### 禁止ping\n禁止发送ping(echo request)或丢弃reply(echo reply)将会破坏fcdns的投毒测试功能.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fblackglory%2Ffcdns","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fblackglory%2Ffcdns","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fblackglory%2Ffcdns/lists"}