echelongraph-mcp 2.3.2 → 2.3.4

package/README.md

@@ -17,7 +17,7 @@ API call a tool needs to answer.
 
 | Tool | What it does |
 |---|---|
-| `cve_summary` | Counts of active CVEs by severity band, the count with no severity band from any source (`summary.none`, sent again as `summary.unscored`: CVEs not yet scored, not a rating of None), and when the feed was last updated. |
+| `cve_summary` | Counts of active CVEs by severity band, the count with no severity band from any source (`summary.none`, sent again as `summary.unscored`: CVEs not yet scored, not a rating of None), the same CVEs counted by NVD's severity label, as provenance (`summary.nvd_critical` to `summary.nvd_none`), the rejected (withdrawn) records outside the total (`summary.rejected`), and when the feed was last updated. |
 | `search_cves` | Search/filter CVEs (severity, min CVSS, text, sort) with EchelonGraph scores and `score_assessed`; the note names each row not yet scored. |
 | `get_cve` | Full record for one CVE: CVSS v3 and (when scored) v4, the EchelonGraph score and its confidence, whether EchelonGraph has scored it (`score_assessed`), EPSS, CISA-KEV status and known ransomware use, the GitHub GHSA id, references, and its published, modified and `updated_at` times. |
 | `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. |
@@ -26,6 +26,30 @@ API call a tool needs to answer.
 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.
 
+### How `cve_summary` reads its counts
+
+`summary.critical`, `summary.high`, `summary.medium` and `summary.low` count the active CVEs by
+severity band, and `summary.total` counts them all. `summary.none` counts the active CVEs with no
+severity band from any source: CVEs not yet scored, not CVEs rated None. The answer sends the same
+count again as `summary.unscored`.
+
+`summary.nvd_critical`, `summary.nvd_high`, `summary.nvd_medium`, `summary.nvd_low` and
+`summary.nvd_none` count the same active CVEs a second time, by NVD's CVSS severity label (v3.x,
+else v4.0). Before NVD's record arrives, or where it gives none, a pre-NVD label from the CVE.org
+record or a GitHub advisory can stand in. They are provenance, never EchelonGraph's severity band. `summary.nvd_none` counts the active CVEs with no
+Critical, High, Medium or Low label there, and many of those carry an NVD CVSS v2 score instead, so
+it is neither a count of CVEs rated None nor the count of CVEs with no severity, which is
+`summary.none`.
+
+`summary.rejected` counts the CVE records rejected (withdrawn) by their numbering authority.
+`summary.total` and the other counts leave them out, and they are withdrawn records, never
+vulnerabilities.
+
+The tool relays the API's JSON as it was sent. When `summary.none`, `summary.nvd_none` or
+`summary.rejected` is above zero, the note says what it counts, with the number from the answer.
+The note says the five NVD counts add up to `summary.total` only when the answer's do, and says
+nothing about a field the answer does not carry.
+
 ### How `get_cve` and `search_cves` read the EchelonGraph score
 
 `echelongraph_score` (0 to 10), its band `echelongraph_severity` and the risk priority

package/dist/index.js

@@ -406,6 +406,46 @@ function summaryNoneNote(d) {
     const same = unscored === none ? ` summary.unscored (${unscored}) is the same count under its own name.` : "";
     return ` summary.none (${none}) is not a severity rating of None: it counts the active CVEs with no severity band from any source, that is, CVEs not yet scored.${same} Report them as not yet scored, not as CVEs rated None.`;
 }
+// ── summary.nvd_*, NVD's label, and summary.rejected (#2641) ──
+//
+// core-backend cve/store.go Summary sends a second histogram beside the first: nvd_critical,
+// nvd_high, nvd_medium, nvd_low and nvd_none bucket the same active CVEs on the records' own
+// `severity` column instead of effectiveSeverityExpr. That column holds NVD's CVSS label (v3.1, else
+// v3.0, else v4.0: cve/poller.go). Before NVD's record arrives it holds a pre-NVD label, the CVE.org
+// record's (cve/mitre/convert.go) or a GitHub advisory's (vendoradv SeedStubCVEFromAdvisory), and
+// where NVD's record gives none, CISA's Vulnrichment v4 label can fill it (vulnrichment/backfill.go).
+// nvd_none counts every active CVE whose label there is none of CRITICAL, HIGH, MEDIUM or LOW.
+// CVESummary's own comment says to render it "as provenance, never as a rating", and nvd_none is
+// large by design: #1107 measured that the feed holds NVD's own CVSS v2 score for 72,359 of them.
+// So nvd_none is not a count of CVEs rated None, and not the count of CVEs with no severity, which
+// is summary.none. rejected is COUNT(*) of the rows whose vuln_status is REJECTED: records withdrawn
+// by their numbering authority, outside the active rows that total and both histograms count.
+// Through 2.3.3 the tool relayed all six fields with no word about any of them, and a model handed
+// nvd_none 75,962 beside a note about summary.none 3,408 (production, 2026-09-30) reports "75,962
+// CVEs rated None". The JSON is relayed as sent. As for summary.none, the note says what nvd_none
+// and rejected count, with the answer's own numbers, whenever each is above zero (a zero has no CVE
+// in it to misreport); it says the five nvd_ counts add up to summary.total only when the answer's
+// do; and an answer without the fields (an API older than them) gets no sentence about them.
+const NVD_HISTOGRAM = ["nvd_critical", "nvd_high", "nvd_medium", "nvd_low", "nvd_none"];
+function summaryNVDNote(d) {
+    const nvdNone = numAt(d, "summary", "nvd_none");
+    if (nvdNone === undefined || nvdNone <= 0)
+        return "";
+    const counts = NVD_HISTOGRAM.map((k) => numAt(d, "summary", k));
+    const total = numAt(d, "summary", "total");
+    const present = NVD_HISTOGRAM.filter((_, i) => counts[i] !== undefined).map((k) => `summary.${k}`);
+    const adds = total !== undefined && counts.every((n) => n !== undefined) && counts.reduce((a, n) => a + (n ?? 0), 0) === total;
+    const histogram = adds
+        ? ` ${listed(present)} add up to summary.total (${total}): the same active CVEs, counted by NVD's severity label as provenance, not by EchelonGraph's severity.`
+        : ` ${listed(present)} ${present.length === 1 ? "counts" : "count"} active CVEs by NVD's severity label, as provenance, not by EchelonGraph's severity.`;
+    return `${histogram} summary.nvd_none (${nvdNone}) is not a count of CVEs rated None, nor of CVEs with no severity: it counts the active CVEs with no Critical, High, Medium or Low CVSS label from NVD (v3.x, else v4.0) or a pre-NVD record, many of them with an NVD CVSS v2 score instead. Report them as CVEs without an NVD severity label, not as CVEs rated None or as CVEs not yet scored.`;
+}
+function summaryRejectedNote(d) {
+    const rejected = numAt(d, "summary", "rejected");
+    if (rejected === undefined || rejected <= 0)
+        return "";
+    return ` summary.rejected (${rejected}) counts CVE records rejected (withdrawn) by their numbering authority, not active CVEs: report them as withdrawn records, never as vulnerabilities.`;
+}
 async function cveSummary() {
     const tool = "cve_summary";
     try {
@@ -428,15 +468,16 @@ async function cveSummary() {
             ],
         };
         const total = numAt(r.data, "summary", "total");
-        const none = summaryNoneNote(r.data);
+        // What summary.none (#2610), the NVD histogram and summary.rejected (#2641) count.
+        const labels = `${summaryNoneNote(r.data)}${summaryNVDNote(r.data)}${summaryRejectedNote(r.data)}`;
         if (total === undefined)
-            return succeeded(r.data, `${head}${none}`, env);
+            return succeeded(r.data, `${head}${labels}`, env);
         if (total === 0) {
-            return succeeded(r.data, `${head} The feed reports 0 active CVEs — a measured empty result (we looked and found nothing), not a lookup failure.${none}`, env);
+            return succeeded(r.data, `${head} The feed reports 0 active CVEs — a measured empty result (we looked and found nothing), not a lookup failure.${labels}`, env);
         }
         // A stamp that is not a real instant stays in the JSON and is not repeated as prose.
         const stamp = realInstant(updated) ? ` (last updated ${updated})` : "";
-        return succeeded(r.data, `${head} The feed holds ${total} active CVEs${stamp}.${none}`, env);
+        return succeeded(r.data, `${head} The feed holds ${total} active CVEs${stamp}.${labels}`, env);
     }
     catch (e) {
         return crashed(tool, e);
@@ -1664,6 +1705,8 @@ const CVERecord = z.looseObject({
     modified: opt(z.string()),
     updated_at: opt(z.string()),
 });
+// One of the NVD histogram's four labelled buckets (#2641).
+const nvdBand = (label) => opt(z.number()).describe(`Of the active CVEs total counts, those whose NVD CVSS severity label is ${label}: NVD's label, as provenance, never EchelonGraph's severity band.`);
 const CVE_SUMMARY_OUTPUT = envelopeSchema({
     data: z.looseObject({
         summary: z
@@ -1676,6 +1719,14 @@ const CVE_SUMMARY_OUTPUT = envelopeSchema({
             // #2610: the not-yet-scored bucket, not a rating (see summaryNoneNote).
             none: opt(z.number()).describe("The active CVEs with no severity band from any source: CVEs not yet scored, not a severity rating of None."),
             unscored: opt(z.number()).describe("The same count as none, under its own name."),
+            // #2641: NVD's label, as provenance, not a rating; and the withdrawn records (see
+            // summaryNVDNote and summaryRejectedNote).
+            nvd_critical: nvdBand("Critical"),
+            nvd_high: nvdBand("High"),
+            nvd_medium: nvdBand("Medium"),
+            nvd_low: nvdBand("Low"),
+            nvd_none: opt(z.number()).describe("Of the active CVEs total counts, those with no Critical, High, Medium or Low NVD CVSS severity label, many of them with an NVD CVSS v2 score instead: neither a count of CVEs rated None nor the count of CVEs with no severity, which is none."),
+            rejected: opt(z.number()).describe("The CVE records rejected (withdrawn) by their numbering authority, which total and every other count here leave out: withdrawn records, never vulnerabilities."),
             last_updated: opt(z.string()),
         })
             .optional(),
@@ -1844,6 +1895,13 @@ const FEED_ENVELOPE = "Its structured result carries state (measured), measured_
 // #2610: what cve_summary says summary.none is (summaryNoneNote), one constant string for the same
 // reason as SCORE_ASSESSED_DESCRIPTION below.
 const SUMMARY_NONE_DESCRIPTION = "summary.none is not a severity rating of None: it counts the active CVEs with no severity band from any source, that is, CVEs not yet scored, and the answer may carry the same count again as summary.unscored. Whenever summary.none is above zero the note says so: report those CVEs as not yet scored, not as CVEs rated None.";
+// #2641: what cve_summary says the NVD histogram and summary.rejected are (summaryNVDNote,
+// summaryRejectedNote), constant strings for the same reason. Neither uses the words "any", "not",
+// "rating", "scored", "source" or "yet": the site's #2610 control (marketing-site
+// lib/mcpToolClaims.test.ts) holds that exactly those words of the /pulse/mcp cve_summary row are
+// backed by SUMMARY_NONE_DESCRIPTION alone, and fails if another sentence backs one.
+const SUMMARY_NVD_DESCRIPTION = "summary.nvd_critical, summary.nvd_high, summary.nvd_medium, summary.nvd_low and summary.nvd_none count the same active CVEs as summary.total by NVD's CVSS severity label (v3.x, else v4.0; before NVD's record arrives, or where it gives none, a pre-NVD label from the CVE.org record or a GitHub advisory can stand in): provenance, never EchelonGraph's severity band. summary.nvd_none counts the active CVEs with no Critical, High, Medium or Low label there, CVEs NVD never labelled under CVSS v3 among them, and many of those carry an NVD CVSS v2 score instead: it is neither a count of CVEs rated None nor the count of CVEs with no severity, which is summary.none. Whenever summary.nvd_none is above zero the note says what it counts, with its count.";
+const SUMMARY_REJECTED_DESCRIPTION = "summary.rejected counts the CVE records rejected (withdrawn) by their numbering authority, which summary.total and the other counts above leave out: report them as withdrawn records, never as vulnerabilities.";
 // #2535: what search_cves and get_cve say about score_assessed, one constant string, since the
 // site's tool-claims check (marketing-site lib/mcpToolClaims.test.ts) folds only constant strings.
 const SCORE_ASSESSED_DESCRIPTION = "echelongraph_score, echelongraph_severity and echelongraph_risk are EchelonGraph's score only when score_assessed is true. With score_assessed false the CVE is NOT YET SCORED, not scored 0: any of those three it carries (0, NONE, 0) is a placeholder, not a rating, and does not mean the CVE is harmless; the API may leave them out instead, score_confidence is NONE, and score_unassessed_reason says why (a rejected record, withdrawn by its numbering authority, is never scored, and the note says NOT SCORED). The note labels each such CVE NOT YET SCORED: report it that way, never as a score of 0. An answer with no score_assessed (an API older than that field) does not say whether the CVE was scored, the note says so, and a 0 there is not a rating either.";
@@ -1853,7 +1911,7 @@ function createServer() {
     const server = new McpServer({ name: NAME, version: VERSION }, { instructions: INSTRUCTIONS, capabilities: { tools: { listChanged: false } } });
     server.registerTool("cve_summary", {
         title: "CVE feed summary",
-        description: `Summary of EchelonGraph's CVE Pulse feed: summary.total active CVEs, their counts by severity band (summary.critical, summary.high, summary.medium, summary.low), the count with no band (summary.none), and summary.last_updated, the newest modification time among those records. ${SUMMARY_NONE_DESCRIPTION} The feed is polled from its sources on a schedule, so this is the state as of that update. ${FEED_ENVELOPE}`,
+        description: `Summary of EchelonGraph's CVE Pulse feed: summary.total active CVEs, their counts by severity band (summary.critical, summary.high, summary.medium, summary.low), the count with no band (summary.none), and summary.last_updated, the newest modification time among those records. ${SUMMARY_NONE_DESCRIPTION} ${SUMMARY_NVD_DESCRIPTION} ${SUMMARY_REJECTED_DESCRIPTION} The feed is polled from its sources on a schedule, so this is the state as of that update. ${FEED_ENVELOPE}`,
         outputSchema: CVE_SUMMARY_OUTPUT,
         annotations: ANNOTATIONS,
     }, async () => checked("cve_summary", CVE_SUMMARY_OUTPUT, await cveSummary()));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "echelongraph-mcp",
-  "version": "2.3.2",
+  "version": "2.3.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",

package/server.json

@@ -8,12 +8,12 @@
     "url": "https://github.com/echelongraph/echelongraph-mcp",
     "source": "github"
   },
-  "version": "2.3.2",
+  "version": "2.3.4",
   "packages": [
     {
       "registryType": "npm",
       "identifier": "echelongraph-mcp",
-      "version": "2.3.2",
+      "version": "2.3.4",
       "transport": {
         "type": "stdio"
       },