echelongraph-mcp 1.0.2 → 1.0.4

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 EchelonGraph
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -21,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 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. |
+| `exposure_radar` | Aggregate totals across the exposure radars: 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; shadow AI. Every number is labelled by what it counts, and a field the tool cannot label is left out and named. |
 
 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.
@@ -40,8 +40,9 @@ Shodan InternetDB refreshes `last_seen` without re-reading the banner, so a patc
 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.
+each observation on ip:port, so a machine answering on two ports counts twice. The API's field
+names are kept (`exposed_hosts` here; `distinct_hosts`, `ransomware_hosts` and each ranked
+row's count in `exposure_radar`), but every one of them counts ip:port services.
 
 The radar only looks for its **tracked** set of CVEs, so a zero means different things:
 
@@ -52,13 +53,105 @@ The radar only looks for its **tracked** set of CVEs, so a zero means different
 | 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
+### How `exposure_radar` counts
 
-`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.
+`exposure_radar` relays each radar's answer cut to the fields it can label, and its note labels
+every number by what it counts. A field this version does not know is left out and the note
+names it, whether it is a total or a field inside a ranked row; so is a known field in an
+unexpected shape, and a list with one malformed row is left out whole, since a partial list
+reads as a complete one. `kev_exposure`, `exposed_databases` and `leaked_credentials` also
+carry `generated_at`, when the API computed their totals, and, when the API can tell,
+`last_run_at`: when that radar last completed a check (each table below says what a completed
+check is for that radar).
+
+`last_run_at` is a timestamp, not a count. It is recorded for the radar as a whole, not for
+the server instance that answered, in UTC to the second. It moves only at the end of a cycle
+whose reads succeeded, so a cycle that read nothing leaves it where it was. It is not the time
+of every record a radar's numbers count: those cover everything still on record, not only what
+the last check found. Nor is it `generated_at`, which is only when the API recomputed the
+totals. The API omits `last_run_at` when it has no completed check on record or cannot read
+it; the result then carries none, and the note says nothing about it. When it is there, the
+note gives it as, for example, "kev_exposure last completed check: 2026-09-27T03:12:44Z".
+
+#### `kev_exposure`
+
+Every count is over the services the KEV-exposure radar keeps: a Shodan banner whose version
+maps to a CISA-KEV-listed CVE (see "How `cve_exposure` counts").
+
+| Field | What it counts |
+|---|---|
+| `kev_exposure.distinct_hosts` | Distinct ip:port services, not machines, with at least one CISA-KEV-listed CVE on record. A machine answering on two ports counts twice. |
+| `kev_exposure.ransomware_hosts` | The services among them with at least one ransomware-linked KEV CVE (one whose KEV entry notes known use in ransomware campaigns). |
+| `kev_exposure.kev_cves_exposed` | Distinct CISA-KEV-listed CVEs with at least one service on record. |
+| `kev_exposure.ransomware_cves` | The ransomware-linked CVEs among them. |
+| `kev_exposure.correlations` | Service×CVE pairs, not services: a service with three KEV CVEs counts three times. |
+| `kev_exposure.top_products`, `kev_exposure.top_countries`, `kev_exposure.top_cves` | Up to 12 products, 10 countries and 12 CVEs, ranked by distinct ip:port services. |
+| `kev_exposure.top_cves[].cvss_v3_score`, `kev_exposure.top_cves[].epss_score` | Scores, not counts: the highest CVSS v3 base score and EPSS probability (0 to 1) recorded on that CVE's observations. |
+| `kev_exposure.trend` | Service×CVE pairs, not services, by the week (starting Monday) in which each pair was first recorded, over the last 12 weeks. Only pairs still on record are counted, so earlier weeks read low. |
+| `kev_exposure.newest_kev` | The 15 CVEs that EchelonGraph's CVE records most recently mark as CISA-KEV-listed (by `added_date`), each with an `exposure_state` (below). |
+| `kev_exposure.newest_kev[].exposed_hosts` | Only on a row whose `exposure_state` is `exposed` (or `measured_zero`): distinct ip:port services on record with that CVE. |
+| `kev_exposure.newest_kev[].cvss_v3_score`, `kev_exposure.newest_kev[].epss_score` | Scores, not counts: the CVE record's CVSS v3 base score and EPSS probability (0 to 1), absent when the record has none. |
+| `kev_exposure.last_run_at` | A timestamp, not a count: when the radar last completed a check, a cycle in which its Shodan search answered at least one query (others may have failed) and its list of services due for a re-check was read. A cycle that skipped the search for want of Shodan query credits, or whose reads failed, does not move it. |
+
+A `newest_kev` row's `exposure_state` says whether its count is a measurement:
+
+| `exposure_state` | What it means |
+|---|---|
+| `exposed` | The radar has services on record with this CVE, and `exposed_hosts` counts them. |
+| `not_assessed` | **NOT ASSESSED**: the answer holds no measurement for this CVE, so no count is relayed. The API answers 0 for every CVE the radar holds no service for, whether or not the radar looks for that CVE at all, and it never marks a CVE as tracked with 0 services, so that 0 is not a measurement. `cve_exposure` says per CVE whether it is in the radar's tracked set. |
+| `measured_zero` | Only if the API ever marks a row `tracked: true` with 0 services: a zero in the radar's sample, not an internet-wide zero. If it marks a row `tracked: false`, that row is `not_assessed` whatever its count. |
+
+#### `exposed_databases`
+
+| Field | What it counts |
+|---|---|
+| `exposed_databases.distinct_hosts` | Distinct ip:port services, not machines, that EchelonGraph's check confirmed answering without authentication: data stores and observability UIs alike. |
+| `exposed_databases.engines` | Distinct engine types among them (for example `redis` or `grafana`). |
+| `exposed_databases.top_engines`, `exposed_databases.top_countries` | Up to 15 engines and 10 countries, ranked by those services. |
+| `exposed_databases.pii_likely`, `exposed_databases.pci_likely` | Services whose schema names pass a high-confidence gate for personal data, or for payment-card data. The names are index, database, table or field names in the Shodan or LeakIX banner or in the check's response, never record values; the gate passes one unambiguous term (such as `ssn` or `cardholder`) or two distinct indicators. It is a precision-first schema gate, not a census: a service whose names do not pass it is not counted, whatever it holds, so the other services are not shown to hold no such data. |
+| `exposed_databases.last_run_at` | A timestamp, not a count: when the radar last completed a check, a cycle in which its Shodan search, or the LeakIX fallback, answered at least one query (others may have failed), its list of services due for a re-check was read, and the scan opt-out register could be consulted. A cycle that searched nothing, or whose reads failed, does not move it. |
+
+#### `leaked_credentials`
+
+| Field | What it counts |
+|---|---|
+| `leaked_credentials.total` | (repository, secret) pairs, not distinct secrets: a secret committed to three repositories counts three times. |
+| `leaked_credentials.distinct_secrets` | Each secret once. |
+| `leaked_credentials.distinct_repos` | Public GitHub repositories with at least one. |
+| `leaked_credentials.top_providers`, `leaked_credentials.top_types` | Up to 15 providers and secret types, ranked by (repository, secret) pairs. |
+| `leaked_credentials.last_run_at` | A timestamp, not a count: when the radar last completed a check, a cycle that read the public GitHub event stream (fetches of some of the commits it lists may have failed). A cycle whose read of that stream failed does not move it. |
+
+None of them is validated. Each is a credential-shaped string in a public commit that passed
+EchelonGraph's filters, at most structurally checked (a checksum or format decode), and never
+tested against its provider, so none of these is a count of working credentials.
+
+#### `shadow_ai`
+
+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, and a field added to one is named too.
 
 ## What a result means
 
@@ -68,9 +161,12 @@ 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`: each radar is cut to the fields listed above, and
+  each `kev_exposure.newest_kev` row gains an `exposure_state`. Its `shadow_ai` 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,10 @@
 // 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
+//     relays each radar's answer cut to the fields it can label by what they count, and names
+//     what it left out (readKEVExposure, readExposedDatabases, readLeakedCredentials and
+//     readShadowAI; #2307, #2313).
 //   - 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 +391,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 +418,525 @@ 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;
+}
+const isKind = (v, k) => (k === "number" ? isCount(v) : typeof v === k);
+// A ranking, a series or a list, each row cut down to the fields its spec names, so a field the
+// backend adds to a row later is left out rather than relayed unlabelled; extra lists those
+// fields so the note can name them. All rows or none: a row that is not an object, lacks a
+// required field, or carries a known field of the wrong type leaves the whole list out, since
+// a partial list reads as a complete one. An optional field may be absent (Go's omitempty).
+function readRows(v, spec) {
+    if (!Array.isArray(v))
+        return { extra: [] };
+    const optional = spec.optional ?? {};
+    const rows = [];
+    const extra = new Set();
+    for (const r of v) {
+        if (!isPlainObject(r))
+            return { extra: [] };
+        const row = {};
+        for (const [k, kind] of Object.entries(spec.required)) {
+            if (!isKind(r[k], kind))
+                return { extra: [] };
+            row[k] = r[k];
+        }
+        for (const [k, kind] of Object.entries(optional)) {
+            if (r[k] === undefined)
+                continue;
+            if (!isKind(r[k], kind))
+                return { extra: [] };
+            row[k] = r[k];
+        }
+        // An own-property test: `in` would also find toString and constructor on the prototype.
+        for (const k of Object.keys(r))
+            if (!Object.prototype.hasOwnProperty.call(spec.required, k) && !Object.prototype.hasOwnProperty.call(optional, k))
+                extra.add(k);
+        rows.push(row);
+    }
+    return { rows, extra: [...extra] };
+}
+// A ranking or a daily series whose rows are a label and a count (the shadow-AI shape).
+const countRows = (v, label) => readRows(v, { required: { [label]: "string", count: "number" } });
+// The note's sentences about what a radar's answer carried that the tool left out.
+function leftOut(radar, unknown, unusable) {
+    const out = [];
+    if (unknown.length)
+        out.push(`Left out of ${radar} because this version of the tool cannot label them: ${unknown.join(", ")}.`);
+    if (unusable.length)
+        out.push(`Left out of ${radar} because they were not in the expected shape: ${unusable.join(", ")}.`);
+    return out;
+}
+function readRadar(body, spec) {
+    const src = isPlainObject(body) ? body : {};
+    const data = {};
+    const unknown = [];
+    const unusable = [];
+    const present = (k) => src[k] !== undefined && src[k] !== null;
+    for (const k of spec.counts) {
+        if (isCount(src[k]))
+            data[k] = src[k];
+        else if (present(k))
+            unusable.push(k);
+    }
+    for (const [k, rowSpec] of Object.entries(spec.rows)) {
+        const r = readRows(src[k], rowSpec);
+        if (r.rows) {
+            data[k] = r.rows;
+            unknown.push(...r.extra.map((x) => `${k}[].${x}`));
+        }
+        else if (present(k))
+            unusable.push(k);
+    }
+    // A timestamp that is not a real instant (the Go zero time) is not relayed as one.
+    for (const k of spec.instants) {
+        const s = strAt(src, k);
+        if (realInstant(s))
+            data[k] = s;
+        else if (present(k) && typeof src[k] !== "string")
+            unusable.push(k);
+    }
+    const known = new Set([...spec.counts, ...Object.keys(spec.rows), ...spec.instants]);
+    unknown.unshift(...Object.keys(src).filter((k) => !known.has(k)));
+    return { data, unknown, unusable };
+}
+// ── last_run_at: when a radar last COMPLETED a check (#2335) ──
+//
+// Since #2335 the kev_exposure, exposed_databases and leaked_credentials stats answers carry
+// last_run_at (core-backend pollerlock/published.go): the radar's completion row in
+// poller_run_state, recorded for the radar as a whole rather than for the instance that
+// answered, UTC, truncated to the second. Each poller writes that row at the END of a cycle,
+// and only when the cycle's reads succeeded (poller.go checkCompleted / recordCheck), so a
+// cycle that read nothing never moves it. What counts as a completed check differs per radar,
+// and LAST_CHECK words each. The API omits the field when no completed check is on record,
+// when its read failed, or when its last good read is more than two minutes old; it never
+// sends the Go zero time.
+//
+// It is a timestamp, not a count, and not the time of the numbers beside it: those count
+// everything still on record, not only what the last check found. Nor is it generated_at,
+// which is only when the API's 60 s stats cache recomputed the totals. An absent stamp (or one
+// that is not a real instant) means the API could not tell, so the note says nothing about it:
+// no "never", no zero.
+const LAST_CHECK = {
+    kev_exposure: "its Shodan search answered at least one query (others may have failed) and its list of services due for a re-check was read; a cycle that skipped the search for want of Shodan query credits, or whose reads failed, does not move it",
+    exposed_databases: "its Shodan search, or the LeakIX fallback, answered at least one query (others may have failed), its list of services due for a re-check was read, and the scan opt-out register could be consulted; a cycle that searched nothing, or whose reads failed, does not move it",
+    leaked_credentials: "it read the public GitHub event stream (fetches of some of the commits it lists may have failed); a cycle whose read of that stream failed does not move it",
+};
+// The note's sentences for one radar's relayed last_run_at, each naming the field so that any
+// one of them quoted alone still says what it is; none when the stamp was not relayed.
+function lastCheck(radar, data) {
+    const at = data.last_run_at;
+    if (typeof at !== "string")
+        return [];
+    return [
+        `${radar} last completed check: ${at} (${radar}.last_run_at, a timestamp, not a count).`,
+        `${radar}.last_run_at is when the radar last finished a cycle whose reads succeeded: ${LAST_CHECK[radar]}.`,
+        `${radar}.last_run_at is not the time of every record the ${radar} numbers count, which cover everything still on record, not only what that check found; nor is it ${radar}.generated_at, when the API computed those numbers.`,
+    ];
+}
+// The first row of a relayed ranking, for the note: "(first: http_server, 9120 services)".
+function firstOf(rows, label, count, unit) {
+    const top = Array.isArray(rows) ? rows[0] : undefined;
+    return top === undefined ? "" : ` (first: ${String(top[label])}, ${String(top[count])} ${unit})`;
+}
+// "a", "a and b", "a, b and c".
+const listed = (xs) => (xs.length < 2 ? xs.join("") : `${xs.slice(0, -1).join(", ")} and ${xs[xs.length - 1]}`);
+const numIn = (d, k) => (isCount(d[k]) ? d[k] : undefined);
+const be = (n) => (n === 1 ? "is" : "are");
+// ── kev_exposure: GET /api/v1/public/kev-exposure/stats (#2313 items 6 and 7) ──
+//
+// core-backend/internal/kevexposure store.go Stats. Every count is over the observation
+// table, one row per (ip:port, CVE) (Upsert keys it obsID(host, cve), the host being
+// "ip:port" from poller.go), filtered to rows whose kev_listed flag the poller copied in at
+// match time:
+//   distinct_hosts    COUNT(DISTINCT host): distinct ip:port services, not machines
+//   kev_cves_exposed  COUNT(DISTINCT cve_id): CVEs with at least one such service
+//   correlations      COUNT(*): service×CVE pairs, so a service with three CVEs counts 3 times
+//   ransomware_cves   COUNT(DISTINCT cve_id) FILTER (WHERE ransomware)
+//   ransomware_hosts  COUNT(DISTINCT host) FILTER (WHERE ransomware): services, not machines
+//   top_products / top_cves / top_countries   COUNT(DISTINCT host) per group, LIMIT 12/12/10;
+//                     a top_cves row's cvss_v3_score and epss_score are MAX() over its rows
+//   trend             COUNT(*) per date_trunc('week', first_seen) over 12 weeks: pairs still on
+//                     record, by the week first recorded (a pruned pair is gone, so earlier
+//                     weeks read low)
+//   newest_kev        the 15 cves rows with kev_listed and the latest kev_added_date, LEFT JOINed
+//                     to COUNT(DISTINCT host) of their KEV-flagged rows, COALESCE(e.h, 0).
+//   last_run_at       the radar's last completed check, KeyKEVExposureCheckCompleted (#2335; see
+//                     LAST_CHECK). Its own row: KeyKEVExposure is the Shodan-credit watermark.
+// So newest_kev[].exposed_hosts is 0 for every CVE the radar holds no row for, whether or not
+// it could ever hold one: the join default, not a measurement. The per-CVE endpoint decides
+// that with `tracked` (store.go trackedVerdict), which is true ONLY when rows exist
+// (exposedHosts > 0) and otherwise false or absent: the backend never reports a measured zero.
+// So a 0 here is never relayed: its row says exposure_state not_assessed and carries no
+// count. If the stats answer ever sends a row's `tracked` (the contract proposed on #2313), it
+// is read the way cve_exposure reads it: false is not assessed whatever the count, and true
+// with 0 is a measured zero in the radar's sample.
+const KEV_SPEC = {
+    counts: ["distinct_hosts", "ransomware_hosts", "kev_cves_exposed", "ransomware_cves", "correlations"],
+    rows: {
+        top_products: { required: { product: "string", hosts: "number" } },
+        top_countries: { required: { country: "string", hosts: "number" } },
+        top_cves: {
+            required: { cve_id: "string", hosts: "number" },
+            optional: { severity: "string", cvss_v3_score: "number", epss_score: "number", ransomware: "boolean" },
+        },
+        trend: { required: { week: "string", new_exposures: "number" } },
+        newest_kev: {
+            required: { cve_id: "string", exposed_hosts: "number" },
+            optional: {
+                added_date: "string",
+                vuln_name: "string",
+                severity: "string",
+                cvss_v3_score: "number",
+                epss_score: "number",
+                ransomware: "boolean",
+                tracked: "boolean",
+            },
+        },
+    },
+    instants: ["generated_at", "last_run_at"],
+};
+// One newest_kev row as relayed: the CVE record's fields, its exposure_state, and a count only
+// when the count is a measurement. `tracked` is read, not relayed: exposure_state says it.
+function newestKEVRow(r) {
+    const hosts = r.exposed_hosts;
+    const tracked = r.tracked;
+    const state = tracked === false ? "not_assessed" : hosts > 0 ? "exposed" : tracked === true ? "measured_zero" : "not_assessed";
+    const row = {};
+    for (const k of ["cve_id", "added_date", "vuln_name", "severity", "cvss_v3_score", "epss_score", "ransomware"]) {
+        if (r[k] !== undefined)
+            row[k] = r[k];
+    }
+    row.exposure_state = state;
+    if (state !== "not_assessed")
+        row.exposed_hosts = hosts;
+    return { row, state, outside: tracked === false };
+}
+function readKEVExposure(body) {
+    const { data, unknown, unusable } = readRadar(body, KEV_SPEC);
+    const sentences = [];
+    const n = (k) => numIn(data, k);
+    const totals = [
+        n("distinct_hosts") !== undefined &&
+            `kev_exposure.distinct_hosts (${n("distinct_hosts")}) counts distinct ip:port services, not machines (a machine answering on two ports counts twice), with at least one CISA-KEV-listed CVE on record`,
+        n("ransomware_hosts") !== undefined &&
+            `kev_exposure.ransomware_hosts (${n("ransomware_hosts")}) counts the services among them with at least one ransomware-linked KEV CVE (one whose KEV entry notes known use in ransomware campaigns)`,
+        n("kev_cves_exposed") !== undefined &&
+            `kev_exposure.kev_cves_exposed (${n("kev_cves_exposed")}) counts distinct CISA-KEV-listed CVEs with at least one service on record`,
+        n("ransomware_cves") !== undefined && `kev_exposure.ransomware_cves (${n("ransomware_cves")}) counts the ransomware-linked CVEs among them`,
+        n("correlations") !== undefined &&
+            `kev_exposure.correlations (${n("correlations")}) counts service×CVE pairs, not services: a service with three KEV CVEs counts three times`,
+    ].filter((p) => typeof p === "string");
+    if (totals.length)
+        sentences.push(`KEV exposure: ${totals.join("; ")}.`);
+    const rankings = [
+        data.top_products !== undefined && `kev_exposure.top_products ranks up to 12 products${firstOf(data.top_products, "product", "hosts", "services")}`,
+        data.top_countries !== undefined && `kev_exposure.top_countries ranks up to 10 countries${firstOf(data.top_countries, "country", "hosts", "services")}`,
+        data.top_cves !== undefined && `kev_exposure.top_cves ranks up to 12 CVEs${firstOf(data.top_cves, "cve_id", "hosts", "services")}`,
+    ].filter((p) => typeof p === "string");
+    if (rankings.length)
+        sentences.push(`${listed(rankings)}, each by distinct ip:port services with a CISA-KEV-listed CVE on record.`);
+    if (data.top_cves !== undefined) {
+        sentences.push("kev_exposure.top_cves[].cvss_v3_score and kev_exposure.top_cves[].epss_score are the highest CVSS v3 base score and EPSS probability (0 to 1) recorded on that CVE's observations: scores, not counts.");
+    }
+    if (data.trend !== undefined) {
+        sentences.push("kev_exposure.trend counts service×CVE pairs, not services, by the week (starting Monday) in which each pair was first recorded, over the last 12 weeks; only pairs still on record are counted, so earlier weeks read low.");
+    }
+    // newest_kev: a 0 is the join's default, never a measurement (see the block comment above).
+    if (Array.isArray(data.newest_kev)) {
+        const read = data.newest_kev.map(newestKEVRow);
+        data.newest_kev = read.map((x) => x.row);
+        const ids = (pred) => read.filter(pred).map((x) => String(x.row.cve_id));
+        const exposed = read.filter((x) => x.state === "exposed");
+        const zero = ids((x) => x.state === "measured_zero");
+        const outside = ids((x) => x.state === "not_assessed" && x.outside);
+        const unsaid = ids((x) => x.state === "not_assessed" && !x.outside);
+        sentences.push(read.length
+            ? `kev_exposure.newest_kev lists the ${read.length} CVEs that EchelonGraph's CVE records most recently mark as CISA-KEV-listed (by added_date), each with an exposure_state.`
+            : "kev_exposure.newest_kev is empty: EchelonGraph's CVE records returned no CISA-KEV-listed CVE with a date added.");
+        if (exposed.length) {
+            sentences.push(`${exposed.length} of them ${be(exposed.length)} exposed (exposure_state exposed): kev_exposure.newest_kev[].exposed_hosts counts distinct ip:port services on record with that CVE (${exposed.map((x) => `${String(x.row.cve_id)}: ${String(x.row.exposed_hosts)}`).join(", ")}).`);
+        }
+        if (zero.length) {
+            sentences.push(`${zero.length} ${be(zero.length)} a measured zero in the radar's sample (exposure_state measured_zero, exposed_hosts 0): the API says the radar tracks them and holds no service for them, though it reads at most the first 100 Shodan results per tracked-product query, so this is not an internet-wide zero: ${zero.join(", ")}.`);
+        }
+        if (outside.length) {
+            sentences.push(`${outside.length} ${be(outside.length)} NOT ASSESSED (exposure_state not_assessed) because the API says they are outside the radar's tracked set, so no count is relayed for them: ${outside.join(", ")}.`);
+        }
+        if (unsaid.length) {
+            sentences.push(`${unsaid.length} ${be(unsaid.length)} NOT ASSESSED (exposure_state not_assessed): ${unsaid.join(", ")}. The API answers 0 for each, and that 0 is not a measurement: it is what the stats answer gives any CVE the radar holds no service for, whether or not the radar looks for that CVE at all, so no count is relayed for them. cve_exposure says per CVE whether it is in the radar's tracked set.`);
+        }
+        sentences.push("kev_exposure.newest_kev[].cvss_v3_score and kev_exposure.newest_kev[].epss_score are the CVE record's CVSS v3 base score and EPSS probability (0 to 1), absent when the record has none: scores, not counts.");
+    }
+    sentences.push(...lastCheck("kev_exposure", data));
+    sentences.push(...leftOut("kev_exposure", unknown, unusable));
+    return { data, sentences };
+}
+// ── exposed_databases: GET /api/v1/public/exposed-databases/stats (#2313 item 7) ──
+//
+// core-backend/internal/exposeddb store.go Stats, over one row per (ip:port, engine)
+// (obsID(host, engine); the host is "ip:port", poller.go obsFrom). A row is stored only after
+// EchelonGraph's own check confirmed the service answering without authentication.
+//   distinct_hosts  COUNT(DISTINCT host): ip:port services, not machines
+//   engines         COUNT(DISTINCT engine): engine types (mongodb, redis, grafana, ...)
+//   pii_likely / pci_likely   COUNT(DISTINCT host) whose data_class names pii / pci AND whose
+//                   schema terms pass the high-confidence gate (2+ distinct indicators, or one
+//                   tier-1 term), mirroring classify.go dataConfidence. The classifier reads
+//                   NAMES only (index / database / table / field names in the banner and the
+//                   check's response, classify.go), never a record, and is precision-first:
+//                   a service whose names miss the gate is not counted, whatever it holds.
+//                   So these are a schema gate, not a census, and the rest are not "no PII".
+//   top_engines / top_countries   COUNT(DISTINCT host) per group, LIMIT 15 / 10.
+//   last_run_at     the radar's last completed check, KeyExposedDBCheckCompleted (#2335; see
+//                   LAST_CHECK). Its own row: KeyExposedDB is claimed at the START of a cycle.
+const EXPOSED_DB_SPEC = {
+    counts: ["distinct_hosts", "engines", "pii_likely", "pci_likely"],
+    rows: {
+        top_engines: { required: { engine: "string", hosts: "number" } },
+        top_countries: { required: { country: "string", hosts: "number" } },
+    },
+    instants: ["generated_at", "last_run_at"],
+};
+function readExposedDatabases(body) {
+    const { data, unknown, unusable } = readRadar(body, EXPOSED_DB_SPEC);
+    const sentences = [];
+    const n = (k) => numIn(data, k);
+    const totals = [
+        n("distinct_hosts") !== undefined &&
+            `exposed_databases.distinct_hosts (${n("distinct_hosts")}) counts distinct ip:port services, not machines (a machine answering on two ports counts twice), that EchelonGraph's check confirmed answering without authentication, data stores and observability UIs alike`,
+        n("engines") !== undefined && `exposed_databases.engines (${n("engines")}) counts the distinct engine types among them`,
+    ].filter((p) => typeof p === "string");
+    if (totals.length)
+        sentences.push(`Exposed data stores: ${totals.join("; ")}.`);
+    const rankings = [
+        data.top_engines !== undefined && `exposed_databases.top_engines ranks up to 15 engines${firstOf(data.top_engines, "engine", "hosts", "services")}`,
+        data.top_countries !== undefined && `exposed_databases.top_countries ranks up to 10 countries${firstOf(data.top_countries, "country", "hosts", "services")}`,
+    ].filter((p) => typeof p === "string");
+    if (rankings.length)
+        sentences.push(`${listed(rankings)}, each by those services.`);
+    const gated = [
+        n("pii_likely") !== undefined && `exposed_databases.pii_likely (${n("pii_likely")}) counts services whose schema names pass a high-confidence gate for personal data`,
+        n("pci_likely") !== undefined && `exposed_databases.pci_likely (${n("pci_likely")}) counts services whose schema names pass a high-confidence gate for payment-card data`,
+    ].filter((p) => typeof p === "string");
+    if (gated.length) {
+        sentences.push(`${gated.join("; ")}. The names are index, database, table or field names in the Shodan or LeakIX banner or in the check's response, never record values, and the gate passes one unambiguous term (such as ssn or cardholder) or two distinct indicators. It is precision-first: a service whose names do not pass it is not counted, whatever it holds, so the other services are not shown to hold no personal or card data.`);
+    }
+    sentences.push(...lastCheck("exposed_databases", data));
+    sentences.push(...leftOut("exposed_databases", unknown, unusable));
+    return { data, sentences };
+}
+// ── leaked_credentials: GET /api/v1/public/leaked-credentials/stats (#2313 item 7) ──
+//
+// core-backend/internal/leakedcreds store.go Stats, over one row per (repository, secret):
+// obsID(repo, fingerprint), "one row per leaked secret per repo".
+//   total             COUNT(*): (repository, secret) pairs, so one secret in three
+//                     repositories counts three times; not distinct secrets
+//   distinct_secrets  COUNT(DISTINCT fingerprint);  distinct_repos  COUNT(DISTINCT repo)
+//   top_providers / top_types   COUNT(*) per group, LIMIT 15: pairs again
+// None is validated: detect.go says "verified" means STRUCTURALLY verified (a checksum or format
+// decode), never "confirmed live", and the radar never uses a credential it finds.
+//   last_run_at       the radar's last completed check, its own KeyLeakedCreds row, written at
+//                     the END of a cycle that read the event stream (#2335; see LAST_CHECK).
+const LEAKED_CREDS_SPEC = {
+    counts: ["total", "distinct_secrets", "distinct_repos"],
+    rows: {
+        top_providers: { required: { provider: "string", count: "number" } },
+        top_types: { required: { secret_type: "string", count: "number" } },
+    },
+    instants: ["generated_at", "last_run_at"],
+};
+function readLeakedCredentials(body) {
+    const { data, unknown, unusable } = readRadar(body, LEAKED_CREDS_SPEC);
+    const sentences = [];
+    const n = (k) => numIn(data, k);
+    const totals = [
+        n("total") !== undefined &&
+            `leaked_credentials.total (${n("total")}) counts (repository, secret) pairs, not distinct secrets: a secret committed to three repositories counts three times`,
+        n("distinct_secrets") !== undefined && `leaked_credentials.distinct_secrets (${n("distinct_secrets")}) counts each secret once`,
+        n("distinct_repos") !== undefined && `leaked_credentials.distinct_repos (${n("distinct_repos")}) counts public GitHub repositories`,
+    ].filter((p) => typeof p === "string");
+    if (totals.length)
+        sentences.push(`Leaked credentials: ${totals.join("; ")}.`);
+    const rankings = [
+        data.top_providers !== undefined && `leaked_credentials.top_providers ranks up to 15 providers${firstOf(data.top_providers, "provider", "count", "pairs")}`,
+        data.top_types !== undefined && `leaked_credentials.top_types ranks up to 15 secret types${firstOf(data.top_types, "secret_type", "count", "pairs")}`,
+    ].filter((p) => typeof p === "string");
+    if (rankings.length)
+        sentences.push(`${listed(rankings)}, each by the same (repository, secret) pairs.`);
+    if (totals.length || rankings.length) {
+        sentences.push("None of these is validated: each is a credential-shaped string in a public commit that passed EchelonGraph's filters, at most structurally checked (a checksum or format decode) and never tested against its provider, so none of them is a count of working credentials.");
+    }
+    sentences.push(...lastCheck("leaked_credentials", data));
+    sentences.push(...leftOut("leaked_credentials", unknown, unusable));
+    return { data, sentences };
+}
 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 = {};
