echelongraph-mcp 3.0.0 → 3.1.0

package/dist/tools/cve_intel.js

@@ -42,6 +42,7 @@
 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";
 import { answering, FULL_ARG, TEXT_BUDGET_DESCRIPTION } from "../textBudget.js";
+import { ONE_PACKAGE_RULE, packagesListedTwice } from "./packageRecords.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"];
@@ -73,9 +74,57 @@ const LEFT_OUT = ["vendor_advisories", "patches", "ai", "trending", "historical_
 // 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.";
+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 and checker repositories, 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.";
+// #3267: the exploit kinds this server classifies, both lists by name, as core-backend's
+// egkev.ExploitCodeKinds lists exploit code ("the one definition of exploit code", #1213, #3038)
+// and every other kind core-backend holds (exploits.Kind* constants) is a detection kind there.
+// Until #3267 this server named only the detection kinds and counted every other kind as exploit
+// code, the inverse of the backend's list: the two failed in opposite directions. core-backend fails
+// closed (egkev/backfill_exploit_poc_available.sql raises on a kind ExploitCodeKinds does not
+// classify); this server failed open, so a kind core-backend added after a release (another scanner
+// or template source) would have reached every client of that release as "N public exploit
+// references", the claim #3039 removed, with nothing erroring. github_checker did exactly that
+// from #3040 (2026-10-12) to #3221. A kind on neither list is now counted as neither: the note
+// names it as a kind this server does not classify (exploitSentences). test/cve_intel.test.mjs holds both
+// lists to core-backend's source in the monorepo, and the kind field's text to the note everywhere.
+const EXPLOIT_CODE_KINDS = ["metasploit", "exploit_db", "github_poc", "vendor_poc"];
+const DETECTION_KINDS = ["nuclei_template", "github_checker"];
+const DETECTION_GLOSS = {
+    nuclei_template: "a Nuclei detection template",
+    github_checker: "a GitHub repository named or described as a checker or scanner",
+};
+const isExploitCodeKind = (k) => EXPLOIT_CODE_KINDS.includes(k);
+const isDetectionKind = (k) => DETECTION_KINDS.includes(k);
+const orList = (xs) => (xs.length <= 1 ? (xs[0] ?? "") : `${xs.slice(0, -1).join(", ")} or ${xs.at(-1)}`);
+const andList = (xs) => (xs.length <= 1 ? (xs[0] ?? "") : `${xs.slice(0, -1).join(", ")} and ${xs.at(-1)}`);
+// #3267's review: the method and exploits_by_kind name the kinds from the same two lists, so neither
+// can name a kind the note counts otherwise; each kind's words are a Record over its list, so a kind
+// added to a list without them does not compile.
+const CODE_NOUN = {
+    metasploit: "Metasploit modules",
+    exploit_db: "Exploit-DB entries",
+    github_poc: "GitHub proof-of-concept repositories",
+    vendor_poc: "vendor proofs of concept",
+};
+const DETECTION_NOUN_METHOD = {
+    nuclei_template: "Nuclei detection templates (nuclei_template)",
+    github_checker: "GitHub checker repositories (github_checker: GitHub repositories named or described as a checker or scanner)",
+};
+const UNCLASSIFIED_KIND = "A kind on neither list is one this server does not classify: the note counts it as neither.";
+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: EchelonGraph's cve_exploits records, whose data model holds public exploit code, namely ${andList(EXPLOIT_CODE_KINDS.map((k) => `${CODE_NOUN[k]} (${k})`))}, and detection checks, namely ${andList(DETECTION_KINDS.map((k) => DETECTION_NOUN_METHOD[k]))}, which check whether a system is affected and are not necessarily exploit code, 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. ${UNCLASSIFIED_KIND} affected_packages and fixed_versions: package-ecosystem advisory data, each row naming its source. timeline: EchelonGraph's enrichment history for the CVE, newest first.`;
+// #3221: the kinds, split as egkev.ExploitCodeKinds splits them (#3038, #3040) and /pulse shows
+// them: exploit code, and the two detection kinds. Until #3221 the field listed nuclei_template
+// beside the exploit-code kinds, and not github_checker, a kind core-backend's data model has held
+// since #3040 (exploits.KindGitHubChecker). The text says what each kind is, not which rows carry
+// it. #3267: built from the two lists the note counts by, so the field cannot name a kind the note
+// counts otherwise, and it says what the note does with any other kind.
+const EXPLOIT_KIND_DESCRIPTION = `Exploit code: ${orList(EXPLOIT_CODE_KINDS)}. A detection check, which checks whether a system is affected and is not necessarily exploit code: ${orList(DETECTION_KINDS.map((k) => `${k} (${DETECTION_GLOSS[k]})`))}. A kind not named here is one this server does not classify: the note counts it as neither.`;
+const EXPLOITS_BY_KIND_DESCRIPTION = `Every reference on record counted by kind (the values of each exploit's kind), past the 10 listed; the counts under ${andList(DETECTION_KINDS)} are detection checks, not exploit code, those under ${andList(EXPLOIT_CODE_KINDS)} are exploit code, and those under any other kind are of a kind this server does not classify, counted as neither.`;
 const FIXED_BRANCHES_DESCRIPTION = 'fixed_branches lists each affected range of the package on record: introduced, and fixed (the range\'s fix) or last_affected (its last affected version, where no fix is on record), each null when absent, with advisory_id (the OSV record that published the range) and source (the loader\'s label for that record), both null on a row loaded before they were stored. Ranges with an advisory_id are in the order their record lists them (records in id order); ranges without one are oldest first. To pick the range for an installed version, compare in the ecosystem\'s version order (release numbers part by part, as numbers: 2.4 is below 2.13.0): the version is in a range when it is at or above introduced ("0" is the first version) and below fixed, or at or below last_affected; its fix is that range\'s fixed, or, while another range still holds that, the other range\'s fixed (none past a range without one); a version in no range is outside every range on record. fixed_branches is null where the package\'s ranges were never loaded, and [] where no version range is on record (the advisory gives none, only commit ranges, or more than are stored), which is not a finding that no fix exists: fixed_version can still name one. fixed_version is one range\'s fix, kept for compatibility (one per package: the range the loader kept, the advisory\'s last as a rule), not the fix for every affected range: for CVE-2021-44228, its advisory gives log4j-core three ranges, and fixed_version 2.12.2 is the fix for the one from 2.4, while the range holding 2.14.1 (from 2.13.0) is fixed in 2.15.0.';
+// #3039: a Nuclei template is a detection check, not necessarily exploit code (core-backend
+// egkev.ExploitCodeKinds, #3038; /pulse words it so since #3022). The head says "exploit code,
+// detection templates" where it said "public exploit code"; the method and the note say what a
+// template is, and count templates apart. The room: "the newest" and "per-CVE" (14 characters).
 // #2876: the exploit dates are named for what they are. Within the 100 characters of headroom
 // under the 2048-character client cut (prompts-resources.test.mjs), the room came from tighter
 // glosses and from the input hint, which inputSchema's cve_id description carries.
@@ -84,7 +133,10 @@ const FIXED_BRANCHES_DESCRIPTION = 'fixed_branches lists each affected range of
 // still-affected 4.17.21 (ranges [0, 4.17.21) and [4.0.0, 4.18.0); the fix is 4.18.0). It now
 // states the walk FIXED_BRANCHES_DESCRIPTION and branchSentences state, in fewer characters than
 // the old rule (a range's bounds folded into the list of its fields), so the headroom holds.
-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 name and source), exploits (each with kind, source_name, source_url, source_published_at (the source's date, null if none), eg_first_seen_at (when EchelonGraph recorded it) and verified_status; at most 10, verified first) with exploits_total, exploits_capped, exploits_by_kind and exploits_by_status, affected_packages (ecosystem, package_name, version_range, fixed_version, fixed_branches), fixed_versions (each fixed version with the vulnerable_range it fixes) and timeline (the newest enrichment-history rows, with timeline_total). fixed_branches lists each affected range on record (from introduced ("0" is the first version) to below fixed, or through last_affected, with advisory_id (its OSV record) and source); in the ecosystem's version order, an affected version's fix is the first fixed above it that no range of its row holds (none past a range with no fixed). fixed_version is one range's fix, kept for compatibility, not the fix for every affected range. fixed_branches [] is not a finding that no fix exists. verified_status is the source's label, not a guarantee the exploit works on a given system. An empty exploits list is not evidence that no public exploit exists: it covers only the sources EchelonGraph ingests, and which 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. Its structured result carries notes, with data, which the first text block holds whole up to 30,000 characters; its coverage names the sections relayed, failed and left out. ${TEXT_BUDGET_DESCRIPTION}`;
+// #3221: "detection checks", /pulse's word for Nuclei templates and GitHub checker repositories
+// together (ExploitWatch.tsx DETECTION_CHECKS_HEADING), where the head said "detection templates",
+// which a checker repository is not; 3 characters shorter. The kinds are the outputSchema's.
+export const CVE_INTEL_DESCRIPTION = `Weakness, exploit code, detection checks, affected packages and fixed versions for one CVE, from EchelonGraph's per-CVE enrichment. Returns cwes (each cwe_id with name and source), exploits (each with kind, source_name, source_url, source_published_at (the source's date, null if none), eg_first_seen_at (when EchelonGraph recorded it) and verified_status; at most 10, verified first) with exploits_total, exploits_capped, exploits_by_kind and exploits_by_status, affected_packages (ecosystem, package_name, version_range, fixed_version, fixed_branches), fixed_versions (each fixed version with the vulnerable_range it fixes) and timeline (newest enrichment-history rows, with timeline_total). fixed_branches lists each affected range on record (from introduced ("0" is the first version) to below fixed, or through last_affected, with advisory_id (its OSV record) and source); in the ecosystem's version order, an affected version's fix is the first fixed above it that no range of its row holds (none past a range with no fixed). fixed_version is one range's fix, kept for compatibility, not the fix for every affected range. fixed_branches [] is not a finding that no fix exists. verified_status is the source's label, not a guarantee the exploit works on a given system. An empty exploits list is not evidence that no public exploit exists: it covers only the sources EchelonGraph ingests, and which 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. Its structured result carries notes, with data, which the first text block holds whole up to 30,000 characters; its coverage names the sections relayed, failed and left out. ${TEXT_BUDGET_DESCRIPTION}`;
 // ── outputSchema ──
 const Rows = (shape) => z.array(z.looseObject(shape));
 const CountMap = z.record(z.string(), z.number());
@@ -97,7 +149,7 @@ function schemas() {
         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."),
+            kind: opt(z.string()).describe(EXPLOIT_KIND_DESCRIPTION),
             source_name: opt(z.string()),
             source_url: opt(z.string()),
             description: opt(z.string()),
@@ -110,7 +162,7 @@ function schemas() {
         }).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_kind: CountMap.optional().describe(EXPLOITS_BY_KIND_DESCRIPTION),
         exploits_by_status: CountMap.optional(),
         affected_packages: Rows({
             ecosystem: opt(z.string()),
@@ -178,6 +230,70 @@ function cweSentence(cve, cwes) {
     });
     return `${cve} is classified under ${listed(named)}.`;
 }
+const DETECTION_NOUN = {
+    nuclei_template: ["Nuclei detection template", "Nuclei detection templates"],
+    github_checker: ["GitHub checker repository", "GitHub checker repositories"],
+};
+// /pulse's DETECTION_TEMPLATE_NOTE and CHECKER_REPOSITORY_NOTE, each lower-cased and without its
+// period, to follow a colon, a semicolon or an opening parenthesis.
+const DETECTION_NOTE = "a detection template checks whether a system is affected; it is not necessarily exploit code";
+const CHECKER_NOTE = "a GitHub repository named or described as a checker or scanner checks whether a system is affected; it is not necessarily exploit code";
+// Both kinds: /pulse's two notes in sequence, as the page prints them, never one merged sentence.
+const BOTH_DETECTION_NOTES = `${DETECTION_NOTE}. ${CHECKER_NOTE[0].toUpperCase()}${CHECKER_NOTE.slice(1)}`;
+const plural = (n, one, many) => `${n} ${n === 1 ? one : many}`;
+const detectedTotal = (c) => DETECTION_KINDS.reduce((s, k) => s + c[k], 0);
+// "1 Nuclei detection template", "3 GitHub checker repositories": each detection kind present.
+const detectionParts = (c) => DETECTION_KINDS.filter((k) => c[k] > 0).map((k) => plural(c[k], ...DETECTION_NOUN[k]));
+// What the detection kinds present are: the template's note, the checker's, or both in sequence.
+const detectionNote = (c) => c.nuclei_template > 0 && c.github_checker > 0 ? BOTH_DETECTION_NOTES : c.github_checker > 0 ? CHECKER_NOTE : DETECTION_NOTE;
+// #3267: a kind on neither list. The note names it only when it reads as a kind (a lower-case
+// identifier, as every exploits.Kind* value is), so the note never carries other text the API sent.
+const UNCLASSIFIED_NOUN = ["reference of a kind this server does not classify", "references of a kind this server does not classify"];
+const KIND_TOKEN = /^[a-z][a-z0-9_]{0,63}$/;
+const unknownKindsOf = (kinds) => [...new Set(kinds.filter((k) => k !== undefined && KIND_TOKEN.test(k) && !isExploitCodeKind(k) && !isDetectionKind(k)))].sort();
+const unclassifiedNote = (kinds) => kinds.length === 0
+    ? "a reference of no kind this server classifies is counted as neither exploit code nor a detection check"
+    : kinds.length === 1
+        ? `the kind ${kinds[0]} is one this server does not classify: it is counted as neither exploit code nor a detection check, and a newer release of this server may classify it`
+        : `the kinds ${listed(kinds)} are ones this server does not classify: they are counted as neither exploit code nor a detection check, and a newer release of this server may classify them`;
+const capitalized = (s) => `${s[0].toUpperCase()}${s.slice(1)}`;
+// The listed rows by class.
+function countsIn(rows) {
+    const kinds = rows.map((r) => strAt(r, "kind"));
+    const detections = Object.fromEntries(DETECTION_KINDS.map((k) => [k, kinds.filter((x) => x === k).length]));
+    const code = kinds.filter(isExploitCodeKind).length;
+    return { code, detections, unclassified: rows.length - code - detectedTotal(detections), unknownKinds: unknownKindsOf(kinds) };
+}
+// Every reference on record by class: exploits_by_kind's counts where the answer carries the map,
+// the listed rows' where they are all of them, undefined otherwise. With the map, what its
+// exploit-code and detection kinds do not account for of exploits_total is unclassified.
+function kindCounts(d, rows, total) {
+    const byKind = field(d, "exploits_by_kind");
+    if (byKind !== null && typeof byKind === "object" && !Array.isArray(byKind)) {
+        const at = (k) => numAt(d, "exploits_by_kind", k) ?? 0;
+        const detections = Object.fromEntries(DETECTION_KINDS.map((k) => [k, at(k)]));
+        const code = EXPLOIT_CODE_KINDS.reduce((s, k) => s + at(k), 0);
+        return {
+            code,
+            detections,
+            unclassified: Math.max(0, total - code - detectedTotal(detections)),
+            unknownKinds: unknownKindsOf(Object.keys(byKind).filter((k) => at(k) > 0)),
+        };
+    }
+    return rows.length === total ? countsIn(rows) : undefined;
+}
+// "1 public exploit reference, 1 Nuclei detection template and 1 reference of a kind this server
+// does not classify": each class present, exploit code first.
+const classParts = (c) => [
+    ...(c.code > 0 ? [plural(c.code, "public exploit reference", "public exploit references")] : []),
+    ...detectionParts(c.detections),
+    ...(c.unclassified > 0 ? [plural(c.unclassified, ...UNCLASSIFIED_NOUN)] : []),
+];
+// What the classes present beside exploit code are: the detection note(s), then the unclassified
+// kind's, each its own sentence.
+const classNotes = (c) => [...(detectedTotal(c.detections) > 0 ? [detectionNote(c.detections)] : []), ...(c.unclassified > 0 ? [unclassifiedNote(c.unknownKinds)] : [])]
+    .map((n, i) => (i === 0 ? n : capitalized(n)))
+    .join(". ");
 function exploitSentences(cve, d, rows) {
     const total = numAt(d, "exploits_total");
     const verified = numAt(d, "exploits_by_status", "verified");
@@ -191,7 +307,13 @@ function exploitSentences(cve, d, rows) {
                 `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}`];
+        const shown = countsIn(rows);
+        const what = shown.code === rows.length
+            ? `${plural(rows.length, "public exploit reference", "public exploit references")}`
+            : shown.code === 0 && shown.unclassified === 0
+                ? `${listed([...detectionParts(shown.detections), "nothing else"])} (${classNotes(shown)})`
+                : `${plural(rows.length, "reference", "references")}: ${listed(classParts(shown))} (${classNotes(shown)})`;
+        return [`exploits lists ${what} 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 [
@@ -200,7 +322,23 @@ function exploitSentences(cve, d, rows) {
     }
     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}`];
+    const counts = kindCounts(d, rows, total);
+    if (counts === undefined) {
+        return [
+            `EchelonGraph holds ${plural(total, "reference", "references")} for ${cve} (exploits_total)${v}; the answer carries no exploits_by_kind, so it does not say how many are exploit code and how many detection checks, Nuclei detection templates or GitHub checker repositories (${BOTH_DETECTION_NOTES}).${cut}`,
+        ];
+    }
+    const detected = detectedTotal(counts.detections);
+    if (detected === 0 && counts.unclassified === 0) {
+        return [`EchelonGraph holds ${plural(total, "public exploit reference", "public exploit references")} for ${cve} (exploits_total)${v}.${cut}`];
+    }
+    // Only detection checks: no exploit code, and no kind this server cannot vouch for.
+    if (counts.code === 0 && counts.unclassified === 0) {
+        return [
+            `EchelonGraph holds ${listed(detectionParts(counts.detections))} for ${cve} and nothing else in exploits (exploits_total ${total}): ${detectionNote(counts.detections)}. It holds no Metasploit module, Exploit-DB entry or proof of concept for ${cve}, which is not evidence that none exists.${cut}`,
+        ];
+    }
+    return [`EchelonGraph holds ${plural(total, "reference", "references")} for ${cve} (exploits_total)${v}: ${listed(classParts(counts))}; ${classNotes(counts)}.${cut}`];
 }
 function listSentence(name, rows) {
     const limit = API_ROW_LIMIT[name] ?? 0;
@@ -209,6 +347,15 @@ function listSentence(name, rows) {
     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}.`;
 }
+// #3285 (3.1.0's lane P): affected_packages lists a package once per stored ecosystem string, as
+// cve_remediation's fixed_branches does, so CVE-2025-48013 has two rows for
+// drupal/quick_node_block, under Packagist:https://packages.drupal.org/8 ([0, 2.0.1)) and Packagist
+// ([0, 2.0.0)), each of one range, and "no range of the row holds", read row by row, gave a
+// Packagist 1.0.0 the fix 2.0.0, which the Drupal row still holds affected. Rows the matcher reads
+// as one package (packageRecords.ts, core-backend registryRecordKey: Packagist or Maven, bare or
+// with a repository URL; a release suffix never) are now said of together, with the walk over all
+// their ranges, which gives 2.0.1, the matcher's fixed_in, and the sentence on rows of several
+// ranges names the others.
 // #2817: where fixed_version is not the whole answer. A row with more than one range in
 // fixed_branches has a fix per range; a row with fixed_branches null has only fixed_version on
 // record, and so does a row with fixed_branches [] and a fixed_version (no version range on
@@ -232,9 +379,12 @@ function branchSentences(rows) {
     const multi = [];
     const unknown = [];
     const noRange = [];
+    // #3285: rows the matcher reads as one package (packageRecords.ts) are said of together, below.
+    const { twice } = packagesListedTwice(rows);
+    const together = new Set(twice.flatMap((g) => g.rows));
     rows.forEach((r, i) => {
         const fb = field(r, "fixed_branches");
-        if (Array.isArray(fb) && fb.length > 1)
+        if (Array.isArray(fb) && fb.length > 1 && !together.has(i))
             multi.push(named(r, i));
         if (fb === null)
             unknown.push(named(r, i));
@@ -245,6 +395,11 @@ function branchSentences(rows) {
     if (multi.length) {
         out.push(`${multi.length} affected_packages row${multi.length === 1 ? " lists" : "s list"} more than one affected range in fixed_branches (${few(multi)}): there, fixed_version is one range's fix, and an installed version's fix is the first fixed above it that no range of the row holds: the fixed of the range that holds it, or, while another range still holds that version, that range's fixed (none where a range on the way has no fixed).`);
     }
+    if (twice.length) {
+        const rowsOf = twice.reduce((t, g) => t + g.rows.length, 0);
+        const pkgs = twice.map((g) => `${g.name} (${listed(g.ecosystems)})`);
+        out.push(`${rowsOf} affected_packages rows are ${twice.length} package${twice.length === 1 ? "" : "s"} (${few(pkgs)}): ${ONE_PACKAGE_RULE("Rows")}, so there an installed version's fix is the first fixed above it that no range of those rows holds: the fixed of the range that holds it, or, while another range of them still holds that version, that range's fixed (none where a range on the way has no fixed); each row's fixed_version is one range's fix.`);
+    }
     if (unknown.length) {
         out.push(`${unknown.length} affected_packages row${unknown.length === 1 ? " carries" : "s carry"} fixed_branches null (${few(unknown)}): ${unknown.length === 1 ? "its" : "their"} ranges are not on record, so fixed_version, one range's fix, is all the answer holds, and it need not be the fix for a given installed version.`);
     }

package/dist/tools/cve_remediation.js

@@ -40,6 +40,7 @@ import { ANNOTATIONS, CVE_ID, SHOWN_BASE, api, badInput, checked, crashed, envel
 import { answering, FULL_ARG, TEXT_BUDGET_DESCRIPTION } from "../textBudget.js";
 import { fixStatusSchema } from "../fixStatus.js";
 import { MATCH_HEADERS } from "./check_affected.js";
+import { ONE_PACKAGE_RULE, packagesListedTwice } from "./packageRecords.js";
 const TOOL = "cve_remediation";
 const SECTIONS = ["cisa", "fixed_branches", "vendor_remediations", "fix_references", "patches"];
 const KINDS = ["vendor_fix", "workaround", "mitigation", "no_fix_planned", "none_available", "other"];
@@ -124,6 +125,10 @@ function schemas() {
                 advisory_id: opt(z.string()),
                 source: opt(z.string()),
             }))),
+            fixed_branches_truncated: z
+                .object({ total: z.number().int(), returned: z.number().int() })
+                .optional()
+                .describe("Present only where the structured result's cut (DATA CUT) kept this package's first ranges, not all: total, its ranges in the answer; returned, the ones data keeps. The same call with full: true returns every range."),
         }))),
         vendor_remediations: opt(z.array(VendorAdvisory)),
         fix_references: opt(z.array(z.looseObject({ url: opt(z.string()), tags: opt(z.array(z.string())), source: opt(z.string()) }))),
