# 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

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