checker-zonemaster

Zonemaster DNS validation checker for happyDomain.

Runs the Zonemaster test suite against a domain via its public JSON-RPC API and stores the full results as an observation. The checker also produces a rich HTML report grouped by Zonemaster module and severity.

Usage

Standalone HTTP server

make
./checker-zonemaster -listen :8080

The server exposes the standard happyDomain external checker endpoints (/health, /definition, /collect, /evaluate, /html-report).

Docker

make docker
docker run -p 8080:8080 happydomain/checker-zonemaster

happyDomain plugin

make plugin
# produces checker-zonemaster.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:

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 zonemaster checker to the URL of the running checker-zonemaster server (e.g., http://checker-zonemaster:8080). happyDomain will delegate observation collection to this endpoint.

Deployment

The /collect endpoint has no built-in authentication and will issue JSON-RPC calls to whatever Zonemaster API URL is configured via the zonemasterAPIURL admin option (defaulting to the official public API at https://zonemaster.net/api). Operators should point this option only at trusted Zonemaster instances; pointing it at an untrusted host turns the checker into an SSRF vector, since responses are parsed and surfaced back to the caller. The checker itself is meant to run on a trusted network, reachable only by the happyDomain instance that drives it. Restrict access via a reverse proxy with authentication, a network ACL, or by binding the listener to a private interface; do not expose it directly to the public internet.

Options

Scope	Id	Description
Run	domainName	Domain name to test (auto-filled from the domain)
Run	profile	Zonemaster profile name (default: default)
User	language	Result language (en, fr, de, …)
Admin	zonemasterAPIURL	Zonemaster JSON-RPC endpoint (default: official API)

Protocol

POST /collect

Request:

{
  "key": "zonemaster",
  "options": {
    "domainName": "example.com",
    "zonemasterAPIURL": "https://zonemaster.net/api",
    "language": "en",
    "profile": "default"
  }
}

The collect call is long-running: it starts a Zonemaster test, polls until completion, and returns the full result tree as the observation payload.

License

This project is licensed under the MIT License (see LICENSE). The third-party Apache-2.0 attributions for checker-sdk-go are recorded in NOTICE and must accompany any binary or source redistribution of this project.