echelongraph-mcp 2.7.2 → 3.0.2

package/dist/tools/scan_manifest.js

@@ -1,6 +1,6 @@
 import * as z from "zod";
-import { TEXT_BUDGET_DESCRIPTION } from "../textBudget.js";
-import { sbomText } from "./check_sbom.js";
+import { answering, FULL_ARG, TEXT_BUDGET_DESCRIPTION } from "../textBudget.js";
+import { sbomData, sbomText } from "./check_sbom.js";
 import { FORMAT_NAMES, FORMATS, NOT_CHECKED_REASONS, detect, readFile } from "./manifests/index.js";
 import { CLEAN_NOTE, DISTRO_NOTE, FRESHNESS_NOTE, MAX_PURLS, MEASURED_AT_NOTE, METHOD, batchDataShape, dedupe, field, plural, purlsRefusal, sendBatches, sendingCoverage, sendingCoverageShape, sendingSentences, verdictSentences, } from "./match_batch.js";
 export const SCAN_MANIFEST = "scan_manifest";
@@ -22,12 +22,20 @@ export const SCAN_MANIFEST_DESCRIPTION = "Check a project's lockfile or pinned m
     " Cut, each row keeps index, purl, verdict, not_assessed_reason and cve_ids at least; not_checked keeps its first 20.";
 // The text's cut: check_sbom's rows and levels, and data.not_checked beside them, cut to its
 // first TEXT_NOT_CHECKED once the first level does not fit (structuredContent.data keeps it whole).
+// #3132's second review: check_sbom's sentence on not_sent_purls says a second call can send them
+// without reading the list, from their positions in the input; here those positions index purls
+// read from the files, which a client cannot rebuild, so the sentence names full: true instead.
 export function manifestText(sent) {
     const sbom = sbomText(sent);
     return {
         ...sbom,
         sides: [
-            ...(sbom.sides ?? []),
+            ...(sbom.sides ?? []).map((side) => side.list === "not_sent_purls"
+                ? {
+                    ...side,
+                    said: (_inText, total) => `The ${total} purls not sent are the purls this tool read from position ${sent + 1} on, counted in the order the note gives for them; structuredContent.data.not_sent_purls lists every one with full: true.`,
+                }
+                : side),
             {
                 list: "not_checked",
                 cap: TEXT_NOT_CHECKED,
@@ -37,6 +45,9 @@ export function manifestText(sent) {
         page: (shown) => `To read every row in the text, pass files that hold ${shown} or fewer distinct purls per call.`,
     };
 }
+// #3013: the structured result's cut, check_sbom's (sbomData: the lists beside the rows, then every
+// row thinned, then rows leaving, clean ones first) with not_checked beside not_sent_purls.
+const MANIFEST_DATA = sbomData(["not_sent_purls", "not_checked"], (k) => `To read every row in data, pass files that hold ${k} or fewer distinct purls per call.`);
 export function readFiles(a) {
     if (!Array.isArray(a.files))
         return "files must be a list of {filename, content}";
@@ -79,8 +90,13 @@ export function readFiles(a) {
         out.skipped = r.skipped;
         out.notes = r.notes;
         out.replaced = r.replaced ?? [];
-        all.push(...r.pinned.map((x) => x.purl));
-        notChecked.push(...r.not_checked.map((x) => ({ file: f.filename, ...x })));
+        // One by one, never push(...list): a 5,000,000-character requirements.txt of unpinned lines
+        // is some 170,000 entries, and, spread into push() as that many arguments, they overflowed
+        // V8's stack ("Maximum call stack size exceeded", #3013's review): the call crashed.
+        for (const p of r.pinned)
+            all.push(p.purl);
+        for (const n of r.not_checked)
+            notChecked.push({ file: f.filename, ...n });
     }
     if (files.every((f) => !f.read))
         return `no file could be read: ${files.map((f) => `${f.filename}: ${f.refused}`).join("; ")}`;
@@ -112,9 +128,13 @@ function noteFor(head, x, d, g) {
     const nc = x.not_checked.length;
     if (nc) {
         const parts = NOT_CHECKED_REASONS.filter((r) => by[r] > 0).map((r) => `${r} ${by[r]}`);
-        out.push(`${plural(nc, "entry was", "entries were")} NOT checked and ${nc === 1 ? "is" : "are"} not clean (${parts.join(", ")}): data.not_checked lists each with its file, line and reason, and none was sent to the API.`);
+        // #3013's review: the note is written before the structured result is cut, and a DATA CUT can
+        // cut data.not_checked (it goes before any row), so this says the list is whole with full:
+        // true, as the sentence on data.not_sent_purls does (match_batch.ts sendingSentences); the
+        // counts above are coverage.not_checked_by_reason's, which no cut touches.
+        out.push(`${plural(nc, "entry was", "entries were")} NOT checked and ${nc === 1 ? "is" : "are"} not clean (${parts.join(", ")}): data.not_checked lists each with its file, line and reason, whole with full: true (past the structured result's budget, that list can be cut by default), and none was sent to the API.`);
     }
-    out.push(...sendingSentences(g, x.purls.length, READ_ORDER, "check_sbom with purls set to"));
+    out.push(...sendingSentences(g, x.purls.length, READ_ORDER, "check_sbom with purls set to", false));
     if (d === null)
         return { note: out.join(" "), assessed: 0 };
     const v = verdictSentences(d, g);
@@ -231,11 +251,15 @@ export function scanManifestOutput(envelopeSchema) {
         freshness: null,
     });
 }
+// One output schema per process, not per request (3.0.2; index.ts envelopeSchema says why).
+const OUTPUTS = new WeakMap();
 // A literal server.registerTool(name, { title, description, … }) call with constant strings:
 // marketing-site lib/mcpToolClaims.test.ts reads it here (it follows index.ts's call to this
 // function) and holds the /pulse/mcp row to this title and description.
 export function registerScanManifest(server, deps) {
-    const output = scanManifestOutput(deps.envelopeSchema);
+    const envelope = deps.envelopeSchema;
+    const output = OUTPUTS.get(envelope) ?? scanManifestOutput(envelope);
+    OUTPUTS.set(envelope, output);
     server.registerTool(SCAN_MANIFEST, {
         title: SCAN_MANIFEST_TITLE,
         description: SCAN_MANIFEST_DESCRIPTION,
@@ -247,11 +271,12 @@ export function registerScanManifest(server, deps) {
                 format: formatEnum.optional().describe("the format to read the file as, when its name does not say"),
             }))
                 .describe("1 to 20 files, up to 5,000,000 characters of content in all; read by this MCP server into purls, and only the purls are sent to the API; over the hosted endpoint (mcp.echelongraph.io) the files are the request body"),
+            full: FULL_ARG,
         }),
         outputSchema: output,
         annotations: deps.annotations,
-    }, async (a, ctx) => {
+    }, async (a, ctx) => answering(a.full, MANIFEST_DATA, async () => {
         const run = scanManifest({ ...deps, signal: ctx.mcpReq.signal }, a);
         return deps.checked(SCAN_MANIFEST, output, await (deps.hold ? deps.hold(run) : run));
-    });
+    }));
 }

