# How DomainGuard tests your domains, and how to re-test it

DomainGuard makes claims about your domains: this host runs WooCommerce 8.4.0, CVE-2026-57777 applies to it, your DMARC record is `p=none`. Every one of those claims can be checked from outside with ordinary tools, and we want you (or your AI agent) to check them. Each verdict you send back, agreeing or not, goes into how we measure and fix the scanner.

This page is the method. The same text is the MCP resource `domainguard://verification`, and every task the API hands out carries its own copy of the relevant steps.

## Connect an agent

**From the dashboard (two clicks).** Settings → API & MCP access → **Connect an AI agent**. Pick your agent and click **Create key & copy setup**. For Claude Code that is one terminal command. For Cursor, VS Code and Claude Desktop it is a config snippet, and for any other agent it is a prompt to paste into the chat.

**By hand.** Create an API key (Pro or Enterprise; read-only is enough) and point any MCP client at:

```
URL:     https://nhmohio.com/api/mcp        (streamable HTTP, POST)
Header:  Authorization: Bearer nhm_…
```

Claude Code:

```
claude mcp add --transport http --scope user domainguard https://nhmohio.com/api/mcp --header "Authorization: Bearer nhm_…"
claude "Use the DomainGuard verify_findings prompt and report back."
```

No MCP? The same work runs over REST with the same header:

```
GET  https://nhmohio.com/api/verification/tasks                 # your domains, most exposed first
GET  https://nhmohio.com/api/verification/tasks?domain_id=53    # that domain's tasks
POST https://nhmohio.com/api/verification/results               # your verdicts (JSON below)
```

## Rules of engagement

1. **Only your domains.** A key only sees its own account's domains, and a task only names hosts we found on them. Don't point the commands at anything else.
2. **Read-only and passive.** Every step is a DNS lookup, one HTTPS GET or HEAD, a TLS handshake, or reading the line a service sends when you connect. Nothing logs in, submits a form, brute-forces, fuzzes or tries an exploit.
3. **A version plus the published range is the whole proof** for a CVE. Never try the exploit to "confirm" it.
4. **Report what you saw, with the command or source.** Confirmations count as much as disputes.
5. **If you can't run a step** (no shell, a blocked port, an OpenSSL without TLS 1.0), answer `could_not_verify` and say why. Don't guess.

## The protocol

1. `get_verification_tasks { domain_id }` → tasks, highest stakes first (known-exploited, then confirmed, then by severity). A finding you verified in the last 7 days is left out while our claim stays the same. Pass `include_verified: true` to see them anyway.
2. Run each task's `how_to_verify` steps and compare with `compare`.
3. `submit_verification_results`:

```json
{
  "domain_id": 53,
  "agent": "Claude Code 2.x",
  "results": [
    { "finding_key": "component:412", "verdict": "confirmed",
      "observed_value": "8.4.0",
      "method": "curl …/wp-content/plugins/woocommerce/readme.txt | grep -m3 '^= '",
      "evidence": "= 8.4.0 2023-12-12 =" },
    { "finding_key": "exposure:9981@www.example.com", "verdict": "incorrect",
      "observed_value": "8.4.0 is below the affected range 8.8.0 - 8.9.2",
      "method": "CVE record affected[] + NVD versionStartIncluding",
      "evidence": "versionStartIncluding 8.8.0, versionEndExcluding 8.9.3" }
  ],
  "missed": [
    { "title": "Theme Enfold 4.5.2 has no advisory listed",
      "detail": "style.css says Version: 4.5.2; DomainGuard lists no theme findings for this host.",
      "evidence": "curl …/themes/enfold/style.css | grep Version" }
  ]
}
```

Verdicts are `confirmed` (we're right), `incorrect` (we're wrong: `observed_value` or `evidence` is required) or `could_not_verify`. Limits: 60 results and 5 missed per call, 400 a day per account.

### What happens to a verdict

- **Every verdict is stored** next to a snapshot of what we claimed at the time, per test method. That gives us a running accuracy figure for each way we test (plugin `?ver=` versus readme, SSH greetings, each checkup rule). The worst-scoring method is the next scanner fix.
- **`incorrect` files a scanner report.** Our operator gets one message per domain, and the finding goes back into the queue for a re-check. It does **not** change your result by itself. We re-test first, because an agent can be wrong too.
- **`missed`** becomes a false-negative report the same way.
- You can see what your agents confirmed and disputed under Settings → API & MCP access.

