# checker-dnssec

DNSSEC operational hygiene checker for [happyDomain](https://www.happydomain.org/).

Cryptographic chain validation is delegated to `checker-dnsviz`. This
checker focuses on **policy and operational hygiene**:

- NSEC vs NSEC3 zone walking exposure
- RFC 9276 NSEC3 parameter compliance (iterations, salt)
- Algorithm policy and key sizes (allowed / forbidden / modern)
- RRSIG presence, validity windows and freshness
- TTL recommendations for DNSKEY / RRSIG
- Per-name-server consistency of the DNSKEY RRset and denial scheme

The HTML report is laid out so the most common operator-facing failure
scenarios appear first, with a fix line citing the relevant RFC.

## Usage

### Standalone HTTP server

```bash
# Build and run
make
./checker-dnssec -listen :8080
```

The server exposes:

- `GET /health`: health check
- `POST /collect`: collect DNSSEC observations (happyDomain external checker protocol)

### Docker

```bash
make docker
docker run -p 8080:8080 happydomain/checker-dnssec
```

### happyDomain plugin

```bash
make plugin
# produces checker-dnssec.so, loadable by happyDomain as a Go plugin
```

The plugin exposes a `NewCheckerPlugin` symbol returning the checker
definition and observation provider, which happyDomain registers in its
global registries at load time.

### Versioning

The binary, plugin, and Docker image embed a version string overridable
at build time:

```bash
make CHECKER_VERSION=1.2.3
make plugin CHECKER_VERSION=1.2.3
make docker CHECKER_VERSION=1.2.3
```

### happyDomain remote endpoint

Set the `endpoint` admin option for the DNSSEC checker to the URL of the
running checker-dnssec server (e.g., `http://checker-dnssec:8080`).
happyDomain will delegate observation collection to this endpoint.

## Build

```sh
make            # standalone binary
make docker     # FROM scratch image
make plugin     # Go plugin (.so)
make test       # tests
```

## Options

### Admin options

| Id         | Type   | Default              | Description                                                                                                  |
|------------|--------|----------------------|--------------------------------------------------------------------------------------------------------------|
| `resolver` | string | `/etc/resolv.conf`   | Bootstrap recursive resolver (`host:port`) used to discover the apex name servers and look up the parent DS. |

### User options

| Id                        | Type   | Default | Description                                                                                                                  |
|---------------------------|--------|---------|------------------------------------------------------------------------------------------------------------------------------|
| `nsec3IterationsMax`      | uint   | `0`     | RFC 9276 §3.1 ceiling on `NSEC3PARAM.Iterations`. Increase only if your signer cannot publish 0 yet.                          |
| `nsec3IterationsSeverity` | choice | `warn`  | Severity when iterations exceed the ceiling. Use `crit` to enforce RFC 9276 strictly.                                         |
| `signatureFreshness`      | uint   | `7`     | Warn when the closest RRSIG expires in fewer than this many days.                                                             |
| `signatureFreshnessCrit`  | uint   | `1`     | Critical when the closest RRSIG expires in fewer than this many days.                                                         |
| `minRSAKeySize`           | uint   | `2048`  | Minimum acceptable RSA modulus size, in bits.                                                                                 |
| `requireSEP`              | bool   | `true`  | Require at least one DNSKEY with the SEP bit (KSK).                                                                           |
| `dnskeyTTLMin`            | uint   | `3600`  | Minimum DNSKEY TTL, in seconds; shorter TTLs hurt cacheability.                                                               |

## Rules

Each rule emits a finding code. Severity may be affected by the options above.

| Code | Default severity | Condition |
|------|-----------------|-----------|
| `dnssec_zone_signed` | critical | Parent DS is published but the apex serves no DNSKEY (broken chain of trust). |
| `dnssec_dnskey_consistent` | critical | Authoritative servers disagree on the apex DNSKEY RRset. |
| `dnssec_dnskey_query_ok` | warning | At least one authoritative server failed to answer the DNSKEY query. |
| `dnssec_algorithm_allowed` | critical (forbidden) / warning (not in allowlist) | A DNSKEY uses a forbidden algorithm or an algorithm not in `allowedAlgorithms`. |
| `dnssec_algorithm_modern` | warning | The zone still uses RSA-family DNSKEYs; ECDSAP256SHA256 (13) or Ed25519 (15) recommended. |
| `dnssec_rsa_keysize` | critical (<1024) / warning (<`minRSAKeySize`) | An RSA DNSKEY has a modulus below the policy threshold. |
| `dnssec_ksk_present` | critical | No DNSKEY carries the SEP (KSK) flag while `requireSEP` is enabled. |
| `dnssec_dnskey_count` | warning | Eight or more DNSKEYs are published, bloating responses and amplification factor. |
| `dnssec_rrsig_present_dnskey` | critical | The apex DNSKEY RRset is unsigned. |
| `dnssec_rrsig_present_soa` | critical | The apex SOA RRset is unsigned. |
| `dnssec_rrsig_validity_window` | critical | An observed RRSIG is outside its `[Inception, Expiration]` window. |
| `dnssec_rrsig_freshness` | warning / critical | The closest RRSIG expires in fewer than `signatureFreshness` / `signatureFreshnessCrit` days. |
| `dnssec_denial_uses_nsec3` | warning | The zone uses NSEC for denial of existence, exposing it to trivial walking (RFC 5155 / RFC 7129). |
| `dnssec_nsec3_iterations` | warning / critical (per `nsec3IterationsSeverity`) | `NSEC3PARAM.Iterations` exceeds `nsec3IterationsMax` (RFC 9276 §3.1). |
| `dnssec_nsec3_salt_empty` | warning | `NSEC3PARAM.SaltLength` is non-zero (RFC 9276 §3.1: a salt buys no measurable protection). |
| `dnssec_nsec3_optout_only_when_signed_delegations` | info | The OPT-OUT flag is set in a leaf zone, where it serves no purpose. |
| `dnssec_denial_consistent` | critical | Authoritative servers disagree on the denial-of-existence scheme (NSEC vs NSEC3, or differing parameters). |
| `dnssec_dnskey_ttl_min` | warning | The DNSKEY TTL is below `dnskeyTTLMin`, hurting cache efficiency. |

## License

Licensed under the **MIT License** (see `LICENSE`).