echelongraph-mcp 2.3.0 → 2.3.2

package/README.md

@@ -17,15 +17,35 @@ API call a tool needs to answer.
 
 | Tool | What it does |
 |---|---|
-| `cve_summary` | Counts of active CVEs by severity, and when the feed was last updated. |
-| `search_cves` | Search/filter CVEs (severity, min CVSS, text, sort) with EchelonGraph scores. |
-| `get_cve` | Full record for one CVE: CVSS v3 and (when scored) v4, the EchelonGraph score and its confidence, EPSS, CISA-KEV status and known ransomware use, the GitHub GHSA id, references, and its published, modified and `updated_at` times. |
+| `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. |
+| `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. |
 | `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; and MCP servers found in EchelonGraph's own Certificate Transparency feed, by RFC 9728 verdict, protocol era and transport. 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.
 
+### How `get_cve` and `search_cves` read the EchelonGraph score
+
+`echelongraph_score` (0 to 10), its band `echelongraph_severity` and the risk priority
+`echelongraph_risk` (0 to 100) are EchelonGraph's score only when the record's
+`score_assessed` is `true`. A CVE EchelonGraph has not scored carries `score_assessed: false`,
+and it is **not yet scored**, not scored 0. The API leaves those three fields out on it, or (an
+API before that change) sends `0`, `NONE` and `0` as placeholders, which are not a rating and do
+not mean the CVE is harmless. Its `score_confidence` is `NONE`, and `score_unassessed_reason`
+says why: no source has yet published severity data EchelonGraph can score, or the record was
+rejected (withdrawn) by its numbering authority, and a rejected record is never scored.
+
+Both tools relay the API's JSON as it was sent, and the note says what the score is, for
+`get_cve` per CVE and for `search_cves` per row, naming each CVE it is about:
+
+| API answer | What the note says |
+|---|---|
+| `score_assessed: true` | Nothing more: the score is a score. |
+| `score_assessed: false` | **NOT YET SCORED**, tagged "(score_assessed: false)": report the CVE as not yet scored, never as a zero or low score. Each of `echelongraph_score`, `echelongraph_severity` and `echelongraph_risk` it carries is named as a placeholder. A rejected record is **NOT SCORED** instead. |
+| no `score_assessed` field | The answer does not say whether the CVE was scored (an API older than the field), and a zero `echelongraph_score` in it is not a rating. |
+
 ### How `cve_exposure` counts
 
 Every 12 hours, when Shodan query credits allow, the KEV-exposure radar runs one Shodan query

package/dist/index.js

@@ -332,6 +332,80 @@ const realInstant = (s) => s !== undefined && Date.parse(s) > 0;
 // Stats, in memory), and is relayed in data but not presented as the feed's freshness.
 const CVE_FEED_METHOD = "EchelonGraph's CVE Pulse feed: CVE records compiled from NVD, MITRE-CNA pre-NVD records, CISA-KEV, EPSS and GitHub GHSA, each polled from its source on a schedule.";
 const NO_FEED_FRESHNESS = "freshness is null: the CVE feed's answer carries no time at which its pollers last completed a poll for the feed as a whole.";
+function scoreStateOf(rec) {
+    const v = boolAt(rec, "score_assessed");
+    return v === true ? "assessed" : v === false ? "not_assessed" : "unstated";
+}
+const scoreRejected = (rec) => strAt(rec, "score_unassessed_reason") === "rejected";
+// The fields that hold a placeholder, not a score, on a CVE that is not scored.
+const PLACEHOLDER_FIELDS = ["echelongraph_score", "echelongraph_severity", "echelongraph_risk"];
+// No sentence below writes a digit: a note that says "0" beside "score" is the defect itself.
+const UNSTATED_SCORE = "echelongraph_score is EchelonGraph's score only when score_assessed is true, so a zero echelongraph_score there is not a rating: it can be the placeholder a CVE not yet scored carries.";
+// get_cve's sentences about the one CVE's score, each starting with a space; none when the
+// answer says the CVE is scored.
+function cveScoreNote(cve, rec) {
+    const state = scoreStateOf(rec);
+    if (state === "assessed")
+        return "";
+    if (state === "unstated") {
+        return ` The answer does not say whether EchelonGraph has scored ${cve}: it carries no score_assessed (an API older than that field sends none). ${UNSTATED_SCORE}`;
+    }
+    const rejected = scoreRejected(rec);
+    const reportAs = rejected ? "not scored" : "not yet scored";
+    const head = rejected
+        ? ` (score_assessed: false) NOT SCORED: the record of ${cve} was rejected (withdrawn) by its numbering authority (score_unassessed_reason rejected), and EchelonGraph does not score a withdrawn record, so the record holds no EchelonGraph score for it.`
+        : ` (score_assessed: false) NOT YET SCORED: EchelonGraph has not yet scored ${cve}, so the record holds no EchelonGraph score for it, and the absence of one does not mean ${cve} is harmless.`;
+    const why = strAt(rec, "score_unassessed_reason") === "no_signal" ? " score_unassessed_reason is no_signal: no source has yet published severity data EchelonGraph can score." : "";
+    const carried = PLACEHOLDER_FIELDS.filter((k) => field(rec, k) !== undefined && field(rec, k) !== null);
+    const placeholders = carried.length
+        ? ` ${listed(carried)} ${carried.length === 1 ? "is a placeholder" : "are placeholders"}, not a score: report ${cve} as ${reportAs}, and do not repeat ${carried.length === 1 ? "that value" : "those values"} as its score.`
+        : ` Report ${cve} as ${reportAs}, not as a zero or low score.`;
+    return `${head}${why}${placeholders}`;
+}
+// search_cves' sentences about its rows' scores, naming each row a sentence is about, each
+// starting with a space; none when every row says it is scored.
+function rowsScoreNote(d) {
+    const rows = field(d, "cves");
+    if (!Array.isArray(rows) || rows.length === 0)
+        return "";
+    const n = rows.length;
+    const ids = (pred) => rows.flatMap((r, i) => (pred(r) ? [strAt(r, "cve_id") ?? `cves[${i}]`] : []));
+    const notYet = ids((r) => scoreStateOf(r) === "not_assessed" && !scoreRejected(r));
+    const rejected = ids((r) => scoreStateOf(r) === "not_assessed" && scoreRejected(r));
+    const unstated = ids((r) => scoreStateOf(r) === "unstated");
+    const of = (k) => (k < n ? `${k} of the ${n} CVEs in this page` : n === 1 ? "the 1 CVE in this page" : `all ${n} CVEs in this page`);
+    const out = [];
+    if (notYet.length) {
+        out.push(`(score_assessed: false) NOT YET SCORED: ${of(notYet.length)} ${be(notYet.length)} not yet scored by EchelonGraph: ${listed(notYet)}. For each, echelongraph_score, echelongraph_severity and echelongraph_risk, where its row carries them, are placeholders, not a score, and the absence of a score does not mean the CVE is harmless: report each as not yet scored, not as a zero or low score.`);
+    }
+    if (rejected.length) {
+        out.push(`(score_assessed: false) NOT SCORED: ${of(rejected.length)} ${rejected.length === 1 ? "has a record" : "have records"} rejected (withdrawn) by the numbering authority (score_unassessed_reason rejected), which EchelonGraph does not score: ${listed(rejected)}. For each, echelongraph_score, echelongraph_severity and echelongraph_risk, where its row carries them, are placeholders, not a score: report each as not scored.`);
+    }
+    if (unstated.length) {
+        out.push(`The answer does not say whether EchelonGraph has scored ${of(unstated.length)}: ${listed(unstated)} (no score_assessed in ${unstated.length === 1 ? "its row" : "their rows"}; an API older than that field sends none). ${UNSTATED_SCORE}`);
+    }
+    return out.map((s) => ` ${s}`).join("");
+}
+// ── summary.none, the not-yet-scored bucket (#2610) ──
+//
+// core-backend cve/store.go Summary buckets the active CVEs on effectiveSeverityExpr: the
+// EchelonGraph band, else NVD's, else the CVSS v2 band, else NONE, where a band of NONE or UNKNOWN
+// counts as none. So summary.none counts the CVEs with no severity band from any source, and the
+// store sends the same number again as summary.unscored (CVESummary: "the residual band-less
+// bucket … numerically identical to None"; Critical+High+Medium+Low+Unscored == Total). It is not
+// a count of CVEs rated severity None, but a model handed "counts by severity … none" reports
+// "3,381 CVEs rated None" (production on 2026-09-30: none 3,381, unscored 3,381). The JSON is
+// relayed as sent; the note says what the count is whenever it is above zero, and names
+// summary.unscored as the same count when the answer carries it equal. A zero is not labelled:
+// there is no CVE in it to misreport.
+function summaryNoneNote(d) {
+    const none = numAt(d, "summary", "none");
+    if (none === undefined || none <= 0)
+        return "";
+    const unscored = numAt(d, "summary", "unscored");
+    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.`;
+}
 async function cveSummary() {
     const tool = "cve_summary";
     try {
@@ -354,14 +428,15 @@ async function cveSummary() {
             ],
         };
         const total = numAt(r.data, "summary", "total");
+        const none = summaryNoneNote(r.data);
         if (total === undefined)
-            return succeeded(r.data, head, env);
+            return succeeded(r.data, `${head}${none}`, 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.`, 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.${none}`, 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}.`, env);
+        return succeeded(r.data, `${head} The feed holds ${total} active CVEs${stamp}.${none}`, env);
     }
     catch (e) {
         return crashed(tool, e);
@@ -411,21 +486,24 @@ async function searchCVEs(a) {
         const relaxedNote = relaxed === true
             ? " The API relaxed the search phrase to all of its words (search_relaxed is true), so these rows are a superset of the rows that match the phrase itself."
             : "";
+        // Then what each row's score is (#2535): empty when every row says it is scored, or there
+        // are no rows.
+        const tail = `${relaxedNote}${rowsScoreNote(r.data)}`;
         // A total the API did not count is not a count: the page's own rows are all that is known.
         if (counted === false) {
             const empty = shown === 0 && (offset ?? 0) === 0;
             return succeeded(r.data, empty
-                ? `${head} The query returned 0 CVEs — a measured empty result: EchelonGraph was queried successfully and nothing matched these filters (we looked and found nothing). This is not a lookup failure.${relaxedNote}`
-                : `${head} The API did not count the matches (total_counted is false), so its total is not a count${shown === undefined ? "" : `; ${shown} returned in this page`}.${relaxedNote}`, env);
+                ? `${head} The query returned 0 CVEs — a measured empty result: EchelonGraph was queried successfully and nothing matched these filters (we looked and found nothing). This is not a lookup failure.${tail}`
+                : `${head} The API did not count the matches (total_counted is false), so its total is not a count${shown === undefined ? "" : `; ${shown} returned in this page`}.${tail}`, env);
         }
         const total = numAt(r.data, "total") ?? shown;
         if (total === undefined)
-            return succeeded(r.data, `${head}${relaxedNote}`, env);
+            return succeeded(r.data, `${head}${tail}`, env);
         if (total === 0 && floor !== true) {
-            return succeeded(r.data, `${head} The query matched 0 CVEs — a measured empty result: EchelonGraph was queried successfully and nothing matched these filters (we looked and found nothing). This is not a lookup failure.${relaxedNote}`, env);
+            return succeeded(r.data, `${head} The query matched 0 CVEs — a measured empty result: EchelonGraph was queried successfully and nothing matched these filters (we looked and found nothing). This is not a lookup failure.${tail}`, env);
         }
         const matched = floor === true ? `at least ${total} CVEs (total_is_lower_bound is true: the count stopped at that floor)` : `${total} CVEs`;
-        return succeeded(r.data, `${head} The query matched ${matched}${shown === undefined ? "" : `; ${shown} returned in this page`}.${relaxedNote}`, env);
+        return succeeded(r.data, `${head} The query matched ${matched}${shown === undefined ? "" : `; ${shown} returned in this page`}.${tail}`, env);
     }
     catch (e) {
         return crashed(tool, e);
@@ -441,7 +519,8 @@ async function getCVE(cve_id) {
         if (!r.ok)
             return failed(tool, r);
         const written = strAt(r.data, "updated_at");
-        return succeeded(r.data, `${okHead(tool, r.status)} Returned the record for ${strAt(r.data, "cve_id") ?? id}.`, {
+        const cve = strAt(r.data, "cve_id") ?? id;
+        return succeeded(r.data, `${okHead(tool, r.status)} Returned the record for ${cve}.${cveScoreNote(cve, r.data)}`, {
             state: "measured",
             measured_at: instantOrNull(written),
             method: CVE_FEED_METHOD,
@@ -1567,9 +1646,13 @@ const CVERecord = z.looseObject({
     cvss_v3_score: opt(z.number()),
     cvss_v4_score: opt(z.number()),
     cvss_v4_severity: opt(z.string()),
-    echelongraph_score: opt(z.number()),
-    echelongraph_severity: opt(z.string()),
+    // #2535: the score is a score only beside score_assessed true (see cveScoreNote).
+    echelongraph_score: opt(z.number()).describe("EchelonGraph's 0-10 score for the CVE: a score only when score_assessed is true. With score_assessed false it is a placeholder, not a rating."),
+    echelongraph_severity: opt(z.string()).describe("The severity band of echelongraph_score: a rating only when score_assessed is true. With score_assessed false it is a placeholder (NONE)."),
+    echelongraph_risk: opt(z.number()).describe("EchelonGraph's 0-100 risk priority, fused from the score, exploitation and automatability: a rating only when score_assessed is true. With score_assessed false it is a placeholder."),
     score_confidence: opt(z.string()),
+    score_assessed: opt(z.boolean()).describe("Whether EchelonGraph has scored the CVE. true: echelongraph_score, echelongraph_severity and echelongraph_risk are its score. false: the CVE is NOT YET SCORED, not scored 0, and any of those three it carries is a placeholder, not a rating; the API may leave them out. Absent (an API older than the field): the answer does not say whether the CVE was scored."),
+    score_unassessed_reason: opt(z.string()).describe("Why score_assessed is false: no_signal, no source has yet published severity data EchelonGraph can score; or rejected, the record was withdrawn by its numbering authority and is never scored. Absent when the CVE is scored."),
     epss_score: opt(z.number()),
     epss_percentile: opt(z.number()),
     kev_listed: opt(z.boolean()),
@@ -1590,7 +1673,9 @@ const CVE_SUMMARY_OUTPUT = envelopeSchema({
             high: opt(z.number()),
             medium: opt(z.number()),
             low: opt(z.number()),
-            none: opt(z.number()),
+            // #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."),
             last_updated: opt(z.string()),
         })
             .optional(),
@@ -1756,19 +1841,25 @@ const ANNOTATIONS = { readOnlyHint: true, destructiveHint: false, idempotentHint
 const CVE_ID_ARG = z.string().describe("a CVE ID, e.g. CVE-2023-44487");
 // What each description says about its structured result, naming only fields its schema holds.
 const FEED_ENVELOPE = "Its structured result carries state (measured), measured_at, method, coverage, freshness (null: the feed serves no poll-completion time) and notes, with data equal to the API's JSON; the result's last text block repeats it without data (the first text block) and without the note's sentences (the text block before it), with which notes ends.";
+// #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.";
+// #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.";
 // One server, built per connection by serveStdio for whichever era the client opens with.
 // tools/list answers in registration order, which is the order below.
 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 and their counts by severity (summary.critical, summary.high, summary.medium, summary.low, summary.none), plus summary.last_updated, the newest modification time among those records. 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} 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()));
     server.registerTool("search_cves", {
         title: "Search CVEs",
-        description: `Search/list CVEs from EchelonGraph's CVE feed (NVD + MITRE-CNA pre-NVD + CISA-KEV + EPSS + GitHub GHSA, each polled on a schedule). Filter by severity, minimum CVSS, free text, and sort. Returns cves, each with cve_id, severity, cvss_v3_score, echelongraph_score, epss_score and kev_listed where the record has them, and the list's total, total_counted (false: the matches were not counted, so total is not a count), total_is_lower_bound (true: at least total), search_relaxed (true: a phrase was relaxed to all of its words), limit and offset. ${FEED_ENVELOPE} coverage repeats total, total_counted, total_is_lower_bound, search_relaxed, limit and offset, and gives returned, the rows in this page.`,
+        description: `Search/list CVEs from EchelonGraph's CVE feed (NVD + MITRE-CNA pre-NVD + CISA-KEV + EPSS + GitHub GHSA, each polled on a schedule). Filter by severity, minimum CVSS, free text, and sort. Returns cves, each with cve_id, severity, cvss_v3_score, echelongraph_score and score_assessed (whether EchelonGraph has scored it), epss_score and kev_listed where the record has them, and the list's total, total_counted (false: the matches were not counted, so total is not a count), total_is_lower_bound (true: at least total), search_relaxed (true: a phrase was relaxed to all of its words), limit and offset. ${SCORE_ASSESSED_DESCRIPTION} ${FEED_ENVELOPE} coverage repeats total, total_counted, total_is_lower_bound, search_relaxed, limit and offset, and gives returned, the rows in this page.`,
         inputSchema: z.object({
             search: z.string().optional().describe("free-text search (product, vendor, or keyword, e.g. 'tomcat')"),
             severity: z.enum(["CRITICAL", "HIGH", "MEDIUM", "LOW"]).optional().describe("filter to one severity"),
@@ -1781,7 +1872,7 @@ function createServer() {
     }, async (a) => checked("search_cves", SEARCH_CVES_OUTPUT, await searchCVEs(a)));
     server.registerTool("get_cve", {
         title: "CVE detail",
-        description: `Full record for one CVE: description, severity, cvss_v3_score, cvss_v4_score and cvss_v4_severity (when the record has a CVSS v4 score), echelongraph_score and echelongraph_severity with score_confidence (EchelonGraph's multi-source score), epss_score and epss_percentile, CISA-KEV status (kev_listed, kev_added_date, and kev_ransomware for known ransomware-campaign use), ghsa_id (GitHub GHSA), references, published, modified and updated_at; each field only where the record has it. Pass a CVE ID like CVE-2023-44487. ${FEED_ENVELOPE}`,
+        description: `Full record for one CVE: description, severity, cvss_v3_score, cvss_v4_score and cvss_v4_severity (when the record has a CVSS v4 score), echelongraph_score and echelongraph_severity with score_confidence (EchelonGraph's multi-source score) and score_assessed (whether EchelonGraph has scored it), epss_score and epss_percentile, CISA-KEV status (kev_listed, kev_added_date, and kev_ransomware for known ransomware-campaign use), ghsa_id (GitHub GHSA), references, published, modified and updated_at; each field only where the record has it. Pass a CVE ID like CVE-2023-44487. ${SCORE_ASSESSED_DESCRIPTION} ${FEED_ENVELOPE}`,
         inputSchema: z.object({ cve_id: CVE_ID_ARG }),
         outputSchema: GET_CVE_OUTPUT,
         annotations: ANNOTATIONS,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "echelongraph-mcp",
-  "version": "2.3.0",
+  "version": "2.3.2",
   "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.0",
+  "version": "2.3.2",
   "packages": [
     {
       "registryType": "npm",
       "identifier": "echelongraph-mcp",
-      "version": "2.3.0",
+      "version": "2.3.2",
       "transport": {
         "type": "stdio"
       },