Initial commit

README.md

@@ -0,0 +1,96 @@
+# checker-ptr
+
+PTR / Reverse DNS checker for [happyDomain](https://www.happydomain.org/).
+
+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
+
+```bash
+# 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
+
+```bash
+make docker
+docker run -p 8080:8080 happydomain/checker-ptr
+```
+
+### happyDomain plugin
+
+```bash
+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:
+
+```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 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`).