checker-resolver-propagation

Worldwide DNS propagation checker for happyDomain.

Probes a curated catalog of public recursive resolvers (Cloudflare, Google, Quad9, OpenDNS, Yandex, regional ISPs, …) across multiple transports (UDP, TCP, DoT, DoH) and regions, then compares their answers to the zone's authoritative nameservers to detect propagation gaps, regional splits, SOA serial drift, stale caches, DNSSEC validation failures, SERVFAIL/NXDOMAIN inconsistencies, and resolver filtering.

Usage

Standalone HTTP server

# Build and run
make
./checker-resolver-propagation -listen :8080

The server exposes:

• GET /health: health check
• POST /collect: collect propagation observations (happyDomain external checker protocol)
• POST /evaluate: run the evaluation rules against an observation
• POST /report: extract metrics / HTML report from an observation

Docker

make docker
docker run -p 8080:8080 happydomain/checker-resolver-propagation

happyDomain plugin

make plugin
# produces checker-resolver-propagation.so, loadable by happyDomain as a Go plugin

The plugin exposes a NewCheckerPlugin symbol returning the checker definition and observation provider, which happyDomain registers in its global registries at load time.

Versioning

The binary, plugin, and Docker image embed a version string overridable at build time:

make CHECKER_VERSION=1.2.3
make plugin CHECKER_VERSION=1.2.3
make docker CHECKER_VERSION=1.2.3

happyDomain remote endpoint

Set the endpoint admin option for the resolver-propagation checker to the URL of the running checker-resolver-propagation server (e.g., http://checker-resolver-propagation:8080). happyDomain will delegate observation collection to this endpoint.

This checker applies to service-level checks and is restricted to the abstract.Origin and abstract.NSOnlyOrigin services (the zone apex / NS configuration).

Options

Id	Type	Default	Description
recordTypes	string	SOA,NS,A,AAAA,MX,TXT,CAA	Comma-separated list of RR types to probe at the apex (and at each subdomains entry).
subdomains	string	www	Comma-separated list of owner names to probe in addition to the apex (e.g. www,mail,@). Empty = apex only.
includeFiltered	bool	false	Probe filtering resolvers (malware/family/adblock). Their answers routinely diverge by design.
region	string	all	Restrict to a region: all, global, na, eu, asia, ru, me.
transports	string	udp	Comma-separated transports to probe: udp, tcp, dot, doh. Encrypted transports are only used where published.
resolverAllowlist	string		Comma-separated resolver IDs or IPs to probe exclusively (e.g. cloudflare,google,9.9.9.9). Empty = catalog selection.
latencyThresholdMs	uint	500	Resolvers averaging above this value emit an info finding.
runTimeoutSeconds	uint	30	Hard wall-clock budget for one propagation run. Slower resolvers report as unreachable.

Rules

Code	Description	Severity
resolver_propagation.selection	Checks that the current option set selects at least one public resolver.	CRITICAL
resolver_propagation.reachable	Checks that at least one selected resolver answered a query.	CRITICAL
resolver_propagation.latency	Flags resolvers that are unreachable or whose average response time exceeds the configured threshold.	WARNING
resolver_propagation.filtered_hit	Reports filtered resolvers returning a different answer than the consensus (typical blocklist behaviour).	INFO
resolver_propagation.consensus	Checks that public resolvers agree on a single answer for each probed RRset.	WARNING
resolver_propagation.matches_authoritative	Checks that the public consensus matches the answer served by the zone's authoritative nameservers.	CRITICAL
resolver_propagation.nxdomain	Flags RRsets for which some resolvers return NXDOMAIN while others return NOERROR.	CRITICAL
resolver_propagation.servfail	Flags RRsets for which any resolver returns SERVFAIL (usually DNSSEC or reachability failure).	CRITICAL
resolver_propagation.regional_split	Flags regions in which every resolver agrees on an answer that differs from the global consensus.	WARNING
resolver_propagation.serial_drift	Flags disagreement on the SOA serial across unfiltered resolvers.	WARNING
resolver_propagation.stale_cache	Flags resolvers still serving an SOA serial below the one saved by happyDomain.	INFO
resolver_propagation.dnssec	Checks that validating resolvers successfully validate the zone's DNSSEC chain.	CRITICAL

License

Licensed under the MIT License (see LICENSE).