checker-authoritative-consistency/README.md

checker-authoritative-consistency

Authoritative name server consistency checker for happyDomain.

Probes every authoritative name server of a zone and verifies they agree with each other and with the parent delegation: NS RRset alignment (RFC 1034 §4.2), SOA serial and field consistency (RFC 1035 §3.3.13, RFC 1912 §2.2), reachability over UDP and TCP (RFC 7766), EDNS0 support (RFC 6891), authoritative answers (no lame delegation), and response latency.

Usage

Standalone HTTP server

# Build and run
make
./checker-authoritative-consistency -listen :8080

The server exposes:

• GET /health: health check
• POST /collect: collect authoritative-consistency observations (happyDomain external checker protocol)

Docker

make docker
docker run -p 8080:8080 happydomain/checker-authoritative-consistency

happyDomain plugin

make plugin
# produces checker-authoritative-consistency.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 propagation checker to the URL of the running checker-authoritative-consistency server (e.g., http://checker-authoritative-consistency:8080). happyDomain will delegate observation collection to this endpoint.

Options

Id	Type	Default	Description
requireTCP	bool	true	When enabled, an authoritative server that fails to answer over TCP is critical (otherwise warning).
checkEDNS	bool	true	Probe each name server for EDNS0 (RFC 6891). Servers that drop or mishandle EDNS0 break DNSSEC.
checkLatency	bool	true	Measure response time of every name server and warn on slow responders.
latencyThresholdMs	uint	500	Response times above this value trigger a slow-server warning.
useParentNS	bool	true	Query the parent zone for the delegation NS RRset and compare it to the service's declared NS list.
warnOnStaleSaved	bool	true	When the saved SOA serial in happyDomain is newer than what authoritative servers publish, warn.
minNameServers	uint	2	Below this count, a warning is emitted (RFC 1034 recommends at least 2).

Rules

Each rule emits a finding code. Severity can be affected by the options above.

Code	Default severity	Condition
authoritative_consistency_no_ns	critical	No name servers could be discovered for the zone (declared list empty and parent query returned nothing).
authoritative_consistency_too_few_ns	warning	Fewer name servers are declared than minNameServers (RFC 1034 recommends at least 2).
authoritative_consistency_parent_query_failed	warning	The parent delegation query failed (network error, REFUSED, etc.).
authoritative_consistency_parent_drift	warning	The parent zone's NS RRset does not match the NS declared in the service.
authoritative_consistency_ns_unresolvable	critical	A declared name server has no A or AAAA record.
authoritative_consistency_ns_udp_failed	critical	A name server did not answer any SOA query over UDP/53.
authoritative_consistency_ns_tcp_failed	critical with requireTCP / warning otherwise	A name server did not answer over TCP/53 (required by RFC 7766 and DNSSEC).
authoritative_consistency_lame	critical	A name server answered without the AA bit set for the zone (lame delegation).
authoritative_consistency_no_soa	critical	A name server is authoritative but returned no SOA for the zone.
authoritative_consistency_edns_unsupported	warning	A name server drops or mishandles EDNS0 queries (RFC 6891).
authoritative_consistency_slow_ns	info	A name server's response time exceeded latencyThresholdMs.
authoritative_consistency_serial_drift	warning	Authoritative servers disagree on the SOA serial (zone not fully propagated).
authoritative_consistency_serial_stale_vs_saved	warning	The saved SOA serial in happyDomain is newer than what authoritative servers publish (likely an un-pushed change).
authoritative_consistency_serial_ahead_of_saved	info	Authoritative servers publish a SOA serial newer than the one saved in happyDomain (out-of-band change).
authoritative_consistency_soa_fields_drift	warning	Authoritative servers disagree on SOA fields (MNAME, RNAME, refresh, retry, expire, minimum).
authoritative_consistency_ns_rrset_drift	warning	Authoritative servers disagree on the NS RRset they publish at the apex.
authoritative_consistency_ns_rrset_mismatch_config	warning	The NS RRset published by authoritative servers does not match the NS declared in the service.

License

Licensed under the MIT License (see LICENSE).