## How we test each kind of claim

### `component`: "HOST runs PRODUCT VERSION"

We read the version from what the site itself publishes. The task's `method_key` says which reader produced it.

| method_key | What we read | Re-test it with |
|---|---|---|
| `asset-ver`, `wordpress-asset` | the `?ver=` query string on a plugin or theme's own files in the homepage HTML | `curl -sL https://HOST/ \| grep -oE 'plugins/SLUG/[^"' ]*\?ver=[^"' &]+'` |
| `readme` | the newest changelog entry in the plugin's `readme.txt` | `curl -s https://HOST/wp-content/plugins/SLUG/readme.txt \| grep -m3 -E '^(= \|#+ )[0-9]'` |
| `generator` | `<meta name="generator">` | `curl -sL https://HOST/ \| grep -oiE '<meta name="generator"[^>]*>'` |
| `style-css` | the `Version:` header of the theme's `style.css` | `curl -s https://HOST/wp-content/themes/SLUG/style.css \| grep -i '^Version:'` |
| `feed-generator` | the `<generator>` in the RSS feed (WordPress core) | `curl -sL https://HOST/feed/ \| grep -o '<generator>[^<]*'` |
| `banner` | the greeting a service sends on connect (SSH, SMTP), or a device's public status JSON (UniFi `/status`) | `nc -w5 HOST 22 </dev/null \| head -1`, `curl -sk https://HOST:8443/status` |
| `container-scanner`, `script-url` | a library's file header or file name (e.g. `/*! jQuery v1.8.3`) | fetch the script and read its first line |

Two traps we check for, and you should too:

- **Bundled libraries print their own version first.** WooCommerce loads jQuery BlockUI as `?ver=2.7.0-wc.8.4.0`, so the plugin's version comes after `-wc.`. A plugin's `readme.txt` "Stable tag" often lags one release behind, and the changelog doesn't.
- **Cached pages.** A CDN can serve an old copy of the homepage. Add a throwaway query string (`?nocache=$RANDOM`) and compare.

### `exposure`: "CVE-X affects PRODUCT VERSION on HOST"

We match the observed version against the affected ranges published for the CVE, and label the result `confirmed` (inside every range the sources give) or `possible` (sources disagree, or the version is uncertain).

Re-test it:

1. Confirm the version first. It's a separate `component` task.
2. Read the CVE record's ranges: `curl -s https://cveawg.mitre.org/api/cve/CVE-X | jq '.containers.cna.affected'`
3. Read NVD's machine ranges: `curl -s 'https://services.nvd.nist.gov/rest/json/cves/2.0?cveId=CVE-X' | jq '[.vulnerabilities[0].cve.configurations[]?.nodes[]?.cpeMatch[]?]'`. Without a key NVD allows 5 requests per 30 seconds.
4. For WordPress plugins and themes, WPVulnerability.net: `curl -s https://www.wpvulnerability.net/plugin/SLUG | jq '.data.vulnerability[] | {name, operator}'`
5. For a Linux distribution package (a build like `OpenSSH_8.2p1 Ubuntu-4ubuntu0.11`), the upstream number is not enough. Distributions back-port fixes without changing it. Check ubuntu.com/security/CVE-X or security-tracker.debian.org for that exact build.

**Check both ends of the range.** A feed can shorten "8.8.0 to 8.9.2" to "< 8.9.3", which would wrongly include 8.4.0. That exact case is why this program exists.

Two traps our own first run hit, so you don't:

- **WPScan's convention.** Records from WPScan write `{ "version": "4.8.4", "lessThan": "4.8.4" }` to mean "< 4.8.4", with no lower bound. A `version` of `n/a`, `0` or `*` also means no lower bound.
- **The CVE record and NVD can disagree.** For jQuery CVE-2020-11022 the record says `>= 1.12.0` and NVD says `>= 1.2`. We follow NVD, so call a finding `incorrect` only when NVD's range excludes the version too. Otherwise answer `could_not_verify` and name both ranges.

### `check`: a security-checkup finding

| Check | We test | Re-test it with |
|---|---|---|
| SPF Record / DNS Lookups / Policy Strength | the TXT record starting `v=spf1`, lookups counted recursively (limit 10) | `dig +short TXT DOMAIN` |
| DMARC Record | `_dmarc` TXT: `p=`, `rua=` (plain ASCII `mailto:` only), `pct=` | `dig +short TXT _dmarc.DOMAIN` |
| DKIM Record | the key at the selector we found (M365 `selector1/2`, Google `google`) | `dig +short TXT SELECTOR._domainkey.DOMAIN` |
| MX Records, Nameservers | the published records | `dig +short MX DOMAIN`, `dig +short NS DOMAIN` |
| MTA-STS, TLS-RPT | `_mta-sts` TXT + the policy file, `_smtp._tls` TXT | `dig`, `curl https://mta-sts.DOMAIN/.well-known/mta-sts.txt` |
| CAA | CAA records (none = any CA may issue) | `dig +short CAA DOMAIN` |
| Security headers (HSTS, CSP, X-Frame-Options, …) | response headers on each host that serves HTML, the apex redirect included | `curl -sI https://HOST/ \| grep -i '^header:'` |
| Certificate (as served) | the certificate from a real TLS handshake | `echo \| openssl s_client -connect HOST:443 -servername HOST \| openssl x509 -noout -issuer -enddate` |
| Certificate Name / Expiry / Trust, TLS 1.3 | every TLS endpoint we found (subdomains, mail and appliance ports) | one `openssl s_client -connect HOST:PORT` per endpoint the finding names |
| TLS Versions | which protocol versions the server accepts | `openssl s_client -tls1_1 …` per version |
| HTTP to HTTPS Redirect, HTTP Status | the redirect and the final status | `curl -sI http://DOMAIN/` |
| Domain Expiry, Registrar, Age | the registry's RDAP record | `curl -sL https://rdap.org/domain/DOMAIN` |
| Subresource Integrity, Third-Party Scripts | external `<script src>` tags and their `integrity=` | `curl -sL https://DOMAIN/ \| grep -oiE '<script[^>]+src=[^>]*>'` |
| IP Blacklist (DNSBL) | blocklist lookups | **could_not_verify.** The big public lists (e.g. Spamhaus) don't allow commercial querying through public resolvers, so we don't ask you to |

## Sources, licences and commercial use

Everything this method points you at can be used commercially, by us and by you.

| Source | Used for | Licence / terms |
|---|---|---|
| Your own servers and public DNS | every version and checkup test | your data |
| CVE Program (cve.org, cveawg.mitre.org, cvelistV5) | CVE records and ranges | CVE Terms of Use: free to use, copy and distribute, with attribution to MITRE/CVE |
| NVD (NIST) | CVSS, machine-readable ranges | US Government work, public domain. *This product uses the NVD API but is not endorsed or certified by the NVD.* |
| CISA Known Exploited Vulnerabilities | "actively exploited" flags | public domain (CC0) |
| WPVulnerability.net | WordPress core, plugin and theme advisories | free and open, data under EUPL-1.2; we credit it and the original publisher (Wordfence, Patchstack, WPScan) on every finding |
| api.wordpress.org | which WordPress releases are insecure | public WordPress.org API |
| RDAP (via rdap.org, the IANA bootstrap) | registration dates and registrar | public registry data |
| Ubuntu / Debian security trackers | back-ported fixes in distribution packages | public advisories |

We deliberately don't use anything that forbids commercial use, such as Spamhaus's public mirrors, which require a paid Data Query Service. The commands use standard open-source tools: `dig` (BIND, MPL-2.0), `curl` (curl licence, MIT-style), `openssl` (Apache-2.0), `nc` (BSD) and `jq` (MIT).

**This document and the recipes in the API are yours to use.** You can copy, adapt and run them for any purpose, commercial included, under [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/). Credit "DomainGuard (nhmohio.com)".

**What you send us.** Verdicts and reports are about DomainGuard's own output. We use them to correct your results and to improve the scanner for every customer, as the [Terms of Service](https://nhmohio.com/terms-of-service) describe. We never publish your domains or evidence.