Initial commit

2026-04-27 01:06:32 +07:00 · 2026-04-27 01:06:32 +07:00 · 1d93a25983
commit 1d93a25983
23 changed files with 2654 additions and 0 deletions
--- a/README.md
+++ b/README.md
@ -0,0 +1,89 @@
+# checker-reverse-zone
+
+PTR coverage checker for reverse DNS zones in [happyDomain](https://www.happydomain.org/).
+
+Inspects every PTR record declared in an `in-addr.arpa` or `ip6.arpa` reverse zone,
+validates Forward-Confirmed Reverse DNS (FCrDNS), target resolvability, hostname
+syntax, generic/auto-generated hostnames, TTL hygiene, and multiple-PTR-per-IP
+violations (RFC 1912 §2.1).
+
+## Usage
+
+### Standalone HTTP server
+
+```bash
+# Build and run
+make
+./checker-reverse-zone -listen :8080
+```
+
+The server exposes:
+
+- `GET /health`: health check
+- `POST /collect`: collect reverse-zone observations (happyDomain external checker protocol)
+
+### Docker
+
+```bash
+make docker
+docker run -p 8080:8080 happydomain/checker-reverse-zone
+```
+
+### happyDomain plugin
+
+```bash
+make plugin
+# produces checker-reverse-zone.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 reverse-zone checker to the URL of the
+running checker-reverse-zone server (e.g., `http://checker-reverse-zone:8080`).
+happyDomain will delegate observation collection to this endpoint.
+
+## Options
+
+| Id                    | Type | Default | Description                                                                                                          |
+|-----------------------|------|---------|----------------------------------------------------------------------------------------------------------------------|
+| `requireForwardMatch` | bool | `true`  | When enabled, a PTR whose target does not resolve back to the original IP is reported as critical (otherwise warning). Mail and SSH servers require FCrDNS. |
+| `allowMultiplePTR`    | bool | `false` | When enabled, more than one PTR at the same owner is allowed (RFC 1912 §2.1 recommends a single PTR per IP).        |
+| `minTTL`              | uint | `300`   | PTR records with a TTL below this threshold (in seconds) are flagged as warning.                                     |
+| `flagGenericPTR`      | bool | `true`  | When enabled, PTR targets that embed the dotted IP or match common ISP auto-generated patterns are reported as warning. |
+| `maxPTRsToCheck`      | uint | `1024`  | Caps the number of PTR records inspected per run, protecting the checker against very large reverse zones.           |
+
+## Rules
+
+Each rule emits a finding code. Severity can be affected by the options above.
+
+| Code | Default severity | Condition |
+|------|-----------------|-----------|
+| `reverse_zone_not_arpa` | critical | The zone is not under `in-addr.arpa` or `ip6.arpa`. |
+| `reverse_zone.load_error` | error | A structural failure prevented observation collection. |
+| `reverse_zone_empty` | warning | The reverse zone declares no PTR records at all. |
+| `ptr_forward_mismatch` | critical / warning with `requireForwardMatch=false` | A PTR target's A/AAAA records do not include the original IP (FCrDNS mismatch). |
+| `ptr_target_unresolvable` | critical / warning with `requireForwardMatch=false` | A PTR target has no A or AAAA record in the forward DNS. |
+| `ptr_multiple` | warning | An IP owner carries more than one PTR record. Skipped when `allowMultiplePTR=true`. |
+| `ptr_target_invalid` | critical | A PTR target is not a syntactically valid hostname (RFC 952/1123). |
+| `ptr_generic_hostname` | warning | A PTR target embeds the IP address or matches common ISP auto-generated patterns. Skipped when `flagGenericPTR=false`. |
+| `ptr_low_ttl` | warning | A PTR record's TTL is below `minTTL`. |
+| `reverse_zone_truncated` | info | The zone has more PTR records than `maxPTRsToCheck`; only the first batch was inspected. |
+
+## License
+
+Licensed under the **MIT License** (see `LICENSE`).