92 lines
4.7 KiB
Markdown
92 lines
4.7 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
|
|
|
|
| Code | Description | Severity |
|
|
|----------------------------|----------------------------------------------------------------------------------------------------|----------|
|
|
| `ptr.in_reverse_arpa` | Verifies the PTR owner lies under in-addr.arpa or ip6.arpa. | CRITICAL |
|
|
| `ptr.owner_decodable` | Verifies the reverse-arpa owner name decodes back to an IP address. | CRITICAL |
|
|
| `ptr.reverse_zone_located` | Verifies the reverse zone serving the PTR owner can be located (SOA found). | CRITICAL |
|
|
| `ptr.query_succeeded` | Verifies the PTR query returns NOERROR from the authoritative servers. | CRITICAL |
|
|
| `ptr.record_present` | Verifies at least one PTR record is served at the owner name. | CRITICAL |
|
|
| `ptr.single_record` | Flags multiple PTR records on the same IP (RFC 1912 §2.1 recommends exactly one). | WARNING |
|
|
| `ptr.declared_match` | Verifies the PTR target served by the authoritative servers matches the declared target. | CRITICAL |
|
|
| `ptr.target_syntax_valid` | Verifies the PTR target is a syntactically valid hostname (RFC 952/1123). | CRITICAL |
|
|
| `ptr.generic_hostname` | Flags PTR targets that embed the IP or match common ISP auto-generated patterns. | WARNING |
|
|
| `ptr.target_resolves` | Verifies the PTR target resolves to at least one A or AAAA record. | CRITICAL |
|
|
| `ptr.fcrdns_match` | Verifies the PTR target's A/AAAA resolves back to the original IP (Forward-Confirmed Reverse DNS). | CRITICAL |
|
|
| `ptr.ipv6` | Reports whether the PTR concerns an IPv6 (ip6.arpa) address. | CRITICAL |
|
|
| `ptr.ttl_hygiene` | Verifies the PTR TTL is at or above the configured minimum. | WARNING |
|
|
|
|
## License
|
|
|
|
Licensed under the **MIT License** (see `LICENSE`).
|