@@ -148,24 +153,50 @@ function schemas() {
 }
 let built;
 const schemasOnce = () => (built ??= schemas());
-// The text cut: vendor texts go first, the kinds, states and URLs stay.
-const CUT = {
-    rows: "vendor_remediations",
-    levels: [
-        { keep: ["vendor", "vendor_advisory_id", "withdrawn", "remediation_state", "remediation_kinds", "items_total", ["items", ["kind", "source_category", "text", "url", "fixed_build"]]], clip: 400, cap: 16 },
-        { keep: ["vendor", "vendor_advisory_id", "remediation_state", "remediation_kinds", ["items", ["kind", "url"]]], clip: 2048, cap: 8 },
-    ],
-    whole: "get_vendor_advisory returns any one of these advisories by its vendor and vendor_advisory_id, whole in its structuredContent.data with full: true, with every remediation item it lists.",
-};
 // #3013: the structured result's cut. CVE-2021-44228's answer is 75,963 characters of structured
 // result, 61,248 of them its 20 vendor_remediations, whose items carry the vendor's text (about 550
 // characters an item, the payload) and its product_ids (about 550, the vendor's own identifiers).
 // Before any advisory leaves, every advisory's items are thinned: product_ids first, keeping each
 // text; then the texts, keeping each item's kind, source_category, url and fixed_build, so every
 // advisory stays named with its state, kinds and links (get_vendor_advisory returns one whole).
