# checker-reverse-zone

PTR coverage checker for reverse DNS zones in [happyDomain](https://www.happydomain.org/).

Inspects every PTR record declared in an `in-addr.arpa` or `ip6.arpa` reverse zone,
validates Forward-Confirmed Reverse DNS (FCrDNS), target resolvability, hostname
syntax, generic/auto-generated hostnames, TTL hygiene, and multiple-PTR-per-IP
violations (RFC 1912 §2.1).

## Usage

### Standalone HTTP server

```bash
# Build and run
make
./checker-reverse-zone -listen :8080
```

The server exposes:

- `GET /health`: health check
- `POST /collect`: collect reverse-zone observations (happyDomain external checker protocol)

### Docker

```bash
make docker
docker run -p 8080:8080 happydomain/checker-reverse-zone
```

### happyDomain plugin

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

## Options

| Id                    | Type | Default | Description                                                                                                          |
|-----------------------|------|---------|----------------------------------------------------------------------------------------------------------------------|
| `requireForwardMatch` | bool | `true`  | When enabled, a PTR whose target does not resolve back to the original IP is reported as critical (otherwise warning). Mail and SSH servers require FCrDNS. |
| `allowMultiplePTR`    | bool | `false` | When enabled, more than one PTR at the same owner is allowed (RFC 1912 §2.1 recommends a single PTR per IP).        |
| `minTTL`              | uint | `300`   | PTR records with a TTL below this threshold (in seconds) are flagged as warning.                                     |
| `flagGenericPTR`      | bool | `true`  | When enabled, PTR targets that embed the dotted IP or match common ISP auto-generated patterns are reported as warning. |
| `maxPTRsToCheck`      | uint | `1024`  | Caps the number of PTR records inspected per run, protecting the checker against very large reverse zones.           |

## Rules

| Code                              | Description                                                                                       | Severity            |
|-----------------------------------|---------------------------------------------------------------------------------------------------|---------------------|
| `reverse_zone.is_reverse_arpa`    | Verifies the zone is under in-addr.arpa or ip6.arpa.                                              | CRITICAL            |
| `reverse_zone.has_ptrs`           | Verifies the reverse zone declares at least one PTR record.                                       | WARNING             |
| `reverse_zone.fcrdns`             | Verifies every PTR target's A/AAAA round-trips back to the original IP (Forward-Confirmed Reverse DNS). | CRITICAL      |
| `reverse_zone.target_resolves`    | Verifies every PTR target resolves to at least one A or AAAA record.                              | CRITICAL            |
| `reverse_zone.single_ptr_per_ip`  | Flags IPs with multiple PTR records (RFC 1912 §2.1 recommends exactly one).                       | WARNING             |
| `reverse_zone.target_syntax`      | Verifies every PTR target is a syntactically valid hostname.                                      | CRITICAL            |
| `reverse_zone.generic_hostname`   | Flags PTR targets that embed the IP or match common ISP auto-generated patterns.                  | WARNING             |
| `reverse_zone.ttl_hygiene`        | Flags PTR records whose TTL is below the configured minimum.                                      | WARNING             |
| `reverse_zone.truncated`          | Reports when the zone has more PTRs than the configured cap allows to inspect.                    | INFO                |

## License

Licensed under the **MIT License** (see `LICENSE`).