89 lines
4 KiB
Markdown
89 lines
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
|
|
|
|
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`).
|