echelongraph-mcp 1.0.0 → 1.0.2

package/README.md

@@ -1,25 +1,89 @@
 # EchelonGraph MCP server
 
-Real-time **CVE & internet-exposure intelligence** for Claude, Cursor, Cline, and any
-[MCP](https://modelcontextprotocol.io) client — straight from
+**CVE and internet-exposure data** for Claude, Cursor, Cline, and any
+[MCP](https://modelcontextprotocol.io) client, straight from
 [EchelonGraph](https://echelongraph.io)'s free public feed.
 
 It exposes EchelonGraph's CVE Pulse (NVD + MITRE-CNA *pre-NVD* + CISA-KEV + EPSS + GitHub
-GHSA, fused into one score) **plus the one thing no other CVE source has: the live
-internet-exposure footprint of a CVE** — how many internet-exposed hosts are running an
-affected version *right now*.
+GHSA, fused into one score) **plus a per-CVE internet-exposure footprint**: how many
+internet-facing services (distinct ip:port) EchelonGraph's KEV-exposure radar has on record
+running a version that maps to the CVE. Exposure counts are derived from Shodan data.
+Shodan data is owned by Shodan, which holds its copyright (© Shodan).
 
-No API key. No auth. Read-only.
+Free and keyless: no API key, no auth, read-only. The server makes no request other than the
+API call a tool needs to answer.
 
 ## Tools
 
 | Tool | What it does |
 |---|---|
-| `cve_summary` | Live counts of active CVEs by severity + feed freshness. |
+| `cve_summary` | Counts of active CVEs by severity, and when the feed was last updated. |
 | `search_cves` | Search/filter CVEs (severity, min CVSS, text, sort) with EchelonGraph scores. |
 | `get_cve` | Full detail for one CVE (CVSS v3/v4, EG score, EPSS, KEV+ransomware, GHSA, CWE, references). |
-| `cve_exposure` | **Unique:** live internet-exposure footprint for a CVE — exposed host count + country/product breakdown. |
-| `exposure_radar` | Live totals across the exposure radars (shadow AI, KEV-exploited hosts, open databases, leaked creds). |
+| `cve_exposure` | Internet-exposure footprint for a CVE: exposed service count (distinct ip:port, the `exposed_hosts` field) + country/product breakdown, from the KEV-exposure radar. |
+| `exposure_radar` | Aggregate totals across the exposure radars: shadow AI; services running CISA-KEV CVEs; 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, which is not a pure read (on Redis it names its client; on ClickHouse its query lands in the server's query log); leaked credentials. |
+
+Every figure is as fresh as the schedule that refreshes it. The CVE feed is polled from its
+sources on a schedule; each radar refreshes on its own.
+
+### How `cve_exposure` counts
+
+Every 12 hours, when Shodan query credits allow, the KEV-exposure 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 (>= 0.5) CVE. A service not seen on its port
+for 21 days is dropped. A count is therefore a banner-version inference over a sample: not an
+exploit test, and not an internet-wide census.
+
+`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 by
+Shodan InternetDB refreshes `last_seen` without re-reading the banner, so a patched service can
+stay counted while its port stays open.
+
+The unit is a service, not a machine. Shodan returns one banner per port and the radar keys
+each observation on ip:port, so a machine answering on two ports counts twice. The API field
+keeps its name, `exposed_hosts`, and so does `distinct_hosts` in the radar totals.
+
+The radar only looks for its **tracked** set of CVEs, so a zero means different things:
+
+| API answer | What the tool says |
+|---|---|
+| `tracked: false` | **NOT ASSESSED**: outside the radar's tracked set; 0 is not a measurement. |
+| `tracked: true`, `exposed_hosts: 0` | A measured zero in the radar's sample: none of the up to 100 services it read per tracked-product query matched. Not an internet-wide zero. |
+| no `tracked` field | The API did not say whether the CVE is in the tracked set: an older API, or the radar cannot decide (for example a CISA-KEV or high-EPSS CVE in a tracked product with 0 services on record). 0 exposed services on record, with no claim either way. |
+| HTTP 400, or an id that is not `CVE-YYYY-NNNN…` | An error result tagged `invalid_input`; nothing was looked up. |
+
+### How `exposure_radar` counts shadow AI
+
+`shadow_ai.stats.total` counts **every** observation, whatever its verification state: that
+many observed, not that many exposed. The confirmed-exposed count is the sum of
+`stats.visible_by_category` (services EchelonGraph's probes found answering without an
+authentication gate), and `last_24h_visible_count` is its last-24-hour slice. The tool's note
+says which is which.
+
+## What a result means
+
+Every tool answers in one of two shapes, so a model reading the result cannot mistake an
+outage for an all-clear:
+
+- **Success** — the first text block is the API's JSON verbatim; the second is a one-line
+  note saying the call succeeded, which base URL answered, and what it found. When the
+  feed genuinely holds nothing for the query the note says so in words ("we looked and
+  found nothing … not a lookup failure"), because a measured zero is a measurement. One
+  exception to verbatim: `exposure_radar` drops the shadow-AI `poller` block when it carries
+  no real completion time. That block's `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 30 minutes of the answer. When `running` is true, the note says the
+  radar's leader last completed a cycle at that time; when it is false, the note says no
+  cycle has completed since that time; when `last_run_at` is absent, the note says the
+  radar's freshness is unknown and the block is left out. An older API answered from
+  whichever server instance served the request, and a follower instance sent
+  `running: false` with the zero time `0001-01-01T00:00:00Z`; that too is unknown freshness,
+  never presented as a stopped radar.
+- **Failure** — an MCP error result (`isError: true`) whenever the lookup did not complete:
+  the host could not be reached, it answered non-2xx, it took longer than the timeout, or
+  it answered 2xx with a body that is not a JSON object. The text names the tool, the
+  cause (status code or error kind), the path, and the base URL, and says it is not a
+  finding. A failure is never rendered as a success with null fields.
 
 ## Install
 
@@ -55,23 +119,35 @@ Add it to your MCP client's config. It runs via `npx` — no global install need
 }
 ```
 
-Restart the client, then ask: *"Is CVE-2023-44487 actively exploited, and how exposed is
-the internet to it?"*
+Restart the client, then ask: *"Is CVE-2023-44487 actively exploited, and how many exposed
+services does EchelonGraph's radar have on record for it?"*
 
 ## Configuration
 
 | Env var | Default | Purpose |
 |---|---|---|
 | `ECHELONGRAPH_API_BASE` | `https://app.echelongraph.io` | Override the API base (self-host / proxy). |
+| `ECHELONGRAPH_API_TIMEOUT_MS` | `15000` | Per-request timeout. A slower answer is reported as a failed lookup, not as empty data. |
 
 ## Develop
 
 ```bash
 npm install
 npm run build      # tsc → dist/
-npm run smoke      # spawn the server + call cve_exposure against the live API
+npm test           # build, then behavioural tests against a stub API (no network needed)
+npm run smoke      # spawn the server + call cve_exposure against the production API
 ```
 
+`npm run smoke` calls the production API with this package's User-Agent, so its requests are
+counted as external MCP adoption. `npm test` never leaves the machine.
+
 ## License
 
-MIT · Data © EchelonGraph, served under the CVE Pulse free-access terms.
+The code is MIT-licensed.
+
+The CVE Pulse compilation (how EchelonGraph combines its CVE sources, and the EchelonGraph
+score) is © EchelonGraph, served under the CVE Pulse free-access terms; the source records it
+compiles stay under their publishers' terms.
+
+Exposure counts are derived from Shodan data. Shodan data is owned by Shodan, which holds its
+copyright (© Shodan). EchelonGraph claims no ownership of it or copyright in it.

package/dist/index.js

@@ -1,51 +1,251 @@
 #!/usr/bin/env node
 // EchelonGraph CVE & internet-exposure MCP server.
-// Exposes EchelonGraph's free public CVE/exposure intelligence as MCP tools so Claude,
-// Cursor, Cline, and any MCP client can query real-time vulnerability data — including the
-// one thing no other CVE source has: the LIVE internet-exposure footprint per CVE.
-// stdio transport; no auth required; read-only.
+// Exposes EchelonGraph's free, keyless public CVE and exposure data as MCP tools for Claude,
+// Cursor, Cline and any MCP client: the CVE feed, and per CVE the internet-exposure footprint
+// that EchelonGraph's KEV-exposure radar derives from Shodan data. Every figure is as fresh as
+// the schedule that refreshes it, and the tool texts say which schedule that is.
+// stdio transport; no auth required; read-only. It makes no request other than the API call a
+// tool needs to answer.
+//
+// Result contract (#1874). A tool answers in exactly one of two shapes, and they never blur:
+//   - 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).
+//   - 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.
+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 = (() => {
+    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";
+    }
+    catch {
+        return "unknown";
+    }
+})();
 const BASE = (process.env.ECHELONGRAPH_API_BASE || "https://app.echelongraph.io").replace(/\/+$/, "");
