checker-reverse-zone/README.md

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

Code	Description	Severity
reverse_zone.is_reverse_arpa	Verifies the zone is under in-addr.arpa or ip6.arpa.	CRITICAL
reverse_zone.has_ptrs	Verifies the reverse zone declares at least one PTR record.	WARNING
reverse_zone.fcrdns	Verifies every PTR target's A/AAAA round-trips back to the original IP (Forward-Confirmed Reverse DNS).	CRITICAL
reverse_zone.target_resolves	Verifies every PTR target resolves to at least one A or AAAA record.	CRITICAL
reverse_zone.single_ptr_per_ip	Flags IPs with multiple PTR records (RFC 1912 §2.1 recommends exactly one).	WARNING
reverse_zone.target_syntax	Verifies every PTR target is a syntactically valid hostname.	CRITICAL
reverse_zone.generic_hostname	Flags PTR targets that embed the IP or match common ISP auto-generated patterns.	WARNING
reverse_zone.ttl_hygiene	Flags PTR records whose TTL is below the configured minimum.	WARNING
reverse_zone.truncated	Reports when the zone has more PTRs than the configured cap allows to inspect.	INFO

License

Licensed under the MIT License (see LICENSE).