echelongraph-mcp 2.3.3 → 2.4.0

package/dist/tools/cve_intel.js

@@ -0,0 +1,276 @@
+// cve_intel (#2720): what weakness a CVE is, whether public exploit code for it is on record,
+// and which packages and versions it affects and fixes — from GET
+// /api/v1/public/cves/:id/enrichment (core-backend cve/handler_enrichment.go).
+//
+// Not /blast-radius: that GET can trigger a live OSV fetch and a database upsert
+// (core-backend cve/handler.go GetBlastRadius), and this server makes no request but a read.
+//
+// The relay is a cut, like exposure_radar's. /enrichment also serves vendor_advisories, patches,
+// ai (generated summaries), trending and historical_incidents; this tool relays only the sections
+// it can label — cwes, exploits with their counts, affected_packages, fixed_versions and timeline —
+// and the note names what it left out. Within those, nothing is rewritten: each relayed section is
+// the API's own value, except timeline, cut to its TIMELINE_RELAYED newest rows (the API's are
+// newest first) with the cut in coverage.
+//
+// An empty section is not "none" unless the answer says it was read. /enrichment fills a section
+// that failed or ran out of its time budget with its empty value. Since #2720 it names each such
+// section in failed_sections; this tool then leaves that section out of data and says so. An
+// answer without failed_sections (an API older than #2720) cannot tell an empty section from a
+// failed one, and the note says so for each empty section it relays.
+//
+// Exploit coverage. cve_exploits is filled by a curated seed and by four pollers (Metasploit,
+// Exploit-DB, nuclei templates, GitHub PoCs), each behind its own environment flag
+// (EXPLOIT_INTEL_ENABLED plus EXPLOIT_METASPLOIT_ENABLED, EXPLOIT_EXPLOITDB_ENABLED,
+// EXPLOIT_NUCLEI_ENABLED, EXPLOIT_POCGITHUB_ENABLED; core-backend cmd/server/main.go). The answer
+// does not say which ran, so no text here says a source is polled: it names the sources the data
+// model holds, and says coverage depends on which pollers run.
+import * as z from "zod";
+import { ANNOTATIONS, CVE_ID, NOT_A_FINDING, SHOWN_BASE, api, badInput, boolAt, checked, crashed, envelopeSchema, failed, failure, field, numAt, okHead, opt, strAt, succeeded, } from "../index.js";
+const TOOL = "cve_intel";
+// The sections relayed, in the answer's order, and the keys each failed_sections name covers.
+const LISTS = ["cwes", "exploits", "affected_packages", "fixed_versions", "timeline"];
+const SECTION_KEYS = {
+    cwes: ["cwes"],
+    exploits: ["exploits"],
+    exploits_total: ["exploits_total", "exploits_capped", "exploits_by_kind", "exploits_by_status"],
+    affected_packages: ["affected_packages"],
+    fixed_versions: ["fixed_versions"],
+    timeline: ["timeline"],
+    timeline_stats: ["timeline_total", "timeline_count_7d", "timeline_count_30d"],
+};
+const RELAYED_KEYS = [
+    "cwes",
+    "exploits",
+    "exploits_total",
+    "exploits_capped",
+    "exploits_by_kind",
+    "exploits_by_status",
+    "affected_packages",
+    "fixed_versions",
+    "timeline",
+    "timeline_total",
+    "timeline_count_7d",
+    "timeline_count_30d",
+];
+// The /enrichment sections this tool does not relay, named in every note.
+const LEFT_OUT = ["vendor_advisories", "patches", "ai", "trending", "historical_incidents"];
+// Per-CVE row limits of the API (core-backend cve/enrichment_store.go): a list this long may be cut.
+const API_ROW_LIMIT = { exploits: 10, affected_packages: 50, fixed_versions: 200, timeline: 100 };
+const TIMELINE_RELAYED = 20;
+const CVE_INTEL_METHOD = "EchelonGraph's per-CVE enrichment (GET /api/v1/public/cves/:id/enrichment). cwes: CWE classifications stored from NVD, GitHub (GHSA) and CVE.org records, each with the source that gave it, named from the MITRE CWE catalog EchelonGraph embeds. exploits: public exploit references from EchelonGraph's cve_exploits records, whose data model holds Metasploit modules (metasploit), Exploit-DB entries (exploit_db), nuclei templates (nuclei_template), GitHub proof-of-concept repositories (github_poc) and vendor proofs of concept (vendor_poc), filled by a curated seed and by one poller per automated source, each run only where it is enabled, so which sources are current depends on the deployment. affected_packages and fixed_versions: package-ecosystem advisory data, each row naming its source. timeline: EchelonGraph's enrichment history for the CVE, newest first.";
+const VERIFIED_STATUS_DESCRIPTION = "verified_status is the label stored with each reference: verified for a Metasploit module, for an Exploit-DB entry Exploit-DB marks verified, and for curated seed rows marked so; reported for a public artefact nothing has confirmed works (nuclei templates, GitHub proofs of concept, unverified Exploit-DB entries); unconfirmed where a curated row says so. It is a label from the source, not a guarantee that the exploit works against a given system.";
+export const CVE_INTEL_DESCRIPTION = `Weakness, public exploit code, affected packages and fixed versions for one CVE, from EchelonGraph's per-CVE enrichment. Returns cwes (each cwe_id with its name and source), exploits (each with kind, source_name, source_url, first_seen_at and verified_status; at most 10, verified first) with exploits_total (every reference on record), exploits_capped (true when exploits lists fewer than exploits_total), exploits_by_kind and exploits_by_status, affected_packages (ecosystem, package_name, version_range, fixed_version), fixed_versions (ecosystem, package_name, vulnerable_range, fixed_version) and timeline (the newest enrichment-history rows, with timeline_total). ${VERIFIED_STATUS_DESCRIPTION} An empty exploits list is not evidence that no public exploit exists: it covers only the sources EchelonGraph ingests, and which of them are polled depends on the deployment. A section the API could not read is named in coverage.sections_failed and left out of data, never relayed as an empty list. Vendor advisories, patches, generated summaries, trending signals and historical incidents are not relayed. Pass a CVE ID like CVE-2021-44228. Its structured result carries state (measured), measured_at (null: each row carries its own time), method, coverage (the sections relayed, failed and left out, and per-list counts), freshness (null) and notes, with data equal to the first text block; the result's last text block repeats it without data and without the note's sentences (the text block before it), with which notes ends.`;
+// ── outputSchema ──
+const Rows = (shape) => z.array(z.looseObject(shape));
+const CountMap = z.record(z.string(), z.number());
+const ListCount = z.strictObject({
+    returned: z.number().int().nullable().describe("Rows the API returned; null when the section was not read."),
+    api_row_limit: z.number().int().describe("The most rows the API returns for this list per CVE: a list this long may be cut."),
+});
+function schemas() {
+    const data = z.strictObject({
+        cve_id: z.string(),
+        cwes: Rows({ cwe_id: opt(z.string()), name: opt(z.string()), source: opt(z.string()) }).optional(),
+        exploits: Rows({
+            kind: opt(z.string()).describe("metasploit, exploit_db, nuclei_template, github_poc or vendor_poc."),
+            source_name: opt(z.string()),
+            source_url: opt(z.string()),
+            description: opt(z.string()),
+            first_seen_at: opt(z.string()),
+            verified_status: opt(z.string()).describe(VERIFIED_STATUS_DESCRIPTION),
+        }).optional(),
+        exploits_total: z.number().int().nullable().optional().describe("Every exploit reference on record for the CVE, not only those listed in exploits."),
+        exploits_capped: z.boolean().optional().describe("true: exploits lists fewer references than exploits_total."),
+        exploits_by_kind: CountMap.optional(),
+        exploits_by_status: CountMap.optional(),
+        affected_packages: Rows({
+            ecosystem: opt(z.string()),
+            package_name: opt(z.string()),
+            version_range: opt(z.string()),
+            fixed_version: opt(z.string()),
+            dependents_count: opt(z.number()),
+            source: opt(z.string()),
+        }).optional(),
+        fixed_versions: Rows({
+            ecosystem: opt(z.string()),
+            package_name: opt(z.string()),
+            vulnerable_range: opt(z.string()),
+            fixed_version: opt(z.string()),
+            source: opt(z.string()),
+        }).optional(),
+        timeline: Rows({ enriched_at: opt(z.string()), enrichment_kind: opt(z.string()), fields_changed: z.unknown().optional(), score_delta: opt(z.number()) }).optional(),
+        timeline_total: z.number().int().optional(),
+        timeline_count_7d: z.number().int().optional(),
+        timeline_count_30d: z.number().int().optional(),
+    });
+    const coverage = z.strictObject({
+        sections_relayed: z.array(z.string()).describe("The sections of the answer relayed in data."),
+        sections_failed: z
+            .array(z.string())
+            .nullable()
+            .describe("The sections the API says it could not read (its failed_sections), left out of data; null when the answer does not say (an API older than failed_sections), so an empty list may be an unread section."),
+        sections_left_out: z.array(z.string()).describe("The sections of the answer this tool does not relay."),
+        exploits: ListCount,
+        affected_packages: ListCount,
+        fixed_versions: ListCount,
+        timeline: z.strictObject({
+            returned: z.number().int().nullable(),
+            relayed: z.number().int().nullable().describe("The newest rows relayed in data.timeline."),
+            api_row_limit: z.number().int(),
+        }),
+    });
+    return { output: envelopeSchema({ data, coverage, freshness: null }) };
+}
+let built;
+// Built on first use: this file is imported by index.ts, so index.ts's own exports are not
+// initialised while this module's top level runs.
+const schemasOnce = () => (built ??= schemas());
+// ── The note ──
+const listed = (xs) => (xs.length <= 1 ? (xs[0] ?? "") : `${xs.slice(0, -1).join(", ")} and ${xs.at(-1)}`);
+function cweSentence(cve, cwes) {
+    if (cwes.length === 0) {
+        return `No CWE classification is on record for ${cve} (cwes is empty): no NVD, GitHub or CVE.org record EchelonGraph holds names one, which is not a finding that the CVE has no weakness class.`;
+    }
+    const named = cwes.map((c, i) => {
+        const id = strAt(c, "cwe_id") ?? `cwes[${i}]`;
+        const name = strAt(c, "name");
+        return name ? `${id} (${name})` : id;
+    });
+    return `${cve} is classified under ${listed(named)}.`;
+}
+function exploitSentences(cve, d, rows) {
+    const total = numAt(d, "exploits_total");
+    const verified = numAt(d, "exploits_by_status", "verified");
+    const capped = boolAt(d, "exploits_capped");
+    const verifiedRows = rows.filter((r) => strAt(r, "verified_status") === "verified").length;
+    if (total === undefined) {
+        // An API older than exploits_total, or the count could not be read.
+        const cut = rows.length >= (API_ROW_LIMIT.exploits ?? 10) ? ` The API lists at most ${API_ROW_LIMIT.exploits} references, so there may be more.` : "";
+        if (rows.length === 0) {
+            return [
+                `exploits is empty and the answer carries no exploits_total, so it does not count the references on record for ${cve}; an empty list is not evidence that no public exploit exists.`,
+            ];
+        }
+        return [`exploits lists ${rows.length} public exploit reference${rows.length === 1 ? "" : "s"} for ${cve}, ${verifiedRows} with verified_status verified; the answer carries no exploits_total, so it does not say how many are on record.${cut}`];
+    }
+    if (total === 0) {
+        return [
+            `EchelonGraph holds no public exploit reference for ${cve} (exploits_total 0). That is not evidence that no public exploit exists: references come only from the sources EchelonGraph ingests, and which of them are polled depends on the deployment.`,
+        ];
+    }
+    const v = verified === undefined ? "" : `, ${verified} of them with verified_status verified`;
+    const cut = capped === true ? ` exploits_capped is true: exploits lists ${rows.length} of the ${total}, verified first.` : "";
+    return [`EchelonGraph holds ${total} public exploit reference${total === 1 ? "" : "s"} for ${cve} (exploits_total)${v}.${cut}`];
+}
+function listSentence(name, rows) {
+    const limit = API_ROW_LIMIT[name] ?? 0;
+    if (rows.length === 0)
+        return `${name} is empty: EchelonGraph holds no ${name === "affected_packages" ? "affected package" : "fixed version"} row for this CVE, which is not a finding that no package is affected or fixed.`;
+    const cut = rows.length >= limit ? `, the most the API returns per CVE, so there may be more` : "";
+    return `${name} lists ${rows.length} row${rows.length === 1 ? "" : "s"}${cut}.`;
+}
+// ── The tool ──
+export async function cveIntel(cve_id) {
+    const id = cve_id.trim();
+    if (!id)
+        return badInput(TOOL, "cve_id is required");
+    if (!CVE_ID.test(id))
+        return badInput(TOOL, `cve_id ${JSON.stringify(id.slice(0, 32))} is not a CVE id (expected the form CVE-2021-44228)`);
+    const cve = id.toUpperCase();
+    try {
+        const r = await api(`/api/v1/public/cves/${encodeURIComponent(cve)}/enrichment`);
+        if (!r.ok)
+            return failed(TOOL, r);
+        const d = r.data;
+        const reported = field(d, "failed_sections");
+        const sectionsFailed = Array.isArray(reported) ? reported.filter((x) => typeof x === "string") : null;
+        const failedKeys = new Set((sectionsFailed ?? []).flatMap((s) => SECTION_KEYS[s] ?? [s]));
+        const data = { cve_id: cve };
+        for (const k of RELAYED_KEYS) {
+            const v = field(d, k);
+            if (v === undefined || failedKeys.has(k))
+                continue;
+            data[k] = k === "timeline" && Array.isArray(v) ? v.slice(0, TIMELINE_RELAYED) : v;
+        }
+        const relayed = LISTS.filter((k) => k in data);
+        // Every list this tool relays could not be read: nothing was measured.
+        if (relayed.length === 0) {
+            const why = sectionsFailed?.length
+                ? `the API answered but could not read any section this tool relays (failed_sections: ${sectionsFailed.join(", ")})`
+                : "the answer carries none of the sections this tool relays (cwes, exploits, affected_packages, fixed_versions, timeline)";
+            return failure("failed", `${TOOL} FAILED: EchelonGraph answered HTTP ${r.status} from ${SHOWN_BASE} for GET /api/v1/public/cves/${cve}/enrichment, but ${why}. ${NOT_A_FINDING}`, {
+                kind: "unexpected_shape",
+                path: `/api/v1/public/cves/${cve}/enrichment`,
+                status: r.status,
+                message: why,
+            });
+        }
+        const rows = (k) => (Array.isArray(data[k]) ? data[k] : null);
+        const said = [];
+        const cwes = rows("cwes");
+        if (cwes)
+            said.push(cweSentence(cve, cwes));
+        const exploits = rows("exploits");
+        if (exploits)
+            said.push(...exploitSentences(cve, data, exploits));
+        for (const k of ["affected_packages", "fixed_versions"]) {
+            const xs = rows(k);
+            if (xs)
+                said.push(listSentence(k, xs));
+        }
+        const timeline = rows("timeline");
+        const apiTimeline = field(d, "timeline");
+        const timelineReturned = Array.isArray(apiTimeline) ? apiTimeline.length : null;
+        const timelineTotal = numAt(data, "timeline_total");
+        if (timeline && timelineReturned !== null && timelineReturned > timeline.length) {
+            said.push(`timeline relays the ${timeline.length} newest of the ${timelineReturned} enrichment-history rows the API returned${timelineTotal === undefined ? "" : ` (timeline_total ${timelineTotal})`}.`);
+        }
+        if (sectionsFailed === null) {
+            const empty = relayed.filter((k) => rows(k)?.length === 0);
+            if (empty.length) {
+                said.push(`The answer carries no failed_sections (an API older than that field), so it does not say whether ${listed(empty)} ${empty.length === 1 ? "was" : "were"} read: an empty list there may be a section the API could not read within its time budget, not a finding of none.`);
+            }
+        }
+        else if (sectionsFailed.length) {
+            said.push(`The API could not read ${listed(sectionsFailed)} (failed_sections): ${sectionsFailed.length === 1 ? "it is" : "they are"} left out of data, and the absence is not a finding of none.`);
+        }
+        said.push(`Not relayed from the answer: ${listed(LEFT_OUT)}.`);
+        const count = (k) => {
+            const v = field(d, k);
+            return Array.isArray(v) && !failedKeys.has(k) ? v.length : null;
+        };
+        const coverage = {
+            sections_relayed: relayed,
+            sections_failed: sectionsFailed,
+            sections_left_out: [...LEFT_OUT],
+            exploits: { returned: count("exploits"), api_row_limit: API_ROW_LIMIT.exploits },
+            affected_packages: { returned: count("affected_packages"), api_row_limit: API_ROW_LIMIT.affected_packages },
+            fixed_versions: { returned: count("fixed_versions"), api_row_limit: API_ROW_LIMIT.fixed_versions },
+            timeline: { returned: count("timeline"), relayed: timeline ? timeline.length : null, api_row_limit: API_ROW_LIMIT.timeline },
+        };
+        return succeeded(data, `${okHead(TOOL, r.status)} ${said.join(" ")}`, {
+            state: "measured",
+            measured_at: null,
+            method: CVE_INTEL_METHOD,
+            coverage,
+            freshness: null,
+            notes: [
+                "measured_at is null: the answer has no single observation time; each row carries its own (first_seen_at, enriched_at).",
+                "freshness is null: the answer does not say when each source was last polled.",
+            ],
+        });
+    }
+    catch (e) {
+        return crashed(TOOL, e);
+    }
+}
+export function registerCveIntel(server) {
+    const { output } = schemasOnce();
+    server.registerTool("cve_intel", {
+        title: "CVE weakness, exploits and packages",
+        description: CVE_INTEL_DESCRIPTION,
+        inputSchema: z.object({ cve_id: z.string().describe("a CVE ID, e.g. CVE-2021-44228") }),
+        outputSchema: output,
+        annotations: ANNOTATIONS,
+    }, async ({ cve_id }) => checked(TOOL, output, await cveIntel(cve_id)));
+}