-const UA = "echelongraph-mcp/1.0 (+https://echelongraph.io/pulse/mcp)";
+const UA = `echelongraph-mcp/${VERSION} (+https://echelongraph.io/pulse/mcp)`;
+const DEFAULT_TIMEOUT_MS = 15_000;
+const TIMEOUT_MS = (() => {
+    const n = Number(process.env.ECHELONGRAPH_API_TIMEOUT_MS);
+    return Number.isFinite(n) && n > 0 ? Math.floor(n) : DEFAULT_TIMEOUT_MS;
+})();
+// The base as quoted in tool results. A proxy credential in the URL's userinfo is dropped.
+const SHOWN_BASE = (() => {
+    try {
+        const u = new URL(BASE);
+        if (!u.username && !u.password)
+            return BASE;
+        return `${u.protocol}//***@${u.host}${u.pathname.replace(/\/+$/, "")}`;
+    }
+    catch {
+        return "the configured ECHELONGRAPH_API_BASE (not a valid URL)";
+    }
+})();
+// Collapse a response body to something quotable: one line, at most 160 characters.
+function snippet(body) {
+    const s = body.replace(/\s+/g, " ").trim();
+    if (!s)
+        return "(empty body)";
+    return s.length > 160 ? `${s.slice(0, 160)}…` : s;
+}
+// A message may echo a URL — undici's refusal of a credentialed URL quotes it whole — so
+// anything shaped scheme://user:pass@host is masked before it can reach a result.
+const redactCredentials = (s) => s.replace(/(\w+:\/\/)[^/\s@]+@/g, "$1***@");
+// The useful part of a fetch error is usually in its cause chain (ECONNREFUSED, ENOTFOUND,
+// "bad port"), so walk it. Messages and codes only — never headers, never a credential.
+function describeError(e) {
+    if (!(e instanceof Error))
+        return String(e);
+    const parts = [e.message];
+    let cause = e.cause;
+    for (let depth = 0; cause instanceof Error && depth < 4; depth++) {
+        const c = cause;
+        const codes = Array.isArray(c.errors)
+            ? c.errors.map((x) => x.code).filter((x) => typeof x === "string")
+            : [];
+        if (codes.length)
+            parts.push(codes.join(", "));
+        else if (typeof c.code === "string")
+            parts.push(c.code);
+        else if (c.message)
+            parts.push(c.message);
+        cause = c.cause;
+    }
+    return redactCredentials(parts.join(": "));
+}
+// The API's error envelope is {"error": "..."}; quote that string when a non-2xx carries it.
+function apiMessage(body) {
+    try {
+        const parsed = JSON.parse(body);
+        const msg = parsed?.error;
+        if (typeof msg === "string" && msg)
+            return msg;
+    }
+    catch {
+        // not JSON — fall through to the raw snippet
+    }
+    return snippet(body);
+}
+// One GET against the API. Never throws: every way the call can fail comes back as a typed
+// Failure so the tool renders it as an error result. A 2xx whose body is not a JSON object
+// (an SPA shell, an edge challenge page, a literal null) is a failure too — it is not data.
 async function api(path) {
     const ctrl = new AbortController();
-    const t = setTimeout(() => ctrl.abort(), 15000);
+    let timedOut = false;
+    const timer = setTimeout(() => {
+        timedOut = true;
+        ctrl.abort();
+    }, TIMEOUT_MS);
+    const timeout = () => ({ ok: false, kind: "timeout", path, detail: `no response within ${TIMEOUT_MS} ms` });
     try {
-        const res = await fetch(`${BASE}${path}`, {
-            headers: { "User-Agent": UA, Accept: "application/json" },
-            signal: ctrl.signal,
-        });
+        let res;
+        try {
+            res = await fetch(`${BASE}${path}`, {
+                headers: { "User-Agent": UA, Accept: "application/json" },
+                signal: ctrl.signal,
+            });
+        }
+        catch (e) {
+            return timedOut ? timeout() : { ok: false, kind: "network", path, detail: describeError(e) };
+        }
+        let body;
+        try {
+            body = await res.text();
+        }
+        catch (e) {
+            return timedOut ? timeout() : { ok: false, kind: "network", path, detail: `reading the body failed: ${describeError(e)}` };
+        }
         if (!res.ok)
-            throw new Error(`EchelonGraph API returned HTTP ${res.status} for ${path}`);
-        return await res.json();
+            return { ok: false, kind: "http", path, status: res.status, detail: apiMessage(body) };
+        let data;
+        try {
+            data = JSON.parse(body);
+        }
+        catch {
+            const ctype = res.headers.get("content-type") ?? "no content-type";
+            return { ok: false, kind: "not_json", path, status: res.status, detail: `${ctype}; body starts: ${snippet(body)}` };
+        }
+        if (data === null || typeof data !== "object") {
+            return { ok: false, kind: "not_object", path, status: res.status, detail: `body was ${snippet(body)}` };
+        }
+        return { ok: true, status: res.status, data };
     }
     finally {
-        clearTimeout(t);
+        clearTimeout(timer);
+    }
+}
+const text = (t) => ({ type: "text", text: t });
+// 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}`;
+    switch (f.kind) {
+        case "network":
+            return `EchelonGraph at ${SHOWN_BASE} could not be reached for GET ${f.path}: ${f.detail}.`;
+        case "timeout":
+            return `EchelonGraph at ${SHOWN_BASE} did not answer GET ${f.path} within ${TIMEOUT_MS} ms.`;
+        case "http":
+            return `EchelonGraph answered HTTP ${f.status} ${where} — the API said: ${f.detail}.`;
+        case "not_json":
+            return `EchelonGraph answered HTTP ${f.status} ${where} but the body was not JSON (${f.detail}).`;
+        case "not_object":
+            return `EchelonGraph answered HTTP ${f.status} ${where} but the body was not a JSON object (${f.detail}).`;
     }
 }