+    const rowExtras = [];
+    for (const [key, label] of SHADOW_AI_ROWS) {
+        const r = countRows(field(stats, key), label);
+        if (take(key, r.rows)) {
+            observed[key] = rows[key] = r.rows;
+            rowExtras.push(...r.extra.map((x) => `stats.${key}[].${x}`));
         }
     }
-    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)`}. Of the shadow_ai numbers, 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}`),
+        ...rowExtras,
+    ];
+    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.");
+    sentences.push(...leftOut("shadow_ai", unknown, unusable));
+    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: 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); leaked credentials sampled from public GitHub push events; and shadow AI services found through Certificate Transparency logs and Shodan and then checked by EchelonGraph's identified probes. Every number in the result is labelled here and in the result's note by what it counts; a field this version cannot label is left out and named in the note. ` +
+    `kev_exposure: kev_exposure.distinct_hosts counts distinct ip:port services, not machines (a machine answering on two ports counts twice), with at least one CISA-KEV-listed CVE on record, and kev_exposure.ransomware_hosts those with a ransomware-linked one; kev_exposure.kev_cves_exposed and kev_exposure.ransomware_cves count distinct CVEs with at least one such service; kev_exposure.correlations counts service×CVE pairs, not services, so a service with three KEV CVEs counts three times. kev_exposure.top_products, kev_exposure.top_countries and kev_exposure.top_cves rank up to 12 products, 10 countries and 12 CVEs by those services; kev_exposure.top_cves[].cvss_v3_score and kev_exposure.top_cves[].epss_score are the highest CVSS v3 base score and EPSS probability recorded on that CVE's observations. kev_exposure.trend counts service×CVE pairs still on record by the week in which each was first recorded, over 12 weeks, so earlier weeks read low. kev_exposure.newest_kev lists the 15 CVEs that EchelonGraph's CVE records most recently mark as CISA-KEV-listed, each with an exposure_state: exposed, where kev_exposure.newest_kev[].exposed_hosts counts distinct ip:port services on record with it; or not_assessed, where the API's answer holds no measurement for that CVE (its 0 is not one) and no count is relayed, and cve_exposure says per CVE whether the radar tracks it. kev_exposure.newest_kev[].cvss_v3_score and kev_exposure.newest_kev[].epss_score are the CVE record's CVSS v3 base score and EPSS probability. ` +
+    `exposed_databases: exposed_databases.distinct_hosts counts distinct ip:port services the check confirmed answering without authentication, and exposed_databases.engines the distinct engine types among them; exposed_databases.top_engines and exposed_databases.top_countries rank up to 15 engines and 10 countries by those services. exposed_databases.pii_likely and exposed_databases.pci_likely count services whose schema names (never record values) pass a high-confidence, precision-first gate for personal or payment-card data, so a service outside them is not shown to hold no such data. ` +
+    `leaked_credentials: leaked_credentials.total counts (repository, secret) pairs, not distinct secrets, so one secret in three repositories counts three times; leaked_credentials.distinct_secrets counts each secret once and leaked_credentials.distinct_repos counts repositories; leaked_credentials.top_providers and leaked_credentials.top_types rank up to 15 providers and secret types by those pairs. None is validated: each is a credential-shaped string that passed EchelonGraph's filters, at most structurally checked and never tested against its provider. Each of those three radars also carries generated_at, when the API computed its totals, and, when the API can tell, last_run_at. kev_exposure.last_run_at, exposed_databases.last_run_at and leaked_credentials.last_run_at are timestamps, not counts: each is when that radar last completed a check, a cycle whose reads succeeded, among them a Shodan search (for exposed_databases, or its LeakIX fallback) that answered at least one query, or for leaked_credentials a read of the public GitHub event stream. A cycle that read nothing does not move it, and it is not the time of every record a radar's numbers count, which cover everything still on record, not only what the last check found. A radar whose answer carries no last_run_at has none in the result, and the note says nothing about it. ` +
+    `shadow_ai: the result is regrouped by what each number counts. 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. Of the shadow_ai numbers, 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)));
@@ -473,9 +962,20 @@ server.tool("exposure_radar", `Aggregate totals from EchelonGraph's internet-exp
                 isError: true,
             };
         }
-        const shadow = readShadowAI(data.shadow_ai);
-        data.shadow_ai = shadow.data;
-        return succeeded(data, `${okHead(tool)} All ${RADARS.length} radars answered: ${RADARS.map(([name]) => name).join(", ")}. ${shadow.sentences.join(" ")} ${RADAR_SOURCES} ${SHODAN_OWNERSHIP} Each radar refreshes on its own schedule.`);
+        // Each radar's answer is relayed cut to the fields its reader can label, in RADARS order.
+        const read = {
+            kev_exposure: readKEVExposure(data.kev_exposure),
+            exposed_databases: readExposedDatabases(data.exposed_databases),
+            leaked_credentials: readLeakedCredentials(data.leaked_credentials),
+            shadow_ai: readShadowAI(data.shadow_ai),
+        };
+        const relayed = {};
+        const sentences = [];
+        for (const [name] of RADARS) {
+            relayed[name] = read[name].data;
+            sentences.push(...read[name].sentences);
+        }
+        return succeeded(relayed, `${okHead(tool)} All ${RADARS.length} radars answered: ${RADARS.map(([name]) => name).join(", ")}. Every number relayed is labelled below by what it counts, and a field this version cannot label is left out and named. ${sentences.join(" ")} ${RADAR_SOURCES} ${SHODAN_OWNERSHIP} Each radar refreshes on its own schedule.`);
     }
     catch (e) {
         return crashed(tool, e);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "echelongraph-mcp",
-  "version": "1.0.2",
+  "version": "1.0.4",
   "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",
@@ -36,7 +36,10 @@
   "homepage": "https://echelongraph.io/pulse/mcp",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/echelongraph/EchelonGraph.git"
+    "url": "git+https://github.com/echelongraph/echelongraph-mcp.git"
+  },
+  "bugs": {
+    "url": "https://github.com/echelongraph/echelongraph-mcp/issues"
   },
   "engines": {
     "node": ">=18"

package/server.json

@@ -4,12 +4,16 @@
   "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",
+  "repository": {
+    "url": "https://github.com/echelongraph/echelongraph-mcp",
+    "source": "github"
+  },
+  "version": "1.0.4",
   "packages": [
     {
       "registryType": "npm",
       "identifier": "echelongraph-mcp",
-      "version": "1.0.2",
+      "version": "1.0.4",
       "transport": {
         "type": "stdio"
       },