echelongraph-mcp 2.3.3 → 2.4.0

package/dist/tools/check_affected.js

@@ -0,0 +1,269 @@
+// check_affected (#2716): "am I affected by product X at version Y?", answered by the same
+// endpoint as echelongraph.io/am-i-affected, GET /api/v1/public/cves/match (core-backend
+// internal/cve/handler.go MatchByProductPublic). Two lookup paths, chosen by the input:
+//
+//   cpe       {product, version}: the CPE matcher (matchByProductPublic). CVEs whose NVD CPE
+//             product field is this token and whose version range includes this version. It
+//             matches the product token across vendors; each match names the vendor NVD asserts
+//             (cpe_vendor) and whether that vendor was verified (vendor_unknown).
+//   registry  {ecosystem, package, version}: the registry matcher (matchByPackage). The OSV
+//             advisory records EchelonGraph holds for this package, each decided against this
+//             version as affected, not affected, or undetermined.
+//
+// #1983: every typed value travels in a request header (X-EG-Product, X-EG-Version,
+// X-EG-Ecosystem, X-EG-Package; handler.go MatchProductHeader..MatchPackageHeader), percent-
+// encoded as the backend's publicMatchParam decodes it, and never in the URL: Cloud Run's request
+// log and its trace spans record the URL and no request header. The backend answers a
+// header-carried lookup with Cache-Control: private, no-store and varies on the four headers. The
+// endpoint reads the CPE vendor from the query string only (handler.go matchByProductPublic), so
+// this tool takes no vendor: sending one would put a typed value in the URL.
+//
+// The verdict is `assessed`, read BEFORE `count` (the endpoint's own contract): assessed false
+// means the lookup did not evaluate this component, and count 0 then asserts nothing. So the
+// envelope's state is measured only when the answer says assessed true; assessed false, or an
+// answer without assessed, is not_assessed, and the note's first sentence after the head says so,
+// with the reason. A 500/503 (advisory_lookup_failed) is a failure like any other non-2xx.
+//
+// The JSON is relayed verbatim as data (#1874): every match keeps kev_listed, ransomware,
+// epss_score, effective_score, effective_severity and score_assessed as the API sent them.
+import * as z from "zod";
+const TOOL = "check_affected";
+export const MATCH_PATH = "/api/v1/public/cves/match";
+// handler.go, the four request headers the endpoint reads before the query string.
+export const MATCH_HEADERS = { product: "X-EG-Product", version: "X-EG-Version", ecosystem: "X-EG-Ecosystem", package: "X-EG-Package" };
+const CPE_METHOD = "EchelonGraph's CPE matcher over its CVE corpus, the matcher behind echelongraph.io/am-i-affected and EchelonGraph's scanner: CVEs whose NVD CPE match criteria name this product token and whose version range includes this version.";
+const REGISTRY_METHOD = "EchelonGraph's registry matcher, the matcher behind echelongraph.io/am-i-affected for a registry package: the OSV advisory records EchelonGraph holds for this package in this ecosystem, each decided against this version as affected, not affected, or undetermined.";
+const NO_TIME = "measured_at is null: a match answer carries no observation time, and each matched CVE is a record of the CVE feed, polled from its sources on a schedule.";
+const NO_FRESHNESS = "freshness is null: the match answer carries no time at which the feed's pollers last completed.";
+// Why an answer says assessed false (core-backend cve/cpematch.go, cve/pkgmatch.go). One sentence
+// each, worded so that none reads as a clean result.
+const REASONS = {
+    product_not_in_cpe_corpus: "no CVE in the CPE corpus has this token as its CPE product, so the component was not located, not cleared; the CPE product token can differ from a package name (spring_boot, not spring-boot), and a registry package can be looked up by ecosystem and package instead.",
+    package_not_cpe_nameable: "the CVEs the CPE corpus holds for this token describe it in a way the CPE lookup cannot decide for this asset (an npm package NVD records only for target_sw node.js is the common case), so a registry lookup by ecosystem and package is the one to use.",
+    candidate_load_pending: "the product's candidate CVEs were still loading when this request's time ran out (degraded), so nothing was compared; the same lookup can be retried shortly.",
+    candidate_window_truncated: "the product has more candidate CVEs than one lookup loads (candidates_capped), so the CVEs below the cut were never examined.",
+    package_not_in_advisory_corpus: "EchelonGraph holds no advisory record for this package in this ecosystem, so the package was not located, not cleared; the ecosystem and package name are worth checking.",
+    no_decidable_advisory: "EchelonGraph holds advisories for this package, but not one of them could be decided either way at this version (see undetermined).",
+    advisory_lookup_failed: "the advisory lookup failed.",
+};
+// The reasons this version describes, and any other string, which the note names as one it does not.
+const REASON = z.union([z.enum(Object.keys(REASONS)), z.string()]).describe("Why assessed is false; empty or absent when it is true.");
+const opt = (t) => t.nullable().optional();
+const Match = z.looseObject({
+    cve_id: opt(z.string()),
+    description: opt(z.string()),
+    severity: opt(z.string()).describe("NVD's own CVSS v3 band, as provenance: it can be NONE for a CVE NVD rated only under CVSS v2. Rank and display on effective_severity."),
+    cvss_v3_score: opt(z.number()),
+    cvss_v2_score: opt(z.number()),
+    cvss_v4_score: opt(z.number()),
+    kev_listed: opt(z.boolean()).describe("Listed in CISA-KEV: known to be exploited."),
+    ransomware: opt(z.boolean()).describe("CISA-KEV records known use in ransomware campaigns."),
+    epss_score: opt(z.number()).describe("EPSS exploitation probability, 0 to 1."),
+    echelongraph_score: opt(z.number()).describe("EchelonGraph's 0-10 score: present only when score_assessed is true."),
+    echelongraph_severity: opt(z.string()),
+    effective_score: opt(z.number()).describe("The best real score held for the CVE (EchelonGraph's, else CVSS), the number the matches are ranked by."),
+    effective_severity: opt(z.string()).describe("The band of effective_score; absent or empty when the CVE has no band at all (unrated, not harmless)."),
+    score_assessed: opt(z.boolean()).describe("Whether EchelonGraph has scored the CVE. false: NOT YET SCORED, and echelongraph_score is withheld."),
+    score_unassessed_reason: opt(z.string()),
+    vendor_severity: opt(z.string()),
+    matched_criteria: opt(z.string()),
+    match_method: opt(z.string()),
+    match_confidence: opt(z.number()),
+    cpe_vendor: opt(z.string()).describe("The vendor NVD's CPE asserts for this match."),
+    vendor_unknown: opt(z.boolean()).describe("true: the vendor was not verified, so the match is real but its attribution to your vendor is not."),
+    match_reason: opt(z.string()),
+    version_evidence: opt(z.string()),
+});
+const Undetermined = z.looseObject({
+    cve_id: opt(z.string()),
+    package: opt(z.string()),
+    ecosystem: opt(z.string()),
+    reason: opt(z.string()),
+    detail: opt(z.string()),
+});
+const DATA = z.looseObject({
+    product: opt(z.string()),
+    version: opt(z.string()),
+    vendor: opt(z.string()),
+    ecosystem: opt(z.string()),
+    ecosystem_recognised: opt(z.boolean()),
+    package: opt(z.string()),
+    assessed: opt(z.boolean()).describe("Read first. true: the lookup evaluated this component. false: it did not, and count 0 says nothing about whether this version is affected."),
+    not_assessed_reason: opt(REASON),
+    match_layer: opt(z.string()),
+    cve_ids: opt(z.array(z.string())),
+    matches: opt(z.array(Match)),
+    count: opt(z.number()),
+    capped: opt(z.boolean()),
+    candidates_capped: opt(z.boolean()),
+    candidate_count: opt(z.number()),
+    advisories_considered: opt(z.number()),
+    excluded_count: opt(z.number()),
+    excluded: z.unknown().optional(),
+    undetermined_count: opt(z.number()),
+    undetermined: opt(z.array(Undetermined)),
+    not_affected_count: opt(z.number()),
+    degraded: opt(z.boolean()),
+    undecidable_excluded_count: opt(z.number()),
+    undecided_candidate_count: opt(z.number()),
+    product_named_count: opt(z.number()),
+    vendor_advisory_count: opt(z.number()),
+});
+const COVERAGE = z.strictObject({
+    assessed: z.boolean().nullable().describe("The answer's assessed, first: null when the answer does not say."),
+    not_assessed_reason: REASON.nullable(),
+    lookup: z.enum(["cpe", "registry"]).describe("Which lookup path this call asked for."),
+    match_layer: z.string().nullable(),
+    count: z.number().nullable(),
+    capped: z.boolean().nullable(),
+    candidates_capped: z.boolean().nullable(),
+    excluded_count: z.number().nullable(),
+    undetermined_count: z.number().nullable(),
+    not_affected_count: z.number().nullable(),
+    degraded: z.boolean().nullable(),
+});
+// Constant strings, so marketing-site lib/mcpToolClaims.test.ts can fold them should it read
+// this file.
+export const CHECK_AFFECTED_TITLE = "Am I affected? (product or package at a version)";
+export const CHECK_AFFECTED_DESCRIPTION = "Whether a product or package at a given version is affected by known CVEs, from the same matcher as echelongraph.io/am-i-affected. Two lookup paths. The CPE path takes product (the NVD CPE product token, such as openssl or nginx) and version, and returns the CVEs whose NVD CPE match criteria name that product with a version range that includes the version; it matches the token across vendors, so each match names the vendor NVD asserts (cpe_vendor) and whether that vendor was verified (vendor_unknown). The registry path takes ecosystem (npm, PyPI, Maven and other OSV ecosystem names), package and version, and decides each OSV advisory record EchelonGraph holds for that package as affected, not affected or undetermined. Read assessed before count: assessed false means the lookup did not evaluate this component, not_assessed_reason says why (product_not_in_cpe_corpus, package_not_cpe_nameable, candidate_load_pending, candidate_window_truncated, package_not_in_advisory_corpus, no_decidable_advisory), the structured result's state is not_assessed, and a count of 0 there must never be reported as not affected. An advisory whose version range cannot be decided at this version is reported as undetermined (undetermined_count, and up to 50 of them in undetermined), never as safe. The answer also carries match_layer (which path answered), capped (the match list stopped at its cap), candidates_capped (not every candidate CVE was loaded), excluded_count (CPE candidates suppressed by the vendor or platform gate), not_affected_count (advisories decided in your favour) and degraded (the lookup ran out of time). Each match carries cve_id, kev_listed, ransomware, epss_score, effective_score, effective_severity and score_assessed (false: EchelonGraph has not scored the CVE yet, so its echelongraph_score is withheld). Product, version, ecosystem and package travel in request headers, never in the URL. Its structured result carries state (measured only when the answer says assessed true), measured_at (null), method (which matcher answered), coverage (assessed and not_assessed_reason first, then the lookup path and the counts above), freshness (null) and notes, with data equal to the API's JSON.";
+export const CHECK_AFFECTED_INPUT = z.object({
+    product: z.string().optional().describe("CPE path: the NVD CPE product token, such as openssl, nginx or linux_kernel. Leave out for the registry path."),
+    ecosystem: z.string().optional().describe("Registry path: the package's ecosystem, such as npm, PyPI or Maven. Give with package, not with product."),
+    package: z.string().optional().describe("Registry path: the package name in that ecosystem, such as lodash."),
+    version: z.string().describe("The version to check, such as 3.0.0."),
+});
+const field = (o, k) => (o !== null && typeof o === "object" ? o[k] : undefined);
+const num = (o, k) => {
+    const v = field(o, k);
+    return typeof v === "number" && Number.isFinite(v) ? v : null;
+};
+const bool = (o, k) => {
+    const v = field(o, k);
+    return typeof v === "boolean" ? v : null;
+};
+const str = (o, k) => {
+    const v = field(o, k);
+    return typeof v === "string" && v ? v : null;
+};
+const plural = (n, one, many) => `${n} ${n === 1 ? one : many}`;
+// The sentences about the matches themselves: how many are KEV-listed, and which are not scored.
+function matchesNote(matches) {
+    const kev = matches.filter((m) => field(m, "kev_listed") === true).length;
+    const ransomware = matches.filter((m) => field(m, "ransomware") === true).length;
+    const unscored = matches.filter((m) => field(m, "score_assessed") === false).map((m, i) => str(m, "cve_id") ?? `matches[${i}]`);
+    const unverified = matches.filter((m) => field(m, "vendor_unknown") === true).length;
+    let out = "";
+    if (unverified > 0) {
+        out += ` ${unverified === matches.length ? "Every match has" : `${plural(unverified, "match has", "matches have")}`} vendor_unknown true: matched on the product name, so the vendor NVD asserts (cpe_vendor) is not verified to be the one you run.`;
+    }
+    if (kev > 0)
+        out += ` ${plural(kev, "of them is", "of them are")} listed in CISA-KEV (kev_listed)${ransomware > 0 ? `, ${ransomware} with known ransomware use` : ""}.`;
+    if (unscored.length > 0) {
+        const shown = unscored.slice(0, 10).join(", ");
+        out += ` NOT YET SCORED (score_assessed: false): ${shown}${unscored.length > 10 ? ` and ${unscored.length - 10} more` : ""}; EchelonGraph has not scored ${unscored.length === 1 ? "it" : "them"}, so an effective_score of zero or an empty effective_severity there means unrated, not harmless.`;
+    }
+    return out;
+}
+async function checkAffected(kit, a) {
+    const product = (a.product ?? "").trim();
+    const ecosystem = (a.ecosystem ?? "").trim();
+    const pkg = (a.package ?? "").trim();
+    const version = (a.version ?? "").trim();
+    if (product && (ecosystem || pkg))
+        return kit.badInput(TOOL, "give product (the CPE path) or ecosystem and package (the registry path), not both");
+    if (!product && !ecosystem && !pkg)
+        return kit.badInput(TOOL, "product, or ecosystem and package, is required");
+    if (!product && !ecosystem)
+        return kit.badInput(TOOL, "ecosystem is required with package");
+    if (!product && !pkg)
+        return kit.badInput(TOOL, "package is required with ecosystem");
+    if (!version)
+        return kit.badInput(TOOL, "version is required");
+    const lookup = product ? "cpe" : "registry";
+    // #1983: percent-encoded, as the backend's publicMatchParam decodes it (url.PathUnescape), so
+    // any value is a legal header and a literal + survives.
+    const enc = encodeURIComponent;
+    const headers = lookup === "cpe"
+        ? { [MATCH_HEADERS.product]: enc(product), [MATCH_HEADERS.version]: enc(version) }
+        : { [MATCH_HEADERS.ecosystem]: enc(ecosystem), [MATCH_HEADERS.package]: enc(pkg), [MATCH_HEADERS.version]: enc(version) };
+    try {
+        const r = await kit.api(MATCH_PATH, { headers });
+        if (!r.ok)
+            return kit.failed(TOOL, r);
+        const d = r.data;
+        const assessed = bool(d, "assessed");
+        const reason = str(d, "not_assessed_reason");
+        const matches = Array.isArray(field(d, "matches")) ? field(d, "matches") : [];
+        const count = num(d, "count") ?? (Array.isArray(field(d, "matches")) ? matches.length : null);
+        const capped = bool(d, "capped");
+        const candidatesCapped = bool(d, "candidates_capped");
+        const undetermined = num(d, "undetermined_count");
+        const notAffected = num(d, "not_affected_count");
+        const excluded = num(d, "excluded_count");
+        const degraded = bool(d, "degraded");
+        const layer = str(d, "match_layer");
+        const what = lookup === "cpe" ? `product ${product} at version ${version}` : `${ecosystem} package ${pkg} at version ${version}`;
+        // assessed, first.
+        let note = kit.okHead(TOOL, r.status);
+        if (assessed === true) {
+            note += ` (state: measured) assessed: true, so the lookup evaluated ${what}.`;
+        }
+        else if (assessed === false) {
+            const why = reason === null ? "the answer gives no not_assessed_reason." : (REASONS[reason] ?? `the answer gives not_assessed_reason ${reason}, which this version of the server does not describe.`);
+            note += ` (state: not_assessed) NOT ASSESSED: assessed is false for ${what}${reason === null ? "" : ` (not_assessed_reason ${reason})`}: ${why} A count of 0 here does not mean this version is not affected: do not report it as unaffected or clean.`;
+        }
+        else {
+            note += ` (state: not_assessed) The answer carries no assessed field (an API older than it sends none), so it does not say whether ${what} was evaluated, and a count of 0 here does not mean this version is not affected.`;
+        }
+        if (count !== null && count > 0) {
+            note += ` AFFECTED: ${plural(count, "CVE matches", "CVEs match")} this version${capped === true ? " (capped: true, so the list stopped at its cap and more may match)" : ""}.${matchesNote(matches)}`;
+        }
+        else if (count === 0 && assessed === true) {
+            note += ` 0 CVEs match this version, a measured result (we looked and found nothing that matches), not a lookup failure.`;
+            if (lookup === "registry" && notAffected !== null)
+                note += ` ${plural(notAffected, "advisory was", "advisories were")} decided not to affect this version (not_affected_count), and only those are cleared.`;
+        }
+        if (undetermined !== null && undetermined > 0) {
+            note += ` UNDETERMINED: ${plural(undetermined, "advisory names", "advisories name")} this package with a version range that could not be decided at this version (undetermined_count, listed in undetermined): report ${undetermined === 1 ? "it" : "them"} as undetermined, never as safe.`;
+        }
+        if (candidatesCapped === true && reason !== "candidate_window_truncated")
+            note += " candidates_capped is true: not every candidate CVE was loaded, so more CVEs may match than the answer lists.";
+        if (excluded !== null && excluded > 0)
+            note += ` ${plural(excluded, "candidate CVE was", "candidate CVEs were")} suppressed by the vendor or platform gate (excluded_count, listed in excluded).`;
+        if (degraded === true)
+            note += " degraded is true: the lookup ran out of time before it finished, so this answer is incomplete.";
+        return kit.succeeded(d, note, {
+            state: assessed === true ? "measured" : "not_assessed",
+            measured_at: null,
+            method: (layer ?? lookup) === "registry" ? REGISTRY_METHOD : CPE_METHOD,
+            coverage: {
+                assessed,
+                not_assessed_reason: reason,
+                lookup,
+                match_layer: layer,
+                count,
+                capped,
+                candidates_capped: candidatesCapped,
+                excluded_count: excluded,
+                undetermined_count: undetermined,
+                not_affected_count: notAffected,
+                degraded,
+            },
+            freshness: null,
+            notes: [NO_TIME, NO_FRESHNESS],
+        });
+    }
+    catch (e) {
+        return kit.crashed(TOOL, e);
+    }
+}
+export function registerCheckAffected(server, kit) {
+    const output = kit.envelopeSchema({ data: DATA, coverage: COVERAGE, freshness: null });
+    server.registerTool(TOOL, {
+        title: CHECK_AFFECTED_TITLE,
+        description: CHECK_AFFECTED_DESCRIPTION,
+        inputSchema: CHECK_AFFECTED_INPUT,
+        outputSchema: output,
+        annotations: kit.annotations,
+    }, async (a) => kit.checked(TOOL, output, await checkAffected(kit, a)));
+}

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