Initial commit

README.md

@@ -0,0 +1,96 @@
+# checker-dnsviz
+
+DNSSEC checker for [happyDomain](https://www.happydomain.org/), implemented as
+a thin wrapper around [DNSViz](https://github.com/dnsviz/dnsviz).
+
+The container ships `dnsviz` (Python) alongside the Go binary that exposes the
+standard happyDomain checker HTTP API (`/health`, `/definition`, `/collect`,
+`/evaluate`, `/report`).
+
+## How it works
+
+For each check run, the Go binary invokes:
+
+```
+dnsviz probe -A <domain> | dnsviz grok
+```
+
+stores the parsed JSON output as the observation, and turns DNSViz's per-zone
+errors and warnings into individual `CheckState` entries. A curated catalog
+of common DNSSEC failure scenarios (broken chain, expired RRSIG, DS digest
+mismatch, deprecated algorithm, …) is matched against the findings to
+generate a "Fix these first" section in the HTML report with plain-language
+remediation hints.
+
+The HTML report renders one block per zone in the chain (root → TLD →
+intermediates → leaf) so a recursive DNSSEC failure can be located at the
+exact level it broke.
+
+## Scope
+
+This checker is intentionally limited to what DNSViz reports. NSEC/NSEC3
+zone-walk hardening and NSEC3PARAM iteration policy (RFC 9276) are
+delivered by a separate `checker-dnssec` module.
+
+## Usage
+
+### Standalone server
+
+```bash
+make
+./checker-dnsviz -listen :8080
+# requires `dnsviz` on PATH
+```
+
+### Docker
+
+```bash
+make docker
+docker run -p 8080:8080 happydomain/checker-dnsviz
+```
+
+### happyDomain plugin
+
+```bash
+make plugin
+# produces checker-dnsviz.so
+```
+
+## Options
+
+| Scope  | Id                    | Default     | Description                                                              |
+|--------|-----------------------|-------------|--------------------------------------------------------------------------|
+| admin  | `dnsvizBin`           | `dnsviz`    | Path to the dnsviz CLI.                                                   |
+| admin  | `probeTimeoutSeconds` | `120`       | Hard timeout for `dnsviz probe`.                                          |
+| admin  | `extraProbeArgs`      | `-A`        | Extra arguments appended verbatim to `dnsviz probe`.                      |
+| domain | `domain_name`         | auto-fill   | Domain to analyse.                                                        |
+
+## Rules
+
+| Rule                       | Description                                                                  |
+|----------------------------|------------------------------------------------------------------------------|
+| `dnsviz_overall_status`    | DNSViz status of the queried domain (SECURE/INSECURE/BOGUS/INDETERMINATE).   |
+| `dnsviz_per_zone_status`   | One state per zone in the chain (root, TLD, intermediates, leaf).            |
+| `dnsviz_zone_errors`       | Every error reported by DNSViz, scoped to the zone where it was found.       |
+| `dnsviz_zone_warnings`     | Every warning reported by DNSViz, scoped to the zone where it was found.    |
+| `dnsviz_common_failures`   | Pattern-matches findings against a catalog of common DNSSEC failures.       |
+
+## Licensing
+
+This repository is split into two licensing zones:
+
+| Path | License | Reason |
+|------|---------|--------|
+| `checker/` | MIT | Pure analysis logic (types, rules, HTML report). Can be imported by third-party Go projects without GPL obligations. |
+| `internal/collect/` | GPL v2 | Invokes the `dnsviz` subprocess. Covered by [DNSViz's GPL v2 licence](https://github.com/dnsviz/dnsviz/blob/master/LICENSE). |
+| `main.go`, `plugin/` | GPL v2 | Wire the two together; distributed binaries include the GPL layer. |
+
+If you only need the analysis primitives (parse grok output, evaluate rules, render the HTML report), import `git.happydns.org/checker-dnsviz/checker` and supply your own `checker.CollectFn` — for example one that calls the HTTP API instead of running DNSViz locally.
+
+## Versioning
+
+```bash
+make CHECKER_VERSION=1.2.3
+make plugin CHECKER_VERSION=1.2.3
+make docker CHECKER_VERSION=1.2.3
+```