# 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

Each rule emits a finding code. Severity can be affected by the options above.

| Code | Default severity | Condition |
|------|-----------------|-----------|
| `reverse_zone_not_arpa` | critical | The zone is not under `in-addr.arpa` or `ip6.arpa`. |
| `reverse_zone.load_error` | error | A structural failure prevented observation collection. |
| `reverse_zone_empty` | warning | The reverse zone declares no PTR records at all. |
| `ptr_forward_mismatch` | critical / warning with `requireForwardMatch=false` | A PTR target's A/AAAA records do not include the original IP (FCrDNS mismatch). |
| `ptr_target_unresolvable` | critical / warning with `requireForwardMatch=false` | A PTR target has no A or AAAA record in the forward DNS. |
| `ptr_multiple` | warning | An IP owner carries more than one PTR record. Skipped when `allowMultiplePTR=true`. |
| `ptr_target_invalid` | critical | A PTR target is not a syntactically valid hostname (RFC 952/1123). |
| `ptr_generic_hostname` | warning | A PTR target embeds the IP address or matches common ISP auto-generated patterns. Skipped when `flagGenericPTR=false`. |
| `ptr_low_ttl` | warning | A PTR record's TTL is below `minTTL`. |
| `reverse_zone_truncated` | info | The zone has more PTR records than `maxPTRsToCheck`; only the first batch was inspected. |

## License

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