安全可控的 DNS 广告拦截管家

基于 Pi-hole v6 API 的 DNS 广告拦截器管理工具，支持状态监控、启停控制与阻断分析，为家庭/企业网络提供便捷的命令行运维能力。

基本信息

• 技能名称?pihole
• 中文名称?安全可控的 DNS 广告拦截管家
• 作者?baanish
• 分类?专业技能
• 版本?v2.0.1
• 标签?devops, networking, security, automation, backend

使用方法

使用说明
核心用法
Pi-hole Skill 是一款面向 ClawdBot 生态的命令行工具，用于远程管理 Pi-hole v6 DNS 广告拦截服务。用户通过自然语言指令即可完成状态查询、广告过滤启停、临时禁用计时器设置以及阻断域名分析等操作。配置方式灵活，支持 YAML 配置文件与环境变量双模式，适配本地自签名证书与生产环境 HTTPS 场景。
显著优点

1. 会话安全机制 ：采用 Pi-hole v6 的 session-based 认证，令牌 30 分钟过期，API 密码以 JSON body 传输而非 URL 暴露，避免进程列表泄露。
2. 输入严格验证 ：内置 validate_number 与 validate_domain 函数，所有用户输入经转义处理，杜绝命令注入风险。
3. 网络传输安全 ：默认启用 SSL 证书验证，支持 insecure 标志适配内网自签名场景，curl 请求统一设置 30 秒超时防止阻塞。
4. 零文件系统写入 ：只读配置文件，不执行任何本地文件写入或系统权限提升操作，攻击面极小。
5. 运维友好设计 ：提供 5 分钟快速禁用、自定义时长禁用等实用功能，满足临时放行广告站点的需求。
   潜在缺点与局限性
   功能边界受限 ：Pi-hole v6 API 已移除域名白名单管理功能，用户必须登录 Web Admin 手动操作，无法通过本 Skill 完成。
   无会话缓存机制 ：每次 API 调用均重新获取 session token，虽安全性高但增加一次往返请求。
   令牌明文存储 ：API token 以明文形式存放于配置文件，依赖用户自行设置 600 权限控制访问。
   外部强依赖 ：完全依赖 Pi-hole 服务可用性，若目标主机网络不可达或 API 变更，Skill 将失效。
   适合的目标群体
   家庭网络管理员：需快速开关广告过滤、查看阻断统计
   中小企业 IT 运维：批量管理多台 Pi-hole 实例
   技术爱好者：偏好命令行交互、集成至自动化工作流
   ClawdBot 用户：已在生态内，希望统一入口管理网络基础设施
   使用风险
   配置泄露风险 ：若 ~/.clawdbot/clawdbot.json 权限设置不当，其他用户可能读取 API 令牌
   误操作风险 ：自然语言指令解析错误可能导致意外禁用广告过滤（如将 "30" 误解为 30 秒而非 30 分钟）
   网络超时风险 ：高延迟网络环境下 30 秒超时可能导致操作失败
   版本兼容性 ：仅支持 Pi-hole v6+，v5 用户需升级或寻找替代方案