Specifications :: Gonemaster

API Reference

Mon, 01 Jan 0001 00:00:00 +0000

gonemaster-server exposes a trusted admin API and a restricted public API. Admin API Base path: /api/v1/ Use this API from trusted clients such as the admin UI, gonemaster-client, cron jobs, and internal scripts. It can manage jobs, batches, domains, tags, runs, entries, profiles, queue state, settings, metrics, and cohorts. Keep it private. Public API Base path: /pub/api/v1/ Use this API for public job submission, public job lookup, public profiles, and read-only public analysis. Public job endpoints use opaque public IDs instead of internal job IDs.

Tags

Mon, 01 Jan 0001 00:00:00 +0000

This directory contains per-module tag catalogs for gonemaster. Each catalog lists all tags that can be emitted by a module’s testcases, together with the default severity level, which testcase(s) emit the tag, and the i18n coverage status across the supported locale files. Files File Module Tags address.md ADDRESS address01-address03 basic.md BASIC basic01-basic03 connectivity.md CONNECTIVITY connectivity01-connectivity04 consistency.md CONSISTENCY consistency01-consistency06 delegation.md DELEGATION delegation01-delegation07 dnssec.md DNSSEC dnssec01-dnssec19 nameserver.md NAMESERVER nameserver01-nameserver15 syntax.md SYNTAX syntax01-syntax08 zone.md ZONE zone01-zone12 Structure Of Each Catalog Every per-module catalog contains:

Tests

Mon, 01 Jan 0001 00:00:00 +0000

This directory contains canonical testcase specifications for gonemaster. Each testcase spec MUST be based on current implementation behavior and SHOULD start from docs/specifications/templates/testcase-spec-template.md. Normalization Rules One testcase specification per file. Canonical file location format: docs/specifications/tests//.md Example: docs/specifications/tests/zone/zone07.md Specs describe gonemaster behavior, not desired future behavior. If upstream and implementation differ, the difference MUST be explicit. Every emitted tag documented for a testcase MUST be possible in code. Normative Language Use RFC 2119 style keywords with their normal meanings:

UI Explanations

Mon, 01 Jan 0001 00:00:00 +0000

Plain-language explanations for DNS findings shown on the public results page. One file per module, authored for a domain owner who is not a DNS operator. The markdown files here are the source of truth. Sync them into the i18n catalogs with: node tools/i18n/sync-ui-explanations.mjs The sync script: Writes every managed key to ui-public/src/i18n/en.json. Existing English values are overwritten from the markdown. Never touches other locales. The t() store falls back to English for missing keys, and tools/i18n/missing-keys.sh doubles as the translator work queue for whatever has not been localized yet. Key families pub.tc_desc. - per-testcase plain-language description (1-3 sentences). Rendered under the testcase

on the results page. pub.tag...header - short (3-6 words) human-readable summary of a single finding tag. Rendered inline before the templated engine message. pub.tag...desc - longer (1-3 sentences) description. Rendered inside a collapsible “About this finding” disclosure under each finding row. Any of the three can be omitted; the UI degrades gracefully.