86 lines
4.4 KiB
Markdown
86 lines
4.4 KiB
Markdown
# 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`).
|