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