开源社区维护的 Pi-hole 管理工具，通过只读 SQL 查询本地 FTL 数据库，为家庭网络管理员提供安全的广告拦截统计与监控能力。
说明：
## 核心用法
pihole-ctl 是一款面向本地 Pi-hole 实例的管理与监控技能，主要服务于家庭网络环境中的 DNS 广告拦截场景。其核心功能分为两大模块：一是**统计查询**，通过 Python 脚本直接读取 Pi-hole 的 FTL 数据库（SQLite），获取 24 小时内的广告拦截量、Top 查询域名、最活跃客户端等关键指标；二是**服务管理**，支持通过标准 CLI 命令启用/禁用拦截功能、更新 Gravity 黑名单数据库。用户可通过自然语言触发，如询问”今天拦截了多少广告”或”Pi-hole 状态如何”，系统即返回结构化的 JSON 数据或命令执行结果。
## 显著优点
1. **数据准确性高**：直接查询 FTL 数据库而非依赖 Web 界面 API，避免缓存延迟，统计结果实时可靠。
2. **安全设计严谨**：数据库连接采用 `mode=ro` 只读 URI 模式，从根本上杜绝误写风险；SQL 查询全面使用参数化语句，彻底消除注入攻击面。
3. **零外部依赖**：仅依赖 Python 标准库（sqlite3、json、argparse 等），无需安装第三方包，部署简洁且供应链攻击风险极低。
4. **权限最小化**：仅需读取数据库文件的权限，无需 root 特权即可运行核心查询功能，符合安全运维最佳实践。
5. **开源可审计**：代码完全公开，逻辑透明，便于管理员自行审查或定制修改。
## 潜在缺点与局限性
1. **本地部署限制**：必须运行在 Pi-hole 所在服务器或具备数据库访问权限的节点上，无法远程管理多实例。
2. **功能边界清晰**：仅支持查询与基础启停控制，缺乏高级功能如自定义黑名单管理、DHCP 配置、Group 策略调整等。
3. **CLI 管理需特权**：`pihole enable/disable` 等管理命令仍需 sudo 权限，自动化场景下需额外配置免密 sudo 或 systemd 权限委派。
4. **数据库路径硬编码**：默认路径为 `/etc/pihole/pihole-FTL.db`，若 Pi-hole 使用非标准安装路径，需手动指定 `–db` 参数。
5. **无历史趋势分析**：仅支持固定时间窗口（如最近 24 小时）的统计，缺乏长期数据聚合与可视化能力。
## 适合的目标群体
– **家庭网络管理员**：已部署 Pi-hole 的个人用户，希望快速获取拦截统计而无需登录 Web 后台。
– **Homelab 爱好者**：拥有自托管基础设施的技术用户，需要将 Pi-hole 监控集成到自动化工作流或通知系统中。
– **小型办公网络运维**：10-50 人规模的内网环境，需定期审计 DNS 查询行为或排查异常客户端。
– **隐私敏感用户**：偏好本地数据处理、拒绝云端 API 依赖的去中心化倡导者。
## 使用风险
1. **权限配置风险**：若错误地将用户加入过高权限组或授予数据库目录写权限，可能导致 FTL 数据库损坏。
2. **路径遍历隐患**：虽然脚本本身对 `–db` 参数无过滤，但需确保调用方传入可信路径，避免恶意构造读取系统敏感文件（如 `/etc/shadow`）。
3. **CLI 命令注入**：若上层应用未对用户输入做过滤，直接将自然语言指令拼接为 `pihole` 命令参数，可能引发命令注入（尽管当前实现未暴露此接口）。
4. **性能影响**：高频查询大型 FTL 数据库（如保留 365 天日志）可能短暂占用磁盘 I/O，影响 Pi-hole 实时解析性能。
5. **版本兼容性**：Pi-hole FTL 数据库 schema 可能随版本升级变更，需关注 skill 与 Pi-hole 的版本匹配。
