Initial commit

README.md

@@ -0,0 +1,79 @@
+# 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.            |
+
+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
+
+Licensed under the **MIT License** (see `LICENSE`).