DNS filtering proxy that queries multiple upstream DNS servers concurrently and enforces block-consensus: if any upstream signals a domain is blocked, the blocked response is returned to the client.
DNSieve relies primarily on upstream filtering rather than maintaining local block lists. Instead of downloading and maintaining lists of known-bad domains (as Pi-hole or AdGuard Home do), DNSieve acts as an intelligent proxy that fans out each DNS query to multiple upstream resolvers -- such as Quad9, Cloudflare for Families, or Control D -- that already perform threat-intelligence filtering on their end. DNSieve then enforces the strictest outcome: if any upstream signals a domain is blocked, DNSieve returns a blocked response to the client. This means there are no lists to download, store, deduplicate, or refresh -- protection is always as current as the upstream providers. Combining multiple providers gives complementary coverage across malware, phishing, and newly registered domains without managing separate subscriptions. For cases where you want to block specific domains not covered by upstream filtering, an optional local blacklist is also available -- it is disabled by default and entirely opt-in. The trade-off is that querying all upstreams concurrently introduces a small amount of latency compared to a single-server setup; for best results, use fast upstream servers and keep the count to 2-3.
Development Status
DNSieve is still under active development. Not all features have been fully tested and edge cases may exist. This project was built for personal use -- use it at your own discretion.
If you encounter any issues, please open a report in the Issues section. Include full app version and commit sha, steps to reproduce and a screenshot when possible -- it helps a lot. I may or may not have time to address every report, but all feedback is appreciated.
This project is AI assisted. The core idea and original code started back in 2020 as a personal project, written in a messy "it works on my machine" style. AI helped finish planned features, clean up and restructure the code, make it more efficient, and catch bugs that weren't even on the radar.
The app communicates only with the IPs and domains you explicitly configure in the config file. If bootstrap servers are unavailable or not configured, it falls back to your computer's default DNS servers to resolve upstream domains. That's it. No telemetry, no callbacks, no surprises. Feel free to read through the code to verify.
- Client sends a DNS query to DNSieve (plain DNS, DoT, or DoH)
- DDR check: queries for
_dns.resolver.arpa. SVCBare answered locally - Whitelist check: if matched, resolve via the whitelist resolver immediately
- Blacklist check: if matched, return a blocked response immediately
- DNSieve checks the cache -- if hit, returns immediately
- On cache miss, DNSieve fans out the query to all configured upstream servers concurrently
- Results are collected:
- If any upstream signals blocked, cache the block and return a blocked response with EDE Blocked (RFC 8914 code 15) to the client. Default mode: NOERROR + 0.0.0.0/:: (configurable: null, nxdomain, nodata, refused)
- If not blocked and all upstreams responded, cache from the highest-priority upstream and return
- If some upstreams had errors, do not cache but still return the best available result
- Nearly-expired cache entries are refreshed in the background to keep responses fast for frequently queried domains
- Concurrent fan-out with block-consensus across multiple upstreams
- DNS-over-HTTPS (RFC 8484), DNS-over-TLS (RFC 7858), and plain DNS for both upstream and downstream
- LRU caching with upstream TTL respect, background refresh for nearly-expired entries, and configurable minimum TTL
- Domain whitelist and blacklist with file-based lists, glob patterns, and wildcard support (
*.example.com); hot-reload without restarts - Bootstrap DNS for resolving DoH/DoT hostnames without system DNS
- Speed testing via
--speedflag - Service management via
--install/--uninstallfor Windows, Linux (systemd/OpenWRT), and macOS (launchd) - TLS hardening with strong cipher suites (TLS 1.2+ with AEAD only)
- Cross-platform builds for Linux, Windows, macOS, and OpenWRT (amd64/arm64), with IPv4 and IPv6 support
# Install via go install
go install github.com/secu-tools/dnsieve@latest
# Or build from source
go build -o dnsieve ./
# Run (generates config on first launch)
./dnsieve
# With custom paths
./dnsieve --cfgfile /etc/dnsieve/config.toml --logdir /var/log/dnsieve/The easiest way to deploy DNSieve is with Docker Compose:
mkdir -p config log
# Place your config.toml in ./config/ (or run dnsieve once to generate one)
docker compose -f docker/docker-compose.yml up -dThe included docker/docker-compose.yml pulls the pre-built image from GHCR and
runs DNSieve with security hardening (dropped capabilities, read-only
filesystem, non-root user).
See docs/docker.md for advanced Docker configuration.
On first run, DNSieve prompts to generate a default config file at the platform-appropriate location:
| Platform | Path |
|---|---|
| Linux / macOS | /etc/dnsieve/config.toml |
| Windows | <exe_dir>\config\config.toml |
Override with --cfgfile /path/to/config.toml.
See docs/configuration.md for the full reference.
# Install as system service (prompts for optional label)
sudo ./dnsieve --install
# With custom paths
sudo ./dnsieve --install --cfgfile /etc/dnsieve/office.toml
# Uninstall (lists services, prompts which to remove)
sudo ./dnsieve --uninstallSupported platforms: Windows (sc.exe), Linux (systemd/OpenWRT procd), macOS (launchd).
# Linux/macOS
./build.sh
# Windows
.\build.ps1
# Or use Make
make buildSee docs/compilation.md for full build instructions including cross-compilation, packaging (.deb/.rpm), and version embedding.
# Test all configured upstreams
./dnsieve --speed
# Test with specific domains
./dnsieve --speed google.com,github.com,example.orgSee docs/testing.md for test instructions including unit tests, e2e tests, integration tests, RFC compliance tests, and fuzz testing.
See docs/faq.md for the full FAQ, including topics such as how block-consensus works, using DNSieve with Pi-hole, whitelist configuration, DoH/DoT setup, caching behaviour, and provider recommendations.
See docs/troubleshooting.md for solutions to common problems including port conflicts, permission errors, blocked or unblocked domains, Docker networking, TLS certificates, service installation, and config validation errors.
- docs/caching.md -- Caching design details
- docs/compilation.md -- Build instructions
- docs/configuration.md -- Configuration reference
- docs/docker.md -- Docker deployment guide
- docs/faq.md -- Frequently asked questions
- docs/files.md -- Project structure and file locations
- docs/protocol.md -- DNS protocol details
- docs/testing.md -- Test instructions
- docs/troubleshooting.md -- Troubleshooting guide
MIT License -- see LICENSE.
Copyright (c) 2020-2026 Jack L. (Cpt-JackL) (https://jack-l.com)
GitHub Repository: https://github.com/secu-tools/dnsieve