Initial commit
This commit is contained in:
commit
30710adfcd
29 changed files with 3955 additions and 0 deletions
121
README.md
Normal file
121
README.md
Normal file
|
|
@ -0,0 +1,121 @@
|
|||
# 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.
|
||||
Loading…
Add table
Add a link
Reference in a new issue