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