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