echelongraph-mcp 2.3.4 → 2.5.0

package/dist/tools/check_sbom.js

@@ -0,0 +1,329 @@
+import * as z from "zod";
+export const CHECK_SBOM = "check_sbom";
+export const BATCH_PATH = "/api/v1/public/cves/match/batch";
+// The backend's cap (cveBatchMaxComponents). A document with more is refused here, before any
+// request, and never truncated: a dropped component would read as a clean one.
+export const MAX_COMPONENTS = 200;
+// The backend's per-purl cap (cveBatchMaxPurlLen).
+const MAX_PURL_LEN = 512;
+// The document's size cap, as JSON text. OWASP Juice Shop 11.1.2's full CycloneDX SBOM (840
+// components) is 0.74 MB; this leaves room for a much larger one while bounding what this process
+// parses.
+export const MAX_SBOM_CHARS = 5_000_000;
+// How many affected components the note names, and how many CVE ids per component.
+const NOTE_AFFECTED_MAX = 25;
+const NOTE_CVES_MAX = 5;
+// CycloneDX nests components; this bounds the walk.
+const MAX_DEPTH = 32;
+const METHOD = "EchelonGraph's registry advisory matcher (POST /api/v1/public/cves/match/batch): each component's purl is mapped to its OSV ecosystem, package name and version, and matched against the affected version ranges EchelonGraph holds from OSV.dev advisory records, the same matcher GET /api/v1/public/cves/match uses when given an ecosystem. No CPE matching, no score, no ranking.";
+// Always in the envelope's notes, whatever the answer: the refusals a model must not read as clean.
+const DISTRO_NOTE = "A deb, apk or rpm purl without a distro qualifier naming its release (for example ?distro=debian-12 or ?distro=alpine-3.20) is not assessed (distro_release_unknown): the advisory corpus is keyed per distro release, and EchelonGraph does not guess one.";
+const CLEAN_NOTE = "Only not_affected is a clean verdict, and only for the advisories decided at that version: an undetermined or not_assessed component is not a finding of no vulnerability, and is reported as unchecked, never as clean.";
+const MEASURED_AT_NOTE = "measured_at is null: the corpus rows are read through a cache whose maximum age the answer states (summary.corpus_cache_max_age_ms), so the answer gives no single time at which they were read.";
+const FRESHNESS_NOTE = "freshness is null: the answer carries no time at which the advisory corpus was last refreshed.";
+export const CHECK_SBOM_TITLE = "Check an SBOM against the advisory corpus";
+export const CHECK_SBOM_DESCRIPTION = "Check a dependency list against EchelonGraph's advisory corpus, one verdict per component. Pass purls (package URLs, up to 200) or sbom (a CycloneDX JSON or SPDX JSON document, as JSON text or as an object, up to 5,000,000 characters). The purls are read from the document on this machine and only they are sent, in the body of one POST, never in a URL; the document itself is not sent. A component without a purl is counted and not checked. Each purl is mapped to its OSV ecosystem, package name and version and matched against the affected version ranges EchelonGraph holds from OSV.dev advisory records; there is no ranking and no score. data.results holds one row per component sent, in order, with verdict (affected, not_affected, undetermined or not_assessed), assessed, not_assessed_reason, cve_ids, matches, count, not_affected_count and undetermined_count; data.summary counts the verdicts. not_affected is the only clean verdict. undetermined: advisories name the package but at least one could not be decided at this version and none matched. not_assessed: no verdict at all, because the package is not in the corpus, the purl type has no OSV ecosystem, a deb, apk or rpm purl carries no distro qualifier naming its release (EchelonGraph does not guess one), the version is missing, the lookup failed, or the batch's time budget ran out first (time_budget). Neither undetermined nor not_assessed is clean, and the note gives their counts. A list or document with more than 200 distinct purls is refused, not truncated: split it. Its structured result carries state (measured when at least one component got a verdict, else not_assessed), measured_at (null: the corpus is read through a cache, so no single read time exists), method, coverage (what the input held and what was sent), 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.";
+const isObj = (v) => v !== null && typeof v === "object" && !Array.isArray(v);
+function dedupe(all) {
+    const seen = new Set();
+    const purls = [];
+    for (const p of all) {
+        if (seen.has(p))
+            continue;
+        seen.add(p);
+        purls.push(p);
+    }
+    return { purls, removed: all.length - purls.length };
+}
+// The purls of a CycloneDX JSON document: every components[] entry, nested ones included.
+// metadata.component (the subject of the SBOM, not a dependency of it) is not checked.
+function fromCycloneDX(doc) {
+    if (doc.components !== undefined && !Array.isArray(doc.components))
+        return "its components is not an array";
+    let total = 0;
+    let without = 0;
+    const found = [];
+    const walk = (cs, depth) => {
+        if (!Array.isArray(cs))
+            return null;
+        if (depth > MAX_DEPTH)
+            return `its components nest deeper than ${MAX_DEPTH} levels`;
+        for (const c of cs) {
+            if (!isObj(c))
+                continue;
+            total++;
+            const p = typeof c.purl === "string" ? c.purl.trim() : "";
+            if (p)
+                found.push(p);
+            else
+                without++;
+            const err = walk(c.components, depth + 1);
+            if (err)
+                return err;
+        }
+        return null;
+    };
+    const err = walk(doc.components, 0);
+    if (err)
+        return err;
+    const { purls, removed } = dedupe(found);
+    return { input: "cyclonedx", components_in_document: total, with_purl: found.length, without_purl: without, duplicates_removed: removed, purls };
+}
+// The purls of an SPDX JSON document: each package's externalRefs entry of referenceType purl
+// (referenceCategory PACKAGE-MANAGER, spelled PACKAGE_MANAGER by some tools; the type decides).
+function fromSPDX(doc) {
+    if (doc.packages !== undefined && !Array.isArray(doc.packages))
+        return "its packages is not an array";
+    const pkgs = Array.isArray(doc.packages) ? doc.packages : [];
+    let total = 0;
+    let without = 0;
+    const found = [];
+    for (const p of pkgs) {
+        if (!isObj(p))
+            continue;
+        total++;
+        const refs = Array.isArray(p.externalRefs) ? p.externalRefs : [];
+        const ref = refs.find((r) => isObj(r) && typeof r.referenceType === "string" && r.referenceType.toLowerCase() === "purl" && typeof r.referenceLocator === "string" && r.referenceLocator.trim());
+        if (ref && isObj(ref))
+            found.push(String(ref.referenceLocator).trim());
+        else
+            without++;
+    }
+    const { purls, removed } = dedupe(found);
+    return { input: "spdx", components_in_document: total, with_purl: found.length, without_purl: without, duplicates_removed: removed, purls };
+}
+// Reads the tool's arguments into the purls to send, or says why it cannot.
+export function extract(a) {
+    const hasPurls = a.purls !== undefined;
+    const hasSbom = a.sbom !== undefined;
+    if (hasPurls === hasSbom)
+        return "pass exactly one of purls (a list of package URLs) or sbom (a CycloneDX JSON or SPDX JSON document)";
+    if (hasPurls) {
+        if (!Array.isArray(a.purls) || a.purls.some((p) => typeof p !== "string"))
+            return "purls must be a list of strings";
+        const trimmed = a.purls.map((p) => p.trim()).filter(Boolean);
+        const { purls, removed } = dedupe(trimmed);
+        return { input: "purls", components_in_document: null, with_purl: trimmed.length, without_purl: a.purls.length - trimmed.length, duplicates_removed: removed, purls };
+    }
+    let doc = a.sbom;
+    if (typeof doc === "string") {
+        if (doc.length > MAX_SBOM_CHARS)
+            return `sbom is ${doc.length} characters; at most ${MAX_SBOM_CHARS} are read`;
+        try {
+            doc = JSON.parse(doc);
+        }
+        catch {
+            return "sbom is not JSON: pass a CycloneDX JSON or SPDX JSON document (XML and SPDX tag-value are not read)";
+        }
+    }
+    else {
+        let size = 0;
+        try {
+            size = JSON.stringify(doc)?.length ?? 0;
+        }
+        catch {
+            return "sbom could not be serialised as JSON";
+        }
+        if (size > MAX_SBOM_CHARS)
+            return `sbom is ${size} characters as JSON; at most ${MAX_SBOM_CHARS} are read`;
+    }
+    if (!isObj(doc))
+        return "sbom must be a JSON object: a CycloneDX JSON or SPDX JSON document";
+    if (typeof doc.bomFormat === "string" && doc.bomFormat.toLowerCase() === "cyclonedx") {
+        const r = fromCycloneDX(doc);
+        return typeof r === "string" ? `the CycloneDX document cannot be read: ${r}` : r;
+    }
+    if (typeof doc.spdxVersion === "string" && doc.spdxVersion.toUpperCase().startsWith("SPDX-")) {
+        const r = fromSPDX(doc);
+        return typeof r === "string" ? `the SPDX document cannot be read: ${r}` : r;
+    }
+    return 'sbom is neither a CycloneDX JSON document (bomFormat "CycloneDX") nor an SPDX JSON document (spdxVersion "SPDX-…")';
+}
+// ── The answer ──
+const field = (o, k) => (isObj(o) ? o[k] : undefined);
+const count = (o, k) => {
+    const v = field(o, k);
+    return typeof v === "number" && Number.isFinite(v) ? v : undefined;
+};
+const plural = (n, one, many) => `${n} ${n === 1 ? one : many}`;
+function noteFor(head, x, d) {
+    const s = field(d, "summary");
+    const affected = count(s, "affected") ?? 0;
+    const notAffected = count(s, "not_affected") ?? 0;
+    const undetermined = count(s, "undetermined") ?? 0;
+    const notAssessed = count(s, "not_assessed") ?? 0;
+    const components = count(s, "components") ?? x.purls.length;
+    const out = [head];
+    if (x.input === "purls") {
+        out.push(`Sent ${plural(x.purls.length, "purl", "purls")}${x.duplicates_removed ? ` (${plural(x.duplicates_removed, "duplicate was", "duplicates were")} sent once)` : ""}.`);
+    }
+    else {
+        const kind = x.input === "cyclonedx" ? "CycloneDX" : "SPDX";
+        const unit = x.input === "cyclonedx" ? "component" : "package";
+        out.push(`Read ${plural(x.components_in_document ?? 0, unit, `${unit}s`)} from the ${kind} document: ${x.with_purl} with a purl${x.without_purl ? `, and ${x.without_purl} without one, which ${x.without_purl === 1 ? "was" : "were"} not checked and ${x.without_purl === 1 ? "is" : "are"} not clean` : ""}${x.duplicates_removed ? `; ${plural(x.duplicates_removed, "duplicate purl was", "duplicate purls were")} sent once` : ""}; sent ${x.purls.length}.`);
+    }
+    out.push(`Of the ${components} components checked: ${affected} affected, ${notAffected} not affected, ${undetermined} undetermined, ${notAssessed} not assessed.`);
+    const by = field(s, "not_assessed_by_reason");
+    if (isObj(by)) {
+        const parts = Object.entries(by)
+            .filter(([, n]) => typeof n === "number" && n > 0)
+            .sort(([a], [b]) => a.localeCompare(b))
+            .map(([r, n]) => `${r} ${n}`);
+        if (parts.length)
+            out.push(`Not assessed, by not_assessed_reason: ${parts.join(", ")}.`);
+        const tb = count(by, "time_budget") ?? 0;
+        if (tb > 0) {
+            out.push(`The batch's time budget ran out before ${plural(tb, "component was", "components were")} looked up: ${tb === 1 ? "it is" : "they are"} not assessed, not clean; check ${tb === 1 ? "it" : "them"} again.`);
+        }
+    }
+    const rows = field(d, "results");
+    if (Array.isArray(rows)) {
+        const hits = rows.filter((r) => field(r, "verdict") === "affected");
+        if (hits.length) {
+            const named = hits.slice(0, NOTE_AFFECTED_MAX).map((r) => {
+                const who = (typeof field(r, "purl") === "string" && field(r, "purl")) || `${field(r, "ecosystem") ?? ""} ${field(r, "package") ?? ""} ${field(r, "version") ?? ""}`.trim();
+                const ids = field(r, "cve_ids");
+                const list = Array.isArray(ids) ? ids.filter((i) => typeof i === "string") : [];
+                const shown = list.slice(0, NOTE_CVES_MAX).join(", ");
+                return `${who} (${shown}${list.length > NOTE_CVES_MAX ? `, and ${list.length - NOTE_CVES_MAX} more` : ""})`;
+            });
+            out.push(`Affected: ${named.join("; ")}${hits.length > NOTE_AFFECTED_MAX ? `; and ${hits.length - NOTE_AFFECTED_MAX} more affected components in data.results` : ""}.`);
+        }
+    }
+    return { note: out.join(" "), assessed: affected + notAffected + undetermined };
+}
+export async function checkSbom(deps, a) {
+    const tool = CHECK_SBOM;
+    try {
+        const x = extract(a);
+        if (typeof x === "string")
+            return deps.badInput(tool, x);
+        if (x.purls.length === 0) {
+            return deps.badInput(tool, x.input === "purls" ? "purls holds no package URL" : `the document holds ${x.components_in_document ?? 0} components and none carries a purl, so there is nothing to check`);
+        }
+        if (x.purls.length > MAX_COMPONENTS) {
+            return deps.badInput(tool, `${x.purls.length} distinct purls; at most ${MAX_COMPONENTS} are checked per call, and none is dropped silently: split the list into calls of ${MAX_COMPONENTS} or fewer`);
+        }
+        const long = x.purls.findIndex((p) => p.length > MAX_PURL_LEN);
+        if (long >= 0)
+            return deps.badInput(tool, `purl ${long + 1} is longer than ${MAX_PURL_LEN} characters`);
+        const r = await deps.api(BATCH_PATH, {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify({ components: x.purls.map((purl) => ({ purl })) }),
+        });
+        if (!r.ok)
+            return deps.failed(tool, r);
+        const { note, assessed } = noteFor(deps.okHead(tool, r.status), x, r.data);
+        const s = field(r.data, "summary");
+        return deps.succeeded(r.data, note, {
+            state: assessed > 0 ? "measured" : "not_assessed",
+            measured_at: null,
+            method: METHOD,
+            coverage: {
+                input: x.input,
+                components_in_document: x.components_in_document,
+                with_purl: x.with_purl,
+                without_purl: x.without_purl,
+                duplicates_removed: x.duplicates_removed,
+                sent: x.purls.length,
+                not_assessed: count(s, "not_assessed") ?? null,
+                partial: typeof field(s, "partial") === "boolean" ? field(s, "partial") : null,
+            },
+            freshness: null,
+            notes: [DISTRO_NOTE, CLEAN_NOTE, MEASURED_AT_NOTE, FRESHNESS_NOTE],
+        });
+    }
+    catch (e) {
+        return deps.crashed(tool, e);
+    }
+}
+// ── Schemas ──
+const opt = (t) => t.nullable().optional();
+const Row = z.looseObject({
+    index: opt(z.number()),
+    input_kind: opt(z.string()),
+    purl: opt(z.string()),
+    verdict: opt(z.string()).describe("affected (count > 0); not_affected (assessed, no match, nothing undetermined: the only clean verdict); undetermined (advisories name the package, at least one could not be decided, none matched: not clean); not_assessed (no verdict: not clean)."),
+    ecosystem: opt(z.string()),
+    package: opt(z.string()),
+    version: opt(z.string()),
+    assessed: opt(z.boolean()).describe("Whether the matcher produced a verdict for this component. false is never clean."),
+    not_assessed_reason: opt(z.string()).describe("Why assessed is false: package_not_in_advisory_corpus, no_decidable_advisory, advisory_lookup_failed, candidate_window_truncated, time_budget, distro_release_unknown, purl_type_unsupported, version_missing or invalid_component."),
+    code: opt(z.string()),
+    error: opt(z.string()),
+    cve_ids: opt(z.array(z.string())),
+    matches: opt(z.array(z.looseObject({ cve_id: opt(z.string()) }))),
+    count: opt(z.number()),
+    advisories_considered: opt(z.number()),
+    not_affected_count: opt(z.number()),
+    undetermined_count: opt(z.number()),
+    undetermined: opt(z.array(z.looseObject({ cve_id: opt(z.string()) }))),
+    capped: opt(z.boolean()),
+    candidates_capped: opt(z.boolean()),
+});
+export function checkSbomOutput(envelopeSchema) {
+    return envelopeSchema({
+        data: z.looseObject({
+            match_layer: opt(z.string()),
+            components: opt(z.number()),
+            summary: z
+                .looseObject({
+                components: opt(z.number()),
+                affected: opt(z.number()),
+                not_affected: opt(z.number()).describe("Components with a decided, clean verdict."),
+                undetermined: opt(z.number()).describe("Components whose advisories could not all be decided and none matched: not clean."),
+                not_assessed: opt(z.number()).describe("Components with no verdict: not clean."),
+                not_assessed_by_reason: opt(z.looseObject({
+                    package_not_in_advisory_corpus: z.number().optional(),
+                    no_decidable_advisory: z.number().optional(),
+                    advisory_lookup_failed: z.number().optional(),
+                    candidate_window_truncated: z.number().optional(),
+                    time_budget: z.number().optional().describe("Components the batch's time budget ran out before: not clean; check them again."),
+                    distro_release_unknown: z.number().optional().describe("deb, apk or rpm purls without a distro qualifier naming the release, which EchelonGraph does not guess."),
+                    purl_type_unsupported: z.number().optional(),
+                    version_missing: z.number().optional(),
+                    invalid_component: z.number().optional(),
+                })).describe("The not_assessed components, counted by not_assessed_reason."),
+                lookups: opt(z.number()),
+                partial: opt(z.boolean()).describe("true when the time budget ran out before every component was looked up."),
+                time_budget_ms: opt(z.number()),
+                elapsed_ms: opt(z.number()),
+                corpus_cache_max_age_ms: opt(z.number()),
+            })
+                .optional(),
+            answered_at: opt(z.string()),
+            results: z.array(Row).optional(),
+        }),
+        coverage: z.strictObject({
+            input: z.enum(["purls", "cyclonedx", "spdx"]).describe("What was passed: a purl list, a CycloneDX JSON document or an SPDX JSON document."),
+            components_in_document: z.number().int().nullable().describe("Components (CycloneDX) or packages (SPDX) in the document; null for a purl list."),
+            with_purl: z.number().int().describe("Of those, the ones carrying a purl."),
+            without_purl: z.number().int().describe("The ones without a purl: not checked, and not clean."),
+            duplicates_removed: z.number().int().describe("Purls that appeared more than once and were sent once."),
+            sent: z.number().int().describe("Distinct purls sent and checked."),
+            not_assessed: z.number().int().nullable().describe("Of those sent, the components with no verdict, as the answer counts them."),
+            partial: z.boolean().nullable().describe("The answer's summary.partial: true when the time budget ran out first."),
+        }),
+        freshness: null,
+    });
+}
+// 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 registerCheckSbom(server, deps) {
+    const output = checkSbomOutput(deps.envelopeSchema);
+    server.registerTool(CHECK_SBOM, {
+        title: CHECK_SBOM_TITLE,
+        description: CHECK_SBOM_DESCRIPTION,
+        inputSchema: z.object({
+            purls: z.array(z.string()).optional().describe("package URLs to check, e.g. pkg:npm/lodash@4.17.20 or pkg:deb/debian/openssl@3.0.11-1~deb12u1?distro=debian-12 (up to 200)"),
+            sbom: z
+                .union([z.string(), z.record(z.string(), z.unknown())])
+                .optional()
+                .describe("a CycloneDX JSON or SPDX JSON document, as JSON text or as an object; its purls are read here and only they are sent"),
+        }),
+        outputSchema: output,
+        annotations: deps.annotations,
+    }, async (a) => deps.checked(CHECK_SBOM, output, await checkSbom(deps, a)));
+}

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)));
+}