Labyrinth DNS Resolver

Pure Go Recursive DNS Resolver with Web Dashboard

"Follow the thread through the DNS labyrinth."

---

Features

• Single binary — DNS resolver + web dashboard + auth, everything in one 6.8 MB executable
• Web dashboard — Real-time DNS monitoring, cache management, live query stream, dark/light theme
• Operator-first dashboard — Compact high-signal matrix, expandable secondary metrics, and inline cache query modal from top domains
• Resolver Observability Panel — Dashboard surface for the v0.6.24 RFC compliance counters: failure cache, server-cookie cache, NSEC/NSEC3 aggressive synthesis (NXDOMAIN vs NODATA split), BADCOOKIE retries, stale-while-refresh — each with hit-ratio bars and operator hints
• DNS Lookup Diagnostics — Live pipeline trace for any name: each iterative step, CNAME chase, and per-RRSIG DNSSEC verdict streamed over WebSocket. Inline pill badges per upstream event show AD bit, CD bit (RFC 6840 §5.9) and any RFC 8914 Extended DNS Error codes the upstream attached. Toggle cache bypass / DNSSEC skip to localise issues in seconds.
• RFC Compliance Matrix — AboutPage surface listing the standards Labyrinth implements, grouped by capability, with IETF datatracker links and "since vX.Y.Z" metadata. Each entry pinned by integrity tests so a typo can't ship as a false compliance claim.
• Smooth live charts — Dashboard trend charts redraw every second to stay responsive during bursty traffic changes
• Zero-config start — Interactive setup wizard on first run, sane defaults for everything
• Recursive only — Navigates root → TLD → authoritative, caches results
• DNSSEC validation — Full signature verification (RSA-SHA1/256/512, ECDSA P-256/P-384, ED25519), trust chain from root KSK, Zone Key bit gating (RFC 4034 §2.1.1), MUST-NOT algorithm refusal (RFC 8624 §3.1), CD bit propagation in forward mode (RFC 6840 §5.9), aggressive NSEC/NSEC3 use (RFC 8198 §5.2/§5.4)
• DNS blocklist — Pi-hole style domain blocking with hosts/domain/AdBlock Plus list formats
• Hardened — JWT auth, bcrypt passwords, bailiwick enforcement (RFC 5452 §3), rate limiting, ACL with EDE 17/18 signalling (RFC 8914); per-source TCP/DoT connection caps, per-delegation NS-name limit, NSEC3 hash budgets and salt-length ceiling close CPU-exhaustion vectors (CVE-2023-50387 / CVE-2023-50868)
• Observable — Prometheus metrics, Zabbix agent, structured logging, WebSocket query stream, 8 new counters for v0.6.24 RFC compliance features
• Self-updating — Automatic version check + one-click update from web dashboard (read-only installs require host-level update/redeploy)
• Fast — Sharded cache, >22M cache reads/sec, <50µs cache hit latency, request coalescing

Quick Install

# One-line install (Linux/macOS, as root)
curl -sSL https://raw.githubusercontent.com/labyrinthdns/labyrinth/main/install.sh | bash

# Then open the dashboard from the installed host to complete setup:
# http://127.0.0.1:9153

The installer downloads the latest release, installs the binary, creates a default config, sets up a systemd service, and starts Labyrinth automatically.

Install Options

# Install without systemd service
curl -sSL .../install.sh | bash -s -- --no-service

# Install specific version
curl -sSL .../install.sh | bash -s -- --version vX.Y.Z

# Uninstall
curl -sSL .../uninstall.sh | bash

Other Installation Methods

# From source
git clone https://github.com/labyrinthdns/labyrinth.git
cd labyrinth
cd web/ui && npm ci && npm run build && cd ../..
go build -ldflags="-s -w" -o labyrinth .

# Docker (GHCR) — DNS ports only by default
docker pull ghcr.io/labyrinthdns/labyrinth:latest
docker run -p 53:53/udp -p 53:53/tcp \
  -v "$PWD/labyrinth.yaml:/etc/labyrinth/labyrinth.yaml:ro" \
  ghcr.io/labyrinthdns/labyrinth:latest \
  -config /etc/labyrinth/labyrinth.yaml

# Docker Compose
docker compose up -d

Web Dashboard

Labyrinth includes a built-in web dashboard bound to http://127.0.0.1:9153 by default. Container examples intentionally do not publish this admin port. For remote or container access, configure non-empty web.auth credentials first, set web.addr explicitly (for example 0.0.0.0:9153), then publish port 9153—preferably on a trusted host interface or behind an authenticated TLS reverse proxy.

Setup Wizard

On first run (no config file), the dashboard shows an interactive setup wizard:

1. Welcome — Server info and version
2. Admin Account — Set username and password
3. Network — Configure listen address and dashboard address
4. DNS Settings — Cache size, QNAME minimization
5. Review & Apply — Writes labyrinth.yaml automatically

Dashboard Pages

Page	Description
Dashboard	Real-time DNS stats with compact matrix view, expandable secondary metrics, 1-second chart redraw cadence, paged Top Clients/Top Domains (up to 2000), and inline domain cache-query modal
Queries	Live DNS query stream via WebSocket — filterable, pausable, DNSSEC badges, blocked indicators
Cache	Cache stats, lookup tool, flush, delete individual entries, negative cache view
Blocklist	List management, quick block/unblock, domain check, source stats
Config	Running configuration viewer, password change
Operations	Live reliability monitoring with configurable thresholds, auto-refresh, incident surfacing
Reports	Operational snapshot exports (JSON, CSV, Markdown) with top clients/domains and time-series
About	Project overview, build metadata, release links, and integrated update controls

Authentication

• JWT-based (HMAC-SHA256, 24h tokens)
• Browsers use a same-origin HttpOnly, SameSite=Strict session cookie; Bearer tokens remain available for programmatic clients
• Passwords stored as bcrypt hashes
• Generate a password hash: labyrinth hash <password>

This is the beginning of the README. Read the rest at the original. Read the full README ↗