checker-reverse-zone

README

checker-reverse-zone

PTR coverage checker for reverse DNS zones in happyDomain.

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

# 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

make docker
docker run -p 8080:8080 happydomain/checker-reverse-zone

happyDomain plugin

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:

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).