Why

Most home and small-office ad blockers forward every question to a big public resolver. RPZ Guard asks the authoritative servers itself, checks their DNSSEC signatures, and applies blocking inside the resolver, using the standard RPZ format that public feeds such as OISD already publish. Nothing leaves your network that the DNS itself does not require, and the policy is enforced in the same process that answers the query.

How it fits together

Features

Design highlights

Feeds are never loaded as downloaded

A downloaded list is parsed by a strict streaming parser that keeps only plain domain triggers (exact names and *. wildcards), refuses $INCLUDE and other directives, and counts anything malformed. The app then writes its own minimal zone file, so a broken or hostile feed cannot inject records into the resolver. Updates are refused if the list is empty, has too many bad lines, or suddenly shrinks by more than half. Every configuration change is checked with unbound-checkconf first and rolled back if Unbound rejects it. The DNS service must never be left broken by a bad feed.

Knowing why a name was blocked

Unbound's telemetry stream does not say which policy matched. RPZ Guard asks Unbound to clear the recursion available flag on blocked answers. A genuine "no such domain" answer always has it set, so the collector can tell a block from a real NXDOMAIN with certainty. It then names the list by walking an in-memory index of all rules in exactly the order Unbound evaluates them. That index reloads within seconds of any list change.

DNS never waits for logging

The Go collector reads Frame Streams from a Unix socket, buffers the records, and writes them to SQLite in batches (every 250 ms or 500 records) in WAL mode. If logging ever falls behind, records are counted and dropped. Resolution is never slowed down.

Least privilege everywhere

• Unbound, the collector, the web app and the web server each run as a separate user with a trimmed illumos privilege set. The collector cannot even open a network socket.
• The web app reaches Unbound only through its local control socket, and the service manager only through a single RBAC authorization.
• All external commands use fixed argument lists, never a shell.

Web security

• TLS 1.2/1.3 in front, the OWASP Core Rule Set (Coraza WAF) and per-client rate limits before any request reaches the app.
• The admin UI answers only on the networks you choose; everything else gets 403.
• argon2id password hashing, login rate limiting, CSRF tokens plus same-origin checks, __Host- session cookies (Secure, HttpOnly, SameSite=Strict).
• A strict Content-Security-Policy with no inline scripts. Data is inserted as text, never as HTML.

Built with

In production it runs comfortably in a 4 GB zone: with the full OISD Big list loaded (about 460,000 rules) Unbound uses under 400 MB of memory.

Lessons from illumos

A few things that cost us time, in case they save you some:

• chmod 2750 does not set the set-group-ID bit on a directory; only chmod g+s does.
• An SMF method that runs as a user without a home directory fails with exit status 96 unless the manifest sets working_directory.
• gunicorn re-owns its Unix socket after binding, which overrides a set-group-ID directory. Hand it over in a when_ready hook, using the file_chown_self privilege.
• Connecting to a Unix socket needs both read and write permission.
• The pure-Go SQLite driver has no illumos port; the cgo driver works well.
• In a Caddyfile, a top-level error runs after handle. Wrap the handlers in a matcher instead.

License

Unbound RPZ Guard is free software under the GNU Affero General Public License v3 (AGPL-3.0). It builds on Unbound by NLnet Labs and on public RPZ feeds such as OISD.