-const ok = (data) => ({ content: [{ type: "text", text: JSON.stringify(data, null, 2) }] });
-const fail = (e) => ({
-    content: [{ type: "text", text: `Error querying EchelonGraph: ${e instanceof Error ? e.message : String(e)}` }],
+// What a model must not conclude from a failure.
+const NOT_A_FINDING = "The lookup did not complete, so this is not a finding: do not report it as zero, none found, absent, or unexposed. Retry later or check ECHELONGRAPH_API_BASE.";
+// A 404 is the one non-2xx that carries an answer of its own — the API's not-found message,
+// quoted in the sentence before it — so it is worded as "no record", not as an outage.
+const NO_RECORD = "The API returned no record for this request; the quoted message is the API's own explanation. This says nothing about internet exposure.";
+// A 400 is the API refusing the input itself, so nothing was looked up and nothing measured.
+// 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.";
+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 {
+        content: [text(`${tool} FAILED: ${describeFailure(f)} ${f.kind === "http" && f.status === 404 ? NO_RECORD : NOT_A_FINDING}`)],
+        isError: true,
+    };
+};
+const badInput = (tool, why) => ({
+    content: [text(`${tool} FAILED ${INVALID_INPUT}: ${why}. Nothing was looked up, so this is not a finding.`)],
     isError: true,
 });
-const server = new McpServer({ name: "echelongraph-cve", version: "1.0.0" });
-server.tool("cve_summary", "Live summary of EchelonGraph's CVE Pulse feed: total active CVEs and counts by severity (critical/high/medium/low/none), plus feed freshness. Use to gauge the current vulnerability landscape.", {}, async () => {
+// 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 succeeded = (data, note) => ({
+    content: [text(JSON.stringify(data, null, 2)), text(note)],
+});
+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
+// the result — content[0] still carries whatever the API sent.
+const field = (o, ...keys) => keys.reduce((v, k) => (v !== null && typeof v === "object" ? v[k] : undefined), o);
+const numAt = (o, ...keys) => {
+    const v = field(o, ...keys);
+    return typeof v === "number" && Number.isFinite(v) ? v : undefined;
+};
+const strAt = (o, ...keys) => {
+    const v = field(o, ...keys);
+    return typeof v === "string" && v ? v : undefined;
+};
+const lenAt = (o, ...keys) => {
+    const v = field(o, ...keys);
+    return Array.isArray(v) ? v.length : undefined;
+};
+const boolAt = (o, ...keys) => {
+    const v = field(o, ...keys);
+    return typeof v === "boolean" ? v : undefined;
+};
+// A timestamp worth repeating as prose. The API has been seen answering the Go zero time
+// (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 () => {
+    const tool = "cve_summary";
     try {
-        return ok(await api("/api/v1/public/cves/summary"));
+        const r = await api("/api/v1/public/cves/summary");
+        if (!r.ok)
+            return failed(tool, r);
+        const head = okHead(tool, r.status);
+        const total = numAt(r.data, "summary", "total");
+        if (total === undefined)
+            return succeeded(r.data, head);
+        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.`);
+        }
+        // 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}.`);
     }
     catch (e) {
-        return fail(e);
+        return crashed(tool, e);
     }
 });