-// Only then do advisories leave from the end, then the patches, then any other list at the top of
-// data. fix_status and fixed_in (#2841) are not lists, and installed is an object, so none of them
-// is ever cut.
+// fix_status and fixed_in (#2841) are not lists, and installed is an object, so none of them is
+// ever cut.
+//
+// #3139: through 3.0.0 advisories then left from the end, before patches, and fixed_branches had no
+// step, so CVE-2023-44487 (KEV-listed) kept 2 of its 20 advisories at 29,704 characters while
+// fixed_branches (13,581 characters, 50 rows) and patches (7,471, 30) stayed whole, and the note
+// named no tool that lists the other 18 (measured on hosted 3.0.0, 2026-10-11; also CVE-2018-12126
+// 6/20, CVE-2019-11135 2/3, CVE-2018-3639 16/20). Now vendor_remediations is a keepAll step: every
+// advisory stays, thinned, while patches (each to its vendor, patch_url and published_at: the
+// erratum, which vendor_remediations names again for Red Hat) and then fixed_branches (each to its
+// package, range, fixed_version and its ranges' introduced, fixed and last_affected, what the
+// sbom_review prompt walks; the per-range source, advisory_id and dependents_count go) are thinned
+// and then lose rows from the end, and then any other list at the top of data (fix_references).
+// Only when all of that is cut and the result is still past the budget do advisories leave, from
+// the end; whenever one does, the note names vendor_advisories_for_cve, which lists every vendor
+// advisory naming the CVE, as where the rest are.
+// #3139's review: that order dropped 2 of CVE-2023-44487's 30 patches while its 50 fixed_branches
+// rows stayed whole (13,581 characters). Decided (2026-10-11): fixed_branches is thinned before any
+// patch row leaves. The order is now:
+//   1. vendor_remediations thinned, as above, every advisory kept (keepAll);
+//   2. fixed_branches thinned (each package to its ecosystem, package_name, version_range,
+//      fixed_version and its ranges' introduced, fixed and last_affected: each range's source and
+//      advisory_id go, and the package's dependents_count and source), then each package's ranges
+//      capped at one number, the most that fit (at least 1), a package with more carrying
+//      fixed_branches_truncated with its total and returned; every package kept (keepAll);
+//   3. patches thinned (vendor, patch_url and published_at), every patch kept (keepAll);
+//   4. any other list at the top of data (fix_references), cut from the end;
+//   5. then patch rows leave from the end, then fixed_branches rows, and only then advisories
+//      (textBudget.ts: the last keepAll step's entries leave first);
+//   6. the room left goes back to each package's ranges, in the order of fixed_branches (giveBack):
+//      step 2 caps them before the patches are cut, and a cap that held while every patch was
+//      whole would otherwise stay after the patches are thinned.
+// Round 2 replayed CVE-2023-44487 at 28 of 30 patches: fix_references (2,191 characters) were cut
+// after patch rows left, and the 30 thinned were about 240 characters past the budget beside them.
+// Round 3 (#3139's second review, 2026-10-11): patches is a keepAll step, so fix_references are cut
+// first and CVE-2023-44487 keeps all 20 advisories, all 50 fixed_branches and all 30 patches, each
+// thinned (test/cve_remediation.test.mjs); round 1 (patches cut before fixed_branches was thinned)
+// kept 11 patches without fix_references.
 //
 // #3013's review: the second level leaves every item's text out of data, and the text is the
 // vendor's step itself (a workaround's or mitigation's wording), which the triage_cve and