package/dist/tools/epss_history.js

@@ -0,0 +1,125 @@
+import * as z from "zod";
+const TOOL = "epss_history";
+const CVE_ID = /^CVE-\d{4}-\d{4,}$/i;
+export const EPSS_HISTORY_METHOD = "EchelonGraph's record of FIRST's EPSS scores: the nightly EPSS fetcher overwrites each CVE's epss_score and epss_percentile from FIRST's published file and, for every CVE whose value changed, records the new values with the time it wrote them; this series is those records, oldest first, with repeated records of one change collapsed into the first.";
+const CHANGE_ONLY = "series_kind is change_only: each point is a change EchelonGraph recorded, at the time it recorded it, and a day with no point is not a recorded value, so the series must not be read or redrawn as a daily series; no point here is interpolated.";
+const BEFORE_FIRST = "The value in force before a CVE's first point is not in the series.";
+const NO_FRESHNESS = "freshness is null: the answer does not carry the time of the EPSS fetcher's last completed run.";
+export const EPSS_HISTORY_DESCRIPTION = `How one CVE's EPSS score (FIRST's exploit-prediction probability, 0 to 1, with its percentile) has changed, as EchelonGraph recorded it: points, oldest first, each with at, epss_score and epss_percentile; current, the record's value now (epss_score, epss_percentile, epss_updated_at); series_kind, always change_only; series_starts_at, when EchelonGraph began recording EPSS changes for any CVE; history_rows, points_truncated and latest_point_matches_current. Pass a CVE ID like CVE-2023-44487. The series is change-only: a point is a recorded change, and a day without a point is not a recorded value. Never interpolate it into a daily series. Before series_starts_at nothing was recorded, so a missing point there means not recorded, not unchanged, and the value in force before a CVE's first point is not in the series. latest_point_matches_current false means a change is missing from the series. Its structured result carries state (measured), measured_at (current.epss_updated_at: when EchelonGraph last wrote a changed value, not FIRST's score date), method, coverage (series_kind, series_starts_at, points, points_truncated), freshness (null) 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.`;
+// The API's JSON. points, series_kind and current are required: an answer without them is not
+// this series, and a series_kind other than change_only would make every note above wrong, so
+// either is a failure (checked), never relayed.
+const opt = (t) => t.nullable().optional();
+const Point = (instant) => z.looseObject({
+    at: instant.describe("When EchelonGraph recorded this change."),
+    epss_score: z.number().describe("The EPSS probability (0 to 1) from that change on."),
+    epss_percentile: opt(z.number()).describe("Its percentile (0 to 1), null where the record held none."),
+});
+const data = (instant) => z.looseObject({
+    cve_id: z.string(),
+    series_kind: z.enum(["change_only"]).describe("Always change_only: one point per recorded change, none for a day without one."),
+    series_starts_at: instant.nullable().describe("The earliest EPSS change EchelonGraph recorded for any CVE: when recording began. Null when nothing has been recorded."),
+    current: z.looseObject({
+        epss_score: opt(z.number()).describe("The record's EPSS probability now; null when it holds none."),
+        epss_percentile: opt(z.number()),
+        epss_updated_at: opt(instant).describe("When EchelonGraph last wrote a changed EPSS value for this CVE."),
+    }),
+    points: z.array(Point(instant)).describe("Recorded changes, oldest first. Never a daily series."),
+    history_rows: opt(z.number().int().min(0)).describe("Raw history rows read, before repeated records of one change were collapsed."),
+    points_truncated: opt(z.boolean()).describe("True when only the newest rows were read, so the earliest points are missing."),
+    latest_point_matches_current: opt(z.boolean()).describe("Whether the newest point equals current; false means a change is missing from the series; null when there is no point or no current value."),
+});
+export function epssHistoryOutput(kit) {
+    return kit.envelopeSchema({
+        data: data(kit.instant),
+        coverage: z.strictObject({
+            series_kind: z.enum(["change_only"]),
+            series_starts_at: kit.instant.nullable(),
+            points: z.number().int().min(0).describe("How many points the series holds."),
+            points_truncated: z.boolean(),
+        }),
+        freshness: null,
+    });
+}
+const isNum = (v) => typeof v === "number" && Number.isFinite(v);
+const isObj = (v) => v !== null && typeof v === "object" && !Array.isArray(v);
+const realInstant = (v) => typeof v === "string" && Date.parse(v) > 0;
+// The note: what came back, in words, and what it does not say.
+function note(head, id, d) {
+    const points = Array.isArray(d.points) ? d.points.filter(isObj) : [];
+    const cur = isObj(d.current) ? d.current : {};
+    const curScore = isNum(cur.epss_score) ? cur.epss_score : undefined;
+    const start = realInstant(d.series_starts_at) ? d.series_starts_at : undefined;
+    const s = [head];
+    s.push(curScore === undefined
+        ? `EchelonGraph's record holds no EPSS score for ${id} (current.epss_score is null).`
+        : `${id}'s EPSS score in EchelonGraph's record is ${curScore}${isNum(cur.epss_percentile) ? ` (percentile ${cur.epss_percentile})` : ""}.`);
+    if (points.length === 0) {
+        s.push(start
+            ? `No EPSS change is recorded for ${id} since recording began at ${start}: a measured empty series, not a lookup failure.`
+            : "No EPSS change has been recorded for any CVE yet (series_starts_at is null), so this empty series says nothing about how the score moved.");
+    }
+    else {
+        const first = points[0];
+        const last = points[points.length - 1];
+        s.push(`${points.length} recorded change${points.length === 1 ? "" : "s"}, from ${first.epss_score} at ${first.at} to ${last.epss_score} at ${last.at}.`);
+    }
+    if (start)
+        s.push(`Recording began at ${start} (series_starts_at): before it a missing point means not recorded, not unchanged.`);
+    if (d.points_truncated === true)
+        s.push("points_truncated is true: only the newest records were read, so the earliest changes are missing from this series.");
+    if (d.latest_point_matches_current === false) {
+        s.push("latest_point_matches_current is false: the newest recorded point is not the record's current value, so at least one change is missing from the series.");
+    }
+    return { note: s.join(" "), own: [CHANGE_ONLY, BEFORE_FIRST] };
+}
+export async function epssHistory(kit, cve_id) {
+    const id = cve_id.trim();
+    if (!id)
+        return kit.badInput(TOOL, "cve_id is required");
+    if (!CVE_ID.test(id))
+        return kit.badInput(TOOL, `cve_id ${JSON.stringify(id.slice(0, 32))} is not a CVE id (expected the form CVE-2023-44487)`);
+    const cve = id.toUpperCase();
+    try {
+        const r = await kit.api(`/api/v1/public/cves/${encodeURIComponent(cve)}/epss-history`);
+        if (!r.ok)
+            return kit.failed(TOOL, r);
+        const d = r.data;
+        const name = typeof d.cve_id === "string" && d.cve_id ? d.cve_id : cve;
+        const { note: n, own } = note(kit.okHead(TOOL, r.status), name, d);
+        const cur = isObj(d.current) ? d.current : {};
+        const written = realInstant(cur.epss_updated_at) ? cur.epss_updated_at : null;
+        return kit.succeeded(r.data, n, {
+            state: "measured",
+            measured_at: written,
+            method: EPSS_HISTORY_METHOD,
+            coverage: {
+                series_kind: d.series_kind,
+                series_starts_at: d.series_starts_at ?? null,
+                points: Array.isArray(d.points) ? d.points.length : 0,
+                points_truncated: d.points_truncated === true,
+            },
+            freshness: null,
+            notes: [
+                ...own,
+                written
+                    ? "measured_at is current.epss_updated_at: when EchelonGraph last wrote a changed EPSS value for this CVE; values are written only on change, so it is not when the value was last checked, and it is not FIRST's score date."
+                    : "measured_at is null: the record carries no epss_updated_at.",
+                NO_FRESHNESS,
+            ],
+        });
+    }
+    catch (e) {
+        return kit.crashed(TOOL, e);
+    }
+}
+export function registerEPSSHistory(server, kit) {
+    const output = epssHistoryOutput(kit);
+    server.registerTool(TOOL, {
+        title: "EPSS change history for one CVE",
+        description: EPSS_HISTORY_DESCRIPTION,
+        inputSchema: z.object({ cve_id: kit.cveIdArg }),
+        outputSchema: output,
+        annotations: kit.annotations,
+    }, async ({ cve_id }) => kit.checked(TOOL, output, await epssHistory(kit, cve_id)));
+}

