echelongraph-mcp 1.0.1 → 1.0.3

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.
@@ -53,11 +54,31 @@ The radar only looks for its **tracked** set of CVEs, so a zero means different
 
 ### 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.
+The shadow-AI radar's answer mixes numbers that count exposed services with numbers that count
+every observation. So `exposure_radar` regroups it by what each number counts, and its note
+labels each one. Only `shadow_ai.confirmed_exposed` counts exposed services.
+
+| Field | What it counts |
+|---|---|
+| `confirmed_exposed.total` | Confirmed exposed: services EchelonGraph's probes found answering without an authentication gate (liveness `active`, or `rechecking` during a re-check). It is the sum of `confirmed_exposed.by_category`. |
+| `confirmed_exposed.by_category` | The same services, by category. |
+| `confirmed_exposed.last_24h` | Confirmed-exposed services first recorded in the last 24 hours. |
+| `observed.total` | Every Certificate Transparency or Shodan observation on record, whatever its verification state: observed, not exposed. |
+| `observed.by_category` | The same observations, by category. |
+| `observed.last_24h` | Observations first recorded in the last 24 hours. |
+| `observed.trend_30d` | Observations per UTC day over the last 30 days. |
+| `observed.top_products`, `observed.top_countries`, `observed.top_issuers` | Up to ten products, countries and issuers, ranked by observations, not by exposed services. An issuer is the certificate's CA for a Certificate Transparency observation, and the hosting operator Shodan reports for a Shodan one. |
+| `observed.last_observation` | When the latest observation was recorded. |
+| `authentication.observed` | Observations where a probe observed an authentication gate: a 401/403, a login page or an auth marker. |
+| `authentication.not_determined` | Observations whose service answered, but where no probe could tell whether it enforces authentication. |
+
+Neither authentication count is part of `confirmed_exposed`, and `observed.total` minus
+`confirmed_exposed.total` is not a count of secured services: it also holds observations not
+yet verified, whose hostname no longer resolves, or whose service no longer answers openly.
+
+The tool relays no number it cannot label. A stats field this version does not know is left
+out, and the note names it; so is a count in an unexpected shape. A ranked row carries only
+its name and its count.
 
 ## What a result means
 
@@ -67,11 +88,19 @@ 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.
+  found nothing … not a lookup failure"), because a measured zero is a measurement. The
+  exception to verbatim is `exposure_radar`'s `shadow_ai`: its counts are regrouped as above,
+  and its `poller` block carries only `running` and `last_run_at`, or is dropped when it
+  carries no real completion time. The block's other fields describe the server instance that
+  answered, not the radar. Its `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 +165,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

@@ -10,7 +10,8 @@
 // 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).
+//     nothing ("we looked and found nothing" is a measurement). One exception: exposure_radar
+//     regroups the shadow-AI answer by what each number counts (readShadowAI, #2307).
 //   - 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
@@ -308,12 +309,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 +357,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)
@@ -382,53 +389,214 @@ const RADARS = [
     ["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).
+// The shadow-AI stats answer, regrouped by what each number counts (#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.
+// GET /api/v1/public/shadow-ai-radar/stats (core-backend shadowctlog store.go Stats) mixes
+// three kinds of number, and only one of them counts exposed services:
+//   - confirmed exposed: rows whose liveness is active or rechecking, the published exposure
+//     set (visible_by_category, last_24h_visible_count);
+//   - observed: every Certificate Transparency or Shodan observation on record, whatever its
+//     verification state (total, by_category, last_24h_count, trend_30d, and the top_products,
+//     top_countries and top_issuers rankings);
+//   - authentication state: rows where a probe observed an authentication gate (auth_confirmed,
+//     liveness authenticated) or could not tell (auth_undetermined, liveness inconclusive).
+// On 2026-09-27 total was 36,222 against 2,000 confirmed exposed, and top_products ranked
+// LiteLLM at 6,813 observations while 1,395 LLM-PROXY services were confirmed exposed. Relayed
+// under the API's names, every one of those reads as an exposure count. So the tool relays them
+// grouped as confirmed_exposed, observed and authentication, with the note labelling each, and
+// relays nothing it cannot label: a stats field this version does not know, a field other than
+// a ranked row's label and count, and the poller block's instance fields are left out, the
+// first named in the note.
 //
-// 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.
+// The `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, as those two fields alone; an
+// unknown block (no real completion time and running verdict) is dropped, so no running:false
+// or zero time reaches the model as freshness. The block's other fields (interval_seconds,
+// shodan_enabled, and a polling instance's last_new_inserts, skipped_as_follower,
+// consecutive_fails and shodan_last_new) describe the instance that answered, not the fleet,
+// and none of them counts AI services.
+const SHADOW_AI_SILENT_AFTER = "30 minutes";
+// The stats fields readShadowAI knows how to label. Any other is left out and named.
+const SHADOW_AI_STATS = new Set([
+    "total",
+    "by_category",
+    "visible_by_category",
+    "last_observation",
+    "last_24h_count",
+    "last_24h_visible_count",
+    "auth_confirmed",
+    "auth_undetermined",
+    "top_products",
+    "top_countries",
+    "top_issuers",
+    "trend_30d",
+]);
+// The observed rankings and the daily series: API field, and the row field that names each row.
+const SHADOW_AI_ROWS = [
+    ["trend_30d", "date"],
+    ["top_products", "product"],
+    ["top_countries", "country"],
+    ["top_issuers", "issuer"],
+];
+const isCount = (v) => typeof v === "number" && Number.isFinite(v);
+const isPlainObject = (v) => v !== null && typeof v === "object" && !Array.isArray(v);
+// A category → count map, or nothing unless every value is a count: a partial map is an
+// undercount that reads as a measurement (store.go categoryCounts).
+function countMap(v) {
+    if (!isPlainObject(v))
+        return undefined;
+    const entries = Object.entries(v);
+    return entries.every(([, n]) => isCount(n)) ? Object.fromEntries(entries) : undefined;
+}
+// A ranking or a daily series, each row cut down to its label and its count, so a field the
+// backend adds to a row later is left out rather than relayed unlabelled. All rows or none.
+function countRows(v, label) {
+    if (!Array.isArray(v))
+        return undefined;
+    const rows = [];
+    for (const r of v) {
+        const name = field(r, label);
+        const count = field(r, "count");
+        if (typeof name !== "string" || !isCount(count))
+            return undefined;
+        rows.push({ [label]: name, count });
+    }
+    return rows;
+}
 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 stats = field(sa, "stats");
