96 lines
4.3 KiB
Markdown
96 lines
4.3 KiB
Markdown
# 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
|
|
|
|
Each rule emits a finding code. Severity can be affected by the options above.
|
|
|
|
| Code | Default severity | Condition |
|
|
|------|-----------------|-----------|
|
|
| `ptr_not_in_reverse_zone` | critical | The PTR owner is not under `in-addr.arpa` or `ip6.arpa`. |
|
|
| `ptr_owner_malformed` | critical | The reverse-arpa owner cannot be decoded back to an IP address. |
|
|
| `ptr_no_reverse_zone` | critical | The reverse zone serving the owner cannot be located (no SOA). |
|
|
| `ptr_query_failed` | critical | The PTR query failed (network error, timeout, unreachable authoritative server). |
|
|
| `ptr_rcode` | critical | The authoritative server returned a non-NOERROR rcode (typically NXDOMAIN). |
|
|
| `ptr_missing` | critical | No PTR record is served at the owner name. |
|
|
| `ptr_multiple` | warning | More than one PTR record exists at the same owner (RFC 1912 §2.1). Suppressed when `allowMultiplePTR` is enabled. |
|
|
| `ptr_declared_mismatch` | critical | The authoritative PTR target differs from the target declared in happyDomain. |
|
|
| `ptr_target_invalid` | critical | The PTR target is not a syntactically valid hostname (RFC 952/1123). |
|
|
| `ptr_generic_hostname` | warning | The PTR target embeds the IP or matches a common ISP auto-generated pattern. Only reported when `flagGenericPTR` is enabled. |
|
|
| `ptr_target_unresolvable` | critical / warning with `requireForwardMatch=false` | The PTR target has no A or AAAA record. |
|
|
| `ptr_forward_mismatch` | critical / warning with `requireForwardMatch=false` | The PTR target's A/AAAA does not include the original IP (FCrDNS check failed). |
|
|
| `ptr_ipv6_missing` | critical | An `ip6.arpa` owner has no PTR record. |
|
|
| `ptr_low_ttl` | warning | The observed PTR TTL is below `minTTL`. |
|
|
| `ptr_declared_low_ttl` | info | The declared PTR TTL is below `minTTL`. |
|
|
|
|
## License
|
|
|
|
Licensed under the **MIT License** (see `LICENSE`).
|