88 lines
3.7 KiB
Markdown
88 lines
3.7 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 <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.
|