echelongraph-mcp 1.0.2 → 1.0.3

package/README.md

@@ -54,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
 
@@ -68,9 +88,11 @@ outage for an all-clear:
 - **Success** — the first text block is the API's JSON verbatim; the second is a one-line
   note saying the call succeeded, which base URL answered, and what it found. When the
   feed genuinely holds nothing for the query the note says so in words ("we looked and
-  found nothing … not a lookup failure"), because a measured zero is a measurement. One
-  exception to verbatim: `exposure_radar` drops the shadow-AI `poller` block when it carries
-  no real completion time. That block's `last_run_at` is when the radar's leader last
+  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

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
@@ -388,13 +389,26 @@ 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's running and last_run_at describe the radar's fleet, not the instance
+// 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
@@ -402,52 +416,187 @@ const RADARS = [
 // 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.
+// 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 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");
+    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;
+    }
+    // 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;
+    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 {
-        const rest = { ...sa };
-        delete rest.poller;
-        data = rest;
         sentences.push("Shadow-AI radar freshness is unknown: the answer's poller block does not give both a real time at which the radar's leader last completed a cycle (poller.last_run_at) and a running verdict (poller.running), so that block was left out of the data above.");
     }
-    const lastObservation = strAt(sa, "stats", "last_observation");
     if (realInstant(lastObservation))
         sentences.push(`Latest shadow-AI observation on record: ${lastObservation}.`);
     return { data, sentences };
 }
-server.tool("exposure_radar", `Aggregate totals from EchelonGraph's internet-exposure radars, each refreshed on its own schedule: shadow AI services found through Certificate Transparency logs and Shodan and then checked by EchelonGraph's identified probes; internet-facing services running actively-exploited (CISA-KEV) CVEs, plus the ransomware-linked subset, derived from Shodan data; unauthenticated data stores and observability UIs, found through Shodan (LeakIX when Shodan query credits run low) and then confirmed by EchelonGraph's own identified check (not a pure read: on Redis it names its client, and on ClickHouse its query is recorded in the server's query log); and leaked credentials sampled from public GitHub push events. The kev_exposure and exposed_databases distinct_hosts figures count distinct ip:port services, so a machine answering on two ports counts twice. For shadow AI, stats.total counts every observation whatever its verification state (observed, not exposed); the confirmed-exposed count is the sum of stats.visible_by_category, and last_24h_visible_count is its last-24-hour slice. The shadow-AI poller block's last_run_at is when the radar's leader last completed a Certificate Transparency (crt.sh) cycle, and its running is true only when that was within ${SHADOW_AI_SILENT_AFTER} of the answer. ${SHODAN_OWNERSHIP}`, {}, async () => {
+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)));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "echelongraph-mcp",
-  "version": "1.0.2",
+  "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. Shodan data is owned by Shodan, which holds its copyright (© Shodan). Free and keyless, for Claude, Cursor and any MCP client.",
   "type": "module",

package/server.json

@@ -4,12 +4,12 @@
   "title": "EchelonGraph CVE & Exposure",
   "description": "CVEs (NVD, CISA-KEV, EPSS, GHSA) and per-CVE exposure from Shodan data (© Shodan). Free, keyless.",
   "websiteUrl": "https://echelongraph.io/pulse/mcp",
-  "version": "1.0.2",
+  "version": "1.0.3",
   "packages": [
     {
       "registryType": "npm",
       "identifier": "echelongraph-mcp",
-      "version": "1.0.2",
+      "version": "1.0.3",
       "transport": {
         "type": "stdio"
       },