-server.tool("search_cves", "Search/list CVEs from EchelonGraph's real-time feed (NVD + MITRE-CNA pre-NVD + CISA-KEV + EPSS + GitHub GHSA). Filter by severity, minimum CVSS, free text, and sort. Returns CVEs with the EchelonGraph multi-source score, severity, CVSS, EPSS, and KEV status.", {
+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) => {
+    const tool = "search_cves";
     try {
         const q = new URLSearchParams();
         if (a.search)
@@ -57,43 +257,231 @@ server.tool("search_cves", "Search/list CVEs from EchelonGraph's real-time feed
         if (a.sort)
             q.set("sort", a.sort);
         q.set("limit", String(a.limit ?? 20));
-        return ok(await api(`/api/v1/public/cves?${q.toString()}`));
+        const r = await api(`/api/v1/public/cves?${q.toString()}`);
+        if (!r.ok)
+            return failed(tool, r);
+        const head = okHead(tool, r.status);
+        const shown = lenAt(r.data, "cves");
+        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} The query matched ${total} CVEs${shown === undefined ? "" : `; ${shown} returned in this page`}.`);
     }
     catch (e) {
-        return fail(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 }) => {
+    const tool = "get_cve";
+    const id = cve_id.trim();
+    if (!id)
+        return badInput(tool, "cve_id is required");
     try {
-        return ok(await api(`/api/v1/public/cves/${encodeURIComponent(cve_id.trim())}`));
+        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}.`);
     }
     catch (e) {
-        return fail(e);
+        return crashed(tool, e);
     }
 });
