dnsward

Audits the DNS health of a domain. It queries live DNS and checks the address records, nameserver count and diversity, SOA timers against RFC 1912, CAA, apex CNAME misconfiguration, TTL sanity, and DNSSEC, then scores the domain from 0 to 100 with a letter grade and specific fixes. No dependencies, no AI. The result is the same every time because it reads real DNS.

dnsward is the infrastructure companion to mailward: mailward covers email authentication, dnsward covers the zone itself.

Install

npm install -g @bobfromarcher/dnsward
# or once:
npx @bobfromarcher/dnsward example.com

Usage

dnsward <domain> [options]

| Option | Description | | --- | --- | | --timeout <ms> | DNS query timeout (default 5000) | | --json | Output JSON | | --quiet, -q | No output, exit code only | | -h, --help | Show help | | -v, --version | Show version |

The exit code is 0 for grade A or B and 1 for C or worse, so it gates a deploy or a monitoring job.

What it checks

• Address: the apex resolves over A or AAAA.
• Apex CNAME: a CNAME at the zone apex is invalid and breaks NS, SOA and MX. dnsward flags it.
• www: the www name resolves, by A record or CNAME.
• Nameservers: at least two, and whether they sit on more than one zone. A single nameserver, or all of them at one provider, is a single point of failure.
• SOA: present, with refresh, retry, expire and minimum timers checked against the RFC 1912 ranges, including the common mistake of retry being larger than refresh.
• CAA: present, so only the certificate authorities you choose can issue for the domain.
• TTL: the apex record TTL is neither so low it is fragile nor so high it is slow to change.
• DNSSEC: whether the zone is signed. This uses a direct DNSKEY query and degrades to "not checked" if the resolver does not answer.

As a library

const { audit } = require('@bobfromarcher/dnsward');

const report = await audit('example.com');
console.log(report.grade, report.score);
for (const check of report.checks) {
  if (check.status === 'fail' || check.status === 'warn') console.log(check.title, check.fix);
}

audit(domain, opts) accepts an injected resolver and a dnssec override, which makes it testable without touching the network.

Examples

dnsward cloudflare.com
dnsward example.com --json | jq '.grade'

Notes

dnsward reports on the public DNS of a zone. It does not check internal or split-horizon DNS, and the nameserver-diversity signal is based on the registrable name, which is a heuristic rather than a network-path analysis.

Development

git clone https://github.com/bobfromarcher/dnsward
cd dnsward
node test/test.js

CI runs the suite on Node 18, 20 and 22 across Linux, macOS and Windows.

License

MIT, bobfromarcher.