checker-ptr

PTR / Reverse DNS checker for happyDomain.

Validates reverse DNS for an IP: confirms the owner lies under in-addr.arpa / ip6.arpa, locates the reverse zone, queries the authoritative servers, and verifies PTR presence, target syntax (RFC 952/1123), forward resolution and Forward-Confirmed Reverse DNS (FCrDNS), single-PTR hygiene (RFC 1912 §2.1), TTL hygiene, and generic-hostname patterns commonly penalised by mail filters.

Usage

Standalone HTTP server

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

The server exposes:

• GET /health: health check
• POST /collect: collect PTR observations (happyDomain external checker protocol)

Docker

make docker
docker run -p 8080:8080 happydomain/checker-ptr

happyDomain plugin

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

Options

Id	Type	Default	Description
requireForwardMatch	bool	true	When enabled, a PTR target whose A/AAAA does not include the original IP is critical (else warning).
followTargetCNAME	bool	true	Follow CNAME chains when resolving the PTR target before comparing A/AAAA to the original IP.
allowMultiplePTR	bool	false	When disabled, more than one PTR at the same owner is flagged as warning (RFC 1912 §2.1).
minTTL	uint	300	PTR records with a TTL below this threshold are flagged as warning.
flagGenericPTR	bool	true	When enabled, PTR targets embedding the IP or matching common ISP auto-generated patterns warn.

Rules

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

Code	Default severity	Condition
ptr_not_in_reverse_zone	critical	The PTR owner is not under in-addr.arpa or ip6.arpa.
ptr_owner_malformed	critical	The reverse-arpa owner cannot be decoded back to an IP address.
ptr_no_reverse_zone	critical	The reverse zone serving the owner cannot be located (no SOA).
ptr_query_failed	critical	The PTR query failed (network error, timeout, unreachable authoritative server).
ptr_rcode	critical	The authoritative server returned a non-NOERROR rcode (typically NXDOMAIN).
ptr_missing	critical	No PTR record is served at the owner name.
ptr_multiple	warning	More than one PTR record exists at the same owner (RFC 1912 §2.1). Suppressed when allowMultiplePTR is enabled.
ptr_declared_mismatch	critical	The authoritative PTR target differs from the target declared in happyDomain.
ptr_target_invalid	critical	The PTR target is not a syntactically valid hostname (RFC 952/1123).
ptr_generic_hostname	warning	The PTR target embeds the IP or matches a common ISP auto-generated pattern. Only reported when flagGenericPTR is enabled.
ptr_target_unresolvable	critical / warning with requireForwardMatch=false	The PTR target has no A or AAAA record.
ptr_forward_mismatch	critical / warning with requireForwardMatch=false	The PTR target's A/AAAA does not include the original IP (FCrDNS check failed).
ptr_ipv6_missing	critical	An ip6.arpa owner has no PTR record.
ptr_low_ttl	warning	The observed PTR TTL is below minTTL.
ptr_declared_low_ttl	info	The declared PTR TTL is below minTTL.

License

Licensed under the MIT License (see LICENSE).