121 lines
6.4 KiB
Markdown
121 lines
6.4 KiB
Markdown
# 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 . <ancestors…> <domain> | dnsviz grok -t <root-trust-anchor>
|
|
```
|
|
|
|
The queried name **and every ancestor up to the root** are passed to
|
|
`dnsviz probe`, in root → leaf order. `dnsviz` only emits a full analysis
|
|
(DNSKEY set, DS at parent, queries) for names listed on the command line;
|
|
ancestors stumbled upon implicitly are kept as "stub" entries that grok
|
|
ignores. Listing them explicitly is what makes every link of the chain
|
|
appear in the report.
|
|
|
|
`dnsviz grok -t <file>` is given a BIND-format DNSKEY trust anchor for the
|
|
root zone. Without it, the root has no parent to chain against and stays
|
|
classified as `NOERROR` (DNS rcode) instead of `SECURE` (DNSSEC).
|
|
|
|
The output is then parsed: per-zone errors and warnings are walked out of
|
|
the nested record tree (`delegation.errors`, `dnskey[i].errors`,
|
|
`queries/.../rrsig[j].errors`, …) and turned into individual `CheckState`
|
|
entries tagged with the JSON path where they were found. 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), each with its delegation/DS records, DNSKEY set,
|
|
authoritative servers, and per-query analysis (RRsets, RRSIG validity,
|
|
NSEC proofs) so a recursive DNSSEC failure can be located at the exact
|
|
level, and the exact record, where 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
|
|
```
|
|
|
|
Runtime requirements:
|
|
|
|
- `dnsviz` on `PATH` (the Python CLI: `pip install dnsviz`, plus
|
|
`pygraphviz` and `graphviz` since `dnsviz grok -t` imports the graph
|
|
module even when only producing JSON).
|
|
- A BIND-format root DNSKEY trust anchor file. The collector
|
|
auto-detects `/usr/share/dnssec-root/trusted-key.key` (Alpine's
|
|
`dnssec-root` package, Debian/Ubuntu's `dns-root-data` ships an
|
|
equivalent at `/usr/share/dns/root.key`); pass `-trust-anchors-file
|
|
<path>` to override. Without it, the root zone in the report stays at
|
|
`NOERROR` instead of `SECURE`.
|
|
|
|
### Docker
|
|
|
|
```bash
|
|
make docker
|
|
docker run -p 8080:8080 happydomain/checker-dnsviz
|
|
```
|
|
|
|
The image bundles `dnsviz`, `pygraphviz`, `graphviz` and the alpine
|
|
`dnssec-root` package, so the trust anchor is in place out of the box.
|
|
When ICANN rolls a new root KSK (KSK-2024 is scheduled to begin signing
|
|
in late 2026), rebuild the image once the upstream alpine package ships
|
|
the new key.
|
|
|
|
### 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`. |
|
|
| admin | `trustAnchorsFile` | `/usr/share/dnssec-root/trusted-key.key` (auto-detected) | BIND DNSKEY file passed to `dnsviz grok -t`. When unset, the collector falls back to the Alpine `dnssec-root` package path if it exists. |
|
|
| 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.
|