-server.tool("cve_exposure", "UNIQUE to EchelonGraph: the LIVE internet-exposure footprint for a CVE — how many internet-exposed hosts our passive radar currently sees running an affected version, with a country/product breakdown and a ransomware flag. Aggregate and host-redacted. No other CVE source has this. Returns exposed_hosts=0 for CVEs the radar doesn't track (it focuses on actively-exploited / high-EPSS CVEs).", { cve_id: z.string().describe("a CVE ID, e.g. CVE-2023-44487") }, async ({ cve_id }) => {
+// 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,
+// when Shodan query credits allow (the poller skips the search below SHODAN_MIN_QUERY_BUDGET),
+// it runs one Shodan query per tracked product and keeps services whose banner version maps
+// to a CISA-KEV or high-EPSS CVE. So a 0 is only a measurement when the CVE is inside that
+// tracked set. The unit is a service, not a machine: the radar keys each observation on
+// ip:port (Shodan returns one banner per port), and exposed_hosts counts distinct ip:port.
+// The API says which with `tracked`; the note reads it and, when the field is absent (an older
+// API, or a CVE the radar cannot decide on), makes no claim either way about the zero.
+//
+// last_seen is not a re-sighting of the vulnerable banner: between searches the radar refreshes
+// it when Shodan InternetDB still lists the service's PORT, without re-reading the version, so
+// a patched service can stay counted while its port stays open. Every text says "last seen
+// listening on its port", never "re-seen" or "most recently seen".
+const CVE_ID = /^CVE-\d{4}-\d{4,}$/i;
+// Quoted when the API does not send its own `method` string.
+const EXPOSURE_METHOD = "Shodan banner match on the radar's tracked products; up to 100 ip:port services per product query; searched every 12 h when Shodan query credits allow";
+const SHODAN_ATTRIBUTION = "Exposure counts are derived from Shodan data.";
+// Shodan's terms (https://static.shodan.io/legal/terms.html, read 2026-09-27) ask for two
+// things: "You must attribute such usage to Shodan", and materials "referencing, including or
+// otherwise based on Shodan information or materials, must clearly indicate Shodan's ownership
+// 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).";
+function exposureNote(head, id, d) {
+    const cve = strAt(d, "cve_id") ?? id;
+    const hosts = numAt(d, "exposed_hosts");
+    const tracked = boolAt(d, "tracked");
+    // The API's own method sentence may end in a full stop; the note supplies one.
+    const how = `Method: ${(strAt(d, "method") ?? EXPOSURE_METHOD).replace(/[.\s]+$/, "")}. ${SHODAN_ATTRIBUTION} ${SHODAN_OWNERSHIP}`;
+    // Before kev_catalog_listed existed, kev_listed was bool_or over the radar's observations:
+    // false for every CVE the radar has no host for, whatever the CISA-KEV catalog says.
+    // kev_catalog_listed is cves.kev_listed, the flag the KEV fetcher sets on EchelonGraph's CVE
+    // record. The fetcher only UPDATEs rows that already exist, and the API answers false when
+    // there is no row, so false cannot be told apart from "no record": it is worded as what
+    // EchelonGraph's data says, never as a fact about the CISA catalog.
+    const catalog = boolAt(d, "kev_catalog_listed");
+    const kev = catalog === undefined
+        ? "Its kev_listed field reflects the radar's own observations, not the CISA-KEV catalog; use get_cve for catalog status."
+        : catalog
+            ? `EchelonGraph's CVE record marks ${cve} as CISA-KEV-listed.`
+            : `EchelonGraph's CVE data does not mark ${cve} as CISA-KEV-listed (kev_catalog_listed is false, which it also is when EchelonGraph holds no record of ${cve}); get_cve shows the record.`;
+    if (hosts === undefined) {
+        return `${head} The answer carries no exposed_hosts count, so it says nothing about exposure to ${cve}. ${how}`;
+    }
+    if (tracked === false) {
+        const why = hosts === 0
+            ? "outside the radar's tracked set; 0 is not a measurement, and it says nothing about whether any host is exposed to it."
+            : `outside the radar's tracked set, so the radar is not looking for it; the ${hosts} service(s) (distinct ip:port) on record are left from earlier scans and are not a current measurement.`;
+        return `${head} (state: not_assessed) NOT ASSESSED: ${cve} is ${why} ${kev} ${how}`;
+    }
+    if (hosts === 0 && tracked === true) {
+        // The backend answers tracked:true only when it holds rows (exposed_hosts > 0), so this
+        // branch does not fire today; it is worded for the day it does.
+        return `${head} (state: measured_zero) The radar has 0 internet-facing services (distinct ip:port) on record whose banner version maps to ${cve}: a measured zero in the radar's sample. ${cve} is in the tracked set, and the radar looked and found nothing. This is not a lookup failure. It is a zero in a sample, not an internet-wide zero: the radar reads at most the first 100 Shodan results per tracked-product query, so a vulnerable service outside those results is not counted. ${kev} ${how}`;
+    }
+    if (hosts === 0) {
+        return `${head} (state: tracking_unknown) EchelonGraph reports 0 exposed services (distinct ip:port) on record for ${cve}. The API does not say whether ${cve} is in the radar's tracked set: it is an API older than that field, or the radar cannot decide for this CVE (for example a CISA-KEV or high-EPSS CVE in a tracked product that it has no service on record for). The radar only looks for a tracked set of CISA-KEV and high-EPSS CVEs in specific products, so this 0 is not evidence either way: it neither shows that nothing is exposed nor that ${cve} went unassessed. This is not a lookup failure. ${kev} ${how}`;
+    }
+    const countries = numAt(d, "countries");
+    const last = strAt(d, "last_seen");
+    const seen = realInstant(last)
+        ? ` Their latest last_seen is ${last}: when one of them was last seen listening on its port, not when its vulnerable version was last confirmed.`
+        : "";
+    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 }) => {
+    const tool = "cve_exposure";
+    const id = cve_id.trim();
+    if (!id)
+        return badInput(tool, "cve_id is required");
+    // Refused here rather than sent: an API older than the id check answers a malformed id
+    // with a 200 and zeros, which would read as an answer about a CVE that does not exist.
+    if (!CVE_ID.test(id)) {
+        return badInput(tool, `cve_id ${JSON.stringify(id.slice(0, 32))} is not a CVE id (expected the form CVE-2023-44487)`);
+    }
+    // The canonical form, which is how the API stores and answers it.
+    const cve = id.toUpperCase();
     try {
-        return ok(await api(`/api/v1/public/kev-exposure/cve/${encodeURIComponent(cve_id.trim())}`));
+        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));
     }
     catch (e) {
-        return fail(e);
+        return crashed(tool, e);
     }
 });