+    const used = new Set();
+    const take = (key, v) => {
+        if (v !== undefined)
+            used.add(key);
+        return v;
+    };
+    // Confirmed exposed: liveness IN ('active','rechecking') (store.go Stats, visible_by_category
+    // and last_24h_visible_count).
+    const confirmed = {};
+    const visible = take("visible_by_category", countMap(field(stats, "visible_by_category")));
+    if (visible) {
+        confirmed.total = Object.values(visible).reduce((a, b) => a + b, 0);
+        confirmed.by_category = visible;
+    }
+    const last24Visible = take("last_24h_visible_count", numAt(stats, "last_24h_visible_count"));
+    if (last24Visible !== undefined)
+        confirmed.last_24h = last24Visible;
+    // Observed: every row of shadow_ct_observations, whatever its liveness.
+    const observed = {};
+    const total = take("total", numAt(stats, "total"));
+    if (total !== undefined)
+        observed.total = total;
+    const byCategory = take("by_category", countMap(field(stats, "by_category")));
+    if (byCategory)
+        observed.by_category = byCategory;
+    const last24 = take("last_24h_count", numAt(stats, "last_24h_count"));
+    if (last24 !== undefined)
+        observed.last_24h = last24;
+    const rows = {};
+    for (const [key, label] of SHADOW_AI_ROWS) {
+        const r = take(key, countRows(field(stats, key), label));
+        if (r)
+            observed[key] = rows[key] = r;
     }
-    const 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");
+    // A timestamp, not a count; one that is not a real instant is dropped (see realInstant).
+    const lastObservation = take("last_observation", strAt(stats, "last_observation"));
+    if (realInstant(lastObservation))
+        observed.last_observation = lastObservation;
+    // Authentication state: liveness 'authenticated' and 'inconclusive'.
+    const authentication = {};
+    const authSeen = take("auth_confirmed", numAt(stats, "auth_confirmed"));
+    if (authSeen !== undefined)
+        authentication.observed = authSeen;
+    const authUnknown = take("auth_undetermined", numAt(stats, "auth_undetermined"));
+    if (authUnknown !== undefined)
+        authentication.not_determined = authUnknown;
+    sentences.push(confirmed.total === undefined
+        ? `Shadow AI: the answer carries no usable stats.visible_by_category, so it does not say how many services are confirmed exposed${last24Visible === undefined ? "" : `; confirmed_exposed.last_24h (${last24Visible}) counts confirmed-exposed services first recorded in the last 24 h`}.`
+        : `Shadow AI confirmed exposed: ${confirmed.total} (confirmed_exposed.total, the sum of confirmed_exposed.by_category: services EchelonGraph's probes found answering without an authentication gate, with liveness active or, during a re-check, rechecking)${last24Visible === undefined ? "" : `, ${last24Visible} of them first recorded in the last 24 h (confirmed_exposed.last_24h)`}. Only confirmed_exposed counts exposed services.`);
     if (total !== undefined) {
-        sentences.push(`stats.total (${total}) counts every observation whatever its verification state: that many observed, not that many exposed.`);
+        sentences.push(`Shadow AI observed: ${total} (observed.total) counts every Certificate Transparency or Shodan observation on record, whatever its verification state: that many observed, not that many exposed.`);
     }
