pihole

核心用法

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 用户需升级或寻找替代方案

核心用法

Pi-hole Control Skill 专为管理本地部署的 Pi-hole DNS 广告拦截器设计，通过 v6 API 实现完整的远程控制。用户可通过自然语言指令查询状态（pihole status）、开关防护（pihole on/off）、设置临时禁用（pihole disable 5m），以及查看拦截统计和被阻域名分析。配置仅需提供 API 地址和应用密码，支持环境变量或配置文件两种方式注入凭据。

显著优点

安全架构扎实：采用 Pi-hole v6 标准会话认证，Token 通过 JSON Body 传输而非 URL，避免泄露风险；支持 HTTPS 加密与可选证书验证绕过，兼顾安全与自签名证书场景。依赖最小化：纯 Shell 实现，零第三方库依赖，仅调用系统标准的 curl 与 jq，供应链攻击面为零。代码质量高：通过 CLS-Certify 六维检测，静态分析 95 分，动态行为 90 分，隐私合规 92 分，无危险函数调用、无硬编码敏感信息、无动态代码下载。功能完整：覆盖状态查询、启停控制、定时禁用、实时统计、拦截日志分析五大核心场景，响应格式清晰易读。

潜在缺点与局限性

v6 API 功能缺失：Pi-hole v6 移除了域名白名单的 API 端点，用户必须通过 Web UI 手动管理白名单，Skill 无法自动化此流程。会话效率待优化：当前实现每次 API 调用均重新获取 30 分钟有效期的会话 Token，虽简化逻辑但增加请求开销。单实例限制：仅支持管理单一 Pi-hole 节点，无法原生适配主备或分布式部署场景。网络依赖刚性：需确保运行环境到 Pi-hole 的网络可达性，防火墙或隔离网络可能导致功能失效。

适合人群

• 家庭网络或小型办公环境中部署 Pi-hole 的技术用户
• 需要快速语音/聊天控制广告拦截状态的智能家居集成者
• 重视供应链安全、拒绝第三方依赖的极简主义管理员
• 已通过 HTTPS 加固 Pi-hole 访问的生产环境运维人员

常规风险

• 配置泄露风险：apiToken 存储于配置文件或环境变量，需确保文件权限（建议 0600）和环境隔离
• 中间人攻击：若禁用证书验证（insecure: true）且使用 HTTP，存在流量嗅探风险
• 误操作阻断：禁用操作若忘记重新启用，可能导致网络长期暴露于广告/追踪
• API 兼容性：Pi-hole v5 用户需升级至 v6，否则 API 端点不兼容

安全评级 S（88 分），来源可信度 T2（GitHub 组织官方仓库），适合生产环境部署。