echelongraph-mcp 1.0.3 → 2.0.0

package/dist/index.js

@@ -11,30 +11,48 @@
 //   - success: content[0] is the API's JSON verbatim; content[1] is a one-line note saying
 //     the call succeeded, where, and what it found — in words, including when it found
 //     nothing ("we looked and found nothing" is a measurement). One exception: exposure_radar
-//     regroups the shadow-AI answer by what each number counts (readShadowAI, #2307).
+//     relays each radar's answer cut to the fields it can label by what they count, and names
+//     what it left out (readKEVExposure, readExposedDatabases, readLeakedCredentials and
+//     readShadowAI; #2307, #2313).
 //   - failure (isError: true): the lookup did not complete — unreachable host, non-2xx,
 //     timeout, or a 2xx whose body is not a JSON object — named by tool, cause and base URL.
 //     Never a success with null fields: a model handed one of those tells its user "no
 //     exposure found", and an outage becomes an all-clear.
+//
+// Structured results (#2311, #2313). Every result, success or failure, also carries
+// structuredContent: one envelope that says how the answer was measured — state (measured,
+// not_assessed, failed, invalid_input), measured_at, method, coverage, freshness and notes —
+// with, on a success, `data` equal to what content[0] carries, and on a failure an `error`.
+// Each tool advertises the envelope as its outputSchema. The text blocks above are unchanged
+// from 1.x, so a client that reads only `content` sees what it always saw.
+//
+// Protocol eras (#2311). serveStdio answers both: a 2026-07-28 client's server/discover and
+// per-request `_meta` envelope, and a 2025-era client's `initialize` handshake. The first
+// message of a connection picks the era; the same factory builds the server for either.
 import { readFileSync } from "node:fs";