-    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 first = (key, label) => {
+        const top = rows[key]?.[0];
+        return top === undefined ? "" : ` (first: ${top[label]}, ${top.count} observations)`;
+    };
+    const observedParts = [
+        byCategory && "observed.by_category counts them by category",
+        last24 !== undefined && `observed.last_24h (${last24}) counts those first recorded in the last 24 h`,
+        rows.trend_30d && "observed.trend_30d counts them per UTC day over the last 30 days",
+        rows.top_products && `observed.top_products ranks up to ten products by observations${first("top_products", "product")}`,
+        rows.top_countries && `observed.top_countries ranks up to ten countries by observations${first("top_countries", "country")}`,
+        rows.top_issuers &&
+            `observed.top_issuers ranks up to ten issuers by observations, an issuer being the certificate's CA for a Certificate Transparency observation and the hosting operator Shodan reports for a Shodan one${first("top_issuers", "issuer")}`,
+    ].filter((p) => typeof p === "string");
+    if (observedParts.length) {
+        sentences.push(`${total === undefined ? "Every number" : "Every other number"} under observed counts the same observations, not exposed services: ${observedParts.join("; ")}.`);
+    }
+    const authParts = [
+        authSeen !== undefined &&
+            `authentication.observed (${authSeen}) counts observations where a probe observed an authentication gate (a 401/403, a login page or an auth marker; liveness authenticated)`,
+        authUnknown !== undefined &&
+            `authentication.not_determined (${authUnknown}) counts observations whose service answered but where no probe could tell whether it enforces authentication (liveness inconclusive)`,
+    ].filter((p) => typeof p === "string");
+    if (authParts.length) {
+        sentences.push(`Shadow AI authentication, over every observation on record: ${authParts.join("; ")}.`);
+        sentences.push("Neither authentication count is part of confirmed_exposed, and observed.total minus confirmed_exposed.total is not a count of secured services: it also holds observations not yet verified (liveness unverified), whose hostname no longer resolves (unreachable), or whose service no longer answers openly (resolved).");
+    }
+    // What the answer carried that the tool cannot label: named, and left out.
+    const unknown = [
+        ...Object.keys(isPlainObject(sa) ? sa : {}).filter((k) => k !== "stats" && k !== "poller"),
+        ...Object.keys(isPlainObject(stats) ? stats : {})
+            .filter((k) => !SHADOW_AI_STATS.has(k))
+            .map((k) => `stats.${k}`),
+    ];
+    const unusable = Object.entries(isPlainObject(stats) ? stats : {})
+        .filter(([k, v]) => SHADOW_AI_STATS.has(k) && !used.has(k) && v !== null)
+        .map(([k]) => `stats.${k}`);
+    if (!isPlainObject(stats))
+        sentences.push("The answer carries no stats object, so it gives no shadow-AI counts.");
+    if (unknown.length) {
+        sentences.push(`Left out of shadow_ai because this version of the tool cannot label them: ${unknown.join(", ")}.`);
+    }
+    if (unusable.length) {
+        sentences.push(`Left out of shadow_ai because they were not in the expected shape: ${unusable.join(", ")}.`);
+    }
+    const data = {};
+    if (Object.keys(confirmed).length)
+        data.confirmed_exposed = confirmed;
+    if (Object.keys(observed).length)
+        data.observed = observed;
+    if (Object.keys(authentication).length)
+        data.authentication = authentication;
+    const lastRun = strAt(sa, "poller", "last_run_at");
+    const running = boolAt(sa, "poller", "running");
+    if (realInstant(lastRun) && running === true) {
+        data.poller = { running, last_run_at: lastRun };
+        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) {
+        data.poller = { running, last_run_at: lastRun };
+        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 {
+        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. The shadow_ai result is regrouped by what each number counts, and carries no number the tool cannot label. shadow_ai.confirmed_exposed counts services EchelonGraph's probes found answering without an authentication gate (liveness active, or rechecking during a re-check): confirmed_exposed.total is the sum of confirmed_exposed.by_category, and confirmed_exposed.last_24h counts those first recorded in the last 24 h. Only confirmed_exposed counts exposed services. shadow_ai.observed counts every Certificate Transparency or Shodan observation on record, whatever its verification state: its numbers are observed, not exposed. They are observed.total; observed.by_category (the same observations by category); observed.last_24h (those first recorded in the last 24 h); observed.trend_30d (observations per UTC day over the last 30 days); and observed.top_products, observed.top_countries and observed.top_issuers (up to ten products, countries and issuers ranked by observations, where an issuer is the certificate's CA for a Certificate Transparency observation and the hosting operator Shodan reports for a Shodan one). shadow_ai.authentication counts observations by probe outcome: authentication.observed where a probe observed an authentication gate (a 401/403, a login page or an auth marker), and authentication.not_determined where the service answered but no probe could tell. Neither authentication count is part of confirmed_exposed, and observed.total minus confirmed_exposed.total is not a count of secured services. The shadow-AI poller block carries only running and last_run_at: last_run_at is when the radar's leader last completed a Certificate Transparency (crt.sh) cycle, and its running is true only when that was within ${SHADOW_AI_SILENT_AFTER} of the answer. ${SHODAN_OWNERSHIP}`, {}, async () => {
     const tool = "exposure_radar";
     try {
         const results = await Promise.all(RADARS.map(([, path]) => api(path)));
@@ -456,7 +624,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.3",
   "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.3",
   "packages": [
     {
       "registryType": "npm",
       "identifier": "echelongraph-mcp",
-      "version": "1.0.1",
+      "version": "1.0.3",
       "transport": {
         "type": "stdio"
       },