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.

Protocol

POST /collect

Request:

{
  "key": "alias",
  "target": {"userId": "...", "domainId": "..."},
  "options": {
    "domain_name": "example.com",
    "subdomain": "www",
    "maxChainLength": 8,
    "minTargetTTL": 60,
    "requireResolvableTarget": true,
    "allowApexCNAME": false,
    "recognizeApexFlattening": true
  }
}

Response (abbreviated):

{
  "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; 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.

5.1 KiB Raw Blame History