-import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
-import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
-import { z } from "zod";
-// The release actually running, read from the package.json that ships beside dist/. The MCP
-// handshake and the User-Agent both carry it, so the API's access log can count adoption per
-// version without a code change per release.
-const VERSION = (() => {
+import { McpServer } from "@modelcontextprotocol/server";
+import { serveStdio } from "@modelcontextprotocol/server/stdio";
+import * as z from "zod";
+// The package actually running, read from the package.json that ships beside dist/. The MCP
+// handshake (serverInfo) and the User-Agent both carry its name and version, so the API's
+// access log can count adoption per version without a code change per release.
+const PKG = (() => {
     try {
         const pkg = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8"));
-        const v = pkg?.version;
-        return typeof v === "string" && v ? v : "unknown";
+        return pkg !== null && typeof pkg === "object" && !Array.isArray(pkg) ? pkg : {};
     }
     catch {
-        return "unknown";
+        return {};
     }
 })();
+const pkgField = (k, fallback) => {
+    const v = PKG[k];
+    return typeof v === "string" && v ? v : fallback;
+};
+const NAME = pkgField("name", "echelongraph-mcp");
+const VERSION = pkgField("version", "unknown");
 const BASE = (process.env.ECHELONGRAPH_API_BASE || "https://app.echelongraph.io").replace(/\/+$/, "");
-const UA = `echelongraph-mcp/${VERSION} (+https://echelongraph.io/pulse/mcp)`;
+const UA = `${NAME}/${VERSION} (+https://echelongraph.io/pulse/mcp)`;
 const DEFAULT_TIMEOUT_MS = 15_000;
 const TIMEOUT_MS = (() => {
     const n = Number(process.env.ECHELONGRAPH_API_TIMEOUT_MS);
@@ -146,6 +164,15 @@ async function api(path) {
     }
 }
 const text = (t) => ({ type: "text", text: t });
+// A note, one sentence per entry. Sentences end in ".", "!" or "?" before whitespace, so a URL,
+// a version or a field path (observed.total, crt.sh) does not split one.
+const sentences = (t) => t
+    .replace(/\s+/g, " ")
+    .trim()
+    .split(/(?<=[.!?])\s+/)
+    .filter(Boolean);
+// A timestamp worth relaying as one: see realInstant below.
+const instantOrNull = (s) => (realInstant(s) ? s : null);
 // One sentence per failure kind: where we looked, for what, and what came back.
 function describeFailure(f) {
     const where = `from ${SHOWN_BASE} for GET ${f.path}`;
@@ -171,26 +198,61 @@ const NO_RECORD = "The API returned no record for this request; the quoted messa
 // It is tagged invalid_input, the same state a request this server refuses locally carries.
 const INVALID_INPUT = "(state: invalid_input)";
 const REJECTED_INPUT = "The API rejected the request as invalid input, so nothing was looked up: this is not a finding. Do not report it as zero, none found, or unexposed; correct the input and retry.";
+// A failure result: the #1874 text, and an envelope saying nothing was measured. The error
+// quotes only what describeFailure already quotes (a redacted cause, the API's own message).
+const failure = (state, message, error, coverage = null) => ({
+    content: [text(message)],
+    structuredContent: { state, measured_at: null, method: null, coverage, freshness: null, notes: sentences(message), error },
+    isError: true,
+});
+const errorOf = (f) => ({ kind: f.kind, path: f.path, status: f.status ?? null, message: f.detail });
 const failed = (tool, f) => {
     if (f.kind === "http" && f.status === 400) {
-        return { content: [text(`${tool} FAILED ${INVALID_INPUT}: ${describeFailure(f)} ${REJECTED_INPUT}`)], isError: true };
+        return failure("invalid_input", `${tool} FAILED ${INVALID_INPUT}: ${describeFailure(f)} ${REJECTED_INPUT}`, errorOf(f));
     }
-    return {
-        content: [text(`${tool} FAILED: ${describeFailure(f)} ${f.kind === "http" && f.status === 404 ? NO_RECORD : NOT_A_FINDING}`)],
-        isError: true,
-    };
+    return failure("failed", `${tool} FAILED: ${describeFailure(f)} ${f.kind === "http" && f.status === 404 ? NO_RECORD : NOT_A_FINDING}`, errorOf(f));
 };
-const badInput = (tool, why) => ({
-    content: [text(`${tool} FAILED ${INVALID_INPUT}: ${why}. Nothing was looked up, so this is not a finding.`)],
-    isError: true,
+const badInput = (tool, why) => failure("invalid_input", `${tool} FAILED ${INVALID_INPUT}: ${why}. Nothing was looked up, so this is not a finding.`, {
+    kind: "invalid_input",
+    path: null,
+    status: null,
+    message: why,
 });
 // A bug in this server is still not a finding — it must never surface as an empty success.
-const crashed = (tool, e) => ({
-    content: [text(`${tool} FAILED inside the MCP server while querying ${SHOWN_BASE}: ${describeError(e)}. ${NOT_A_FINDING}`)],
-    isError: true,
+const crashed = (tool, e) => failure("failed", `${tool} FAILED inside the MCP server while querying ${SHOWN_BASE}: ${describeError(e)}. ${NOT_A_FINDING}`, {
+    kind: "internal",
+    path: null,
+    status: null,
+    message: describeError(e),
 });
-const succeeded = (data, note) => ({
+// A 2xx whose fields do not match the tool's outputSchema (a field of a type the schema does
+// not allow) cannot be relayed as structuredContent: a client validates it against the schema
+// and rejects it. So it is a failure, worded as one, rather than the SDK's bare validation error.
+function unexpectedShape(tool, error) {
+    const issues = error.issues
+        .slice(0, 3)
+        .map((i) => `${i.path.map(String).join(".") || "(root)"}: ${i.message}`)
+        .join("; ");
+    const detail = `the answer did not match this tool's output schema (${issues})`;
+    return failure("failed", `${tool} FAILED: EchelonGraph at ${SHOWN_BASE} answered, but ${detail}, so it is not relayed. ${NOT_A_FINDING}`, {
+        kind: "unexpected_shape",
+        path: null,
+        status: null,
+        message: detail,
+    });
+}
+// Every success is checked against the tool's own outputSchema before it is returned.
+const checked = (tool, schema, r) => {
+    if (r.isError)
+        return r;
+    const p = schema.safeParse(r.structuredContent);
+    return p.success ? r : unexpectedShape(tool, p.error);
+};
+// A success: content[0] is the data, content[1] the note; the envelope carries both, the note
+// as sentences after any the envelope adds about itself.
+const succeeded = (data, note, env) => ({
     content: [text(JSON.stringify(data, null, 2)), text(note)],
+    structuredContent: { ...env, notes: [...(env.notes ?? []), ...sentences(note)], data },
 });
 const okHead = (tool, status) => `${tool} OK: EchelonGraph answered${status === undefined ? "" : ` HTTP ${status}`} from ${SHOWN_BASE}.`;
 // Tolerant readers for the note: a missing or renamed field degrades the sentence, never
@@ -216,36 +278,54 @@ const boolAt = (o, ...keys) => {
 // (0001-01-01T00:00:00Z) where it had no instant to give; that is not a time, so it is never
 // presented as one.
 const realInstant = (s) => s !== undefined && Date.parse(s) > 0;
-const server = new McpServer({ name: "echelongraph-cve", version: VERSION });
-server.tool("cve_summary", "Summary of EchelonGraph's CVE Pulse feed: total active CVEs and counts by severity (critical/high/medium/low/none), plus when the feed was last updated. The feed is polled from its sources on a schedule, so this is the state as of that update.", {}, async () => {
+// ── The CVE feed tools: cve_summary, search_cves, get_cve ──
+//
+// Their numbers are CVE records and scores, not exposure counts, so a success is measured.
+// measured_at is the time the answer itself gives for its records, where it gives one:
+// summary.last_updated (MAX(modified) over the active records, core-backend cve/store.go
+// Summary) for cve_summary, the record's updated_at (when EchelonGraph last wrote it) for
+// get_cve, and none for a search page, whose rows each carry their own. None of them serves a
+// fleet-wide time at which the feed's pollers last completed, so freshness is null: the
+// summary's poller.last_poll_at is the answering instance's own NVD poller (cve/poller.go
+// Stats, in memory), and is relayed in data but not presented as the feed's freshness.
+const CVE_FEED_METHOD = "EchelonGraph's CVE Pulse feed: CVE records compiled from NVD, MITRE-CNA pre-NVD records, CISA-KEV, EPSS and GitHub GHSA, each polled from its source on a schedule.";
+const NO_FEED_FRESHNESS = "freshness is null: the CVE feed's answer carries no time at which its pollers last completed a poll for the feed as a whole.";
+async function cveSummary() {
     const tool = "cve_summary";
     try {
         const r = await api("/api/v1/public/cves/summary");
         if (!r.ok)
             return failed(tool, r);
         const head = okHead(tool, r.status);
+        const updated = strAt(r.data, "summary", "last_updated");
+        const env = {
+            state: "measured",
+            measured_at: instantOrNull(updated),
+            method: CVE_FEED_METHOD,
+            coverage: null,
+            freshness: null,
+            notes: [
+                realInstant(updated)
+                    ? "measured_at is summary.last_updated: the newest modification time among the active CVE records these counts include."
+                    : "measured_at is null: the answer carries no real summary.last_updated.",
+                NO_FEED_FRESHNESS,
+            ],
+        };
         const total = numAt(r.data, "summary", "total");
         if (total === undefined)
-            return succeeded(r.data, head);
+            return succeeded(r.data, head, env);
         if (total === 0) {
-            return succeeded(r.data, `${head} The feed reports 0 active CVEs — a measured empty result (we looked and found nothing), not a lookup failure.`);
+            return succeeded(r.data, `${head} The feed reports 0 active CVEs — a measured empty result (we looked and found nothing), not a lookup failure.`, env);
         }
         // A stamp that is not a real instant stays in the JSON and is not repeated as prose.
-        const updated = strAt(r.data, "summary", "last_updated");
         const stamp = realInstant(updated) ? ` (last updated ${updated})` : "";
-        return succeeded(r.data, `${head} The feed holds ${total} active CVEs${stamp}.`);
+        return succeeded(r.data, `${head} The feed holds ${total} active CVEs${stamp}.`, env);
     }
     catch (e) {
         return crashed(tool, e);
     }
-});
-server.tool("search_cves", "Search/list CVEs from EchelonGraph's CVE feed (NVD + MITRE-CNA pre-NVD + CISA-KEV + EPSS + GitHub GHSA, each polled on a schedule). Filter by severity, minimum CVSS, free text, and sort. Returns CVEs with the EchelonGraph multi-source score, severity, CVSS, EPSS, and KEV status.", {
-    search: z.string().optional().describe("free-text search (product, vendor, or keyword, e.g. 'tomcat')"),
-    severity: z.enum(["CRITICAL", "HIGH", "MEDIUM", "LOW"]).optional().describe("filter to one severity"),
-    min_cvss: z.number().min(0).max(10).optional().describe("minimum CVSS score"),
-    sort: z.enum(["published", "modified", "nvd", "echelongraph", "epss"]).optional().describe("sort order (default: published)"),
-    limit: z.number().int().min(1).max(50).optional().describe("page size (default 20, max 50)"),
-}, async (a) => {
+}
+async function searchCVEs(a) {
     const tool = "search_cves";
     try {
         const q = new URLSearchParams();
@@ -263,19 +343,53 @@ server.tool("search_cves", "Search/list CVEs from EchelonGraph's CVE feed (NVD +
             return failed(tool, r);
         const head = okHead(tool, r.status);
         const shown = lenAt(r.data, "cves");
+        const counted = boolAt(r.data, "total_counted");
+        const floor = boolAt(r.data, "total_is_lower_bound");
+        const relaxed = boolAt(r.data, "search_relaxed");
+        const offset = numAt(r.data, "offset");
+        const env = {
+            state: "measured",
+            measured_at: null,
+            method: CVE_FEED_METHOD,
+            coverage: {
+                total: numAt(r.data, "total") ?? null,
+                total_counted: counted ?? null,
+                total_is_lower_bound: floor ?? null,
+                search_relaxed: relaxed ?? null,
+                returned: shown ?? null,
+                limit: numAt(r.data, "limit") ?? null,
+                offset: offset ?? null,
+            },
+            freshness: null,
+            notes: [
+                "measured_at is null: a page of search results has no single observation time; each CVE record in data.cves carries its own times where the API sends them.",
+                NO_FEED_FRESHNESS,
+            ],
+        };
+        const relaxedNote = relaxed === true
+            ? " The API relaxed the search phrase to all of its words (search_relaxed is true), so these rows are a superset of the rows that match the phrase itself."
+            : "";
+        // A total the API did not count is not a count: the page's own rows are all that is known.
+        if (counted === false) {
+            const empty = shown === 0 && (offset ?? 0) === 0;
+            return succeeded(r.data, empty
+                ? `${head} The query returned 0 CVEs — a measured empty result: EchelonGraph was queried successfully and nothing matched these filters (we looked and found nothing). This is not a lookup failure.${relaxedNote}`
+                : `${head} The API did not count the matches (total_counted is false), so its total is not a count${shown === undefined ? "" : `; ${shown} returned in this page`}.${relaxedNote}`, env);
+        }
         const total = numAt(r.data, "total") ?? shown;
         if (total === undefined)
-            return succeeded(r.data, head);
-        if (total === 0) {
-            return succeeded(r.data, `${head} The query matched 0 CVEs — a measured empty result: EchelonGraph was queried successfully and nothing matched these filters (we looked and found nothing). This is not a lookup failure.`);
+            return succeeded(r.data, `${head}${relaxedNote}`, env);
+        if (total === 0 && floor !== true) {
+            return succeeded(r.data, `${head} The query matched 0 CVEs — a measured empty result: EchelonGraph was queried successfully and nothing matched these filters (we looked and found nothing). This is not a lookup failure.${relaxedNote}`, env);
         }
-        return succeeded(r.data, `${head} The query matched ${total} CVEs${shown === undefined ? "" : `; ${shown} returned in this page`}.`);
+        const matched = floor === true ? `at least ${total} CVEs (total_is_lower_bound is true: the count stopped at that floor)` : `${total} CVEs`;
+        return succeeded(r.data, `${head} The query matched ${matched}${shown === undefined ? "" : `; ${shown} returned in this page`}.${relaxedNote}`, env);
     }
     catch (e) {
         return crashed(tool, e);
     }
-});
-server.tool("get_cve", "Full detail for one CVE: description, NVD CVSS v3/v4, the EchelonGraph multi-source score + confidence, EPSS, CISA-KEV status (including ransomware-campaign use), GitHub GHSA, CWE, and references. Pass a CVE ID like CVE-2023-44487.", { cve_id: z.string().describe("a CVE ID, e.g. CVE-2023-44487") }, async ({ cve_id }) => {
+}
+async function getCVE(cve_id) {
     const tool = "get_cve";
     const id = cve_id.trim();
     if (!id)
@@ -284,12 +398,25 @@ server.tool("get_cve", "Full detail for one CVE: description, NVD CVSS v3/v4, th
         const r = await api(`/api/v1/public/cves/${encodeURIComponent(id)}`);
         if (!r.ok)
             return failed(tool, r);
-        return succeeded(r.data, `${okHead(tool, r.status)} Returned the record for ${strAt(r.data, "cve_id") ?? id}.`);
+        const written = strAt(r.data, "updated_at");
+        return succeeded(r.data, `${okHead(tool, r.status)} Returned the record for ${strAt(r.data, "cve_id") ?? id}.`, {
+            state: "measured",
+            measured_at: instantOrNull(written),
+            method: CVE_FEED_METHOD,
+            coverage: null,
+            freshness: null,
+            notes: [
+                realInstant(written)
+                    ? "measured_at is the record's updated_at: when EchelonGraph last wrote this record."
+                    : "measured_at is null: the record carries no real updated_at.",
+                NO_FEED_FRESHNESS,
+            ],
+        });
     }
     catch (e) {
         return crashed(tool, e);
     }
-});
+}
 // cve_exposure. What the API's footprint means, and what it does not (#2306, #2307).
 //
 // The counts come from the KEV-exposure radar, which does not look at every CVE: every 12 h,
@@ -315,6 +442,7 @@ const SHODAN_ATTRIBUTION = "Exposure counts are derived from Shodan data.";
 // and copyright in the applicable Shodan materials" (#2306). The attribution above does the
 // first; this sentence, placed beside it wherever Shodan data is named, does the second.
 const SHODAN_OWNERSHIP = "Shodan data is owned by Shodan, which holds its copyright (© Shodan).";
+const CVE_EXPOSURE_DESCRIPTION = `Internet-exposure footprint for one CVE from EchelonGraph's KEV-exposure radar: how many internet-facing services (distinct ip:port, returned as exposed_hosts; a machine answering on two ports counts twice) the radar has on record running a version its CVE matcher maps to this CVE, with a country/product breakdown and a ransomware flag. Aggregate and host-redacted; free and keyless. Method: exposure counts are derived from Shodan data. ${SHODAN_OWNERSHIP} Every 12 h, when Shodan query credits allow, the radar runs one Shodan query per tracked product, reads up to 100 ip:port services per query, and keeps a service when its banner version matches a CISA-KEV or high-EPSS CVE; a service not seen on its port for 21 days is dropped. last_seen is when a service was last seen listening on its port, not when its vulnerable version was last confirmed: between searches a re-check that finds the port still listed refreshes it without re-reading the banner, so a patched service can stay counted while its port stays open. A count is therefore a banner-version inference over a sample, not an exploit test and not an internet-wide census. The radar only looks for its tracked set of CVEs: for a CVE outside that set the result says NOT ASSESSED, and its 0 is not a measurement.`;
 function exposureNote(head, id, d) {
     const cve = strAt(d, "cve_id") ?? id;
     const hosts = numAt(d, "exposed_hosts");
@@ -357,7 +485,53 @@ function exposureNote(head, id, d) {
         : "";
     return `${head} (state: exposed) The radar has ${hosts} internet-facing services (distinct ip:port, the exposed_hosts field) on record whose banner version maps to ${cve}${countries === undefined ? "" : ` across ${countries} countries`}.${seen} ${kev} ${how}`;
 }
-server.tool("cve_exposure", `Internet-exposure footprint for one CVE from EchelonGraph's KEV-exposure radar: how many internet-facing services (distinct ip:port, returned as exposed_hosts; a machine answering on two ports counts twice) the radar has on record running a version its CVE matcher maps to this CVE, with a country/product breakdown and a ransomware flag. Aggregate and host-redacted; free and keyless. Method: exposure counts are derived from Shodan data. ${SHODAN_OWNERSHIP} Every 12 h, when Shodan query credits allow, the radar runs one Shodan query per tracked product, reads up to 100 ip:port services per query, and keeps a service when its banner version matches a CISA-KEV or high-EPSS CVE; a service not seen on its port for 21 days is dropped. last_seen is when a service was last seen listening on its port, not when its vulnerable version was last confirmed: between searches a re-check that finds the port still listed refreshes it without re-reading the banner, so a patched service can stay counted while its port stays open. A count is therefore a banner-version inference over a sample, not an exploit test and not an internet-wide census. The radar only looks for its tracked set of CVEs: for a CVE outside that set the result says NOT ASSESSED, and its 0 is not a measurement.`, { cve_id: z.string().describe("a CVE ID, e.g. CVE-2023-44487") }, async ({ cve_id }) => {
+function cveExposureState(d) {
+    const hosts = numAt(d, "exposed_hosts");
+    const tracked = boolAt(d, "tracked");
+    if (hosts === undefined)
+        return null;
+    if (tracked === false)
+        return "not_assessed";
+    if (hosts === 0)
+        return tracked === true ? "measured_zero" : "tracking_unknown";
+    return "exposed";
+}
+// The envelope of a cve_exposure answer. Only a count of services on record that the API dates
+// (last_seen, when one of them was last seen listening on its port) is measured; every other
+// answer is not_assessed, and its notes say why. A tracked zero is not_assessed too: it has no
+// observation to date it, and the per-CVE answer does not carry the time of the radar's last
+// completed check (exposure_radar relays that as kev_exposure.last_run_at).
+function cveExposureEnvelope(cve, d) {
+    const exposureState = cveExposureState(d);
+    const last = strAt(d, "last_seen");
+    const measured = exposureState === "exposed" && realInstant(last);
+    const tracked = boolAt(d, "tracked");
+    const why = {
+        exposed: measured
+            ? `state is measured: exposed_hosts counts the services the radar has on record for ${cve}, and measured_at is their latest last_seen, when one of them was last seen listening on its port (not when its vulnerable version was last confirmed).`
+            : `state is not_assessed: the answer gives no real last_seen for the services it counts for ${cve}, so that count is not presented as a dated measurement.`,
+        measured_zero: `state is not_assessed: the API marks ${cve} as tracked with 0 services on record, but a zero has no observation to date it and the answer does not say when the radar last looked, so it is not presented as a dated measurement.`,
+        not_assessed: `state is not_assessed: ${cve} is outside the radar's tracked set, so no number in data is a measurement of its exposure.`,
+        tracking_unknown: `state is not_assessed: the API does not say whether ${cve} is in the radar's tracked set, so its 0 is not a measurement.`,
+        none: `state is not_assessed: the answer carries no exposed_hosts count for ${cve}.`,
+    };
+    return {
+        state: measured ? "measured" : "not_assessed",
+        measured_at: measured ? last : null,
+        method: (strAt(d, "method") ?? EXPOSURE_METHOD).replace(/\s+$/, ""),
+        coverage: { in_scope: tracked ?? null },
+        freshness: null,
+        exposure_state: exposureState,
+        notes: [
+            why[exposureState ?? "none"],
+            tracked === undefined
+                ? "coverage.in_scope is null: the answer does not say whether the CVE is in the radar's tracked set."
+                : `coverage.in_scope is the API's tracked verdict: ${tracked ? "the CVE is in the radar's tracked set" : "the CVE is outside the radar's tracked set"}.`,
+            "freshness is null: the per-CVE answer does not carry the time of the radar's last completed check.",
+        ],
+    };
+}
+async function cveExposure(cve_id) {
     const tool = "cve_exposure";
     const id = cve_id.trim();
     if (!id)
@@ -373,12 +547,12 @@ server.tool("cve_exposure", `Internet-exposure footprint for one CVE from Echelo
         const r = await api(`/api/v1/public/kev-exposure/cve/${encodeURIComponent(cve)}`);
         if (!r.ok)
             return failed(tool, r);
-        return succeeded(r.data, exposureNote(okHead(tool, r.status), cve, r.data));
+        return succeeded(r.data, exposureNote(okHead(tool, r.status), cve, r.data), cveExposureEnvelope(strAt(r.data, "cve_id") ?? cve, r.data));
     }
     catch (e) {
         return crashed(tool, e);
     }
-});
+}
 // Every quadrant that finds its services through Shodan, attributed. The exposed-database
 // radar searches Shodan dorks and falls back to LeakIX when the Shodan query budget is low
 // (core-backend/internal/exposeddb/poller.go).
@@ -455,20 +629,355 @@ function countMap(v) {
     const entries = Object.entries(v);
     return entries.every(([, n]) => isCount(n)) ? Object.fromEntries(entries) : undefined;
 }
-// A ranking or a daily series, each row cut down to its label and its count, so a field the
-// backend adds to a row later is left out rather than relayed unlabelled. All rows or none.
-function countRows(v, label) {
+const isKind = (v, k) => (k === "number" ? isCount(v) : typeof v === k);
+// A ranking, a series or a list, each row cut down to the fields its spec names, so a field the
+// backend adds to a row later is left out rather than relayed unlabelled; extra lists those
+// fields so the note can name them. All rows or none: a row that is not an object, lacks a
+// required field, or carries a known field of the wrong type leaves the whole list out, since
+// a partial list reads as a complete one. An optional field may be absent (Go's omitempty).
+function readRows(v, spec) {
     if (!Array.isArray(v))
-        return undefined;
+        return { extra: [] };
+    const optional = spec.optional ?? {};
     const rows = [];
+    const extra = new Set();
     for (const r of v) {
-        const name = field(r, label);
-        const count = field(r, "count");
-        if (typeof name !== "string" || !isCount(count))
-            return undefined;
-        rows.push({ [label]: name, count });
+        if (!isPlainObject(r))
+            return { extra: [] };
+        const row = {};
+        for (const [k, kind] of Object.entries(spec.required)) {
+            if (!isKind(r[k], kind))
+                return { extra: [] };
+            row[k] = r[k];
+        }
+        for (const [k, kind] of Object.entries(optional)) {
+            if (r[k] === undefined)
+                continue;
+            if (!isKind(r[k], kind))
+                return { extra: [] };
+            row[k] = r[k];
+        }
+        // An own-property test: `in` would also find toString and constructor on the prototype.
+        for (const k of Object.keys(r))
+            if (!Object.prototype.hasOwnProperty.call(spec.required, k) && !Object.prototype.hasOwnProperty.call(optional, k))
+                extra.add(k);
+        rows.push(row);
     }
-    return rows;
+    return { rows, extra: [...extra] };
+}
+// A ranking or a daily series whose rows are a label and a count (the shadow-AI shape).
+const countRows = (v, label) => readRows(v, { required: { [label]: "string", count: "number" } });
+// The note's sentences about what a radar's answer carried that the tool left out.
+function leftOut(radar, unknown, unusable) {
+    const out = [];
+    if (unknown.length)
+        out.push(`Left out of ${radar} because this version of the tool cannot label them: ${unknown.join(", ")}.`);
+    if (unusable.length)
+        out.push(`Left out of ${radar} because they were not in the expected shape: ${unusable.join(", ")}.`);
+    return out;
+}
+function readRadar(body, spec) {
+    const src = isPlainObject(body) ? body : {};
+    const data = {};
+    const unknown = [];
+    const unusable = [];
+    const present = (k) => src[k] !== undefined && src[k] !== null;
+    for (const k of spec.counts) {
+        if (isCount(src[k]))
+            data[k] = src[k];
+        else if (present(k))
+            unusable.push(k);
+    }
+    for (const [k, rowSpec] of Object.entries(spec.rows)) {
+        const r = readRows(src[k], rowSpec);
+        if (r.rows) {
+            data[k] = r.rows;
+            unknown.push(...r.extra.map((x) => `${k}[].${x}`));
+        }
+        else if (present(k))
+            unusable.push(k);
+    }
+    // A timestamp that is not a real instant (the Go zero time) is not relayed as one.
+    for (const k of spec.instants) {
+        const s = strAt(src, k);
+        if (realInstant(s))
+            data[k] = s;
+        else if (present(k) && typeof src[k] !== "string")
+            unusable.push(k);
+    }
+    const known = new Set([...spec.counts, ...Object.keys(spec.rows), ...spec.instants]);
+    unknown.unshift(...Object.keys(src).filter((k) => !known.has(k)));
+    return { data, unknown, unusable };
+}
+// ── last_run_at: when a radar last COMPLETED a check (#2335) ──
+//
+// Since #2335 the kev_exposure, exposed_databases and leaked_credentials stats answers carry
+// last_run_at (core-backend pollerlock/published.go): the radar's completion row in
+// poller_run_state, recorded for the radar as a whole rather than for the instance that
+// answered, UTC, truncated to the second. Each poller writes that row at the END of a cycle,
+// and only when the cycle's reads succeeded (poller.go checkCompleted / recordCheck), so a
+// cycle that read nothing never moves it. What counts as a completed check differs per radar,
+// and LAST_CHECK words each. The API omits the field when no completed check is on record,
+// when its read failed, or when its last good read is more than two minutes old; it never
+// sends the Go zero time.
+//
+// It is a timestamp, not a count, and not the time of the numbers beside it: those count
+// everything still on record, not only what the last check found. Nor is it generated_at,
+// which is only when the API's 60 s stats cache recomputed the totals. An absent stamp (or one
+// that is not a real instant) means the API could not tell, so the note says nothing about it:
+// no "never", no zero.
+const LAST_CHECK = {
+    kev_exposure: "its Shodan search answered at least one query (others may have failed) and its list of services due for a re-check was read; a cycle that skipped the search for want of Shodan query credits, or whose reads failed, does not move it",
+    exposed_databases: "its Shodan search, or the LeakIX fallback, answered at least one query (others may have failed), its list of services due for a re-check was read, and the scan opt-out register could be consulted; a cycle that searched nothing, or whose reads failed, does not move it",
+    leaked_credentials: "it read the public GitHub event stream (fetches of some of the commits it lists may have failed); a cycle whose read of that stream failed does not move it",
+};
+// The note's sentences for one radar's relayed last_run_at, each naming the field so that any
+// one of them quoted alone still says what it is; none when the stamp was not relayed.
+function lastCheck(radar, data) {
+    const at = data.last_run_at;
+    if (typeof at !== "string")
+        return [];
+    return [
+        `${radar} last completed check: ${at} (${radar}.last_run_at, a timestamp, not a count).`,
+        `${radar}.last_run_at is when the radar last finished a cycle whose reads succeeded: ${LAST_CHECK[radar]}.`,
+        `${radar}.last_run_at is not the time of every record the ${radar} numbers count, which cover everything still on record, not only what that check found; nor is it ${radar}.generated_at, when the API computed those numbers.`,
+    ];
+}
+// The first row of a relayed ranking, for the note: "(first: http_server, 9120 services)".
+function firstOf(rows, label, count, unit) {
+    const top = Array.isArray(rows) ? rows[0] : undefined;
+    return top === undefined ? "" : ` (first: ${String(top[label])}, ${String(top[count])} ${unit})`;
+}
+// "a", "a and b", "a, b and c".
+const listed = (xs) => (xs.length < 2 ? xs.join("") : `${xs.slice(0, -1).join(", ")} and ${xs[xs.length - 1]}`);
+const numIn = (d, k) => (isCount(d[k]) ? d[k] : undefined);
+const be = (n) => (n === 1 ? "is" : "are");
+// ── kev_exposure: GET /api/v1/public/kev-exposure/stats (#2313 items 6 and 7) ──
+//
+// core-backend/internal/kevexposure store.go Stats. Every count is over the observation
+// table, one row per (ip:port, CVE) (Upsert keys it obsID(host, cve), the host being
+// "ip:port" from poller.go), filtered to rows whose kev_listed flag the poller copied in at
+// match time:
+//   distinct_hosts    COUNT(DISTINCT host): distinct ip:port services, not machines
+//   kev_cves_exposed  COUNT(DISTINCT cve_id): CVEs with at least one such service
+//   correlations      COUNT(*): service×CVE pairs, so a service with three CVEs counts 3 times
+//   ransomware_cves   COUNT(DISTINCT cve_id) FILTER (WHERE ransomware)
+//   ransomware_hosts  COUNT(DISTINCT host) FILTER (WHERE ransomware): services, not machines
+//   top_products / top_cves / top_countries   COUNT(DISTINCT host) per group, LIMIT 12/12/10;
+//                     a top_cves row's cvss_v3_score and epss_score are MAX() over its rows
+//   trend             COUNT(*) per date_trunc('week', first_seen) over 12 weeks: pairs still on
+//                     record, by the week first recorded (a pruned pair is gone, so earlier
+//                     weeks read low)
+//   newest_kev        the 15 cves rows with kev_listed and the latest kev_added_date, LEFT JOINed
+//                     to COUNT(DISTINCT host) of their KEV-flagged rows, COALESCE(e.h, 0).
+//   last_run_at       the radar's last completed check, KeyKEVExposureCheckCompleted (#2335; see
+//                     LAST_CHECK). Its own row: KeyKEVExposure is the Shodan-credit watermark.
+// So newest_kev[].exposed_hosts is 0 for every CVE the radar holds no row for, whether or not
+// it could ever hold one: the join default, not a measurement. The per-CVE endpoint decides
+// that with `tracked` (store.go trackedVerdict), which is true ONLY when rows exist
+// (exposedHosts > 0) and otherwise false or absent: the backend never reports a measured zero.
+// So a 0 here is never relayed: its row says exposure_state not_assessed and carries no
+// count. If the stats answer ever sends a row's `tracked` (the contract proposed on #2313), it
+// is read the way cve_exposure reads it: false is not assessed whatever the count, and true
+// with 0 is a measured zero in the radar's sample.
+const KEV_SPEC = {
+    counts: ["distinct_hosts", "ransomware_hosts", "kev_cves_exposed", "ransomware_cves", "correlations"],
+    rows: {
+        top_products: { required: { product: "string", hosts: "number" } },
+        top_countries: { required: { country: "string", hosts: "number" } },
+        top_cves: {
+            required: { cve_id: "string", hosts: "number" },
+            optional: { severity: "string", cvss_v3_score: "number", epss_score: "number", ransomware: "boolean" },
+        },
+        trend: { required: { week: "string", new_exposures: "number" } },
+        newest_kev: {
+            required: { cve_id: "string", exposed_hosts: "number" },
+            optional: {
+                added_date: "string",
+                vuln_name: "string",
+                severity: "string",
+                cvss_v3_score: "number",
+                epss_score: "number",
+                ransomware: "boolean",
+                tracked: "boolean",
+            },
+        },
+    },
+    instants: ["generated_at", "last_run_at"],
+};
+// One newest_kev row as relayed: the CVE record's fields, its exposure_state, and a count only
+// when the count is a measurement. `tracked` is read, not relayed: exposure_state says it.
+function newestKEVRow(r) {
+    const hosts = r.exposed_hosts;
+    const tracked = r.tracked;
+    const state = tracked === false ? "not_assessed" : hosts > 0 ? "exposed" : tracked === true ? "measured_zero" : "not_assessed";
+    const row = {};
+    for (const k of ["cve_id", "added_date", "vuln_name", "severity", "cvss_v3_score", "epss_score", "ransomware"]) {
+        if (r[k] !== undefined)
+            row[k] = r[k];
+    }
+    row.exposure_state = state;
+    if (state !== "not_assessed")
+        row.exposed_hosts = hosts;
+    return { row, state, outside: tracked === false };
+}
+function readKEVExposure(body) {
+    const { data, unknown, unusable } = readRadar(body, KEV_SPEC);
+    const sentences = [];
+    const n = (k) => numIn(data, k);
+    const totals = [
+        n("distinct_hosts") !== undefined &&
+            `kev_exposure.distinct_hosts (${n("distinct_hosts")}) counts distinct ip:port services, not machines (a machine answering on two ports counts twice), with at least one CISA-KEV-listed CVE on record`,
+        n("ransomware_hosts") !== undefined &&
+            `kev_exposure.ransomware_hosts (${n("ransomware_hosts")}) counts the services among them with at least one ransomware-linked KEV CVE (one whose KEV entry notes known use in ransomware campaigns)`,
+        n("kev_cves_exposed") !== undefined &&
+            `kev_exposure.kev_cves_exposed (${n("kev_cves_exposed")}) counts distinct CISA-KEV-listed CVEs with at least one service on record`,
+        n("ransomware_cves") !== undefined && `kev_exposure.ransomware_cves (${n("ransomware_cves")}) counts the ransomware-linked CVEs among them`,
+        n("correlations") !== undefined &&
+            `kev_exposure.correlations (${n("correlations")}) counts service×CVE pairs, not services: a service with three KEV CVEs counts three times`,
+    ].filter((p) => typeof p === "string");
+    if (totals.length)
+        sentences.push(`KEV exposure: ${totals.join("; ")}.`);
+    const rankings = [
+        data.top_products !== undefined && `kev_exposure.top_products ranks up to 12 products${firstOf(data.top_products, "product", "hosts", "services")}`,
+        data.top_countries !== undefined && `kev_exposure.top_countries ranks up to 10 countries${firstOf(data.top_countries, "country", "hosts", "services")}`,
+        data.top_cves !== undefined && `kev_exposure.top_cves ranks up to 12 CVEs${firstOf(data.top_cves, "cve_id", "hosts", "services")}`,
+    ].filter((p) => typeof p === "string");
+    if (rankings.length)
+        sentences.push(`${listed(rankings)}, each by distinct ip:port services with a CISA-KEV-listed CVE on record.`);
+    if (data.top_cves !== undefined) {
+        sentences.push("kev_exposure.top_cves[].cvss_v3_score and kev_exposure.top_cves[].epss_score are the highest CVSS v3 base score and EPSS probability (0 to 1) recorded on that CVE's observations: scores, not counts.");
+    }
+    if (data.trend !== undefined) {
+        sentences.push("kev_exposure.trend counts service×CVE pairs, not services, by the week (starting Monday) in which each pair was first recorded, over the last 12 weeks; only pairs still on record are counted, so earlier weeks read low.");
+    }
+    // newest_kev: a 0 is the join's default, never a measurement (see the block comment above).
+    if (Array.isArray(data.newest_kev)) {
+        const read = data.newest_kev.map(newestKEVRow);
+        data.newest_kev = read.map((x) => x.row);
+        const ids = (pred) => read.filter(pred).map((x) => String(x.row.cve_id));
+        const exposed = read.filter((x) => x.state === "exposed");
+        const zero = ids((x) => x.state === "measured_zero");
+        const outside = ids((x) => x.state === "not_assessed" && x.outside);
+        const unsaid = ids((x) => x.state === "not_assessed" && !x.outside);
+        sentences.push(read.length
+            ? `kev_exposure.newest_kev lists the ${read.length} CVEs that EchelonGraph's CVE records most recently mark as CISA-KEV-listed (by added_date), each with an exposure_state.`
+            : "kev_exposure.newest_kev is empty: EchelonGraph's CVE records returned no CISA-KEV-listed CVE with a date added.");
+        if (exposed.length) {
+            sentences.push(`${exposed.length} of them ${be(exposed.length)} exposed (exposure_state exposed): kev_exposure.newest_kev[].exposed_hosts counts distinct ip:port services on record with that CVE (${exposed.map((x) => `${String(x.row.cve_id)}: ${String(x.row.exposed_hosts)}`).join(", ")}).`);
+        }
+        if (zero.length) {
+            sentences.push(`${zero.length} ${be(zero.length)} a measured zero in the radar's sample (exposure_state measured_zero, exposed_hosts 0): the API says the radar tracks them and holds no service for them, though it reads at most the first 100 Shodan results per tracked-product query, so this is not an internet-wide zero: ${zero.join(", ")}.`);
+        }
+        if (outside.length) {
+            sentences.push(`${outside.length} ${be(outside.length)} NOT ASSESSED (exposure_state not_assessed) because the API says they are outside the radar's tracked set, so no count is relayed for them: ${outside.join(", ")}.`);
+        }
+        if (unsaid.length) {
+            sentences.push(`${unsaid.length} ${be(unsaid.length)} NOT ASSESSED (exposure_state not_assessed): ${unsaid.join(", ")}. The API answers 0 for each, and that 0 is not a measurement: it is what the stats answer gives any CVE the radar holds no service for, whether or not the radar looks for that CVE at all, so no count is relayed for them. cve_exposure says per CVE whether it is in the radar's tracked set.`);
+        }
+        sentences.push("kev_exposure.newest_kev[].cvss_v3_score and kev_exposure.newest_kev[].epss_score are the CVE record's CVSS v3 base score and EPSS probability (0 to 1), absent when the record has none: scores, not counts.");
+    }
+    sentences.push(...lastCheck("kev_exposure", data));
+    sentences.push(...leftOut("kev_exposure", unknown, unusable));
+    return { data, sentences };
+}
+// ── exposed_databases: GET /api/v1/public/exposed-databases/stats (#2313 item 7) ──
+//
+// core-backend/internal/exposeddb store.go Stats, over one row per (ip:port, engine)
+// (obsID(host, engine); the host is "ip:port", poller.go obsFrom). A row is stored only after
+// EchelonGraph's own check confirmed the service answering without authentication.
+//   distinct_hosts  COUNT(DISTINCT host): ip:port services, not machines
+//   engines         COUNT(DISTINCT engine): engine types (mongodb, redis, grafana, ...)
+//   pii_likely / pci_likely   COUNT(DISTINCT host) whose data_class names pii / pci AND whose
+//                   schema terms pass the high-confidence gate (2+ distinct indicators, or one
+//                   tier-1 term), mirroring classify.go dataConfidence. The classifier reads
+//                   NAMES only (index / database / table / field names in the banner and the
+//                   check's response, classify.go), never a record, and is precision-first:
+//                   a service whose names miss the gate is not counted, whatever it holds.
+//                   So these are a schema gate, not a census, and the rest are not "no PII".
+//   top_engines / top_countries   COUNT(DISTINCT host) per group, LIMIT 15 / 10.
+//   last_run_at     the radar's last completed check, KeyExposedDBCheckCompleted (#2335; see
+//                   LAST_CHECK). Its own row: KeyExposedDB is claimed at the START of a cycle.
+const EXPOSED_DB_SPEC = {
+    counts: ["distinct_hosts", "engines", "pii_likely", "pci_likely"],
+    rows: {
+        top_engines: { required: { engine: "string", hosts: "number" } },
+        top_countries: { required: { country: "string", hosts: "number" } },
+    },
+    instants: ["generated_at", "last_run_at"],
+};
+function readExposedDatabases(body) {
+    const { data, unknown, unusable } = readRadar(body, EXPOSED_DB_SPEC);
+    const sentences = [];
+    const n = (k) => numIn(data, k);
+    const totals = [
+        n("distinct_hosts") !== undefined &&
+            `exposed_databases.distinct_hosts (${n("distinct_hosts")}) counts distinct ip:port services, not machines (a machine answering on two ports counts twice), that EchelonGraph's check confirmed answering without authentication, data stores and observability UIs alike`,
+        n("engines") !== undefined && `exposed_databases.engines (${n("engines")}) counts the distinct engine types among them`,
+    ].filter((p) => typeof p === "string");
+    if (totals.length)
+        sentences.push(`Exposed data stores: ${totals.join("; ")}.`);
+    const rankings = [
+        data.top_engines !== undefined && `exposed_databases.top_engines ranks up to 15 engines${firstOf(data.top_engines, "engine", "hosts", "services")}`,
+        data.top_countries !== undefined && `exposed_databases.top_countries ranks up to 10 countries${firstOf(data.top_countries, "country", "hosts", "services")}`,
+    ].filter((p) => typeof p === "string");
+    if (rankings.length)
+        sentences.push(`${listed(rankings)}, each by those services.`);
+    const gated = [
+        n("pii_likely") !== undefined && `exposed_databases.pii_likely (${n("pii_likely")}) counts services whose schema names pass a high-confidence gate for personal data`,
+        n("pci_likely") !== undefined && `exposed_databases.pci_likely (${n("pci_likely")}) counts services whose schema names pass a high-confidence gate for payment-card data`,
+    ].filter((p) => typeof p === "string");
+    if (gated.length) {
+        sentences.push(`${gated.join("; ")}. The names are index, database, table or field names in the Shodan or LeakIX banner or in the check's response, never record values, and the gate passes one unambiguous term (such as ssn or cardholder) or two distinct indicators. It is precision-first: a service whose names do not pass it is not counted, whatever it holds, so the other services are not shown to hold no personal or card data.`);
+    }
+    sentences.push(...lastCheck("exposed_databases", data));
+    sentences.push(...leftOut("exposed_databases", unknown, unusable));
+    return { data, sentences };
+}
+// ── leaked_credentials: GET /api/v1/public/leaked-credentials/stats (#2313 item 7) ──
+//
+// core-backend/internal/leakedcreds store.go Stats, over one row per (repository, secret):
+// obsID(repo, fingerprint), "one row per leaked secret per repo".
+//   total             COUNT(*): (repository, secret) pairs, so one secret in three
+//                     repositories counts three times; not distinct secrets
+//   distinct_secrets  COUNT(DISTINCT fingerprint);  distinct_repos  COUNT(DISTINCT repo)
+//   top_providers / top_types   COUNT(*) per group, LIMIT 15: pairs again
+// None is validated: detect.go says "verified" means STRUCTURALLY verified (a checksum or format
+// decode), never "confirmed live", and the radar never uses a credential it finds.
+//   last_run_at       the radar's last completed check, its own KeyLeakedCreds row, written at
+//                     the END of a cycle that read the event stream (#2335; see LAST_CHECK).
+const LEAKED_CREDS_SPEC = {
+    counts: ["total", "distinct_secrets", "distinct_repos"],
+    rows: {
+        top_providers: { required: { provider: "string", count: "number" } },
+        top_types: { required: { secret_type: "string", count: "number" } },
+    },
+    instants: ["generated_at", "last_run_at"],
+};
+function readLeakedCredentials(body) {
+    const { data, unknown, unusable } = readRadar(body, LEAKED_CREDS_SPEC);
+    const sentences = [];
+    const n = (k) => numIn(data, k);
+    const totals = [
+        n("total") !== undefined &&
+            `leaked_credentials.total (${n("total")}) counts (repository, secret) pairs, not distinct secrets: a secret committed to three repositories counts three times`,
+        n("distinct_secrets") !== undefined && `leaked_credentials.distinct_secrets (${n("distinct_secrets")}) counts each secret once`,
+        n("distinct_repos") !== undefined && `leaked_credentials.distinct_repos (${n("distinct_repos")}) counts public GitHub repositories`,
+    ].filter((p) => typeof p === "string");
+    if (totals.length)
+        sentences.push(`Leaked credentials: ${totals.join("; ")}.`);
+    const rankings = [
+        data.top_providers !== undefined && `leaked_credentials.top_providers ranks up to 15 providers${firstOf(data.top_providers, "provider", "count", "pairs")}`,
+        data.top_types !== undefined && `leaked_credentials.top_types ranks up to 15 secret types${firstOf(data.top_types, "secret_type", "count", "pairs")}`,
+    ].filter((p) => typeof p === "string");
+    if (rankings.length)
+        sentences.push(`${listed(rankings)}, each by the same (repository, secret) pairs.`);
+    if (totals.length || rankings.length) {
+        sentences.push("None of these is validated: each is a credential-shaped string in a public commit that passed EchelonGraph's filters, at most structurally checked (a checksum or format decode) and never tested against its provider, so none of them is a count of working credentials.");
+    }
+    sentences.push(...lastCheck("leaked_credentials", data));
+    sentences.push(...leftOut("leaked_credentials", unknown, unusable));
+    return { data, sentences };
 }
 function readShadowAI(sa) {
     const sentences = [];
@@ -502,10 +1011,13 @@ function readShadowAI(sa) {
     if (last24 !== undefined)
         observed.last_24h = last24;
     const rows = {};
+    const rowExtras = [];
     for (const [key, label] of SHADOW_AI_ROWS) {
-        const r = take(key, countRows(field(stats, key), label));
-        if (r)
-            observed[key] = rows[key] = r;
+        const r = countRows(field(stats, key), label);
+        if (take(key, r.rows)) {
+            observed[key] = rows[key] = r.rows;
+            rowExtras.push(...r.extra.map((x) => `stats.${key}[].${x}`));
+        }
     }
     // A timestamp, not a count; one that is not a real instant is dropped (see realInstant).
     const lastObservation = take("last_observation", strAt(stats, "last_observation"));
@@ -521,7 +1033,7 @@ function readShadowAI(sa) {
         authentication.not_determined = authUnknown;
     sentences.push(confirmed.total === undefined
         ? `Shadow AI: the answer carries no usable stats.visible_by_category, so it does not say how many services are confirmed exposed${last24Visible === undefined ? "" : `; confirmed_exposed.last_24h (${last24Visible}) counts confirmed-exposed services first recorded in the last 24 h`}.`
-        : `Shadow AI confirmed exposed: ${confirmed.total} (confirmed_exposed.total, the sum of confirmed_exposed.by_category: services EchelonGraph's probes found answering without an authentication gate, with liveness active or, during a re-check, rechecking)${last24Visible === undefined ? "" : `, ${last24Visible} of them first recorded in the last 24 h (confirmed_exposed.last_24h)`}. Only confirmed_exposed counts exposed services.`);
+        : `Shadow AI confirmed exposed: ${confirmed.total} (confirmed_exposed.total, the sum of confirmed_exposed.by_category: services EchelonGraph's probes found answering without an authentication gate, with liveness active or, during a re-check, rechecking)${last24Visible === undefined ? "" : `, ${last24Visible} of them first recorded in the last 24 h (confirmed_exposed.last_24h)`}. Of the shadow_ai numbers, only confirmed_exposed counts exposed services.`);
     if (total !== undefined) {
         sentences.push(`Shadow AI observed: ${total} (observed.total) counts every Certificate Transparency or Shodan observation on record, whatever its verification state: that many observed, not that many exposed.`);
     }
@@ -557,18 +1069,14 @@ function readShadowAI(sa) {
         ...Object.keys(isPlainObject(stats) ? stats : {})
             .filter((k) => !SHADOW_AI_STATS.has(k))
             .map((k) => `stats.${k}`),
+        ...rowExtras,
     ];
     const unusable = Object.entries(isPlainObject(stats) ? stats : {})
         .filter(([k, v]) => SHADOW_AI_STATS.has(k) && !used.has(k) && v !== null)
         .map(([k]) => `stats.${k}`);
     if (!isPlainObject(stats))
         sentences.push("The answer carries no stats object, so it gives no shadow-AI counts.");
-    if (unknown.length) {
-        sentences.push(`Left out of shadow_ai because this version of the tool cannot label them: ${unknown.join(", ")}.`);
-    }
-    if (unusable.length) {
-        sentences.push(`Left out of shadow_ai because they were not in the expected shape: ${unusable.join(", ")}.`);
-    }
+    sentences.push(...leftOut("shadow_ai", unknown, unusable));
     const data = {};
     if (Object.keys(confirmed).length)
         data.confirmed_exposed = confirmed;
@@ -596,7 +1104,22 @@ function readShadowAI(sa) {
         sentences.push(`Latest shadow-AI observation on record: ${lastObservation}.`);
     return { data, sentences };
 }
-server.tool("exposure_radar", `Aggregate totals from EchelonGraph's internet-exposure radars, each refreshed on its own schedule: shadow AI services found through Certificate Transparency logs and Shodan and then checked by EchelonGraph's identified probes; internet-facing services running actively-exploited (CISA-KEV) CVEs, plus the ransomware-linked subset, derived from Shodan data; unauthenticated data stores and observability UIs, found through Shodan (LeakIX when Shodan query credits run low) and then confirmed by EchelonGraph's own identified check (not a pure read: on Redis it names its client, and on ClickHouse its query is recorded in the server's query log); and leaked credentials sampled from public GitHub push events. The kev_exposure and exposed_databases distinct_hosts figures count distinct ip:port services, so a machine answering on two ports counts twice. The shadow_ai result is regrouped by what each number counts, and carries no number the tool cannot label. shadow_ai.confirmed_exposed counts services EchelonGraph's probes found answering without an authentication gate (liveness active, or rechecking during a re-check): confirmed_exposed.total is the sum of confirmed_exposed.by_category, and confirmed_exposed.last_24h counts those first recorded in the last 24 h. Only confirmed_exposed counts exposed services. shadow_ai.observed counts every Certificate Transparency or Shodan observation on record, whatever its verification state: its numbers are observed, not exposed. They are observed.total; observed.by_category (the same observations by category); observed.last_24h (those first recorded in the last 24 h); observed.trend_30d (observations per UTC day over the last 30 days); and observed.top_products, observed.top_countries and observed.top_issuers (up to ten products, countries and issuers ranked by observations, where an issuer is the certificate's CA for a Certificate Transparency observation and the hosting operator Shodan reports for a Shodan one). shadow_ai.authentication counts observations by probe outcome: authentication.observed where a probe observed an authentication gate (a 401/403, a login page or an auth marker), and authentication.not_determined where the service answered but no probe could tell. Neither authentication count is part of confirmed_exposed, and observed.total minus confirmed_exposed.total is not a count of secured services. The shadow-AI poller block carries only running and last_run_at: last_run_at is when the radar's leader last completed a Certificate Transparency (crt.sh) cycle, and its running is true only when that was within ${SHADOW_AI_SILENT_AFTER} of the answer. ${SHODAN_OWNERSHIP}`, {}, async () => {
+const EXPOSURE_RADAR_DESCRIPTION = `Aggregate totals from EchelonGraph's internet-exposure radars, each refreshed on its own schedule: internet-facing services running actively-exploited (CISA-KEV) CVEs, plus the ransomware-linked subset, derived from Shodan data; unauthenticated data stores and observability UIs, found through Shodan (LeakIX when Shodan query credits run low) and then confirmed by EchelonGraph's own identified check (not a pure read: on Redis it names its client, and on ClickHouse its query is recorded in the server's query log); leaked credentials sampled from public GitHub push events; and shadow AI services found through Certificate Transparency logs and Shodan and then checked by EchelonGraph's identified probes. Every number in the result is labelled here and in the result's note by what it counts; a field this version cannot label is left out and named in the note. ` +
+    `kev_exposure: kev_exposure.distinct_hosts counts distinct ip:port services, not machines (a machine answering on two ports counts twice), with at least one CISA-KEV-listed CVE on record, and kev_exposure.ransomware_hosts those with a ransomware-linked one; kev_exposure.kev_cves_exposed and kev_exposure.ransomware_cves count distinct CVEs with at least one such service; kev_exposure.correlations counts service×CVE pairs, not services, so a service with three KEV CVEs counts three times. kev_exposure.top_products, kev_exposure.top_countries and kev_exposure.top_cves rank up to 12 products, 10 countries and 12 CVEs by those services; kev_exposure.top_cves[].cvss_v3_score and kev_exposure.top_cves[].epss_score are the highest CVSS v3 base score and EPSS probability recorded on that CVE's observations. kev_exposure.trend counts service×CVE pairs still on record by the week in which each was first recorded, over 12 weeks, so earlier weeks read low. kev_exposure.newest_kev lists the 15 CVEs that EchelonGraph's CVE records most recently mark as CISA-KEV-listed, each with an exposure_state: exposed, where kev_exposure.newest_kev[].exposed_hosts counts distinct ip:port services on record with it; or not_assessed, where the API's answer holds no measurement for that CVE (its 0 is not one) and no count is relayed, and cve_exposure says per CVE whether the radar tracks it. kev_exposure.newest_kev[].cvss_v3_score and kev_exposure.newest_kev[].epss_score are the CVE record's CVSS v3 base score and EPSS probability. ` +
+    `exposed_databases: exposed_databases.distinct_hosts counts distinct ip:port services the check confirmed answering without authentication, and exposed_databases.engines the distinct engine types among them; exposed_databases.top_engines and exposed_databases.top_countries rank up to 15 engines and 10 countries by those services. exposed_databases.pii_likely and exposed_databases.pci_likely count services whose schema names (never record values) pass a high-confidence, precision-first gate for personal or payment-card data, so a service outside them is not shown to hold no such data. ` +
+    `leaked_credentials: leaked_credentials.total counts (repository, secret) pairs, not distinct secrets, so one secret in three repositories counts three times; leaked_credentials.distinct_secrets counts each secret once and leaked_credentials.distinct_repos counts repositories; leaked_credentials.top_providers and leaked_credentials.top_types rank up to 15 providers and secret types by those pairs. None is validated: each is a credential-shaped string that passed EchelonGraph's filters, at most structurally checked and never tested against its provider. Each of those three radars also carries generated_at, when the API computed its totals, and, when the API can tell, last_run_at. kev_exposure.last_run_at, exposed_databases.last_run_at and leaked_credentials.last_run_at are timestamps, not counts: each is when that radar last completed a check, a cycle whose reads succeeded, among them a Shodan search (for exposed_databases, or its LeakIX fallback) that answered at least one query, or for leaked_credentials a read of the public GitHub event stream. A cycle that read nothing does not move it, and it is not the time of every record a radar's numbers count, which cover everything still on record, not only what the last check found. A radar whose answer carries no last_run_at has none in the result, and the note says nothing about it. ` +
+    `shadow_ai: the result is regrouped by what each number counts. shadow_ai.confirmed_exposed counts services EchelonGraph's probes found answering without an authentication gate (liveness active, or rechecking during a re-check): confirmed_exposed.total is the sum of confirmed_exposed.by_category, and confirmed_exposed.last_24h counts those first recorded in the last 24 h. Of the shadow_ai numbers, only confirmed_exposed counts exposed services. shadow_ai.observed counts every Certificate Transparency or Shodan observation on record, whatever its verification state: its numbers are observed, not exposed. They are observed.total; observed.by_category (the same observations by category); observed.last_24h (those first recorded in the last 24 h); observed.trend_30d (observations per UTC day over the last 30 days); and observed.top_products, observed.top_countries and observed.top_issuers (up to ten products, countries and issuers ranked by observations, where an issuer is the certificate's CA for a Certificate Transparency observation and the hosting operator Shodan reports for a Shodan one). shadow_ai.authentication counts observations by probe outcome: authentication.observed where a probe observed an authentication gate (a 401/403, a login page or an auth marker), and authentication.not_determined where the service answered but no probe could tell. Neither authentication count is part of confirmed_exposed, and observed.total minus confirmed_exposed.total is not a count of secured services. The shadow-AI poller block carries only running and last_run_at: last_run_at is when the radar's leader last completed a Certificate Transparency (crt.sh) cycle, and its running is true only when that was within ${SHADOW_AI_SILENT_AFTER} of the answer. ${SHODAN_OWNERSHIP}`;
+// exposure_radar's envelope. Every radar answered, but no stats answer says when the services
+// or records it counts were observed: each count covers everything that radar still holds on
+// record, and the answer carries only generated_at (when the API computed the totals) and
+// last_run_at (the radar's last completed check), neither of which is that time (#2335). So
+// the result is not_assessed with measured_at null, and says why; its numbers keep their labels,
+// and freshness carries each radar's last_run_at where the API serves one.
+const RADAR_METHOD = "Aggregate counts over what each radar holds on record: kev_exposure, Shodan banners whose version maps to a CISA-KEV-listed CVE; exposed_databases, services found through Shodan (LeakIX when Shodan query credits run low) and confirmed by EchelonGraph's own identified check; leaked_credentials, credential-shaped strings in public GitHub push events; shadow_ai, services found through Certificate Transparency logs and Shodan and checked by EchelonGraph's identified probes.";
+const RADAR_NAMES = RADARS.map(([name]) => name);
+const RADAR_STATE_NOTE = "state is not_assessed: every radar answered, but no stats answer says when the services or records it counts were observed, so no count here is presented as a dated measurement and measured_at is null. Each count is what that radar holds on record, labelled below by what it counts.";
+const RADAR_FRESHNESS_NOTE = "freshness gives each radar's last completed check where the API serves one (freshness.kev_exposure.last_run_at, freshness.exposed_databases.last_run_at, freshness.leaked_credentials.last_run_at, and freshness.shadow_ai.last_run_at with freshness.shadow_ai.running), and null where it does not.";
+async function exposureRadar() {
     const tool = "exposure_radar";
     try {
         const results = await Promise.all(RADARS.map(([, path]) => api(path)));
@@ -617,20 +1140,310 @@ server.tool("exposure_radar", `Aggregate totals from EchelonGraph's internet-exp
             const withheld = answered.length
                 ? ` The ${answered.length} radar(s) that did answer (${answered.join(", ")}) are withheld: a partial radar picture would be read as the whole one.`
                 : "";
-            return {
-                content: [text(`${tool} FAILED: ${failures.length} of ${RADARS.length} radars could not be read from ${SHOWN_BASE}.\n${lines.join("\n")}\n${NOT_A_FINDING}${withheld}`)],
-                isError: true,
-            };
+            const message = `${tool} FAILED: ${failures.length} of ${RADARS.length} radars could not be read from ${SHOWN_BASE}.\n${lines.join("\n")}\n${NOT_A_FINDING}${withheld}`;
+            const radars = failures.map(([radar, f]) => ({ radar, kind: f.kind, path: f.path, status: f.status ?? null, message: f.detail }));
+            return failure("failed", message, { kind: "radars", path: null, status: null, message: `${failures.length} of ${RADARS.length} radars could not be read`, radars }, { radars: RADAR_NAMES, answered, failed: failures.map(([name]) => name) });
         }
-        const shadow = readShadowAI(data.shadow_ai);
-        data.shadow_ai = shadow.data;
-        return succeeded(data, `${okHead(tool)} All ${RADARS.length} radars answered: ${RADARS.map(([name]) => name).join(", ")}. ${shadow.sentences.join(" ")} ${RADAR_SOURCES} ${SHODAN_OWNERSHIP} Each radar refreshes on its own schedule.`);
+        // Each radar's answer is relayed cut to the fields its reader can label, in RADARS order.
+        const read = {
+            kev_exposure: readKEVExposure(data.kev_exposure),
+            exposed_databases: readExposedDatabases(data.exposed_databases),
+            leaked_credentials: readLeakedCredentials(data.leaked_credentials),
+            shadow_ai: readShadowAI(data.shadow_ai),
+        };
+        const relayed = {};
+        const said = [];
+        for (const [name] of RADARS) {
+            relayed[name] = read[name].data;
+            said.push(...read[name].sentences);
+        }
+        // Only what the readers relayed: a last_run_at that is not a real instant never got there.
+        const stamp = (radar, ...keys) => instantOrNull(strAt(relayed[radar], ...keys));
+        const running = boolAt(relayed.shadow_ai, "poller", "running");
+        return succeeded(relayed, `${okHead(tool)} All ${RADARS.length} radars answered: ${RADARS.map(([name]) => name).join(", ")}. Every number relayed is labelled below by what it counts, and a field this version cannot label is left out and named. ${said.join(" ")} ${RADAR_SOURCES} ${SHODAN_OWNERSHIP} Each radar refreshes on its own schedule.`, {
+            state: "not_assessed",
+            measured_at: null,
+            method: RADAR_METHOD,
+            coverage: { radars: RADAR_NAMES, answered: RADAR_NAMES, failed: [] },
+            freshness: {
+                kev_exposure: { last_run_at: stamp("kev_exposure", "last_run_at") },
+                exposed_databases: { last_run_at: stamp("exposed_databases", "last_run_at") },
+                leaked_credentials: { last_run_at: stamp("leaked_credentials", "last_run_at") },
+                shadow_ai: { last_run_at: stamp("shadow_ai", "poller", "last_run_at"), running: running ?? null },
+            },
+            notes: [RADAR_STATE_NOTE, RADAR_FRESHNESS_NOTE],
+        });
     }
     catch (e) {
         return crashed(tool, e);
     }
+}
+// ── outputSchema: the envelope, per tool (#2311, #2313) ──
+//
+// A discriminated union on state: a success (measured, not_assessed) carries data and a method;
+// a failure (failed, invalid_input) carries error, and measured_at, method and freshness null.
+// The CVE-feed and cve_exposure tools relay the API's JSON verbatim as data, so their data
+// schemas name the fields the tool descriptions mention and admit the rest (a field the API
+// adds later must not turn an answer into a failure). exposure_radar's data is the tool's own
+// cut, so its schema is closed: exactly the fields the readers relay, and nothing else.
+const Instant = z.string().describe("An RFC 3339 instant.");
+const ERROR_KINDS = ["network", "timeout", "http", "not_json", "not_object", "invalid_input", "internal", "unexpected_shape", "radars"];
+const ErrorSchema = z.strictObject({
+    kind: z.enum(ERROR_KINDS).describe("What failed: the request (network, timeout), the answer (http, not_json, not_object, unexpected_shape), the input, or this server."),
+    path: z.string().nullable().describe("The API path requested, when a request was made."),
+    status: z.number().int().nullable().describe("The HTTP status, when the API answered one."),
+    message: z.string().describe("The cause: the API's own message, or what went wrong."),
+});
+const NOTES = z.array(z.string()).describe("Caveats, one sentence each.");
+function envelopeSchema(o) {
+    const coverage = o.coverage ? o.coverage.nullable() : z.null();
+    return z.discriminatedUnion("state", [
+        z.strictObject({
+            state: z.enum(["measured", "not_assessed"]).describe("measured: a measurement of what was asked; an exposure count is measured only with measured_at and method. not_assessed: no dated measurement of what was asked, and no number in it is a finding."),
+            measured_at: Instant.nullable().describe("When the underlying observation was made, as the API states it; null when the answer does not say or holds no observation."),
+            method: z.string().describe("How the numbers were produced."),
+            coverage: coverage.describe("What the answer covers; null where the answer says nothing about it."),
+            freshness: (o.freshness ? o.freshness.nullable() : z.null()).describe("The producing radar's last completed check (last_run_at), where the API serves one."),
+            notes: NOTES,
+            ...(o.extra ?? {}),
+            data: o.data,
+        }),
+        z.strictObject({
+            state: z.enum(["failed", "invalid_input"]).describe("failed: the lookup did not complete. invalid_input: the input was refused, so nothing was looked up. Neither is a finding."),
+            measured_at: z.null(),
+            method: z.null(),
+            coverage,
+            freshness: z.null(),
+            notes: NOTES,
+            error: o.error ?? ErrorSchema,
+        }),
+    ]);
+}
+// A field of the API's JSON: optional, and null where the Go type can marshal null.
+const opt = (t) => t.nullable().optional();
+const CVERecord = z.looseObject({
+    cve_id: opt(z.string()),
+    description: opt(z.string()),
+    severity: opt(z.string()),
+    cvss_v3_score: opt(z.number()),
+    cvss_v4_score: opt(z.number()),
+    cvss_v4_severity: opt(z.string()),
+    echelongraph_score: opt(z.number()),
+    echelongraph_severity: opt(z.string()),
+    score_confidence: opt(z.string()),
+    epss_score: opt(z.number()),
+    epss_percentile: opt(z.number()),
+    kev_listed: opt(z.boolean()),
+    kev_ransomware: opt(z.boolean()),
+    kev_added_date: opt(z.string()),
+    ghsa_id: opt(z.string()),
+    references: z.unknown().optional(),
+    published: opt(z.string()),
+    modified: opt(z.string()),
+    updated_at: opt(z.string()),
+});
+const CVE_SUMMARY_OUTPUT = envelopeSchema({
+    data: z.looseObject({
+        summary: z
+            .looseObject({
+            total: opt(z.number()),
+            critical: opt(z.number()),
+            high: opt(z.number()),
+            medium: opt(z.number()),
+            low: opt(z.number()),
+            none: opt(z.number()),
+            last_updated: opt(z.string()),
+        })
+            .optional(),
+    }),
+    coverage: null,
+    freshness: null,
+});
+const SEARCH_CVES_OUTPUT = envelopeSchema({
+    data: z.looseObject({
+        cves: z.array(CVERecord).optional(),
+        total: opt(z.number()),
+        total_counted: opt(z.boolean()),
+        total_is_lower_bound: opt(z.boolean()),
+        search_relaxed: opt(z.boolean()),
+        limit: opt(z.number()),
+        offset: opt(z.number()),
+    }),
+    coverage: z.strictObject({
+        total: z.number().nullable(),
+        total_counted: z.boolean().nullable(),
+        total_is_lower_bound: z.boolean().nullable(),
+        search_relaxed: z.boolean().nullable(),
+        returned: z.number().nullable(),
+        limit: z.number().nullable(),
+        offset: z.number().nullable(),
+    }),
+    freshness: null,
+});
+const GET_CVE_OUTPUT = envelopeSchema({ data: CVERecord, coverage: null, freshness: null });
+const CountryRows = z.array(z.looseObject({ country: opt(z.string()), hosts: opt(z.number()) }));
+const CVE_EXPOSURE_OUTPUT = envelopeSchema({
+    data: z.looseObject({
+        cve_id: opt(z.string()),
+        exposed_hosts: opt(z.number()),
+        countries: opt(z.number()),
+        tracked: opt(z.boolean()),
+        kev_listed: opt(z.boolean()),
+        kev_catalog_listed: opt(z.boolean()),
+        kev_seen_in_observations: opt(z.boolean()),
+        ransomware: opt(z.boolean()),
+        top_countries: opt(CountryRows),
+        top_products: opt(z.array(z.looseObject({ product: opt(z.string()), hosts: opt(z.number()) }))),
+        last_seen: opt(z.string()),
+        method: opt(z.string()),
+        generated_at: opt(z.string()),
+    }),
+    coverage: z.strictObject({
+        in_scope: z.boolean().nullable().describe("The API's tracked verdict: whether the CVE is in the radar's tracked set; null when the answer does not say."),
+    }),
+    freshness: null,
+    extra: {
+        exposure_state: z
+            .enum(["exposed", "measured_zero", "not_assessed", "tracking_unknown"])
+            .nullable()
+            .describe("What the answer's count is: exposed, a measured zero, not assessed, or tracking unknown; null when it carries no count."),
+    },
 });
-const transport = new StdioServerTransport();
-await server.connect(transport);
+// exposure_radar's data, from the readers' own specs, so the schema cannot drift from them.
+const zKind = (k) => (k === "number" ? z.number() : k === "string" ? z.string() : z.boolean());
+const zRow = (spec) => z.strictObject({
+    ...Object.fromEntries(Object.entries(spec.required).map(([k, kind]) => [k, zKind(kind)])),
+    ...Object.fromEntries(Object.entries(spec.optional ?? {}).map(([k, kind]) => [k, zKind(kind).optional()])),
+});
+const zRadar = (spec, rows = {}) => z.strictObject({
+    ...Object.fromEntries(spec.counts.map((k) => [k, z.number().optional()])),
+    ...Object.fromEntries(Object.entries(spec.rows).map(([k, rs]) => [k, (rows[k] ?? z.array(zRow(rs))).optional()])),
+    ...Object.fromEntries(spec.instants.map((k) => [k, Instant.optional()])),
+});
+// A newest_kev row as newestKEVRow relays it: `tracked` is read, not relayed, and a count only
+// when the row's exposure_state is not not_assessed.
+const { tracked: _read, ...newestKEVOptional } = KEV_SPEC.rows.newest_kev.optional ?? {};
+const NewestKEVRow = z.strictObject({
+    cve_id: z.string(),
+    ...Object.fromEntries(Object.entries(newestKEVOptional).map(([k, kind]) => [k, zKind(kind).optional()])),
+    exposure_state: z.enum(["exposed", "measured_zero", "not_assessed"]),
+    exposed_hosts: z.number().optional(),
+});
+const CountMap = z.record(z.string(), z.number());
+const countRowsOf = (label) => z.array(z.strictObject({ [label]: z.string(), count: z.number() }));
+const ShadowAIData = z.strictObject({
+    confirmed_exposed: z.strictObject({ total: z.number().optional(), by_category: CountMap.optional(), last_24h: z.number().optional() }).optional(),
+    observed: z
+        .strictObject({
+        total: z.number().optional(),
+        by_category: CountMap.optional(),
+        last_24h: z.number().optional(),
+        ...Object.fromEntries(SHADOW_AI_ROWS.map(([key, label]) => [key, countRowsOf(label).optional()])),
+        last_observation: Instant.optional(),
+    })
+        .optional(),
+    authentication: z.strictObject({ observed: z.number().optional(), not_determined: z.number().optional() }).optional(),
+    poller: z.strictObject({ running: z.boolean(), last_run_at: Instant }).optional(),
+});
+const LastRun = z.strictObject({ last_run_at: Instant.nullable() });
+const EXPOSURE_RADAR_OUTPUT = envelopeSchema({
+    data: z.strictObject({
+        kev_exposure: zRadar(KEV_SPEC, { newest_kev: z.array(NewestKEVRow) }),
+        exposed_databases: zRadar(EXPOSED_DB_SPEC),
+        leaked_credentials: zRadar(LEAKED_CREDS_SPEC),
+        shadow_ai: ShadowAIData,
+    }),
+    coverage: z.strictObject({
+        radars: z.array(z.string()).describe("The radars this tool reads."),
+        answered: z.array(z.string()).describe("The radars that answered. On a failure their answers are withheld."),
+        failed: z.array(z.string()).describe("The radars that could not be read."),
+    }),
+    freshness: z.strictObject({
+        kev_exposure: LastRun,
+        exposed_databases: LastRun,
+        leaked_credentials: LastRun,
+        shadow_ai: z.strictObject({ last_run_at: Instant.nullable(), running: z.boolean().nullable() }),
+    }),
+    error: ErrorSchema.extend({
+        radars: z
+            .array(z.strictObject({
+            radar: z.string(),
+            kind: z.enum(["network", "timeout", "http", "not_json", "not_object"]),
+            path: z.string(),
+            status: z.number().int().nullable(),
+            message: z.string(),
+        }))
+            .optional()
+            .describe("Each radar that could not be read, and why."),
+    }),
+});
+// ── Server instructions (#2311) ──
+// No sentence here names a re-probe interval; any that does must say it applies to hosts we do
+// not own (the package's tests hold every shipped text to that).
+const INSTRUCTIONS = [
+    "EchelonGraph's public CVE and internet-exposure data, read-only and keyless.",
+    "Everything these tools return is public: EchelonGraph's CVE Pulse feed, and aggregate, host-redacted totals from its exposure radars.",
+    "Every result's structuredContent says how it was measured: state, measured_at, method, coverage, freshness and notes.",
+    "state is measured, not_assessed, failed or invalid_input.",
+    "not_assessed means the answer holds no dated measurement of what was asked (for example a CVE outside the KEV-exposure radar's tracked set), so a zero in it is not a finding of no exposure.",
+    "failed and invalid_input mean nothing was measured: never report them as zero, none found or unexposed.",
+    "measured_at is when the underlying observation was made, and null when the answer does not say or holds none.",
+    "freshness gives the producing radar's last_run_at: when it last completed a check whose reads succeeded.",
+    "That is not the time of every record the radar's numbers count, which cover everything still on record, and it is null when the API does not say.",
+    "Every figure is as fresh as the schedule that refreshes it.",
+    "Exposure numbers are aggregate: counts of distinct ip:port services on EchelonGraph's record (a machine answering on two ports counts twice), not machines, and not an internet-wide census.",
+    `${SHODAN_ATTRIBUTION} ${SHODAN_OWNERSHIP}`,
+].join(" ");
+const ANNOTATIONS = { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true };
+const CVE_ID_ARG = z.string().describe("a CVE ID, e.g. CVE-2023-44487");
+// What each description says about its structured result, naming only fields its schema holds.
+const FEED_ENVELOPE = "Its structured result carries state (measured), measured_at, method, coverage, freshness (null: the feed serves no poll-completion time) and notes, with data equal to the API's JSON.";
+// One server, built per connection by serveStdio for whichever era the client opens with.
+// tools/list answers in registration order, which is the order below.
+function createServer() {
+    const server = new McpServer({ name: NAME, version: VERSION }, { instructions: INSTRUCTIONS, capabilities: { tools: { listChanged: false } } });
+    server.registerTool("cve_summary", {
+        title: "CVE feed summary",
+        description: `Summary of EchelonGraph's CVE Pulse feed: summary.total active CVEs and their counts by severity (summary.critical, summary.high, summary.medium, summary.low, summary.none), plus summary.last_updated, the newest modification time among those records. The feed is polled from its sources on a schedule, so this is the state as of that update. ${FEED_ENVELOPE}`,
+        outputSchema: CVE_SUMMARY_OUTPUT,
+        annotations: ANNOTATIONS,
+    }, async () => checked("cve_summary", CVE_SUMMARY_OUTPUT, await cveSummary()));
+    server.registerTool("search_cves", {
+        title: "Search CVEs",
+        description: `Search/list CVEs from EchelonGraph's CVE feed (NVD + MITRE-CNA pre-NVD + CISA-KEV + EPSS + GitHub GHSA, each polled on a schedule). Filter by severity, minimum CVSS, free text, and sort. Returns cves, each with cve_id, severity, cvss_v3_score, echelongraph_score, epss_score and kev_listed where the record has them, and the list's total, total_counted (false: the matches were not counted, so total is not a count), total_is_lower_bound (true: at least total), search_relaxed (true: a phrase was relaxed to all of its words), limit and offset. ${FEED_ENVELOPE} coverage repeats total, total_counted, total_is_lower_bound, search_relaxed, limit and offset, and gives returned, the rows in this page.`,
+        inputSchema: z.object({
+            search: z.string().optional().describe("free-text search (product, vendor, or keyword, e.g. 'tomcat')"),
+            severity: z.enum(["CRITICAL", "HIGH", "MEDIUM", "LOW"]).optional().describe("filter to one severity"),
+            min_cvss: z.number().min(0).max(10).optional().describe("minimum CVSS score"),
+            sort: z.enum(["published", "modified", "nvd", "echelongraph", "epss"]).optional().describe("sort order (default: published)"),
+            limit: z.number().int().min(1).max(50).optional().describe("page size (default 20, max 50)"),
+        }),
+        outputSchema: SEARCH_CVES_OUTPUT,
+        annotations: ANNOTATIONS,
+    }, async (a) => checked("search_cves", SEARCH_CVES_OUTPUT, await searchCVEs(a)));
+    server.registerTool("get_cve", {
+        title: "CVE detail",
+        description: `Full record for one CVE: description, severity, cvss_v3_score, cvss_v4_score and cvss_v4_severity (when the record has a CVSS v4 score), echelongraph_score and echelongraph_severity with score_confidence (EchelonGraph's multi-source score), epss_score and epss_percentile, CISA-KEV status (kev_listed, kev_added_date, and kev_ransomware for known ransomware-campaign use), ghsa_id (GitHub GHSA), references, published, modified and updated_at; each field only where the record has it. Pass a CVE ID like CVE-2023-44487. ${FEED_ENVELOPE}`,
+        inputSchema: z.object({ cve_id: CVE_ID_ARG }),
+        outputSchema: GET_CVE_OUTPUT,
+        annotations: ANNOTATIONS,
+    }, async ({ cve_id }) => checked("get_cve", GET_CVE_OUTPUT, await getCVE(cve_id)));
+    server.registerTool("cve_exposure", {
+        title: "Internet exposure for one CVE",
+        description: `${CVE_EXPOSURE_DESCRIPTION} Its structured result's state is measured only for a count of services on record that last_seen dates (measured_at); a tracked zero, a CVE outside the tracked set, or an answer that does not say, is not_assessed. exposure_state is exposed, measured_zero, not_assessed or tracking_unknown; coverage.in_scope is the API's tracked verdict; freshness is null, since the per-CVE answer carries no last completed check; data is the API's JSON.`,
+        inputSchema: z.object({ cve_id: CVE_ID_ARG }),
+        outputSchema: CVE_EXPOSURE_OUTPUT,
+        annotations: ANNOTATIONS,
+    }, async ({ cve_id }) => checked("cve_exposure", CVE_EXPOSURE_OUTPUT, await cveExposure(cve_id)));
+    server.registerTool("exposure_radar", {
+        title: "Exposure radar totals",
+        description: `${EXPOSURE_RADAR_DESCRIPTION} Its structured result's state is not_assessed with measured_at null: every radar answered, but no stats answer says when the services or records it counts were observed, so no count is presented as a dated measurement. freshness gives each radar's last_run_at (and shadow_ai's running) where the API serves one; coverage names the radars that answered; data is the relayed result above.`,
+        outputSchema: EXPOSURE_RADAR_OUTPUT,
+        annotations: ANNOTATIONS,
+    }, async () => checked("exposure_radar", EXPOSURE_RADAR_OUTPUT, await exposureRadar()));
+    return server;
+}
+// Both eras on stdio: a 2026-07-28 client's server/discover, and a 2025-era client's initialize.
+serveStdio(createServer, { legacy: "serve" });
 // MCP uses stdout for the protocol — diagnostics go to stderr.
-console.error(`EchelonGraph CVE MCP server running (API: ${SHOWN_BASE}, timeout ${TIMEOUT_MS} ms)`);
+console.error(`EchelonGraph CVE MCP server ${NAME}@${VERSION} running (API: ${SHOWN_BASE}, timeout ${TIMEOUT_MS} ms)`);