Pi-hole Control

Control Pi-hole v6 DNS ad blocker: check status, view stats, enable/disable block, and analyze blocked domains via API.

Security Scan

The skill's stated purpose (controlling a local Pi‑hole via its v6 API) matches its instructions, but there are configuration/manifest mismatches and a privilege concern: the agent can autonomously invoke a skill that can toggle network ad‑blocking.

Purpose & Capability

Name and SKILL.md describe Pi‑hole v6 control and the documented API calls match that purpose. However the registry metadata lists no required binaries or env vars while the SKILL.md explicitly requires curl and jq and documents PIHOLE_API_URL/PIHOLE_API_TOKEN/PIHOLE_INSECURE — a manifest mismatch that should be corrected.

Instruction Scope

Runtime instructions are narrowly scoped to calling Pi‑hole API endpoints (auth, status, enable/disable, stats, queries). They do not instruct reading unrelated files or exfiltrating data. Note: the SKILL.md documents an 'insecure' option that adds curl -k (bypassing TLS verification) which reduces transport security when used.

Install Mechanism

This is instruction-only with no install spec, so nothing is written to disk by an installer. That lowers risk. There is one shell script (pihole.sh) included — you should inspect it before enabling the skill.

Credentials

The skill uses a Pi‑hole API token and URL (documented in SKILL.md and as environment variables or Clawdbot config), but the registry metadata declares no required environment variables. The skill appropriately needs only the Pi‑hole credentials, but the manifest should list them explicitly. Also confirm how the included pihole.sh handles the token (environment variable vs command line) because command‑line embedding could expose secrets via process listings on some systems.

Persistence & Privilege

The skill does not set disableModelInvocation and is therefore callable by the model autonomously. Because the skill can enable/disable network ad‑blocking (a disruptive network control), allowing the model to trigger it without explicit user invocation is a meaningful risk. Consider requiring explicit user invocation or setting disableModelInvocation.

What to consider before installing

Before installing: (1) Inspect the included pihole.sh to confirm it only contacts your Pi‑hole API and does not read unrelated files or contact external endpoints. Check how it sends the API token — avoid command‑line embedding that can appear in process lists. (2) Update/confirm the skill manifest lists required binaries (curl, jq) and required config/env variables (PIHOLE_API_URL, PIHOLE_API_TOKEN, PIHOLE_INSECURE). (3) If you do not want the agent to toggle your network ad blocker autonomously, set disableModelInvocation: true (or require explicit user invocation). (4) Be cautious with the 'insecure' option (curl -k) — use it only on trusted local networks. (5) If you’re unsure, run the script in a restricted environment or review/modify it to log minimal info and not expose secrets.

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:

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:

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)

{
  "apiUrl": "https://pi-hole.example.com/api",
  "apiToken": "...",
  "insecure": false
}

Self-Signed/Local Cert

{
  "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)