package/dist/tools/get_cwe.js

@@ -0,0 +1,148 @@
+// get_cwe (#2720): one CWE's name and description, and a page of the active CVEs classified
+// under it, from GET /api/v1/public/cwes/:cwe_id?page=N (core-backend cve/handler_cwe.go
+// GetCWELanding, cwe_landing_store.go). The JSON is relayed as the API sent it.
+//
+// The order is the API's to state. Since #2720 the answer carries `order` (KEV-listed first);
+// before it, a DISTINCT ON put cve_id first in the sort, so page 1 was the oldest CVE ids. So the
+// note repeats `order` when the answer has it, and otherwise says the answer does not state its
+// order, rather than calling the rows KEV-first.
+//
+// The API answers a page past max_page as max_page, and an id it does not know with total 0, so
+// the note compares the page asked for with the page served, and says when total counts CVEs no
+// page lists. Each page is cached by the API for up to an hour (cweLandingTTL) behind a CDN, so
+// the note says it can lag the feed.
+import * as z from "zod";
+import { ANNOTATIONS, api, badInput, checked, crashed, envelopeSchema, failed, field, lenAt, numAt, okHead, opt, rowsScoreNote, strAt, succeeded, } from "../index.js";
+const TOOL = "get_cwe";
+const CWE_ARG = /^(?:CWE-)?0*(\d{1,6})$/i;
+const MAX_PAGE = 200;
+const GET_CWE_METHOD = "EchelonGraph's per-CWE listing (GET /api/v1/public/cwes/:cwe_id): the CWE's name and description from the MITRE CWE catalog EchelonGraph embeds (catalog_version), and the active CVEs in EchelonGraph's CVE feed that an NVD, GitHub (GHSA) or CVE.org record classifies under it, rejected and reserved records left out, 50 to a page.";
+export const GET_CWE_DESCRIPTION = `One CWE (weakness class) and the CVEs classified under it. Returns cwe_id, name and description (from the MITRE CWE catalog EchelonGraph embeds, version catalog_version), total (the active CVEs in EchelonGraph's feed that an NVD, GitHub or CVE.org record classifies under it, rejected and reserved records left out), and cves, one page of 50: each with cve_id, severity, cvss_v3_score, echelongraph_score, echelongraph_severity, score_assessed, kev_listed, published and a shortened description. order says how the rows are sorted (CISA-KEV-listed first, then EchelonGraph score); an answer without order does not state its order, and the note says so. page is the page served, page_size its size and max_page the last page the API serves: a later page is answered as max_page, so past max_page pages total counts CVEs no page lists. echelongraph_score is EchelonGraph's score only when score_assessed is true; the note labels each row that is NOT YET SCORED. A total of 0 says that no CVE in EchelonGraph's feed is classified under that CWE, not that none exists. Pass cwe_id like CWE-79 (or 79) and an optional page (1-${MAX_PAGE}). Its structured result carries state (measured), measured_at (null), method, coverage (total, returned, page, page_requested, page_size, max_page), freshness (null) 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.`;
+function schemas() {
+    const row = z.looseObject({
+        cve_id: opt(z.string()),
+        severity: opt(z.string()),
+        cvss_v3_score: opt(z.number()),
+        cvss_v2_score: opt(z.number()),
+        cvss_v2_severity: opt(z.string()),
+        echelongraph_score: opt(z.number()).describe("EchelonGraph's 0-10 score: a score only when score_assessed is true."),
+        echelongraph_severity: opt(z.string()),
+        score_assessed: opt(z.boolean()).describe("Whether EchelonGraph has scored the CVE; false: NOT YET SCORED, not scored 0."),
+        kev_listed: opt(z.boolean()),
+        published: opt(z.string()),
+        description: opt(z.string()),
+    });
+    const data = z.looseObject({
+        cwe_id: opt(z.string()),
+        name: opt(z.string()),
+        description: opt(z.string()),
+        catalog_version: opt(z.string()).describe("The version of the MITRE CWE catalog name and description come from."),
+        total: opt(z.number()).describe("The active CVEs classified under the CWE, rejected and reserved records left out."),
+        cves: z.array(row).optional(),
+        page: opt(z.number()),
+        page_size: opt(z.number()),
+        max_page: opt(z.number()).describe("The last page the API serves; a later page is answered as this one."),
+        order: opt(z.string()).describe("How cves is sorted, as the API states it; absent from an API older than the field, which sorted by CVE id."),
+    });
+    const coverage = z.strictObject({
+        total: z.number().nullable(),
+        returned: z.number().nullable(),
+        page: z.number().nullable().describe("The page served."),
+        page_requested: z.number().describe("The page asked for."),
+        page_size: z.number().nullable(),
+        max_page: z.number().nullable(),
+    });
+    return { output: envelopeSchema({ data, coverage, freshness: null }) };
+}
+let built;
+// Built on first use: index.ts imports this file, so its exports are not initialised while this
+// module's top level runs.
+const schemasOnce = () => (built ??= schemas());
+export async function getCwe(cwe_id, page) {
+    const raw = cwe_id.trim();
+    if (!raw)
+        return badInput(TOOL, "cwe_id is required");
+    const m = CWE_ARG.exec(raw);
+    if (!m)
+        return badInput(TOOL, `cwe_id ${JSON.stringify(raw.slice(0, 32))} is not a CWE id (expected the form CWE-79)`);
+    const asked = page ?? 1;
+    if (!Number.isInteger(asked) || asked < 1 || asked > MAX_PAGE)
+        return badInput(TOOL, `page must be a whole number from 1 to ${MAX_PAGE}`);
+    const cwe = `CWE-${Number(m[1])}`;
+    try {
+        const r = await api(`/api/v1/public/cwes/${encodeURIComponent(cwe)}${asked > 1 ? `?page=${asked}` : ""}`);
+        if (!r.ok)
+            return failed(TOOL, r);
+        const d = r.data;
+        const id = strAt(d, "cwe_id") ?? cwe;
+        const total = numAt(d, "total");
+        const returned = lenAt(d, "cves");
+        const served = numAt(d, "page");
+        const size = numAt(d, "page_size");
+        const maxPage = numAt(d, "max_page");
+        const order = strAt(d, "order");
+        const name = strAt(d, "name");
+        const version = strAt(d, "catalog_version");
+        const said = [];
+        said.push(name
+            ? `${id} is ${name} in the MITRE CWE catalog${version ? ` (version ${version})` : ""}.`
+            : `The answer carries no name for ${id}: the MITRE CWE catalog EchelonGraph embeds has no entry for it, or the API sent none.`);
+        if (total === 0) {
+            said.push(`No active CVE in EchelonGraph's feed is classified under ${id} (total 0): a measured empty result (we looked and found nothing), which says only that no NVD, GitHub or CVE.org record EchelonGraph holds puts a CVE in this class, not that none exists.`);
+        }
+        else if (total !== undefined) {
+            const of = returned === undefined ? "" : `; this page lists ${returned}`;
+            const pg = served === undefined ? "" : ` (page ${served}${maxPage === undefined ? "" : ` of at most ${maxPage}`})`;
+            said.push(`EchelonGraph's feed holds ${total} active CVEs classified under ${id} (total, rejected and reserved records left out)${of}${pg}.`);
+            if (maxPage !== undefined && size !== undefined && total > maxPage * size) {
+                said.push(`Only the first ${maxPage * size} of them can be paged to: the API serves no page past max_page ${maxPage}.`);
+            }
+        }
+        if (served !== undefined && served !== asked) {
+            said.push(`Page ${asked} was asked for and the API served page ${served}.`);
+        }
+        if (returned) {
+            const rows = field(d, "cves");
+            const kev = Array.isArray(rows) ? rows.filter((c) => field(c, "kev_listed") === true).length : 0;
+            said.push(order
+                ? `The rows are sorted by ${order}, as the answer states (order); ${kev} of the ${returned} on this page are CISA-KEV-listed (kev_listed).`
+                : `The answer does not state how its rows are sorted (no order field; an API older than it sorted them by CVE id), so the first rows are not necessarily the CISA-KEV-listed or highest-scored ones; ${kev} of the ${returned} on this page are CISA-KEV-listed (kev_listed).`);
+        }
+        said.push("The API serves each page from a cache refreshed at most hourly, behind a CDN, so it can lag the feed by an hour or more.");
+        const scores = rowsScoreNote(d);
+        return succeeded(d, `${okHead(TOOL, r.status)} ${said.join(" ")}${scores}`, {
+            state: "measured",
+            measured_at: null,
+            method: GET_CWE_METHOD,
+            coverage: {
+                total: total ?? null,
+                returned: returned ?? null,
+                page: served ?? null,
+                page_requested: asked,
+                page_size: size ?? null,
+                max_page: maxPage ?? null,
+            },
+            freshness: null,
+            notes: [
+                "measured_at is null: a page of CVEs has no single observation time; each row carries its own published date.",
+                "freshness is null: the answer does not say when its cached page was computed.",
+            ],
+        });
+    }
+    catch (e) {
+        return crashed(TOOL, e);
+    }
+}
+export function registerGetCwe(server) {
+    const { output } = schemasOnce();
+    server.registerTool("get_cwe", {
+        title: "CWE and its CVEs",
+        description: GET_CWE_DESCRIPTION,
+        inputSchema: z.object({
+            cwe_id: z.string().describe("a CWE ID, e.g. CWE-79 (or 79)"),
+            page: z.number().int().min(1).max(MAX_PAGE).optional().describe(`page of 50 CVEs (default 1, max ${MAX_PAGE})`),
+        }),
+        outputSchema: output,
+        annotations: ANNOTATIONS,
+    }, async ({ cwe_id, page }) => checked(TOOL, output, await getCwe(cwe_id, page)));
+}