Initial commit

2026-04-26 11:06:47 +07:00 · 2026-04-26 11:06:47 +07:00 · 2b72492a59
commit 2b72492a59
25 changed files with 3147 additions and 0 deletions
--- a/README.md
+++ b/README.md
@ -0,0 +1,101 @@
+# checker-authoritative-consistency
+
+Authoritative name server consistency checker for [happyDomain](https://www.happydomain.org/).
+
+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
+
+```bash
+# 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
+
+```bash
+make docker
+docker run -p 8080:8080 happydomain/checker-authoritative-consistency
+```
+
+### happyDomain plugin
+
+```bash
+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:
+
+```bash
+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`).