adguard-home-skill

# AdGuard Home Skill 🛡️ Query AdGuard Home instances for DNS statistics, blocked domains, and client activity 🛡️ 查询 AdGuard Home 实例的 DNS 统计、拦截域名和客户端活动 --- ## Features | 功能特性 - ✅ Multi-instance support | 支持多实例配置 - ✅ Real-time DNS query statistics | 实时 DNS 查询统计 - ✅ Blocked domains leaderboard | 拦截域名排行 - ✅ Active client analysis | 活跃客户端分析 - ✅ Health status check | 健康状态检查 - ✅ Service status monitoring | 服务状态监控 - ✅ DNS configuration details | DNS 配置详情 - ✅ Filter rules inspection | 过滤规则和列表 - ✅ Recent query log | 最近查询日志 - ✅ TLS/encryption status | TLS/加密状态 --- ## Installation | 安装方法 ### Method 1: ClawHub CLI (Recommended) | 方法 1: ClawHub CLI（推荐） ```bash # Install from ClawHub registry | 从 ClawHub 安装 clawhub install adguard-home # Verify installation | 验证安装 clawhub list | grep adguard-home ``` ### Method 2: Manual Install | 方法 2: 手动安装 ```bash # Clone the repository | 克隆仓库 git clone https://github.com/foxleoly/adguard-home-skill.git cd adguard-home-skill # Copy to your skills directory | 复制到技能目录 cp -r . ~/.openclaw/workspace/skills/adguard-home/ ``` ### Post-Installation Setup | 安装后配置 1. **Create configuration file | 创建配置文件:** ```bash # Edit adguard-instances.json | 编辑配置文件 vim ~/.openclaw/workspace/adguard-instances.json ``` 2. **Add your instances | 添加实例:** ```json { "instances": { "dns1": { "url": "http://192.168.1.1:80", "username": "admin", "password": "your-password" } } } ``` 3. **Secure the config file | 保护配置文件:** ```bash chmod 600 ~/.openclaw/workspace/adguard-instances.json ``` 4. **Test the skill | 测试技能:** ```bash /adguard stats dns1 ``` --- ## Usage | 使用方法 ### Basic Commands | 基础命令 ```bash # Statistics & Monitoring | 统计与监控 /adguard stats [instance] # DNS statistics | DNS 统计 /adguard top-clients [instance] # Top 10 active clients | 活跃客户端 Top 10 /adguard top-blocked [instance] # Top 10 blocked domains | 被拦截域名 Top 10 /adguard health [instance] # Health check | 健康检查 /adguard status [instance] # Service status | 服务状态 # Configuration & Rules | 配置与规则 /adguard dns-info [instance] # DNS configuration | DNS 配置详情 /adguard filter-rules [instance] # Filter rules and lists | 过滤规则和列表 /adguard clients [instance] # Configured clients | 已配置的客户端 /adguard tls-status [instance] # TLS/encryption status | TLS/加密状态 # Query Log | 查询日志 /adguard querylog [instance] [n] # Recent n queries (default: 10) | 最近 n 条查询 ``` ### Examples | 命令示例 ```bash # Query dns1 instance statistics | 查询 dns1 实例的统计 /adguard stats dns1 # Check service status | 检查服务状态 /adguard status dns1 # View DNS configuration | 查看 DNS 配置 /adguard dns-info dns1 # View filter rules | 查看过滤规则 /adguard filter-rules dns1 # View last 20 DNS queries | 查看最近 20 条 DNS 查询 /adguard querylog dns1 20 # Check TLS status | 检查 TLS 状态 /adguard tls-status dns1 # If no instance specified, uses the first configured instance | 不指定实例则使用第一个 /adguard stats ``` ### Output Examples | 输出示例 **stats command | stats 命令：** ``` 📊 AdGuard Home Statistics (dns1) Total DNS Queries: 141,647 Blocked Requests: 32,540 (23.0%) Avg Response Time: 0.005ms ``` **status command | status 命令：** ``` 🔧 AdGuard Home Status (dns1) Version: v0.107.72 Running: ✅ Yes Protection: ✅ Enabled DNS Port: 53 HTTP Port: 1080 Language: zh-cn DHCP Available: ✅ Yes ``` **dns-info command | dns-info 命令：** ``` 🌐 DNS Configuration (dns1) Protection: ✅ Enabled Rate Limit: 20 req/s Upstream Mode: parallel Cache: ✅ 4MB DNSSEC: ❌ Disabled IPv6: ✅ Enabled Upstream DNS Servers: 1. https://dns.alidns.com/dns-query 2. 192.168.1.1:53 3. 8.8.8.8:53 ``` **filter-rules command | filter-rules 命令：** ``` 🛡️ Filter Rules (dns1) Filtering: ✅ Enabled Update Interval: 12 hours User Rules: 6 custom rules Filter Lists: 1. ✅ AdAway Default Blocklist (6540 rules) 2. ✅ gh_100M_block (1110461 rules) 3. ✅ 三角洲行动黑名单 (78126 rules) ``` **querylog command | querylog 命令：** ``` 📜 Recent DNS Queries (dns1) - Last 5 entries 1. [12:26:44 AM] 🚫 BLOCKED api.telegram.org (192.168.145.188) 2. [12:26:43 AM] 🚫 BLOCKED self.events.data.microsoft.com (192.168.145.123) Rule: ||events.data.microsoft.com^ 3. [12:26:42 AM] ✅ OK open.feishu.cn (192.168.145.188) ``` --- ## Configuration | 配置说明 ### 🔒 Security Best Practices | 安全最佳实践 **⚠️ Important:** Do not store plaintext credentials in configuration files. Use one of these secure methods: **⚠️ 重要：** 不要在配置文件中存储明文凭证。请使用以下安全方式之一： #### Option 1: Environment Variables (Recommended) | 方案一：环境变量（推荐） Set environment variables before running commands: 运行命令前设置环境变量： ```bash export ADGUARD_URL="http://192.168.145.249:1080" export ADGUARD_USERNAME="admin" export ADGUARD_PASSWORD="your-secure-password" ``` #### Option 2: 1Password CLI | 方案二：1Password CLI Use `op read` to inject secrets at runtime: 使用 `op read` 在运行时注入密钥： ```bash export ADGUARD_PASSWORD=$(op read "op://vault/AdGuard/credential") ``` #### Option 3: Workspace Config (Local Development Only) | 方案三：工作区配置（仅本地开发） For local development, create `adguard-instances.json` in your **current workspace root only**: 本地开发时，仅在**当前工作区根目录**创建 `adguard-instances.json`： ```json { "instances": { "dns1": { "url": "http://192.168.145.249:1080", "username": "admin", "password": "your-secure-password" } } } ``` **⚠️ Never commit this file to version control. Add it to `.gitignore`.** **⚠️ 切勿将此文件提交到版本控制。将其添加到 `.gitignore`。** --- ### Configuration Parameters | 配置参数 | Parameter | Description | Example | |-----------|-------------|---------| | `url` | AdGuard Home URL (with port) | `http://192.168.145.249:1080` | | `username` | Admin username | `admin` | | `password` | Admin password (use env var or secrets manager) | `your-secure-password` | | 参数 | 说明 | 示例 | |------|------|------| | `url` | AdGuard Home 访问地址（含端口） | `http://192.168.145.249:1080` | | `username` | 管理员用户名 | `admin` | | `password` | 管理员密码（建议使用环境变量或密钥管理） | `your-secure-password` | --- ## Technical Details | 技术实现 - **Authentication | 认证方式:** Cookie-based (POST `/control/login`) - **Data API | 数据接口:** GET `/control/*` endpoints - **Runtime | 运行环境:** Node.js (ES Module) - **Entrypoint | 入口文件:** `index.js` ### API Endpoints Used | 使用的 API 端点 - `/control/stats` - Statistics data | 统计数据 - `/control/status` - Service status | 服务状态 - `/control/dns_info` - DNS configuration | DNS 配置 - `/control/filtering/status` - Filter rules | 过滤规则 - `/control/querylog` - Query log | 查询日志 - `/control/clients` - Client management | 客户端管理 - `/control/tls/status` - TLS status | TLS 状态 --- ## FAQ | 常见问题 **Q: Error "No AdGuard instances configured"?** **Q: 提示 "No AdGuard instances configured"？** A: Ensure environment variables are set (`ADGUARD_URL`, `ADGUARD_USERNAME`, `ADGUARD_PASSWORD`). For local development only, you can create `adguard-instances.json` in your current workspace root. A: 请确保已设置环境变量（`ADGUARD_URL`、`ADGUARD_USERNAME`、`ADGUARD_PASSWORD`）。仅本地开发时，可在当前工作区根目录创建 `adguard-instances.json`。 --- **Q: Authentication error when querying?** **Q: 查询失败，返回认证错误？** A: Verify username/password in config file. Ensure AdGuard Home service is running. A: 检查配置文件中的用户名密码是否正确，确认 AdGuard Home 服务正常运行。 --- **Q: How to add more instances?** **Q: 如何添加更多实例？** A: Add new key-value pairs to the `instances` object in `adguard-instances.json`. A: 在 `adguard-instances.json` 的 `instances` 对象中添加新的键值对即可。 --- **Q: querylog shows no data?** **Q: querylog 没有数据？** A: Ensure query log is enabled in AdGuard Home settings (Settings → DNS Settings → Query log). A: 确保 AdGuard Home 设置中已启用查询日志（设置 → DNS 设置 → 查询日志）。 --- ## Version History | 版本历史 ### v1.2.7 (2026-02-26) - Registry Metadata Fix 📝 **Metadata Consistency | 元数据一致性：** - ✅ Fixed `clawhub.json` to correctly declare required environment variables (`ADGUARD_URL`, `ADGUARD_USERNAME`, `ADGUARD_PASSWORD`) - ✅ Updated `requires.env` to match actual code requirements - ✅ Fixed `security.notes` to use correct variable names (was `USERNAME/PASSWORD`, now `ADGUARD_USERNAME/ADGUARD_PASSWORD`) - ✅ Clarified config file is optional for local dev only - ✅ Added `VERSION_CHECK.md` to published files ### v1.2.6 (2026-02-25) - Documentation Consistency 📄 **Documentation | 文档改进：** - ✅ Removed file config references from FAQ - ✅ Docs match code behavior ### v1.2.5 (2026-02-25) - Registry Metadata Fix 📝 **Metadata | 元数据修复：** - ✅ Fixed registry metadata to declare required env vars (but had naming inconsistency) ### v1.2.4 (2026-02-25) - English SKILL.md 🇬🇧 **Documentation | 文档：** - ✅ English-only SKILL.md for ClawHub registry - ✅ Security: env vars or 1Password only ### v1.2.3 (2026-02-25) - Security: Remove File Loading 🔒 **Security | 安全：** - ✅ Removed file loading from code (workspace-only config) ### v1.2.2 (2026-02-25) - Security: Remove File Credentials 🔐 **Security | 安全：** - ✅ Removed file-based credential storage - ✅ Env vars or 1Password only ### v1.2.1 (2026-02-25) - Credential Security 🔐 **Security Improvements | 安全改进：** - ✅ **Removed plaintext credential storage** - No longer instructs creating config files with admin credentials - ✅ **Environment variable support** - Secure credential injection via `ADGUARD_URL`, `ADGUARD_USERNAME`, `ADGUARD_PASSWORD` - ✅ **1Password integration** - Supports secrets management via `op read` - ✅ **Removed multi-path search** - No longer searches `~/.openclaw-*/workspace/` paths - ✅ **Workspace-only config** - Local config file only checked in skill directory (dev use) - ✅ **Updated documentation** - Security best practices prominently featured ### v1.2.0 (2026-02-24) - Security Hardening 🔒 **Security Improvements | 安全改进：** - ✅ **Removed command injection vulnerability** - Replaced `execSync` + `curl` with native HTTPS client - ✅ **Input validation** - Sanitized instance names, commands, and parameters - ✅ **Command whitelist** - Only allowed commands can be executed - ✅ **URL validation** - Verified URL format before making requests - ✅ **Parameter bounds** - Limited querylog limit to 1-100 entries - ✅ **No shell escaping issues** - Pure JavaScript HTTP requests **Technical Changes | 技术变更：** - Removed dependency on `child_process` and external `curl` commands - Implemented native `http`/`https` module for all API calls - Added cookie-based session management - Improved error handling and validation ### v1.1.0 (2026-02-24) - Enhanced **New Commands | 新增命令：** - `status` - Service status (version, protection, ports) | 服务状态（版本、保护、端口） - `dns-info` - DNS configuration details | DNS 配置详情 - `filter-rules` - Filter rules and lists | 过滤规则和列表 - `querylog [n]` - Recent DNS queries | 最近 DNS 查询 - `clients` - Configured clients | 已配置的客户端 - `tls-status` - TLS/encryption status | TLS/加密状态 **Improvements | 改进：** - Bilingual documentation (Chinese/English) | 中英文双语文档 - Better error handling | 更好的错误处理 - Enhanced output formatting | 增强的输出格式 ### v1.0.0 (2026-02-24) - Initial **Features | 功能：** - stats/top-clients/top-blocked/health commands | 支持 stats/top-clients/top-blocked/health 命令 - Multi-instance configuration support | 多实例配置支持 - ES Module implementation | ES Module 实现 --- ## Author | 作者 **Leo Li (@foxleoly)** License: MIT