echelongraph-mcp 1.0.0 → 1.0.1

package/README.md

@@ -1,25 +1,82 @@
 # 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.
 
-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 read-only check; 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 run time. That block describes whichever server instance answered, and a follower
+  instance reports `running: false` and the zero time `0001-01-01T00:00:00Z`; the note then
+  says the poller's freshness is unknown rather than presenting either as freshness.
+- **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 +112,28 @@ 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.

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,
+});
+// 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 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 () => {
+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,212 @@ 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.";
+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}`;
+    // 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. 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 describes whichever server instance answered, not the radar. A follower
+// instance answers running:false and last_run_at 0001-01-01T00:00:00Z, which reads as "the
+// radar is down and has never run". A block without a real run time is dropped from the
+// relayed data, and the note says freshness is unknown instead.
+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;
+    if (field(sa, "poller") !== undefined) {
+        const lastRun = strAt(sa, "poller", "last_run_at");
+        if (boolAt(sa, "poller", "running") === true && realInstant(lastRun)) {
+            sentences.push(`The server instance that answered last ran the shadow-AI poller at ${lastRun}.`);
+        }
+        else {
+            const rest = { ...sa };
+            delete rest.poller;
+            data = rest;
+            sentences.push("Shadow-AI poller freshness is unknown: the server instance that answered had no completed poller run of its own to report (a follower instance, or one that has not run yet), so its poller 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 read-only check; 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.", {}, 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} 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.1",
+  "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. 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": "CVE data (NVD, CISA-KEV, EPSS, GHSA) and Shodan-derived internet exposure per CVE. Free, keyless.",
+  "websiteUrl": "https://echelongraph.io/pulse/mcp",
+  "version": "1.0.1",
+  "packages": [
+    {
+      "registryType": "npm",
+      "identifier": "echelongraph-mcp",
+      "version": "1.0.1",
+      "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"
+        }
+      ]
+    }
+  ]
+}