package/dist/tools/vendor_advisories.js

@@ -59,7 +59,7 @@
 // Logic only: the envelope, the failure contract and the API call are index.ts's, handed in as
 // a VendorAdvisoryKit so this file cannot drift from them.
 import * as z from "zod";
-import { TEXT_BUDGET_DESCRIPTION } from "../textBudget.js";
+import { answering, FULL_ARG, NO_DATA_CUT, TEXT_BUDGET_DESCRIPTION, wholePage } from "../textBudget.js";
 // core-backend vendoradv.SearchHeader.
 export const VENDOR_ADVISORY_SEARCH_HEADER = "X-EG-Advisory-Search";
 // handler.go List caps the search at 100 bytes; a longer term would be cut, possibly inside a
@@ -317,8 +317,8 @@ const ROW_CUT_LEVELS = [
     { keep: ["vendor", "vendor_advisory_id", "title", "severity", "cve_ids", "vendor_published_at", "withdrawn", "rejected_cve_ids", "remediation_kinds", "remediation_state"], clip: 100, cap: 10 },
 ];
 // get_vendor_advisory's own first text block is cut too past the budget (#2802): only its
-// structuredContent.data is one advisory whole.
-const WHOLE = "get_vendor_advisory returns any one of these advisories by its vendor and vendor_advisory_id, whole in its structuredContent.data, and in its first text block with every field (past 30,000 characters, each list cut to its first entries).";
+// structuredContent.data is one advisory whole, with full: true (#3013).
+const WHOLE = "get_vendor_advisory returns any one of these advisories by its vendor and vendor_advisory_id, whole in its structuredContent.data with full: true, and in its first text block with every field (past 30,000 characters, each list cut to its first entries).";
 const FOR_CVE_TEXT = { rows: "advisories", levels: ROW_CUT_LEVELS, whole: WHOLE };
 const searchText = (a) => ({
     rows: "advisories",
@@ -326,9 +326,37 @@ const searchText = (a) => ({
     whole: WHOLE,
     page: (shown, _rows, d) => `To read the rows left out in the text, call search_vendor_advisories again with the same arguments and offset ${(num(d, "offset") ?? a.offset ?? 0) + shown}; a page of ${shown} rows or fewer like these fits the text without leaving rows out.`,
 });
+// #3013: the structured result's cut. A production row is up to about 1,700 characters of compact
+// JSON, 782 of them its affected_products, so search_vendor_advisories "log4j" at its default page
+// was 38,733 characters of structured result. Before any row leaves, every row is thinned: first
+// without affected_products, then without summary too (get_vendor_advisory returns one whole);
+// only then do rows leave data from the end, and the note gives the offset to read them from. The
+// by-CVE answer (at most 20 advisories, 12,652 characters for CVE-2021-44228) is cut the same way.
+const ADVISORY_ROW_THIN = [
+    [
+        "vendor", "vendor_display_name", "vendor_advisory_id", "advisory_id", "title", "severity", "cvss_v3_score", "cve_ids", "summary", "vendor_published_at", "our_first_seen_at", "withdrawn",
+        "rejected_cve_ids", "remediation_kinds", "remediation_state",
+    ],
+    ["vendor", "vendor_advisory_id", "title", "severity", "cvss_v3_score", "cve_ids", "vendor_published_at", "withdrawn", "rejected_cve_ids", "remediation_kinds", "remediation_state"],
+];
+const FOR_CVE_DATA = { steps: [{ lists: ["advisories"], thin: ADVISORY_ROW_THIN }] };
+// The page size the note says fits data whole is counted on the rows whole (#3013's review: it was
+// the number of thinned rows kept, and a page of that many came back thinned again).
+const SEARCH_DATA = {
+    steps: [{ lists: ["advisories"], thin: ADVISORY_ROW_THIN }],
+    page: (t, d, at) => {
+        const k = t.advisories?.returned;
+        if (!k || !t.advisories || k === t.advisories.total)
+            return "";
+        return `To read the rows past the first ${k} in data, call search_vendor_advisories again with the same arguments and offset ${(num(d, "offset") ?? 0) + k}; ${wholePage(at.wholeFit("advisories"))}`;
+    },
+};
 const ROW_CUT_DESCRIPTION = " Cut, each row keeps vendor, vendor_advisory_id, title, severity and cve_ids at least, its strings and lists shortened";
-export function registerVendorAdvisoryTools(server, kit) {
-    const FOR_CVE_OUTPUT = kit.envelopeSchema({
+// The three tools' output schemas, one each per process, not per request (3.0.2; index.ts
+// envelopeSchema says why).
+const OUTPUTS = new WeakMap();
+function outputsOf(envelopeSchema) {
+    const FOR_CVE_OUTPUT = envelopeSchema({
         data: z.looseObject({
             cve_id: opt(z.string()),
             advisories: opt(z.array(AdvisoryRow)),
@@ -348,7 +376,7 @@ export function registerVendorAdvisoryTools(server, kit) {
         }),
         freshness: null,
     });
-    const DETAIL_OUTPUT = kit.envelopeSchema({
+    const DETAIL_OUTPUT = envelopeSchema({
         data: AdvisoryRow.extend({
             description: opt(z.string()),
             known_cve_ids: opt(z.array(z.string())).describe("The CVE IDs of cve_ids that have a record in EchelonGraph's CVE feed."),
@@ -377,7 +405,7 @@ export function registerVendorAdvisoryTools(server, kit) {
         }),
         freshness: null,
     });
-    const SEARCH_OUTPUT = kit.envelopeSchema({
+    const SEARCH_OUTPUT = envelopeSchema({
         data: z.looseObject({
             advisories: opt(z.array(AdvisoryRow)),
             total: opt(z.number()).describe("The matches; when total_capped is true, a lower bound: 1,000 or more."),
@@ -399,6 +427,12 @@ export function registerVendorAdvisoryTools(server, kit) {
         }),
         freshness: null,
     });
+    return { FOR_CVE_OUTPUT, DETAIL_OUTPUT, SEARCH_OUTPUT };
+}
+export function registerVendorAdvisoryTools(server, kit) {
+    const outputs = OUTPUTS.get(kit.envelopeSchema) ?? outputsOf(kit.envelopeSchema);
+    OUTPUTS.set(kit.envelopeSchema, outputs);
+    const { FOR_CVE_OUTPUT, DETAIL_OUTPUT, SEARCH_OUTPUT } = outputs;
     // The vendors' windows, read beside a tool's own request. Never a failure of the tool.
     async function readWindows() {
         const r = await kit.api(VENDOR_COVERAGE_PATH);
@@ -617,20 +651,21 @@ export function registerVendorAdvisoryTools(server, kit) {
     server.registerTool("vendor_advisories_for_cve", {
         title: "Vendor advisories for one CVE",
         description: `The vendor-published advisories that name one CVE, newest first, at most 20: for each, vendor, vendor_display_name, vendor_advisory_id, title, severity and cvss_v3_score where the vendor gives them. Covers the vendor feeds EchelonGraph polls, for example Microsoft MSRC, Red Hat, Cisco, Palo Alto Networks and GitHub GHSA; an empty answer means none of the advisories EchelonGraph holds names the CVE, not that no vendor published one. ${DATES_DESCRIPTION} ${REJECTED_CVE_DESCRIPTION} The answer's cve_rejected is true when the CVE record of the CVE asked for was rejected. Each row has remediation_kinds and remediation_state (not_parsed is not none). coverage gives returned, cap, at_cap (true: there may be more) and cve_year; vendor_windows, each vendor's held window: ${WINDOW_HEAD}; and vendors_not_fully_held, the vendors absent from the answer of which EchelonGraph holds none, whose held_since is after 1 January of cve_year or not known, or whose history is still being read, which the note names. ${NOT_HELD_HEAD} ${TEXT_BUDGET_DESCRIPTION}${ROW_CUT_DESCRIPTION}.`,
-        inputSchema: z.object({ cve_id: z.string().describe("a CVE ID, e.g. CVE-2024-21412") }),
+        inputSchema: z.object({ cve_id: z.string().describe("a CVE ID, e.g. CVE-2024-21412"), full: FULL_ARG }),
         outputSchema: FOR_CVE_OUTPUT,
         annotations: kit.annotations,
-    }, async ({ cve_id }) => kit.checked("vendor_advisories_for_cve", FOR_CVE_OUTPUT, await forCVE(cve_id)));
+    }, async ({ cve_id, full }) => kit.checked("vendor_advisories_for_cve", FOR_CVE_OUTPUT, await answering(full, FOR_CVE_DATA, () => forCVE(cve_id))));
     server.registerTool("get_vendor_advisory", {
         title: "Vendor advisory detail",
         description: `One vendor advisory in full, by vendor and the vendor's advisory ID (the vendor and vendor_advisory_id of a vendor advisory row): title, description, severity, cvss_v3_score, cve_ids and known_cve_ids (those with a record in EchelonGraph's CVE feed), affected_products, remediation, references, vendor_modified_at, and withdrawn_at and withdrawn_reason when the vendor withdrew it. remediations lists each remediation the vendor lists, with kind (the vendor's own category, never read from the text: vendor_fix, workaround, mitigation, no_fix_planned, none_available or other), source_category, text, url and the cve_ids and product_ids it covers; each text is the vendor's, verbatim, untested by EchelonGraph. remediation_state is parsed, none_in_source, not_parsed or withdrawn: none_in_source and not_parsed are not a finding that no fix exists. ${DATES_DESCRIPTION} ${REJECTED_CVE_DESCRIPTION} coverage.vendor_window is that vendor's window in what EchelonGraph holds: ${WINDOW_HEAD}; null when the windows could not be read or carry none for that vendor. measured_at is our_first_seen_at. ${ENVELOPE_DESCRIPTION} ${TEXT_BUDGET_DESCRIPTION}`,
         inputSchema: z.object({
             vendor: z.string().describe("the vendor slug, e.g. microsoft, redhat, github"),
             advisory_id: z.string().describe("the vendor's advisory ID, e.g. RHSA-2024:1234 or GHSA-xxxx-xxxx-xxxx"),
+            full: FULL_ARG,
         }),
         outputSchema: DETAIL_OUTPUT,
         annotations: kit.annotations,
-    }, async ({ vendor, advisory_id }) => kit.checked("get_vendor_advisory", DETAIL_OUTPUT, await detail(vendor, advisory_id)));
+    }, async ({ vendor, advisory_id, full }) => kit.checked("get_vendor_advisory", DETAIL_OUTPUT, await answering(full, NO_DATA_CUT, () => detail(vendor, advisory_id))));
     server.registerTool("search_vendor_advisories", {
         title: "Search vendor advisories",
         description: `Search or list vendor-published advisories, newest first. ${SEARCH_MATCH_HEAD} Filter by vendor (slug), severity band and whether the advisory names any CVE ID. Advisories their vendor withdrew are left out. Returns advisories, each with vendor, vendor_advisory_id, title, severity, cvss_v3_score, cve_ids, summary and affected_products where present, and total, total_capped, limit, offset, search_applied and search_match. ${TOTAL_CAPPED_HEAD} ${REJECTED_CVE_DESCRIPTION} The query is sent in a request header, never in the URL. coverage repeats those beside returned, and gives vendor_windows, each vendor's window in what EchelonGraph holds: ${WINDOW_HEAD}. ${NOT_HELD_HEAD} ${TEXT_BUDGET_DESCRIPTION}${ROW_CUT_DESCRIPTION}, or rows are left out and the note gives the offset to call next.`,
@@ -641,8 +676,9 @@ export function registerVendorAdvisoryTools(server, kit) {
             has_cve: z.boolean().optional().describe("true: only advisories naming a CVE; false: only those naming none"),
             limit: z.number().int().min(1).max(50).optional().describe("page size (default 20, max 50)"),
             offset: z.number().int().min(0).max(10000).optional().describe("rows to skip (default 0)"),
+            full: FULL_ARG,
         }),
         outputSchema: SEARCH_OUTPUT,
         annotations: kit.annotations,
-    }, async (a) => kit.checked("search_vendor_advisories", SEARCH_OUTPUT, await search(a)));
+    }, async (a) => kit.checked("search_vendor_advisories", SEARCH_OUTPUT, await answering(a.full, SEARCH_DATA, () => search(a))));
 }

package/docs/exposure-radar.md

@@ -0,0 +1,181 @@
+# How `exposure_radar` counts
+
+Part of the [echelongraph-mcp README](../README.md): every number `exposure_radar` relays, radar by
+radar, and what it counts. It is kept out of the README because npm keeps only the first 65,536
+characters of a package's README, and the package ships it in `docs/`. Exposure counts are derived
+from Shodan data. Shodan data is owned by Shodan, which holds its copyright (© Shodan).
+
+`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](tools.md#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. |
+| `kev_exposure.window.from`, `kev_exposure.window.to` | Timestamps, not counts: when Shodan collected the banners of the oldest and the newest of the service×CVE pairs counted, Shodan's own times, not when EchelonGraph stored or re-checked a pair; a span of observations made at different times. Relayed only when every counted pair has such a time; otherwise the note says how many do not. |
+
+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.window.from`, `exposed_databases.window.to` | Timestamps, not counts: when EchelonGraph's check last confirmed the oldest and the newest of the services counted answering without authentication, a span of checks made at different times. Relayed only when every counted service has such a time; otherwise the note says how many do not. |
+| `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.window.from`, `leaked_credentials.window.to` | Timestamps, not counts: when EchelonGraph's detector last found the oldest and the newest of the (repository, secret) pairs counted in a public commit. |
+| `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. |
+| `confirmed_exposed.window.from`, `confirmed_exposed.window.to` | Timestamps, not counts: when EchelonGraph's verifier ran the probe that last decided the oldest and the newest of the confirmed-exposed services, a span of probes made at different times. Relayed only when every one has such a time. |
+| `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. The `poller` block's keys are
+checked the same way: a key this version does not know is left out and named, while the
+instance fields it knows are left out as the README's [What a result means](../README.md#what-a-result-means)
+describes.
+
+## `mcp_servers`
+
+The AI-exposure radar's MCP-server verdicts, from `GET /api/v1/public/ai-exposure/stats?service=mcp`.
+Every hostname was named like an MCP server in EchelonGraph's own Certificate Transparency
+feed, matched by hostname pattern; no Shodan data is used. Each is checked by EchelonGraph's
+identified MCP probe: a `server/discover` request, and `initialize` only if that is refused. It
+never sends `tools/call`. The answer is counts and timestamps only, with no hostname, version or
+server name, and the tool repeats no string it carries but its timestamps. Each hostname is
+counted once, by its latest verdict on record. EchelonGraph's own control servers are left
+out, and so is every hostname whose owner opted out of scanning, since it is not checked again
+while the opt-out stands and its last verdict cannot be re-checked. The unit is a hostname, not an ip:port service.
+
+| Field | What it counts |
+|---|---|
+| `mcp_servers.total` | Hostnames the radar has checked for an MCP server, each once, by its latest verdict on record. Not every one is an MCP server: see `mcp_servers.not_assessed_by_reason`. It is `mcp_servers.protected` + `mcp_servers.pending_readjudication` + `mcp_servers.not_assessed`. |
+| `mcp_servers.protected` | Hostnames whose `/mcp` endpoint asked for credentials (a 401 or 403) and whose OAuth protected-resource metadata validated under RFC 9728: a 200 JSON document whose resource is identical to the server's identifier and that names at least one authorization server. |
+| `mcp_servers.prm_via.header`, `mcp_servers.prm_via.wellknown_path`, `mcp_servers.prm_via.wellknown_root` | The protected ones, by where that document was found: the same-origin URL the credential challenge named; `/.well-known/oauth-protected-resource` followed by the endpoint's path; or `/.well-known/oauth-protected-resource` itself. They add up to `mcp_servers.protected`. |
+| `mcp_servers.pending_readjudication` | Verdicts decided by a rule EchelonGraph has since replaced and not yet re-checked under the current rules. They are in neither `mcp_servers.protected` nor `mcp_servers.not_assessed`. |
+| `mcp_servers.not_assessed` | The rest, whose protection the radar could not assess. Not assessed does not mean unprotected. `mcp_servers.not_assessed_by_reason` puts each of them in exactly one bucket (below). |
+| `mcp_servers.own_controls_excluded` | EchelonGraph's own control servers, left out of every other `mcp_servers` number. |
+| `mcp_servers.withheld_opted_out` | Hostnames whose owner opted out of scanning, left out of every other `mcp_servers` number. Such a hostname is not checked again while the opt-out stands, so its last verdict cannot be re-checked; the API's unparameterised answer withholds the same hostnames under the same name. An answer that does not carry this field (an API that predates it) counted them, and the note says so. |
+| `mcp_servers.window.from`, `mcp_servers.window.to` | Timestamps, not counts: when the oldest and the newest of the verdicts counted were last checked. The counts are each hostname's latest verdict, not one sweep at one time. With no verdict counted there is no window. |
+| `mcp_servers.last_run_at` | A timestamp, not a count: when the AI-exposure radar, which checks other AI services as well as MCP servers, last completed a check (a cycle whose reads succeeded and whose scan opt-out register answered). It is not the time of every verdict counted. |
+| `mcp_servers.enabled` | Whether the API reports the radar running: true when a check completed within 45 minutes of its answer. |
+| `mcp_servers.counted_at` | A timestamp, not a count: when the API read these counts. |
+
+`mcp_servers.not_assessed_by_reason` divides `mcp_servers.not_assessed`:
+
+| Bucket | What it holds |
+|---|---|
+| `mcp_servers.not_assessed_by_reason.identified_no_challenge` | Servers that identified themselves as MCP servers (a DiscoverResult, an InitializeResult, or the endpoint event of the deprecated HTTP+SSE transport) and did not ask for credentials at the handshake. That is normal in MCP: authorization is optional in the spec, and a server can enforce it at `tools/call` instead, which EchelonGraph never sends. So this bucket is not a finding of exposure. |
+| `mcp_servers.not_assessed_by_reason.resource_mismatch` | An endpoint that asked for credentials, whose metadata document's resource is absent or not identical to the server's identifier. |
+| `mcp_servers.not_assessed_by_reason.cross_origin_pointer` | An endpoint that asked for credentials, whose challenge named a metadata URL on another origin, which EchelonGraph records and does not request. |
+| `mcp_servers.not_assessed_by_reason.bare_challenge_no_prm` | An endpoint that asked for credentials, whose challenge named no metadata URL, and neither well-known URI answered 2xx. |
+| `mcp_servers.not_assessed_by_reason.pointer_unreachable` | An endpoint that asked for credentials, whose same-origin metadata URL did not answer 2xx in full. |
+| `mcp_servers.not_assessed_by_reason.pointer_invalid` | An endpoint that asked for credentials, whose challenge's metadata pointer is not a URL EchelonGraph will request. |
+| `mcp_servers.not_assessed_by_reason.no_authorization_servers` | An endpoint that asked for credentials, whose metadata document names no authorization server. |
+| `mcp_servers.not_assessed_by_reason.wellknown_unreachable` | An endpoint that asked for credentials, where a well-known metadata request got no complete HTTP answer. |
+| `mcp_servers.not_assessed_by_reason.metadata_invalid` | An endpoint that asked for credentials, whose metadata answer is not a 200 with a JSON object within the size cap. |
+| `mcp_servers.not_assessed_by_reason.challenge_unadjudicated` | An endpoint that asked for credentials before EchelonGraph read RFC 9728 metadata, not re-checked since. |
+| `mcp_servers.not_assessed_by_reason.no_http_answer` | Hostnames that gave no HTTP answer: DNS, TCP or TLS failed, or the request timed out. Not a count of MCP servers. |
+| `mcp_servers.not_assessed_by_reason.not_identified_as_mcp` | Hostnames that answered HTTP with nothing that identified an MCP server: a login or error page, a body that is not JSON-RPC, a 4xx or 5xx. Not a count of MCP servers. |
+
+The eight credential-challenge buckets hold endpoints that asked for credentials: only their
+metadata did not validate, so none of them is shown to lack protection.
+
+`mcp_servers.era` and `mcp_servers.transport` each divide every counted hostname, so each adds
+up to `mcp_servers.total`:
+
+| Bucket | What it holds |
+|---|---|
+| `mcp_servers.era.legacy` | An initialize-era server: an InitializeResult, or the endpoint event of the deprecated HTTP+SSE transport. |
+| `mcp_servers.era.dual` | A server that answered `server/discover` and itself named an initialize-era version too. A lower bound: a server built on the reference SDK names only modern versions there, and is counted modern. |
+| `mcp_servers.era.modern` | A server that answered `server/discover` and named no initialize-era version. Not proven modern-only: EchelonGraph does not send it `initialize` to tell. |
+| `mcp_servers.era.unknown` | Nothing identified an era; every credential challenge is here. |
+| `mcp_servers.era.not_measured` | A verdict recorded before EchelonGraph's probe began recording the era, not re-checked since. |
+| `mcp_servers.transport.streamable_http` | Identified by a POST to `/mcp`. |
+| `mcp_servers.transport.legacy_sse` | Identified by the endpoint event of `GET /sse`, the deprecated HTTP+SSE transport. |
+| `mcp_servers.transport.unknown` | Nothing identified a transport. |
+| `mcp_servers.transport.not_measured` | Recorded before the era probe, not re-checked since. |
+
+The tool refuses the answer, as a failure of that radar and never as zeros, when it does not say
+`service` `mcp` (an API older than `?service=mcp` ignores the parameter and answers its counts
+over every AI service it checks), when `mcp_servers.total`, `mcp_servers.protected`,
+`mcp_servers.pending_readjudication` or `mcp_servers.not_assessed` is missing or not a whole
+number, or when they contradict each other. A partition whose buckets are not exactly those
+above, each a whole number adding up to the count it divides, is left out whole and named. A
+field this version does not know is left out, and named only when its name is shaped like a
+field name.

package/docs/rate-limits.md

@@ -0,0 +1,50 @@
+# echelongraph-mcp: rate limits
+
+Part of the README's [Rate limits](../README.md#rate-limits), in full: every limit the API and the
+hosted endpoint apply, path by path, and what a tool answers past each. It is kept out of the README
+because npm keeps only the first 65,536 characters of a package's README, and the package ships it
+in `docs/`.
+
+No API key, so the API limits each caller, one IPv4 address or one IPv6 /64 network as its
+platform records it. Its WAF counts all your requests together in a 60-second window and
+refuses one once the count passes the ceiling for its path:
+
+| Path | Ceiling per minute | Tools |
+|---|---|---|
+| `/api/v1/public/cves` and every path under it | 12,000 | `cve_summary`, `search_cves`, `get_cve`, `epss_history`, `cve_intel`, `cve_remediation`, `check_affected`, `check_sbom`, `scan_manifest` |
+| `/api/v1/public/cwes`, `/api/v1/public/vendor-advisories`, `/api/v1/public/kev/recent`, `/api/v1/public/shadow-ai-radar` | 6,000 | `get_cwe`, the three vendor-advisory tools, `kev_recent`, and one of `exposure_radar`'s five calls |
+| any other `/api/v1/public` path | 600 | `cve_exposure`, and the rest of `exposure_radar`'s calls |
+
+Because the count is shared, heavy use of one path also uses up the lower ceilings. On top of
+that, 500 requests per second per caller is a burst cap on each serving instance, and
+`check_sbom`'s and `scan_manifest`'s batch route is charged per component: 1,200 components a minute per caller.
+Over a limit the API answers 429 with `Retry-After`, and the tool returns a failure
+(`state` `failed`, `error.status` 429), never empty data. `check_sbom` and `scan_manifest` are the exception: each
+sends a long list as batches of 200, waits out a 429's `Retry-After` and sends the batch again,
+within 50 seconds per call (MCP clients time a call out at about 60 s). From a fresh budget a
+list of up to 1,200 distinct purls finishes in one call; a longer one (the cap is 2,000) is
+checked in two calls a minute apart. When a wait would pass the 50 seconds, it
+answers the batches it has as `measured` with `coverage.partial` true and the rest counted in
+`coverage.not_sent` (`not_sent_reason` `time_budget`); only a 429 on the first batch is a failure. The API's own documentation of these
+limits: <https://echelongraph.io/pulse/api>.
+
+The hosted endpoint adds its own limit before the API's: 120 MCP requests a minute per client
+address, counted by each server instance, answered over it with HTTP 429, `Retry-After` and a
+JSON-RPC error (code `-32029`) that names the limit and the seconds to wait. A request body over
+64 KiB is refused (HTTP 413, code `-32600`), except a `tools/call` of `check_sbom` or
+`scan_manifest`, or a `prompts/get` of `sbom_review`, which may be up to 6 MiB: enough for a
+CycloneDX or SPDX document, or a call's lockfiles, at the tools' 5,000,000-character cap. Each server instance reads at most two such large bodies at
+once; a third is answered HTTP 503 with `Retry-After` and a JSON-RPC error (code `-32030`). Each
+instance serves at most 64 requests at once; the next waits up to 10 seconds for one to finish,
+and is then answered the same way. A `subscriptions/listen` stream, which stays open until its
+client leaves, is not one of the 64.
+
+A call whose client goes away (its own timeout, a closed tab) is stopped only once the server
+learns of it. Its API calls are then cancelled, `check_sbom` and `scan_manifest` send no further batch, and its
+large-body slot is freed. Over HTTP/1.1, Cloud Run does not pass a client's disconnect on to the
+server at all (<https://docs.cloud.google.com/run/docs/troubleshooting>). The hosted endpoint
+speaks HTTP/2 to Cloud Run, where the same page says a disconnect is passed on. Measured on
+2026-10-05, Cloud Run reset the stream of a client that stopped reading its answer 15 s in, and the
+call was logged as a client that closed. Whether a client that aborts mid-call is passed on at once
+has not been observed yet. Until it is, an abandoned `check_sbom` or `scan_manifest` call may run for up to its
+50-second budget and hold its slot that long.

package/docs/structured-results.md

@@ -0,0 +1,43 @@
+# echelongraph-mcp: the structured result, tool by tool
+
+Part of the README's [Structured results](../README.md#structured-results), which says what each
+envelope field and `state` means: here, tool by tool, what each one's `state`, `measured_at`,
+`coverage` and `freshness` hold. It is kept out of the README because npm keeps only the first
+65,536 characters of a package's README, and the package ships it in `docs/`. Exposure counts are
+derived from Shodan data. Shodan data is owned by Shodan, which holds its copyright (© Shodan).
+
+Every field comes from what the API sends; where the API does not say, the field is `null` and
+a note says so. Per tool:
+
+- `cve_summary` is `measured`, and its `measured_at` is `summary.last_updated`, the newest
+  modification time among the active CVE records it counts.
+- `search_cves` is `measured`, with `measured_at` `null`: each record carries its own times. Its
+  `coverage` repeats the list's `total`, `total_counted`, `total_is_lower_bound`,
+  `search_relaxed`, `limit` and `offset`, and adds `returned`, the rows in the page. When
+  `total_counted` is false the total is not a count, and the note does not call it one.
+- `get_cve` is `measured`, and its `measured_at` is the record's `updated_at`, when EchelonGraph
+  last wrote it.
+- `cve_exposure` is `not_assessed` with `measured_at` `null`, every answer: the per-CVE answer
+  carries no time at which the services it counts were observed. Its `last_seen` is when
+  EchelonGraph last wrote or refreshed one of their rows, not when any of them was observed,
+  so it is never `measured_at`, and a note says so. A tracked zero is `not_assessed` too, since
+  a zero has no observation to date it. The count is still relayed, labelled: `exposure_state`
+  is `exposed`, `measured_zero`, `not_assessed` or `tracking_unknown`, the cases of [How
+  `cve_exposure` counts](tools.md#how-cve_exposure-counts), and `coverage.in_scope` is the API's `tracked`. It becomes `measured`
+  only when the API serves a time at which the counted services were observed.
+- `exposure_radar` is `not_assessed` with `measured_at` `null`: every radar answered, but no
+  answer gives one time at which what it counts was observed, so no count is presented as a
+  dated measurement. `mcp_servers` dates its verdicts only by a window, `mcp_servers.window.from`
+  to `mcp_servers.window.to`, over checks made at different times, which is not one observation
+  time; so, since #2438, do `exposed_databases.window`, `leaked_credentials.window` and
+  `shadow_ai.confirmed_exposed.window`, and `kev_exposure.window`, from Shodan's banner
+  timestamps, where the API serves it. Its numbers keep the labels [exposure-radar.md](exposure-radar.md) gives them. `freshness` holds each radar's `last_run_at` where the
+  API serves one, for `shadow_ai` also `running`, and for `mcp_servers` also `enabled`.
+- `check_affected` is `measured` only when the answer says `assessed` true, and `not_assessed`
+  when it says false or does not say. Its `measured_at` and `freshness` are `null`: a match answer
+  carries no observation time. Its `coverage` gives `assessed` and `not_assessed_reason` first,
+  then `lookup` (`cpe` or `registry`), `match_layer`, `count`, `capped`, `candidates_capped`,
+  `excluded_count`, `undetermined_count`, `not_affected_count` and `degraded`.
+
+The CVE feed tools' `freshness` is `null`: the feed's answers carry no time at which its
+pollers last completed a poll for the feed as a whole.