156 lines
5.1 KiB
Markdown
156 lines
5.1 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. |
|
|
|
|
## Protocol
|
|
|
|
### POST /collect
|
|
|
|
Request:
|
|
```json
|
|
{
|
|
"key": "alias",
|
|
"target": {"userId": "...", "domainId": "..."},
|
|
"options": {
|
|
"domain_name": "example.com",
|
|
"subdomain": "www",
|
|
"maxChainLength": 8,
|
|
"minTargetTTL": 60,
|
|
"requireResolvableTarget": true,
|
|
"allowApexCNAME": false,
|
|
"recognizeApexFlattening": true
|
|
}
|
|
}
|
|
```
|
|
|
|
Response (abbreviated):
|
|
```json
|
|
{
|
|
"data": {
|
|
"owner": "www.example.com.",
|
|
"apex": "example.com.",
|
|
"auth_servers": ["ns1.example.net:53"],
|
|
"chain": [
|
|
{"owner": "www.example.com.", "kind": "CNAME", "target": "host.example.net.", "ttl": 300},
|
|
{"owner": "host.example.net.", "kind": "TARGET"}
|
|
],
|
|
"final_target": "host.example.net.",
|
|
"final_a": ["192.0.2.10"],
|
|
"final_aaaa": ["2001:db8::10"],
|
|
"rcode": "NOERROR",
|
|
"zone_signed": true,
|
|
"cname_signed": true,
|
|
"findings": [
|
|
{
|
|
"code": "alias_low_ttl",
|
|
"severity": "warn",
|
|
"message": "hop www.example.com. → host.example.net. has TTL 30s (< 60)",
|
|
"subject": "www.example.com.",
|
|
"hint": "Raise the CNAME TTL to improve cache efficiency."
|
|
}
|
|
]
|
|
}
|
|
}
|
|
```
|
|
|
|
Finding codes emitted by the checker include: `alias_no_apex`,
|
|
`alias_loop`, `alias_chain_too_long`, `alias_query_failed`,
|
|
`alias_rcode`, `alias_low_ttl`, `alias_cname_at_apex`,
|
|
`alias_apex_flattening`, `alias_coexisting_rrset`,
|
|
`alias_cname_not_signed`, `alias_target_unresolvable`,
|
|
`alias_multiple_records`.
|
|
|
|
## License & licensing roadmap
|
|
|
|
This project is currently licensed under the **GNU Affero General Public
|
|
License v3.0** (see `LICENSE`), because it still imports
|
|
`happydns.ServiceMessage` and `abstract.Server` from the happyDomain
|
|
server module (`git.happydns.org/happyDomain/model` and
|
|
`git.happydns.org/happyDomain/services/abstract`), which are themselves
|
|
distributed under AGPL-3.0 and a commercial license.
|
|
|
|
The core checker types (`CheckerOptions`, `CheckerDefinition`,
|
|
`ObservationProvider`, `CheckRule`, …) have already been migrated to
|
|
[`checker-sdk-go`](https://git.happydns.org/checker-sdk-go); only the
|
|
service-message types remain on the AGPL side.
|
|
|
|
**Planned relicensing:** as soon as the remaining `ServiceMessage` /
|
|
`abstract.Server` dependency has been removed (moved into a dedicated
|
|
permissively licensed module), this project will be relicensed under the
|
|
**MIT License**, in line with the rest of the happyDomain checker
|
|
ecosystem (see `checker-dummy` for the target shape).
|
|
|
|
**Contributors notice:** by submitting a contribution to this repository,
|
|
you accept that your contribution will be relicensed from AGPL-3.0 to MIT
|
|
at the time of the relicensing described above. If you do not agree with
|
|
this, please do not submit contributions until the relicensing has taken
|
|
place.
|
|
|
|
The third-party Apache-2.0 attributions for `checker-sdk-go` are recorded
|
|
in `NOTICE` and must accompany any binary or source redistribution of this
|
|
project.
|