@@ -175,6 +206,22 @@ const CUT = {
 // with full: true returns this data whole; the prompts send the model there when it is cut.
 const ADVISORY_FIELDS = ["vendor", "vendor_display_name", "vendor_advisory_id", "vendor_published_at", "withdrawn", "remediation_state", "remediation_kinds", "items_total"];
 const ITEM_TEXT_ELSEWHERE = "No item in data keeps its text, the vendor's own wording of the step (a workaround or mitigation among them): get_vendor_advisory, given an advisory's vendor and its vendor_advisory_id as advisory_id, returns it among that advisory's remediations, whole in its structuredContent.data with full: true.";
+const FIXED_BRANCHES_THIN = ["ecosystem", "package_name", "version_range", "fixed_version", ["fixed_branches", ["introduced", "fixed", "last_affected"]]];
+// A package whose ranges a cut keeps the first `cap` of: fixed_branches_truncated with its total
+// and returned. The structured cut's step 2 marks them so, and (3.1.0's phase A review) the text's.
+const rangesTruncated = (row, cap) => {
+    const n = Array.isArray(row.fixed_branches) ? row.fixed_branches.length : 0;
+    return n > cap ? { fixed_branches_truncated: { total: n, returned: cap } } : {};
+};
+// 3.1.0's phase C review: the note's fix walk ("the first fixed above it that no range of its
+// package holds", branchSentence below), over a capped package's kept ranges alone, can name a
+// version a range left out still holds (test/cve_remediation.test.mjs: a package whose every fix
+// the next range holds walks to c.0.0 over its first c ranges, to N.0.0 over all N). Both notes say
+// so of a capped package, and where its fix is read: data with full: true (the text beside a cut
+// data, and data itself), or data as it is (the text beside a data the call asked whole).
+const CAPPED_FIX_DATA = "its fix, walked over its kept ranges alone, can be wrong (read that package's fix with full: true)";
+const cappedFixText = (full) => `A capped package's fix, walked over its kept ranges alone, can be wrong: read that package's fix ${full ? "with full: true" : "from structuredContent.data"}.`;
+const PATCHES_THIN = ["vendor", "patch_url", "published_at"];
 const CVE_REMEDIATION_DATA = {
     steps: [
         {
@@ -183,15 +230,96 @@ const CVE_REMEDIATION_DATA = {
                 [...ADVISORY_FIELDS, ["items", ["kind", "source_category", "source_subcategory", "text", "text_truncated", "text_chars", "url", "fixed_build", "product_count"]]],
                 [...ADVISORY_FIELDS, ["items", ["kind", "source_category", "url", "fixed_build"]]],
             ],
+            keepAll: true,
+        },
+        {
+            lists: ["fixed_branches"],
+            thin: [
+                FIXED_BRANCHES_THIN,
+                {
+                    keep: FIXED_BRANCHES_THIN,
+                    capped: "fixed_branches",
+                    least: 1,
+                    mark: rangesTruncated,
+                    said: (cap) => `each package's fixed_branches keeping at most its first ${cap} range${cap === 1 ? "" : "s"}, a package with more carrying fixed_branches_truncated with its total and returned, and ${CAPPED_FIX_DATA}`,
+                },
+            ],
+            keepAll: true,
+            giveBack: true,
         },
-        { lists: ["patches"] },
+        // #3139 round 3: every patch row stays, thinned (keepAll), while the step after it (any other
+        // list at the top of data: fix_references) is cut; patch rows leave only after that, and
+        // before any fixed_branches row or advisory (the last keepAll step's entries leave first).
+        { lists: ["patches"], thin: [PATCHES_THIN], keepAll: true },
     ],
-    // Said where the advisories kept are thinned to a level whose items keep no text.
-    page: (_t, _d, at) => {
+    // Said where the advisories kept are thinned to a level whose items keep no text, and (#3139)
+    // wherever an advisory is left out.
+    page: (t, _d, at) => {
         const items = at.keeps.vendor_remediations?.find((x) => typeof x !== "string" && x[0] === "items");
-        return items && !items[1].includes("text") ? ITEM_TEXT_ELSEWHERE : "";
+        const v = t.vendor_remediations;
+        return [items && !items[1].includes("text") ? ITEM_TEXT_ELSEWHERE : "", v && v.returned < v.total ? advisoriesElsewhere(v.total - v.returned, "data") : ""].filter(Boolean).join(" ");
     },
 };
+// #3139: where the advisories a cut leaves out are read. vendor_advisories_for_cve lists every one
+// naming the CVE, with its vendor and vendor_advisory_id (CVE-2023-44487's 20 at 15,505
+// characters on hosted 3.0.0), and get_vendor_advisory then returns any one whole. #3272: the
+// first text block's cut says it too, of the advisories it leaves out.
+const advisoriesElsewhere = (n, of) => `vendor_advisories_for_cve, given this CVE, lists every vendor advisory naming it, the ${n} left out of ${of} among them, each with its vendor and vendor_advisory_id.`;
+// The text cut: vendor texts go first, the kinds, states and URLs stay.
+// #3272: through 3.0.2 the first text block was still cut the 3.0.0 way, which #3139 fixed only in
+// structuredContent.data: CUT named no list beside the advisories, so once its leanest level did not
+// fit, advisories left the text from the end while fixed_branches, patches and fix_references stayed
+// whole beside them. On the recorded CVE-2023-44487 answer (test/fixtures/cve_remediation-
+// CVE-2023-44487.json) the text kept 19 of 20 advisories beside 50/50 fixed_branches and 30/30
+// patches, and the same answer with 1, 5, 10 and 16 more fixed_branches packages 18, 13, 8 and 2
+// (from 18 more, the text fell through to step 4's every-list cap and kept 20 again); the TEXT CUT
+// note named get_vendor_advisory, which needs the advisory's ID, and never vendor_advisories_for_cve.
+// Now the text follows the structured cut's order (beforeRows, textBudget.ts step 3): the advisories
+// are cut level by level with every list beside them whole; once the leanest level does not fit,
+// fixed_branches is cut to FIXED_BRANCHES_THIN's fields, then patches to PATCHES_THIN's, every row
+// kept; then fix_references, then patches, then fixed_branches lose rows from the end, each emptied
+// before the next loses any; only then do advisories leave, from the end, and the note names
+// vendor_advisories_for_cve as where the rest are. The recorded answer now keeps all 20 advisories
+// beside every fixed_branches row (thinned), patch and fix_reference.
+// 3.1.0's phase A review: the text kept every range of each fixed_branches row it kept, capping no
+// package's ranges as the structured cut's step 2 does, so a package too long to fit alone left the
+// text with every package after it, and the lists emptied before it stayed empty: CVE-2023-44487's
+// answer with one package of N ranges put first among 51 kept 11 of 20 references at 150 ranges, 51
+// packages, 14 patches and no reference at 200, 43 packages and no patch at 250, and, from 400
+// ranges, no package, patch or reference in 6,347 characters, where 3.0.2's every-list cap kept 32
+// packages, 30 patches and 20 references at every size. Now, once fixed_branches and patches are
+// thinned and the text still does not fit, each package's ranges are cut to its first c, the most
+// that fit with patches and references as they stand (at least 1), every package kept and marked
+// fixed_branches_truncated as data marks it; only if 1 does not fit do references, then patches,
+// then packages leave from the end, and the room they leave goes back to c. The note names the
+// packages so cut and says data holds every range.
+const CUT = {
+    rows: "vendor_remediations",
+    levels: [
+        { keep: ["vendor", "vendor_advisory_id", "withdrawn", "remediation_state", "remediation_kinds", "items_total", ["items", ["kind", "source_category", "text", "url", "fixed_build"]]], clip: 400, cap: 16 },
+        { keep: ["vendor", "vendor_advisory_id", "remediation_state", "remediation_kinds", ["items", ["kind", "url"]]], clip: 2048, cap: 8 },
+    ],
+    sides: [
+        {
+            list: "fixed_branches",
+            keep: FIXED_BRANCHES_THIN,
+            beforeRows: true,
+            capped: {
+                list: "fixed_branches",
+                least: 1,
+                mark: rangesTruncated,
+                name: (e) => `${strAt(e, "package_name") ?? "?"} (${strAt(e, "ecosystem") ?? "?"})`,
+                said: (cap, names, full) => `In it, each package's fixed_branches keeps at most its first ${cap} range${cap === 1 ? "" : "s"}: ${names.length <= 3 ? listed(names) : `${names.slice(0, 3).join(", ")} and ${names.length - 3} more`} ${names.length === 1 ? "has more, carrying" : "have more, each carrying"} fixed_branches_truncated with its total and returned, and structuredContent.data holds every range${full ? " with full: true" : ""}. ${cappedFixText(full)}`,
+            },
+        },
+        { list: "patches", keep: PATCHES_THIN, beforeRows: true },
+        { list: "fix_references", beforeRows: true },
+    ],
+    whole: "get_vendor_advisory returns any one of these advisories by its vendor and vendor_advisory_id, whole in its structuredContent.data with full: true, with every remediation item it lists.",
+    page: (inText, rows) => advisoriesElsewhere(rows - inText, "the first text block"),
+};
+// The text cut, for the tests that replay it (test/cve_remediation.test.mjs).
+export { CUT as CVE_REMEDIATION_TEXT_CUT };
 const listed = (xs) => (xs.length <= 1 ? (xs[0] ?? "") : `${xs.slice(0, -1).join(", ")} and ${xs.at(-1)}`);
 const arr = (v) => (Array.isArray(v) ? v : null);
 const strs = (v) => (Array.isArray(v) ? v.filter((x) => typeof x === "string") : null);
@@ -225,6 +353,21 @@ function vendorSentences(cve, rows) {
         out.push(`${few(states.withdrawn)} ${states.withdrawn.length === 1 ? "was" : "were"} withdrawn by ${states.withdrawn.length === 1 ? "its" : "their"} vendor: ${states.withdrawn.length === 1 ? "its" : "their"} remediation is not relayed.`);
     return out;
 }
+// #3285: the ecosystems whose ":" suffix is a repository, not a release (core-backend
+// cve/pkgecosystem.go baseTokenMatchableEcosystems): an entry of one package_name under
+// "Packagist:https://packages.drupal.org/8" and one under "Packagist" are one package to the
+// matcher (cve/pkgmatch_fixedin.go registryRecordKey), which walks their ranges together; a
+// release suffix (Debian:12, Alpine:v3.20) is never folded. CVE-2025-48013's fixed_branches lists
+// drupal/quick_node_block under both (fixed 2.0.1 and fixed 2.0.0, each from 0): read entry by
+// entry, the rule gave a Packagist 1.0.0 the fix 2.0.0, which the Drupal advisory still holds
+// affected; as one package it gives 2.0.1, the matcher's fixed_in. packageRecords.ts holds the
+// reading, which cve_intel's note states of affected_packages too.
+// The packages fixed_branches lists under more than one such ecosystem, each as its package_name
+// with the ecosystems it is listed under, and how many entries fold into another so.
+function onePackageListedTwice(rows) {
+    const { twice, folded } = packagesListedTwice(rows);
+    return { named: twice.map((g) => `${g.name} (${listed(g.ecosystems)})`), folded };
+}
 function branchSentence(rows) {
     if (rows.length === 0)
         return "fixed_branches is empty: no affected package range is on record, which is not a finding that no fix exists.";
@@ -237,7 +380,14 @@ function branchSentence(rows) {
                 fixed++;
         }
     }
-    return `fixed_branches lists ${rows.length} affected package${rows.length === 1 ? "" : "s"} with ${ranges} affected range${ranges === 1 ? "" : "s"}, ${fixed} with a fix on record; an installed version's fix is the first fixed above it that no range of its package holds (the fixed of the range that holds it, or, while another range still holds that version, that range's fixed), compared in the ecosystem's version order.`;
+    const twice = onePackageListedTwice(rows);
+    const packages = rows.length - twice.folded;
+    const listedAs = twice.folded === 0 ? `${rows.length} affected package${rows.length === 1 ? "" : "s"}` : `${rows.length} entries, ${packages} affected package${packages === 1 ? "" : "s"},`;
+    const rule = `fixed_branches lists ${listedAs} with ${ranges} affected range${ranges === 1 ? "" : "s"}, ${fixed} with a fix on record; an installed version's fix is the first fixed above it that no range of its package holds (the fixed of the range that holds it, or, while another range still holds that version, that range's fixed), compared in the ecosystem's version order.`;
+    if (twice.named.length === 0)
+        return rule;
+    const few = twice.named.length <= 3 ? listed(twice.named) : `${twice.named.slice(0, 3).join(", ")} and ${twice.named.length - 3} more`;
+    return `${rule} ${ONE_PACKAGE_RULE("Entries")}: here ${few}.`;
 }
 // fix_status's sentence: what the API's rule says, relayed. Nothing about the fix is inferred here.
 function fixStatusSentence(cve, fs) {
@@ -250,7 +400,13 @@ function fixStatusSentence(cve, fs) {
     const unread = Array.isArray(field(fs, "unread_inputs")) ? field(fs, "unread_inputs").filter((x) => typeof x === "string") : [];
     const why = state === "none_confirmed" ? ", which is not a finding that no fix exists" : "";
     const notRead = unread.length ? `; it rests without ${listed(unread)}, which the API could not read (unread_inputs)` : "";
-    return `fix_status for ${cve} is ${state}${basis ? ` (basis ${basis})` : ""}, the API's fix-status rule${why}${notRead}.`;
+    // #3076, third pass: what vendor_fix_released evidence is, so "available" is not read as more
+    // than it says. Relayed from the field the API set, nothing inferred.
+    const released = field(fs, "vendor_released");
+    const qualifier = released !== null && released !== undefined && typeof released === "object"
+        ? `; the vendor states a fix is released, but the CVE record names no fixed version (vendor_released), so the fixed release is the vendor advisory's to name`
+        : "";
+    return `fix_status for ${cve} is ${state}${basis ? ` (basis ${basis})` : ""}, the API's fix-status rule${why}${qualifier}${notRead}.`;
 }
 // The sentence on the installed version asked: what the API answered for it, relayed.
 function installedSentence(asked, d) {