Documentation
Everything you need to run it — and nothing invented.
DNS Daddy's documentation lives in the repository, next to the code it describes, so it can never drift out of sync with the software. This page is a guided way in rather than a second copy that slowly goes stale.
Quick start with Docker Compose
The fastest way to try DNS Daddy is a container on a machine you control. Do this on a lab box or a spare VM first — not on the resolver your business depends on.
git clone https://github.com/jameshoulder/dnsdaddy.git cd dnsdaddy docker compose up -d
dig @127.0.0.1 example.com +short
Note
These commands are a summary for orientation. Ports, volumes, the admin password and upstream resolver settings are all covered properly in the deployment guide — read it before exposing anything beyond localhost.
Read docs/deploy.md →Start here
Capabilities — read this first
The repository's single source of truth for what is available, what is experimental and what is only planned. Everything else is expected to agree with it.
docs/capabilities.md →Getting started
What DNS Daddy is, what it gives you out of the box, and the limitations to read before you deploy anything.
README.md →Documentation index
The full contents of docs/ — how to run DNS Daddy, and how DNS security works, mixed together on purpose.
docs/README.md →Roadmap
What might come next, why, and what would have to be true first. No dates, no promises, and nothing on it is implemented.
docs/roadmap.md →Deploy and operate
Installation & deployment
A VPS walkthrough, TLS, firewalling, backups, upgrades and uninstall — including who is permitted to use the resolver.
docs/deploy.md →Deployment matrix
The acceptance checklist for clean machines, VMs and VPSes — and what has actually been run rather than assumed.
docs/deployment-matrix.md →Configuration reference
A fully commented example configuration covering listeners, upstreams, categories, feeds and policies.
dnsdaddy.example.yaml →Integrations
pfSense, OPNsense, UniFi, FortiGate, Windows, roaming clients, and the firewall-side mitigations for DoH bypass.
docs/integrations.md →Running alongside Pi-hole
Which order to chain them in, and what each one costs you in the arrangement.
docs/pi-hole.md →Privacy & telemetry
What is stored, for how long, how to store less, and what DNS Daddy never sends anywhere.
docs/privacy.md →Detection and intelligence
Behavioural detection
The pipeline, the design principles, the finding schema, and every one of the six experimental detectors — including what each will miss.
docs/detection/README.md →External API providers
Bring your own intelligence: VirusTotal, Safe Browsing and custom HTTP providers, and exactly what enabling one changes about your threat model.
docs/external-apis.md →Decision records
Why a domain was blocked: the evidence behind each decision, stored as it stood at the time rather than re-derived later.
docs/decision-records.md →Threat intelligence feeds
Every default feed, where it comes from, how categories map, and how to handle a false positive.
docs/threat-intel.md →SIEM and log shipping
Structured findings exported as NDJSON for Wazuh, Filebeat, Fluent Bit, Vector or a Splunk forwarder — and why there is no client per vendor.
docs/siem.md →ATT&CK mapping policy
Every mapping the detectors claim, and the ones deliberately left off.
docs/detection/mitre.md →Threat hunting
Six hunts you can run against the telemetry DNS Daddy produces.
docs/threat-hunting/README.md →The lab
An offline lab with seven scenarios, two of which are supposed to find nothing.
labs/ →DNS security and DNSSEC
DNSSEC — what DNS Daddy can honestly tell you
Recording a validating upstream's verdict, and why that is a strictly weaker statement than validating signatures locally.
docs/dns-security/dnssec.md →Daddybound
The experimental DNSSEC validation engine: what it does, what it deliberately cannot reach, and how the differential lab tests it.
docs/daddybound/README.md →Encrypted DNS and bypass
DoH, DoT, and clients that route around you entirely.
docs/dns-security/encrypted-dns.md →Architecture
How a query flows through listeners, cache, policy evaluation, feed matching and upstream forwarding — and why it is built that way.
docs/architecture.md →Security, assurance & contributing
Assurance
What is checked, by what tooling, and what none of it proves.
docs/assurance.md →Threat model
Assets, boundaries, actors, threats, mitigations — and the residual risk left behind each one.
docs/threat-model.md →Security policy & disclosure
The supported reporting route for vulnerabilities, and what to expect after you report one.
SECURITY.md →Static analysis triage
A real worked example: Semgrep findings triaged one by one, including a Markdown-injection issue that was fixed.
docs/security/semgrep-triage-2026-07-29.md →API reference
The REST API. Each build also serves its own OpenAPI 3.1 specification at /openapi.yaml, so the spec cannot drift from the binary.
openapi 3.1 →Contributing
Development setup, coding expectations, tests, and how to open a pull request that stands a chance of being merged.
CONTRIBUTING.md →Documentation gaps are bugs.
If a step didn't work, an assumption wasn't stated, or a page assumed you already knew DNS, that is worth reporting. Documentation fixes are among the most useful pull requests this project can receive.