3.9 KiB
checker-dnsviz
DNSSEC checker for happyDomain, implemented as a thin wrapper around DNSViz.
The container ships dnsviz (Python) alongside the Go binary that exposes the
standard happyDomain checker HTTP API (/health, /definition, /collect,
/evaluate, /report).
How it works
For each check run, the Go binary invokes:
dnsviz probe -A <domain> | dnsviz grok
stores the parsed JSON output as the observation, and turns DNSViz's per-zone
errors and warnings into individual CheckState entries. A curated catalog
of common DNSSEC failure scenarios (broken chain, expired RRSIG, DS digest
mismatch, deprecated algorithm, …) is matched against the findings to
generate a "Fix these first" section in the HTML report with plain-language
remediation hints.
The HTML report renders one block per zone in the chain (root → TLD → intermediates → leaf) so a recursive DNSSEC failure can be located at the exact level it broke.
Scope
This checker is intentionally limited to what DNSViz reports. NSEC/NSEC3
zone-walk hardening and NSEC3PARAM iteration policy (RFC 9276) are
delivered by a separate checker-dnssec module.
Usage
Standalone server
make
./checker-dnsviz -listen :8080
# requires `dnsviz` on PATH
Docker
make docker
docker run -p 8080:8080 happydomain/checker-dnsviz
happyDomain plugin
make plugin
# produces checker-dnsviz.so
Options
| Scope | Id | Default | Description |
|---|---|---|---|
| admin | dnsvizBin |
dnsviz |
Path to the dnsviz CLI. |
| admin | probeTimeoutSeconds |
120 |
Hard timeout for dnsviz probe. |
| admin | extraProbeArgs |
-A |
Extra arguments appended verbatim to dnsviz probe. |
| domain | domain_name |
auto-fill | Domain to analyse. |
Rules
| Rule | Description |
|---|---|
dnsviz_overall_status |
DNSViz status of the queried domain (SECURE/INSECURE/BOGUS/INDETERMINATE). |
dnsviz_per_zone_status |
One state per zone in the chain (root, TLD, intermediates, leaf). |
dnsviz_zone_errors |
Every error reported by DNSViz, scoped to the zone where it was found. |
dnsviz_zone_warnings |
Every warning reported by DNSViz, scoped to the zone where it was found. |
dnsviz_common_failures |
Pattern-matches findings against a catalog of common DNSSEC failures. |
Licensing
This repository is split into two licensing zones:
| Path | License | Reason |
|---|---|---|
checker/ |
MIT | Pure analysis logic (types, rules, HTML report). Can be imported by third-party Go projects without GPL obligations. |
internal/collect/ |
GPL v2 | Invokes the dnsviz subprocess. Covered by DNSViz's GPL v2 licence. |
main.go, plugin/ |
GPL v2 | Wire the two together; distributed binaries include the GPL layer. |
If you only need the analysis primitives (parse grok output, evaluate rules, render the HTML report), import git.happydns.org/checker-dnsviz/checker and supply your own checker.CollectFn — for example one that calls the HTTP API instead of running DNSViz locally.
Versioning
make CHECKER_VERSION=1.2.3
make plugin CHECKER_VERSION=1.2.3
make docker CHECKER_VERSION=1.2.3