echelongraph-mcp 1.0.1 → 1.0.2

package/README.md

@@ -8,6 +8,7 @@ It exposes EchelonGraph's CVE Pulse (NVD + MITRE-CNA *pre-NVD* + CISA-KEV + EPSS
 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).
 
 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.
@@ -20,7 +21,7 @@ API call a tool needs to answer.
 | `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` | 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. |
+| `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.
@@ -69,9 +70,15 @@ outage for an all-clear:
   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.
+  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
@@ -136,4 +143,11 @@ 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

@@ -308,12 +308,18 @@ 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}`;
+    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
@@ -350,7 +356,7 @@ 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. 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 }) => {
+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)
@@ -388,10 +394,18 @@ const RADARS = [
 // 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.
+// 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");
@@ -411,24 +425,29 @@ function readShadowAI(sa) {
         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 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 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 () => {
+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 results = await Promise.all(RADARS.map(([, path]) => api(path)));
@@ -456,7 +475,7 @@ server.tool("exposure_radar", "Aggregate totals from EchelonGraph's internet-exp
         }
         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.`);
+        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 crashed(tool, e);

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "echelongraph-mcp",
-  "version": "1.0.1",
+  "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. Free and keyless, for Claude, Cursor and any MCP client.",
+  "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"

package/server.json

@@ -2,14 +2,14 @@
   "$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.",
+  "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.1",
+  "version": "1.0.2",
   "packages": [
     {
       "registryType": "npm",
       "identifier": "echelongraph-mcp",
-      "version": "1.0.1",
+      "version": "1.0.2",
       "transport": {
         "type": "stdio"
       },