checker-ptr/README.md

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

Code	Description	Severity
ptr.in_reverse_arpa	Verifies the PTR owner lies under in-addr.arpa or ip6.arpa.	CRITICAL
ptr.owner_decodable	Verifies the reverse-arpa owner name decodes back to an IP address.	CRITICAL
ptr.reverse_zone_located	Verifies the reverse zone serving the PTR owner can be located (SOA found).	CRITICAL
ptr.query_succeeded	Verifies the PTR query returns NOERROR from the authoritative servers.	CRITICAL
ptr.record_present	Verifies at least one PTR record is served at the owner name.	CRITICAL
ptr.single_record	Flags multiple PTR records on the same IP (RFC 1912 §2.1 recommends exactly one).	WARNING
ptr.declared_match	Verifies the PTR target served by the authoritative servers matches the declared target.	CRITICAL
ptr.target_syntax_valid	Verifies the PTR target is a syntactically valid hostname (RFC 952/1123).	CRITICAL
ptr.generic_hostname	Flags PTR targets that embed the IP or match common ISP auto-generated patterns.	WARNING
ptr.target_resolves	Verifies the PTR target resolves to at least one A or AAAA record.	CRITICAL
ptr.fcrdns_match	Verifies the PTR target's A/AAAA resolves back to the original IP (Forward-Confirmed Reverse DNS).	CRITICAL
ptr.ipv6	Reports whether the PTR concerns an IPv6 (ip6.arpa) address.	CRITICAL
ptr.ttl_hygiene	Verifies the PTR TTL is at or above the configured minimum.	WARNING

License

Licensed under the MIT License (see LICENSE).