91 lines
3.9 KiB
Markdown
91 lines
3.9 KiB
Markdown
# checker-alias
|
|
|
|
CNAME / DNAME / ALIAS chain checker for [happyDomain](https://www.happydomain.org/).
|
|
|
|
Walks the alias chain of a name, validates hop count, TTLs, target
|
|
resolvability, apex coexistence (RFC 1912 §2.4, RFC 1034 §3.6.2,
|
|
RFC 2181 §10.1), DNAME substitutions, and DNSSEC signing of the CNAME
|
|
RRset.
|
|
|
|
## Usage
|
|
|
|
### Standalone HTTP server
|
|
|
|
```bash
|
|
# Build and run
|
|
make
|
|
./checker-alias -listen :8080
|
|
```
|
|
|
|
The server exposes:
|
|
|
|
- `GET /health`: health check
|
|
- `POST /collect`: collect alias observations (happyDomain external checker protocol)
|
|
|
|
### Docker
|
|
|
|
```bash
|
|
make docker
|
|
docker run -p 8080:8080 happydomain/checker-alias
|
|
```
|
|
|
|
### happyDomain plugin
|
|
|
|
```bash
|
|
make plugin
|
|
# produces checker-alias.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 alias checker to the URL of the
|
|
running checker-alias server (e.g., `http://checker-alias:8080`).
|
|
happyDomain will delegate observation collection to this endpoint.
|
|
|
|
## Options
|
|
|
|
| Id | Type | Default | Description |
|
|
|---------------------------|------|---------|-----------------------------------------------------------------------------|
|
|
| `maxChainLength` | uint | `8` | Above this number of hops the chain is reported as critical. |
|
|
| `minTargetTTL` | uint | `60` | Hops with a TTL below this threshold are flagged as a warning. |
|
|
| `requireResolvableTarget` | bool | `true` | When enabled, a final target with no A/AAAA is critical (otherwise warning).|
|
|
| `allowApexCNAME` | bool | `false` | When enabled, a CNAME at apex is only a warning (RFC 1912 forbids it). |
|
|
| `recognizeApexFlattening` | bool | `true` | Recognize provider-side ALIAS/ANAME flattening as informational. |
|
|
|
|
## Rules
|
|
|
|
Each rule emits a finding code. Severity can be affected by the options above.
|
|
|
|
| Code | Default severity | Condition |
|
|
|------|-----------------|-----------|
|
|
| `apex_lookup` | critical | Zone apex (SOA) cannot be located for the queried name. |
|
|
| `chain_loop` | critical | A CNAME/DNAME cycle is detected in the resolution chain. |
|
|
| `chain_length` | critical | The chain exceeds `maxChainLength` hops. |
|
|
| `chain_query_error` | warning | A DNS query fails while walking the chain (network error, timeout). |
|
|
| `chain_rcode` | critical (mid-chain) / warning (final) | A non-NOERROR response code is encountered during chain resolution or the final A/AAAA lookup. |
|
|
| `hop_ttl` | warning | A CNAME/DNAME hop has a TTL below `minTargetTTL`. |
|
|
| `cname_at_apex` | critical / warning with `allowApexCNAME` | A CNAME exists at the zone apex, conflicting with SOA/NS (RFC 1912 §2.4). |
|
|
| `apex_flattening` | info | A/AAAA records coexist with SOA/NS at the apex without a CNAME, provider-side ALIAS/ANAME flattening. Only reported when `recognizeApexFlattening` is enabled. |
|
|
| `cname_coexistence` | critical / warning with `allowApexCNAME` at apex | Other RRsets (beyond A/AAAA) coexist at a CNAME owner, violating RFC 1034 §3.6.2 / RFC 2181 §10.1. |
|
|
| `cname_dnssec` | critical | The zone is DNSSEC-signed but the CNAME RRset at the queried name lacks an RRSIG. |
|
|
| `target_resolvable` | critical / warning with `requireResolvableTarget=false` | The final target of the chain has no A or AAAA record. |
|
|
| `multiple_records` | critical | An owner in the chain carries more than one CNAME/DNAME record (malformed). |
|
|
|
|
## License
|
|
|
|
Licensed under the **MIT License** (see `LICENSE`).
|