-server.tool("exposure_radar", "Live totals from EchelonGraph's passive internet-exposure radars: exposed AI services, hosts running actively-exploited (CISA-KEV) CVEs (plus ransomware-linked), unauthenticated databases, and leaked credentials. The current state of internet exposure EchelonGraph maps passively.", {}, async () => {
+// 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).
+const RADAR_SOURCES = "KEV-exposure, exposed-database and shadow-AI discovery use Shodan data (shadow AI also uses Certificate Transparency logs; exposed databases fall back to LeakIX when Shodan query credits run low).";
+const RADARS = [
+    ["kev_exposure", "/api/v1/public/kev-exposure/stats"],
+    ["exposed_databases", "/api/v1/public/exposed-databases/stats"],
+    ["leaked_credentials", "/api/v1/public/leaked-credentials/stats"],
+    ["shadow_ai", "/api/v1/public/shadow-ai-radar/stats"],
+];
+// The shadow-AI stats answer, read honestly (#2307).
+//
+// stats.total counts EVERY observation, whatever its verification state (35,473 on
+// 2026-09-26); the confirmed-exposed count is the sum of stats.visible_by_category (1,983
+// that day). Only the second may be called exposed.
+//
+// Its `poller` block's running and last_run_at describe the radar's fleet, not the instance
+// that answered (core-backend shadowctlog Poller.Status): last_run_at is when the fleet's
+// leader last COMPLETED a crt.sh (Certificate Transparency) cycle, and running is true only
+// when that was within pollerSilentAfter, 30 minutes, of the answer. The API sends both or
+// neither, and omits both when it cannot tell; it never sends the Go zero time. An API older
+// than that answered from the serving instance's own memory, so a follower sent running:false
+// and last_run_at 0001-01-01T00:00:00Z, which reads as "the radar is down and has never run".
+// So the note reads three cases: running with a real completion time, stopped since a real
+// completion time, and unknown. Only the first two are relayed; an unknown block (no real
+// completion time and running verdict) is dropped, so no running:false or zero time reaches
+// the model as freshness.
+const SHADOW_AI_SILENT_AFTER = "30 minutes";
+function readShadowAI(sa) {
+    const sentences = [];
+    const byCategory = field(sa, "stats", "visible_by_category");
+    let confirmed;
+    if (byCategory !== null && typeof byCategory === "object" && !Array.isArray(byCategory)) {
+        const counts = Object.values(byCategory);
+        if (counts.every((n) => typeof n === "number" && Number.isFinite(n))) {
+            confirmed = counts.reduce((a, b) => a + b, 0);
+        }
+    }
+    const last24 = numAt(sa, "stats", "last_24h_visible_count");
+    sentences.push(confirmed === undefined
+        ? "Shadow AI: the answer carries no usable stats.visible_by_category, so it does not say how many services are confirmed exposed."
+        : `Shadow AI: ${confirmed} confirmed exposed (the sum of stats.visible_by_category: services EchelonGraph's probes found answering without an authentication gate)${last24 === undefined ? "" : `, ${last24} of them observed in the last 24 h (last_24h_visible_count)`}.`);
+    const total = numAt(sa, "stats", "total");
+    if (total !== undefined) {
+        sentences.push(`stats.total (${total}) counts every observation whatever its verification state: that many observed, not that many exposed.`);
+    }
+    let data = sa;
+    const lastRun = strAt(sa, "poller", "last_run_at");
+    const running = boolAt(sa, "poller", "running");
+    if (realInstant(lastRun) && running === true) {
+        sentences.push(`Shadow-AI radar freshness: the radar's leader last completed a Certificate Transparency (crt.sh) discovery cycle at ${lastRun} (poller.running is true: that was within ${SHADOW_AI_SILENT_AFTER} of the API's answer).`);
+    }
+    else if (realInstant(lastRun) && running === false) {
+        sentences.push(`Shadow-AI radar freshness: no Certificate Transparency (crt.sh) discovery cycle has completed since ${lastRun}, when the radar's leader last completed one (poller.running is false: that was more than ${SHADOW_AI_SILENT_AFTER} before the API's answer), so the shadow-AI figures may be stale.`);
+    }
+    else if (field(sa, "poller") === undefined) {
+        sentences.push("Shadow-AI radar freshness is unknown: the answer carries no poller block.");
+    }
+    else {
+        const rest = { ...sa };
+        delete rest.poller;
+        data = rest;
+        sentences.push("Shadow-AI radar freshness is unknown: the answer's poller block does not give both a real time at which the radar's leader last completed a cycle (poller.last_run_at) and a running verdict (poller.running), so that block was left out of the data above.");
+    }
+    const lastObservation = strAt(sa, "stats", "last_observation");
+    if (realInstant(lastObservation))
+        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. For shadow AI, stats.total counts every observation whatever its verification state (observed, not exposed); the confirmed-exposed count is the sum of stats.visible_by_category, and last_24h_visible_count is its last-24-hour slice. The shadow-AI poller block's 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 tool = "exposure_radar";
     try {
-        const [kev, db, leaked, shadow] = await Promise.all([
-            api("/api/v1/public/kev-exposure/stats").catch(() => null),
-            api("/api/v1/public/exposed-databases/stats").catch(() => null),
-            api("/api/v1/public/leaked-credentials/stats").catch(() => null),
-            api("/api/v1/public/shadow-ai-radar/stats").catch(() => null),
-        ]);
-        return ok({ kev_exposure: kev, exposed_databases: db, leaked_credentials: leaked, shadow_ai: shadow });
+        const results = await Promise.all(RADARS.map(([, path]) => api(path)));
+        const data = {};
+        const failures = [];
+        RADARS.forEach(([name], i) => {
+            const r = results[i];
+            if (r.ok)
+                data[name] = r.data;
+            else
+                failures.push([name, r]);
+        });
+        if (failures.length) {
+            // All or nothing: a radar picture with one quadrant missing reads as the whole one,
+            // and the missing quadrant reads as zero. Name every failure; withhold the rest.
+            const answered = Object.keys(data);
+            const lines = failures.map(([name, f]) => `- ${name}: ${describeFailure(f)}`);
+            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 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.`);
     }
     catch (e) {
-        return fail(e);
+        return crashed(tool, e);
     }
 });
 const transport = new StdioServerTransport();
 await server.connect(transport);
 // MCP uses stdout for the protocol — diagnostics go to stderr.
-console.error(`EchelonGraph CVE MCP server running (API: ${BASE})`);
+console.error(`EchelonGraph CVE MCP server running (API: ${SHOWN_BASE}, timeout ${TIMEOUT_MS} ms)`);

package/package.json

@@ -1,19 +1,22 @@
 {
   "name": "echelongraph-mcp",
-  "version": "1.0.0",
-  "description": "EchelonGraph CVE & internet-exposure intelligence as an MCP server — real-time CVEs, EchelonGraph multi-source scores, CISA-KEV/EPSS, and the unique LIVE internet-exposure footprint per CVE — for Claude, Cursor, and any MCP client.",
+  "version": "1.0.2",
+  "mcpName": "io.echelongraph/echelongraph-mcp",
+  "description": "EchelonGraph CVE and internet-exposure data as an MCP server: CVEs with EchelonGraph multi-source scores, CISA-KEV and EPSS, plus a per-CVE internet-exposure footprint derived from Shodan data. Shodan data is owned by Shodan, which holds its copyright (© Shodan). Free and keyless, for Claude, Cursor and any MCP client.",
   "type": "module",
   "bin": {
     "echelongraph-mcp": "dist/index.js"
   },
   "files": [
     "dist",
-    "README.md"
+    "README.md",
+    "server.json"
   ],
   "scripts": {
     "build": "tsc",
     "start": "node dist/index.js",
-    "smoke": "node test/smoke.mjs"
+    "smoke": "node test/smoke.mjs",
+    "test": "npm run build && node --test test/tools.test.mjs"
   },
   "keywords": [
     "mcp",
@@ -33,7 +36,7 @@
   "homepage": "https://echelongraph.io/pulse/mcp",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/AkshayDubey29/EchelonGraph.git"
+    "url": "git+https://github.com/echelongraph/EchelonGraph.git"
   },
   "engines": {
     "node": ">=18"

package/server.json

@@ -0,0 +1,34 @@
+{
+  "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
+  "name": "io.echelongraph/echelongraph-mcp",
+  "title": "EchelonGraph CVE & Exposure",
+  "description": "CVEs (NVD, CISA-KEV, EPSS, GHSA) and per-CVE exposure from Shodan data (© Shodan). Free, keyless.",
+  "websiteUrl": "https://echelongraph.io/pulse/mcp",
+  "version": "1.0.2",
+  "packages": [
+    {
+      "registryType": "npm",
+      "identifier": "echelongraph-mcp",
+      "version": "1.0.2",
+      "transport": {
+        "type": "stdio"
+      },
+      "environmentVariables": [
+        {
+          "name": "ECHELONGRAPH_API_BASE",
+          "description": "Override the API base URL (self-host or proxy).",
+          "isRequired": false,
+          "format": "string",
+          "default": "https://app.echelongraph.io"
+        },
+        {
+          "name": "ECHELONGRAPH_API_TIMEOUT_MS",
+          "description": "Per-request timeout in milliseconds. A slower answer is reported as a failed lookup, not as empty data.",
+          "isRequired": false,
+          "format": "number",
+          "default": "15000"
+        }
+      ]
+    }
+  ]
+}