checker-alias

CNAME / DNAME / ALIAS chain checker for happyDomain.

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

# 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

make docker
docker run -p 8080:8080 happydomain/checker-alias

happyDomain plugin

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:

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).