DNS Monitoring¶

The Control Center integrates with Pi-hole to provide DNS monitoring and ad-blocking management.

How DNS Works in the Infrastructure¶

AI VM (192.168.10.10)
  └── DNS query → 192.168.10.1 (virbr0 gateway)
                    └── dnsmasq → Pi-hole (172.20.10.53)
                                    ├── Gravity list → BLOCKED (NXDOMAIN)
                                    └── Allowed → Upstream resolvers

DNS lookups are always allowed, even in "Locked" firewall mode. This is intentional — it lets you see what the AI is trying to reach before granting access.

Pi-hole API Integration¶

The Control Center supports both Pi-hole v5 and v6 APIs:

v6 API (Primary)¶

Uses session-based authentication:

POST /api/auth  →  {"password": "..."}  →  {"session": {"sid": "..."}}
GET  /api/stats/summary  →  (with sid header)
GET  /api/queries?length=100
GET  /api/stats/top_domains?count=15
GET  /api/stats/top_domains?blocked=true&count=15
POST /api/dns/blocking

v5 API (Fallback)¶

Uses query-string token authentication:

GET /admin/api.php?summary&auth=<token>
GET /admin/api.php?getAllQueries=100&auth=<token>
GET /admin/api.php?topItems=15&auth=<token>

The Control Center tries v6 first, falls back to v5 if the endpoint returns non-200.

Available Endpoints¶

Endpoint	Description
`GET /api/dns/summary`	Total queries, blocked count, percentage, gravity size
`GET /api/dns/queries?limit=100`	Recent DNS lookup history with timestamps
`GET /api/dns/top-domains`	Top 15 most queried domains
`GET /api/dns/top-blocked`	Top 15 blocked domains
`POST /api/dns/toggle`	Toggle ad-blocking on/off

What to Look For¶

In "Locked" Mode¶

DNS queries show you what the AI wants to access. Common patterns:

Domain Pattern	What It Means
`pypi.org`, `files.pythonhosted.org`	Installing Python packages
`api.github.com`, `github.com`	GitHub API calls or git operations
`registry.npmjs.org`	Installing Node.js packages
`api.openai.com`	Calling OpenAI API
Unknown domains	Investigate before granting access

Blocked Domains¶

Pi-hole's gravity list blocks known ad/tracker domains. A high block count from the VM may indicate the AI is accessing ad-heavy websites.

Configuration¶

Environment Variable	Default	Description
`PIHOLE_URL`	`http://172.20.10.53`	Pi-hole API base URL
`PIHOLE_PASSWORD`	(empty)	Pi-hole admin password

The Pi-hole password is configured via the .env file in the Docker Compose directory.