Skill: baanish/pihole (version 2.0.1)

# Pi-hole Skill Control your Pi-hole DNS ad blocker via the Pi-hole v6 API. ## Setup Set your Pi-hole API configuration in Clawdbot config: ```yaml skills: entries: pihole: apiUrl: "https://pi-hole.local/api" # v6 API path apiToken: "your-app-password-here" # Get from Pi-hole Admin insecure: false # Set to true for self-signed certs ``` Alternatively, set environment variables: ```bash export PIHOLE_API_URL="https://pi-hole.local/api" export PIHOLE_API_TOKEN="your-app-password-here" export PIHOLE_INSECURE="false" ``` ### Getting API Credentials 1. Open Pi-hole Admin at `http://pi-hole.local/admin` 2. Navigate to **Settings** > **API** 3. Generate an app password 4. Use that password as `apiToken` ## Capabilities ### Status - Get current Pi-hole status (enabled/disabled) - View stats: queries blocked, queries today, domains being blocked, active clients - See recent query activity ### Controls - **Enable/Disable**: Turn Pi-hole on or off - **Disable for 5 minutes**: Temporarily disable ad blocking for a short period - **Disable for custom duration**: Set specific disable time (in minutes) ### Block Analysis - **Check blocked domains**: See what domains were blocked in a time window - **Show top blocked**: Most frequently blocked domains ## Usage Examples ``` # Check Pi-hole status "pihole status" # Turn off ad blocking "pihole off" # Turn on ad blocking "pihole on" # Disable for 5 minutes (for a site that needs ads) "pihole disable 5m" # Disable for 30 minutes "pihole disable 30" # See what was blocked in the last 30 minutes "pihole blocked" # See blocked domains in last 10 minutes (600 seconds) "pihole blocked 600" # Show statistics "pihole stats" ``` ## API Endpoints (Pi-hole v6) ### Authentication ``` POST /api/auth Content-Type: application/json {"password":"your-app-password"} Response: { "session": { "sid": "session-token-here", "validity": 1800 } } ``` ### Status ``` GET /api/dns/blocking Headers: sid: <session-token> Response: { "blocking": "enabled" | "disabled", "timer": 30 // seconds until re-enable (if disabled with timer) } ``` ### Enable/Disable ``` POST /api/dns/blocking Headers: sid: <session-token> Content-Type: application/json Enable: {"blocking":true} Disable: {"blocking":false} Disable with timer (seconds): {"blocking":false,"timer":300} ``` ### Stats ``` GET /api/stats/summary Headers: sid: <session-token> Response: { "queries": { "total": 233512, "blocked": 23496, "percent_blocked": 10.06 }, "gravity": { "domains_being_blocked": 165606 }, "clients": { "active": 45 } } ``` ### Queries ``` GET /api/queries?start=-<seconds> Headers: sid: <session-token> Response: { "queries": [ { "domain": "example.com", "status": "GRAVITY", "time": 1768363900, "type": "A" } ] } ``` ## v5 vs v6 API Changes Pi-hole v6 introduced significant API changes: | Feature | v5 API | v6 API | |---------|----------|----------| | Base URL | `/admin/api.php` | `/api` | | Auth | Token in URL/headers | Session-based | | Status | `?status` | `/api/dns/blocking` | | Stats | `?summaryRaw` | `/api/stats/summary` | | Queries | `?recentBlocked` | `/api/queries` | | Whitelist | Supported via API | **Not available via API** | **Important:** Domain whitelisting is no longer available via the v6 API. You must whitelist domains through the Pi-hole Admin UI. ## SSL Certificates ### Production (Valid Cert) ```yaml { "apiUrl": "https://pi-hole.example.com/api", "apiToken": "...", "insecure": false } ``` ### Self-Signed/Local Cert ```yaml { "apiUrl": "https://pi-hole.local/api", "apiToken": "...", "insecure": true } ``` The `insecure` flag adds the `-k` option to curl to bypass certificate validation. ## Security Notes - Session tokens expire after 30 minutes (1800 seconds) - API password is sent in JSON body, not URL - All requests have a 30-second timeout - Token is not visible in process list (passed via environment) ## Troubleshooting ### "Failed to authenticate" - Check that `apiToken` matches your Pi-hole app password - Verify `apiUrl` is correct (must end in `/api`) - Ensure Pi-hole is accessible from your network ### "Could not determine status" - Check API URL is reachable - If using HTTPS with self-signed cert, set `insecure: true` - Verify API password is correct ### Network Errors - Ensure clawdbot's machine can reach the Pi-hole - Check firewall rules allow API access - Verify URL scheme (http vs https) ## Requirements - Pi-hole v6 or later - App password generated in Pi-hole Admin - Network access to Pi-hole API - `curl`, `jq` (installed on most Unix systems)


Security scan verdicts — ClawScan: suspicious | static analysis: clean | VirusTotal: clean | SkillSpector: suspicious (MEDIUM)