krunalg/gravity-shield

# Pi-hole AI Guardian 为 Pi-hole 提供本地 AI 辅助的 DNS 威胁分类和威胁情报同步。 ## 功能 - 实时监控 Pi-hole DNS 查询日志。 - 在要求 Granite 进行推理之前，先提取确定性的域名特征。 - 在拦截之前，使用相同的分类器验证威胁情报源的命中情况。 - 将恶意域名写入 Pi-hole 的 `Adaptive Threat Blocklist` 组。 - 批量处理 Pi-hole 列表重载，而不是在每次插入后都进行重载。 - 为关键/已知合法域名保留核心的永不对抗策略（never-block policy）。 ## 架构 ``` Pi-hole FTL log -> DomainWatcher -> feature extraction -> Granite reasoning via Ollama -> structured verdict -> Pi-hole gravity.db -> Adaptive Threat Blocklist group Threat feeds (URLhaus, OpenPhish) -> ThreatIntelSyncer -> dedupe -> feature extraction + Granite verification -> Pi-hole gravity.db -> Adaptive Threat Blocklist group ``` ## 环境要求 - 安装了 Pi-hole v6.4+ 的 Raspberry Pi - Python 3.11+ - GNU Make - 包含 `granite4.1:3b` 的 Ollama ``` ollama pull granite4.1:3b ollama serve ``` ## 安装 ``` git clone pihole-ai cd pihole-ai make install make test make setup ``` 设置向导会创建： - `.venv` - `config_local.py` - systemd 服务 `pihole-ai-$USER` - 用于 `pihole reloadlists` 的 sudoers 规则 - Pi-hole 数据库/日志访问权限 ## 验证 ``` make daemon-status make logs ``` 检查最近的分类： ``` sqlite3 state.db \ "SELECT domain, category, confidence, rule_score, blocked FROM classifications ORDER BY classified_at DESC LIMIT 20" ``` 检查 Pi-hole 拦截情况： ``` sudo sqlite3 /etc/pihole/gravity.db \ "SELECT domain, comment FROM domainlist WHERE comment LIKE 'AI:%' OR comment LIKE 'TI:%' LIMIT 20" ``` 检查拦截组： ``` sudo sqlite3 /etc/pihole/gravity.db \ "SELECT id, name FROM \"group\" WHERE name='Adaptive Threat Blocklist'" ``` ## 分类流程 分类器不再仅仅将原始域名发送给 Granite。它首先会构建结构化证据： - 词法指标 - Shannon 熵 - 数字和连字符指标 - punycode/同形异义字信号 - TLD 风险 - 品牌相似度 - DGA 分数 - 规则分数及确定性原因 - 可用时的威胁情报上下文 Granite 返回 JSON： ``` { "classification": "PHISHING", "confidence": 0.97, "severity": "HIGH", "risk_score": 91, "reasons": ["Brand impersonation", "Suspicious TLD"], "recommended_action": "BLOCK" } ``` 只有当 action/category、置信度和规则分数通过配置的阈值时，域名才会被拦截。 ## Pi-hole 组行为 每个新拦截的域名都会被映射到： ``` Adaptive Threat Blocklist ``` 当存在 Pi-hole 组表时，`PiholeClient` 会创建该组，并将映射插入到 `domainlist_by_group` 中。 现有的历史条目不会自动迁移。 ## 重载行为 域名会立即写入 `gravity.db`，但 Pi-hole 的重载是批量处理的： ``` PIHOLE_RELOAD_INTERVAL_SECONDS = 60 ``` 在 `config_local.py` 中将其设置为 `0` 即可立即重载。 ## 永不拦截策略 受保护的域名和后缀配置于： ``` NEVER_BLOCK_DOMAINS NEVER_BLOCK_SUFFIXES ``` 该策略在最终的 Pi-hole 插入层执行，因此即使分类器或情报源结果出错，也无法插入受保护的域名。 ## 配置 默认配置位于 `config.py` 中；本地覆盖配置位于 `config_local.py` 中。 重要设置： ``` OLLAMA_MODEL = "granite4.1:3b" BLOCK_CONFIDENCE_THRESHOLD = 0.80 RULE_SCORE_THRESHOLD = 70 DGA_THRESHOLD = 0.70 ENTROPY_THRESHOLD = 3.8 BRAND_MATCH_THRESHOLD = 0.80 THREAT_INTEL_INTERVAL_HOURS = 6 PIHOLE_BLOCK_GROUP_NAME = "Adaptive Threat Blocklist" PIHOLE_RELOAD_INTERVAL_SECONDS = 60 ``` ## 测试 ``` make test ``` 当前测试套件：44 个测试。所有外部服务均已被 mock。 ## 项目结构 ``` config.py config_local.py daemon.py watcher.py syncer.py classifier.py ollama_client.py pihole_client.py state_db.py threat_intel.py domain_policy.py features/ extractor.py lexical.py entropy.py digits.py hyphens.py punycode.py tld.py brand.py dga.py rules.py tests/ ``` ## 故障排除 Ollama： ``` curl http://localhost:11434/api/tags ollama list ``` 守护进程： ``` sudo systemctl status pihole-ai-$USER sudo journalctl -u pihole-ai-$USER -n 100 ``` 重载权限： ``` sudo -n pihole reloadlists ``` 状态数据库： ``` sqlite3 state.db "SELECT * FROM sync_log ORDER BY synced_at DESC LIMIT 10" sqlite3 state.db "SELECT * FROM classifications ORDER BY classified_at DESC LIMIT 5" ```

标签：AI风险缓解, DLL 劫持, DNS安全, IP 地址批量处理, Pi-hole, Sigma 规则, 域名分析, 大语言模型, 威胁情报, 开发者工具, 网络安全, 逆向工具, 隐私保护