echelongraph-mcp 2.6.8 → 2.7.0

package/dist/tools/cve_remediation.js

@@ -0,0 +1,257 @@
+// cve_remediation (#2841): how one CVE is fixed, as its sources state it, from GET
+// /api/v1/public/cves/:id/remediation (core-backend cve/remediation.go). Nothing here is
+// generated: every text and URL is relayed as the API sends it, and the API's own texts are its
+// sources' (CISA's KEV catalog, the OSV ranges #2817 loads, the vendors' advisories #2840 parses,
+// the CVE record's references as NVD tagged them).
+//
+// What the answer holds:
+//   cisa                 CISA KEV's required_action, due_date, short_description and notes_urls
+//                        for a KEV-listed CVE. CISA directs the action at US federal civilian
+//                        agencies (BOD 22-01); it is not EchelonGraph's advice.
+//   fixed_branches       each affected package with every affected range and its fix.
+//   vendor_remediations  each vendor advisory naming the CVE (at most 20, newest first), with its
+//                        remediation_state and the items it lists for the CVE, each with the
+//                        vendor's own category (kind): vendor_fix, workaround, mitigation,
+//                        no_fix_planned, none_available or other.
+//   fix_references       the record's references tagged Patch or Mitigation.
+//   patches              cve_patches rows.
+//   coverage             parsed_vendors, vendors_not_parsed and the caps.
+//   failed_sections      the sections the API could not read.
+//
+// The rules the note keeps: not_parsed is not "no remediation"; none_in_source is what the
+// advisory lists, not a finding that no fix exists; an empty section is "none on record", never
+// "no fix"; a failed section is named, never relayed as empty. A REJECTED CVE is not_assessed.
+import * as z from "zod";
+import { ANNOTATIONS, CVE_ID, SHOWN_BASE, api, badInput, checked, crashed, envelopeSchema, failed, failure, field, NOT_A_FINDING, okHead, opt, strAt, succeeded } from "../index.js";
+import { TEXT_BUDGET_DESCRIPTION } from "../textBudget.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"];
+const STATES = ["parsed", "none_in_source", "not_parsed", "withdrawn"];
+// Required in the description's head (src/requiredText.ts REQUIRED_IN_HEAD.cve_remediation).
+export const REMEDIATION_UNTESTED = "Every text is relayed as stated by its source; EchelonGraph has not tested it.";
+export const REMEDIATION_NOT_A_ZERO = "An empty list or a remediation_state of none_in_source or not_parsed is not a finding that no fix exists.";
+export const REMEDIATION_CISA = "CISA's required_action is directed at US federal civilian agencies (BOD 22-01) and is not EchelonGraph's advice.";
+const METHOD = "EchelonGraph's stored sources for one CVE (GET /api/v1/public/cves/:id/remediation): CISA's Known Exploited Vulnerabilities catalog text; the affected ranges and fixes of OSV advisories; the remediation each vendor advisory lists, categorised by the vendor's own category (Red Hat CSAF remediations, MSRC CVRF Workaround, Mitigation and Vendor Fix rows, Palo Alto's solution and work_around sections); the CVE record's references NVD tagged Patch or Mitigation; and cve_patches. Nothing is generated or tested.";
+export const CVE_REMEDIATION_DESCRIPTION = `How one CVE is fixed, as its sources state it, in one answer. ${REMEDIATION_UNTESTED} ${REMEDIATION_NOT_A_ZERO} Returns cisa (kev_listed, and for a KEV-listed CVE CISA's required_action, due_date, short_description and notes_urls, verbatim; ${REMEDIATION_CISA}), fixed_branches (each affected package with fixed_branches: every affected range, introduced and fixed or last_affected, and fixed_version, one range's fix), vendor_remediations (each vendor advisory naming the CVE, newest first, at most 20: vendor, vendor_advisory_id, remediation_state, remediation_kinds and items, each item with kind, source_category, text, url, fixed_build, product_ids and product_count), fix_references (the record's references NVD tagged Patch or Mitigation), patches, coverage (parsed_vendors, vendors_not_parsed and the caps) and failed_sections. kind is the vendor's own category, never read from the text: vendor_fix, workaround, mitigation, no_fix_planned, none_available, or other with the vendor's name for it in source_category. remediation_state is parsed, none_in_source (parsed; the advisory lists none for this CVE), not_parsed (EchelonGraph does not read that vendor's remediation) or withdrawn. A section the API could not read is named in failed_sections and coverage.sections_failed, never relayed as empty. A REJECTED CVE answers not_assessed. Pass a CVE ID like CVE-2021-44228. ${TEXT_BUDGET_DESCRIPTION} Cut, vendor texts are shortened first; kinds, states and URLs are kept.`;
+// ── outputSchema ──
+// Built on first use: index.ts imports this file, so its exports are not initialised while this
+// module's top level runs.
+function schemas() {
+    const Kind = z.union([z.enum(KINDS), z.string()]);
+    const State = z.union([z.enum(STATES), z.string()]);
+    const Item = z.looseObject({
+        kind: opt(Kind).describe("The vendor's own category: vendor_fix, workaround, mitigation, no_fix_planned, none_available or other."),
+        source_category: opt(z.string()).describe("The vendor's own name for the category (CSAF vendor_fix, MSRC Vendor Fix, Palo Alto work_around)."),
+        source_subcategory: opt(z.string()).describe("MSRC's SubType, e.g. Security Update; null elsewhere."),
+        text: opt(z.string()).describe("The vendor's text, verbatim but for HTML markup removed, cut at coverage.item_text_cap characters (text_truncated)."),
+        text_truncated: opt(z.boolean()),
+        text_chars: opt(z.number()).describe("The length of the vendor's text in characters."),
+        url: opt(z.string()),
+        fixed_build: opt(z.string()).describe("MSRC's FixedBuild; null elsewhere."),
+        product_ids: opt(z.array(z.string())).describe("The vendor's own product identifiers the item applies to, the first 16."),
+        product_count: opt(z.number()),
+    });
+    const VendorAdvisory = z.looseObject({
+        vendor: opt(z.string()),
+        vendor_display_name: opt(z.string()),
+        vendor_advisory_id: opt(z.string()),
+        vendor_published_at: opt(z.string()),
+        withdrawn: opt(z.boolean()),
+        remediation_state: opt(State).describe("parsed; none_in_source (parsed, and the advisory lists no remediation for this CVE, which is not a finding that no fix exists); not_parsed (EchelonGraph does not read this vendor's remediation, or has not yet read this advisory); withdrawn (the vendor rescinded it)."),
+        remediation_kinds: opt(z.array(Kind)),
+        items: opt(z.array(Item)),
+        items_total: opt(z.number()),
+    });
+    const data = z.looseObject({
+        cve_id: opt(z.string()),
+        state: opt(z.string()).describe("assessed, or not_assessed for a CVE record rejected by its numbering authority."),
+        not_assessed_reason: opt(z.string()),
+        cisa: z
+            .looseObject({
+            kev_listed: opt(z.boolean()),
+            required_action: opt(z.string()).describe(`CISA's requiredAction, verbatim. ${REMEDIATION_CISA}`),
+            due_date: opt(z.string()),
+            short_description: opt(z.string()),
+            notes_urls: opt(z.array(z.string())),
+        })
+            .nullable()
+            .optional(),
+        fixed_branches: opt(z.array(z.looseObject({
+            ecosystem: opt(z.string()),
+            package_name: opt(z.string()),
+            fixed_version: opt(z.string()).describe("One range's fix, kept for compatibility; not the fix for every affected range."),
+            fixed_branches: opt(z.array(z.looseObject({
+                introduced: opt(z.string()),
+                fixed: opt(z.string()),
+                last_affected: opt(z.string()).describe("The range's last affected version, where no fix is on record; never a fix."),
+                advisory_id: opt(z.string()),
+                source: opt(z.string()),
+            }))),
+        }))),
+        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()) }))),
+        patches: opt(z.array(z.unknown())),
+        coverage: z.unknown().optional(),
+        failed_sections: opt(z.array(z.string())),
+    });
+    const coverage = z.strictObject({
+        sections_relayed: z.array(z.string()),
+        sections_failed: z.array(z.string()).nullable().describe("The sections the API could not read (its failed_sections); null when the answer does not say."),
+        parsed_vendors: z.array(z.string()).nullable().describe("The vendors whose remediation EchelonGraph parses."),
+        vendors_not_parsed: z.array(z.string()).nullable().describe("The vendors in this answer whose remediation EchelonGraph does not parse."),
+        vendor_advisory_limit: z.number().nullable(),
+        item_text_cap: z.number().nullable(),
+        items_per_advisory_cap: z.number().nullable(),
+    });
+    return { output: envelopeSchema({ data, coverage, freshness: null }) };
+}
+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 every remediation item it lists.",
+};
+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);
+function vendorSentences(cve, rows) {
+    if (rows.length === 0) {
+        return [`No vendor advisory on record names ${cve}, which is not a finding that no vendor published a fix.`];
+    }
+    const out = [];
+    const byKind = new Map();
+    const states = {};
+    for (const r of rows) {
+        const who = `${strAt(r, "vendor") ?? "?"} ${strAt(r, "vendor_advisory_id") ?? "?"}`;
+        const st = strAt(r, "remediation_state") ?? "unknown";
+        (states[st] ??= []).push(who);
+        for (const k of strs(field(r, "remediation_kinds")) ?? []) {
+            if (!byKind.has(k))
+                byKind.set(k, []);
+            byKind.get(k).push(who);
+        }
+    }
+    const few = (xs) => (xs.length <= 4 ? listed(xs) : `${xs.slice(0, 4).join(", ")} and ${xs.length - 4} more`);
+    const kinds = [...KINDS.filter((k) => byKind.has(k)), ...[...byKind.keys()].filter((k) => !KINDS.includes(k))];
+    if (kinds.length) {
+        out.push(`Vendor remediation for ${cve}, by the vendor's own category: ${kinds.map((k) => `${k} from ${few(byKind.get(k))}`).join("; ")}. Each is the vendor's text as stated; EchelonGraph has not tested it.`);
+    }
+    if (states.none_in_source)
+        out.push(`${few(states.none_in_source)} ${states.none_in_source.length === 1 ? "lists" : "list"} no remediation for ${cve} (none_in_source), which is not a finding that no fix exists.`);
+    if (states.not_parsed)
+        out.push(`EchelonGraph does not read the remediation of ${few(states.not_parsed)} (not_parsed): read ${states.not_parsed.length === 1 ? "it" : "each"} with get_vendor_advisory; not_parsed is not "no remediation".`);
+    if (states.withdrawn)
+        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;
+}
+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.";
+    let ranges = 0;
+    let fixed = 0;
+    for (const r of rows) {
+        for (const b of arr(field(r, "fixed_branches")) ?? []) {
+            ranges++;
+            if (strAt(b, "fixed"))
+                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 fixed of the range that holds it, compared in the ecosystem's version order.`;
+}
+export async function cveRemediation(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();
+    const path = `/api/v1/public/cves/${encodeURIComponent(cve)}/remediation`;
+    try {
+        const r = await api(path);
+        if (!r.ok)
+            return failed(TOOL, r);
+        const d = r.data;
+        const state = strAt(d, "state");
+        if (state !== "assessed" && state !== "not_assessed") {
+            const why = "the answer carries no state (assessed or not_assessed)";
+            return failure("failed", `${TOOL} FAILED: EchelonGraph answered HTTP ${r.status} from ${SHOWN_BASE} for GET ${path}, but ${why}. ${NOT_A_FINDING}`, {
+                kind: "unexpected_shape",
+                path,
+                status: r.status,
+                message: why,
+            });
+        }
+        const reported = strs(field(d, "failed_sections"));
+        const cov = field(d, "coverage");
+        const coverage = {
+            sections_relayed: SECTIONS.filter((k) => field(d, k) !== undefined && !(reported ?? []).includes(k)),
+            sections_failed: reported,
+            parsed_vendors: strs(field(cov, "parsed_vendors")),
+            vendors_not_parsed: strs(field(cov, "vendors_not_parsed")),
+            vendor_advisory_limit: typeof field(cov, "vendor_advisory_limit") === "number" ? field(cov, "vendor_advisory_limit") : null,
+            item_text_cap: typeof field(cov, "item_text_cap") === "number" ? field(cov, "item_text_cap") : null,
+            items_per_advisory_cap: typeof field(cov, "items_per_advisory_cap") === "number" ? field(cov, "items_per_advisory_cap") : null,
+        };
+        const head = okHead(TOOL, r.status);
+        if (state === "not_assessed") {
+            const reason = strAt(d, "not_assessed_reason") ?? "the API gives no reason";
+            return succeeded(d, `${head} NOT ASSESSED: ${cve}'s remediation is not assessed (${reason}). A rejected CVE record is not an active vulnerability, so no fix is relayed for it.`, {
+                state: "not_assessed",
+                measured_at: null,
+                method: METHOD,
+                coverage,
+                freshness: null,
+                notes: ["measured_at is null: the answer dates no observation.", "freshness is null: the answer carries no poll-completion time."],
+            });
+        }
+        const said = [];
+        const cisa = field(d, "cisa");
+        const action = strAt(cisa, "required_action");
+        if (field(cisa, "kev_listed") === true) {
+            said.push(action
+                ? `${cve} is in CISA's KEV catalog; cisa.required_action is CISA's text, verbatim${strAt(cisa, "due_date") ? `, due ${strAt(cisa, "due_date")}` : ""}: ${REMEDIATION_CISA}`
+                : `${cve} is in CISA's KEV catalog, and no required_action is on record for it.`);
+        }
+        const pkgs = arr(field(d, "fixed_branches"));
+        if (pkgs && !(reported ?? []).includes("fixed_branches"))
+            said.push(branchSentence(pkgs));
+        const vendors = arr(field(d, "vendor_remediations"));
+        if (vendors && !(reported ?? []).includes("vendor_remediations"))
+            said.push(...vendorSentences(cve, vendors));
+        const refs = arr(field(d, "fix_references"));
+        if (refs)
+            said.push(refs.length ? `fix_references lists ${refs.length} reference${refs.length === 1 ? "" : "s"} the CVE record tags Patch or Mitigation.` : "No reference of the CVE record is tagged Patch or Mitigation.");
+        if (reported === null)
+            said.push("The answer carries no failed_sections, so an empty section may be one the API could not read, not a finding of none.");
+        else if (reported.length)
+            said.push(`The API could not read ${listed(reported)} (failed_sections): an empty value there is not a finding of none.`);
+        said.push(REMEDIATION_UNTESTED);
+        return succeeded(d, `${head} ${said.join(" ")}`, {
+            state: "measured",
+            measured_at: null,
+            method: METHOD,
+            coverage,
+            freshness: null,
+            notes: ["measured_at is null: the answer has no single observation time.", "freshness is null: the answer carries no poll-completion time."],
+        }, CUT);
+    }
+    catch (e) {
+        return crashed(TOOL, e);
+    }
+}
+export function registerCveRemediation(server) {
+    const { output } = schemasOnce();
+    server.registerTool(TOOL, {
+        title: "How one CVE is fixed",
+        description: CVE_REMEDIATION_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 cveRemediation(cve_id)));
+}

package/dist/tools/epss_history.js

@@ -6,7 +6,7 @@ export const EPSS_HISTORY_METHOD = "EchelonGraph's record of FIRST's EPSS scores
 const CHANGE_ONLY = "series_kind is change_only: each point is a change EchelonGraph recorded, at the time it recorded it, and a day with no point is not a recorded value, so the series must not be read or redrawn as a daily series; no point here is interpolated.";
 const BEFORE_FIRST = "The value in force before a CVE's first point is not in the series.";
 const NO_FRESHNESS = "freshness is null: the answer does not carry the time of the EPSS fetcher's last completed run.";
-export const EPSS_HISTORY_DESCRIPTION = `How one CVE's EPSS score (FIRST's exploit-prediction probability, 0 to 1, with its percentile) has changed, as EchelonGraph recorded it: points, oldest first, each with at, epss_score and epss_percentile; current, the record's value now (epss_score, epss_percentile, epss_updated_at); series_kind, always change_only; series_starts_at, when EchelonGraph began recording EPSS changes for any CVE; history_rows, points_truncated and latest_point_matches_current. Pass a CVE ID like CVE-2023-44487. The series is change-only: a point is a recorded change, and a day without a point is not a recorded value. A daily series interpolated from it holds values EchelonGraph never recorded, so the series is never a daily series. Before series_starts_at nothing was recorded, so a missing point there means not recorded, not unchanged, and the value in force before a CVE's first point is not in the series. latest_point_matches_current false means a change is missing from the series. Its structured result carries state (measured), measured_at (current.epss_updated_at: when EchelonGraph last wrote a changed value, not FIRST's score date), method, coverage (series_kind, series_starts_at, points, points_truncated), freshness (null) and notes, with data equal to the API's JSON; the result's last text block repeats it without data (the first text block) and without the note's sentences (the text block before it), with which notes ends. ${TEXT_BUDGET_DESCRIPTION}`;
+export const EPSS_HISTORY_DESCRIPTION = `How one CVE's EPSS score (FIRST's exploit-prediction probability, 0 to 1, with its percentile) has changed, as EchelonGraph recorded it: points, oldest first, each with at, epss_score, epss_percentile and score_date (FIRST's score date, null where the record does not hold it); current, the record's value now (epss_score, epss_percentile, epss_updated_at); series_kind, always change_only; series_starts_at, when EchelonGraph began recording EPSS changes for any CVE; complete_since, from when the record holds every change; coverage, which FIRST score dates the record holds; history_rows, points_truncated and latest_point_matches_current. Pass a CVE ID like CVE-2023-44487. The series is change-only: a point is a recorded change, and a day without a point is not a recorded value. A daily series interpolated from it holds values EchelonGraph never recorded, so the series is never a daily series. Before series_starts_at nothing was recorded, so a missing point there means not recorded, not unchanged, and the value in force before a CVE's first point is not in the series. Between series_starts_at and complete_since the record misses changes, so a missing point there does not mean unchanged either; only from complete_since on is every change a point. coverage.days_missing and coverage.days_partial name the FIRST score dates the record does not hold, or holds for some CVEs only. latest_point_matches_current false means a change is missing from the series. Its structured result's measured_at is current.epss_updated_at (when EchelonGraph last wrote a changed value, not FIRST's score date), its coverage says which part of the record is complete and which score dates it holds, and its freshness is null. ${TEXT_BUDGET_DESCRIPTION}`;
 // The API's JSON. points, series_kind and current are required: an answer without them is not
 // this series, and a series_kind other than change_only would make every note above wrong, so
 // either is a failure (checked), never relayed.
@@ -15,11 +15,29 @@ const Point = (instant) => z.looseObject({
     at: instant.describe("When EchelonGraph recorded this change."),
     epss_score: z.number().describe("The EPSS probability (0 to 1) from that change on."),
     epss_percentile: opt(z.number()).describe("Its percentile (0 to 1), null where the record held none."),
+    score_date: opt(z.string()).describe("FIRST's score date (YYYY-MM-DD) of the logged refresh that wrote this point; null where no logged refresh covers it."),
+});
+const Day = z.string().describe("A FIRST score date, YYYY-MM-DD.");
+const ApiCoverage = (instant) => z.looseObject({
+    recorded_from: opt(instant).describe("series_starts_at: when recording began."),
+    complete_since: opt(instant).describe("From here on every change a refresh applied is a point; before it changes are missing."),
+    series_complete: opt(z.boolean()).describe("True only when nothing in the record predates complete_since."),
+    points_before_complete_since: opt(z.number().int().min(0)).describe("This CVE's points in the part of the record that misses changes."),
+    run_log_since: opt(instant).describe("The first logged refresh: score dates before it are not listed, held or missing."),
+    first_day: opt(Day).describe("The earliest score date in the run log."),
+    last_day: opt(Day).describe("The latest score date in the run log."),
+    days_held: opt(z.number().int().min(0)).describe("Score dates from first_day to last_day that a refresh applied completely."),
+    days_partial: opt(z.array(Day)).describe("Score dates whose refreshes all failed part-way: some CVEs hold that day, some do not."),
+    days_missing: opt(z.array(Day)).describe("Score dates from first_day to last_day that no refresh applied."),
+    runs_undated: opt(z.number().int().min(0)),
+    refresh_runs_truncated: opt(z.boolean()),
 });
 const data = (instant) => z.looseObject({
     cve_id: z.string(),
     series_kind: z.enum(["change_only"]).describe("Always change_only: one point per recorded change, none for a day without one."),
     series_starts_at: instant.nullable().describe("The earliest EPSS change EchelonGraph recorded for any CVE: when recording began. Null when nothing has been recorded."),
+    complete_since: opt(instant).describe("From when the record holds every change a refresh applied. Between series_starts_at and complete_since changes are missing, so a missing point there does not mean unchanged. Absent from an API older than #2867."),
+    coverage: opt(ApiCoverage(instant)).describe("Which part of the record is complete and which FIRST score dates it holds."),
     current: z.looseObject({
         epss_score: opt(z.number()).describe("The record's EPSS probability now; null when it holds none."),
         epss_percentile: opt(z.number()),
@@ -36,8 +54,16 @@ export function epssHistoryOutput(kit) {
         coverage: z.strictObject({
             series_kind: z.enum(["change_only"]),
             series_starts_at: kit.instant.nullable(),
+            complete_since: kit.instant.nullable().describe("From when every change is a point; null when the API did not say, and then no part of the series is known complete."),
+            series_complete: z.boolean().describe("True only when the API says nothing in the record predates complete_since."),
             points: z.number().int().min(0).describe("How many points the series holds."),
+            points_before_complete_since: z.number().int().min(0).nullable().describe("How many of them fall where changes are missing; null when the API did not say."),
             points_truncated: z.boolean(),
+            first_day: z.string().nullable().describe("The earliest FIRST score date the run log lists; null when it lists none."),
+            last_day: z.string().nullable(),
+            days_held: z.number().int().min(0).nullable().describe("Score dates from first_day to last_day the record holds; null when none are listed."),
+            days_partial: z.array(z.string()).describe("Score dates held for some CVEs only."),
+            days_missing: z.array(z.string()).describe("Score dates from first_day to last_day the record does not hold."),
         }),
         freshness: null,
     });
@@ -45,8 +71,37 @@ export function epssHistoryOutput(kit) {
 const isNum = (v) => typeof v === "number" && Number.isFinite(v);
 const isObj = (v) => v !== null && typeof v === "object" && !Array.isArray(v);
 const realInstant = (v) => typeof v === "string" && Date.parse(v) > 0;
+const isDay = (v) => typeof v === "string" && /^\d{4}-\d{2}-\d{2}$/.test(v);
+const dayList = (v) => (Array.isArray(v) ? v.filter(isDay) : []);
+// A day list in the note: the first DAYS_IN_NOTE, then how many more coverage holds.
+const DAYS_IN_NOTE = 10;
+const sayDays = (days, field) => days.length <= DAYS_IN_NOTE ? days.join(", ") : `${days.slice(0, DAYS_IN_NOTE).join(", ")} and ${days.length - DAYS_IN_NOTE} more (coverage.${field})`;
+function completeness(d, points) {
+    const cov = isObj(d.coverage) ? d.coverage : {};
+    const completeSince = realInstant(d.complete_since) ? d.complete_since : realInstant(cov.complete_since) ? cov.complete_since : undefined;
+    let pointsBefore;
+    if (isNum(cov.points_before_complete_since))
+        pointsBefore = cov.points_before_complete_since;
+    else if (completeSince)
+        pointsBefore = points.filter((p) => realInstant(p.at) && Date.parse(p.at) < Date.parse(completeSince)).length;
+    const firstDay = isDay(cov.first_day) ? cov.first_day : undefined;
+    const lastDay = isDay(cov.last_day) ? cov.last_day : undefined;
+    return {
+        completeSince,
+        // Complete only on the API's word AND with a complete_since to be complete from.
+        seriesComplete: completeSince !== undefined && cov.series_complete === true,
+        pointsBefore,
+        firstDay,
+        lastDay,
+        daysHeld: firstDay && isNum(cov.days_held) ? cov.days_held : undefined,
+        daysPartial: dayList(cov.days_partial),
+        daysMissing: dayList(cov.days_missing),
+        runLogSince: realInstant(cov.run_log_since) ? cov.run_log_since : undefined,
+        hasCoverage: isObj(d.coverage),
+    };
+}
 // The note: what came back, in words, and what it does not say.
-function note(head, id, d) {
+function note(head, id, d, c) {
     const points = Array.isArray(d.points) ? d.points.filter(isObj) : [];
     const cur = isObj(d.current) ? d.current : {};
     const curScore = isNum(cur.epss_score) ? cur.epss_score : undefined;
@@ -56,9 +111,19 @@ function note(head, id, d) {
         ? `EchelonGraph's record holds no EPSS score for ${id} (current.epss_score is null).`
         : `${id}'s EPSS score in EchelonGraph's record is ${curScore}${isNum(cur.epss_percentile) ? ` (percentile ${cur.epss_percentile})` : ""}.`);
     if (points.length === 0) {
-        s.push(start
-            ? `No EPSS change is recorded for ${id} since recording began at ${start}: a measured empty series, not a lookup failure.`
-            : "No EPSS change has been recorded for any CVE yet (series_starts_at is null), so this empty series says nothing about how the score moved.");
+        if (!start) {
+            s.push("No EPSS change has been recorded for any CVE yet (series_starts_at is null), so this empty series says nothing about how the score moved.");
+        }
+        else if (c.seriesComplete) {
+            s.push(`No EPSS change is recorded for ${id} since recording began at ${start}: a measured empty series, not a lookup failure.`);
+        }
+        else if (c.completeSince) {
+            // "Measured" only for the complete part (#2867).
+            s.push(`No EPSS change is recorded for ${id} since recording began at ${start}. From complete_since (${c.completeSince}) that is measured: no refresh since then changed it. Before complete_since the record misses changes, so the empty series is not evidence that the score held still from ${start} to ${c.completeSince}.`);
+        }
+        else {
+            s.push(`No EPSS change is recorded for ${id} since recording began at ${start}. The answer does not say from when the record is complete, so the empty series is not evidence that the score held still.`);
+        }
     }
     else {
         const first = points[0];
@@ -67,6 +132,26 @@ function note(head, id, d) {
     }
     if (start)
         s.push(`Recording began at ${start} (series_starts_at): before it a missing point means not recorded, not unchanged.`);
+    if (c.seriesComplete) {
+        s.push(`The record is complete (complete_since ${c.completeSince}): every change a refresh applied since recording began is a point.`);
+    }
+    else if (c.completeSince) {
+        const where = c.pointsBefore ? ` ${c.pointsBefore} of this series' ${points.length} point${points.length === 1 ? "" : "s"} fall there.` : "";
+        s.push(`The record is complete only from ${c.completeSince} (complete_since): from then on every change a refresh applied is a point. Between ${start ?? "series_starts_at"} and complete_since EchelonGraph's earlier write path missed changes, so there a missing point does not mean unchanged, and this series is not complete.${where}`);
+    }
+    else if (start) {
+        s.push("The answer does not say from when the record is complete (complete_since is absent), so a missing point anywhere in this series may be a missed change, not an unchanged score.");
+    }
+    if (c.firstDay && c.lastDay) {
+        const held = c.daysHeld === undefined ? "" : `, ${c.daysHeld} held`;
+        const missing = c.daysMissing.length ? `; not held: ${sayDays(c.daysMissing, "days_missing")}` : "; none missing";
+        const partial = c.daysPartial.length ? `; held for some CVEs only (a refresh failed part-way): ${sayDays(c.daysPartial, "days_partial")}` : "";
+        const since = c.runLogSince ? ` (run log since ${c.runLogSince}; earlier dates are not listed)` : "";
+        s.push(`FIRST score dates in EchelonGraph's run log${since}: ${c.firstDay} to ${c.lastDay}${held}${missing}${partial}.`);
+    }
+    else if (c.hasCoverage) {
+        s.push("The run log lists no FIRST score date yet, so this answer does not say which days the record holds, and no point carries a score_date.");
+    }
     if (d.points_truncated === true)
         s.push("points_truncated is true: only the newest records were read, so the earliest changes are missing from this series.");
     if (d.latest_point_matches_current === false) {
@@ -87,7 +172,8 @@ export async function epssHistory(kit, cve_id) {
             return kit.failed(TOOL, r);
         const d = r.data;
         const name = typeof d.cve_id === "string" && d.cve_id ? d.cve_id : cve;
-        const { note: n, own } = note(kit.okHead(TOOL, r.status), name, d);
+        const c = completeness(d, Array.isArray(d.points) ? d.points.filter(isObj) : []);
+        const { note: n, own } = note(kit.okHead(TOOL, r.status), name, d, c);
         const cur = isObj(d.current) ? d.current : {};
         const written = realInstant(cur.epss_updated_at) ? cur.epss_updated_at : null;
         return kit.succeeded(r.data, n, {
@@ -97,8 +183,16 @@ export async function epssHistory(kit, cve_id) {
             coverage: {
                 series_kind: d.series_kind,
                 series_starts_at: d.series_starts_at ?? null,
+                complete_since: c.completeSince ?? null,
+                series_complete: c.seriesComplete,
                 points: Array.isArray(d.points) ? d.points.length : 0,
+                points_before_complete_since: c.pointsBefore ?? null,
                 points_truncated: d.points_truncated === true,
+                first_day: c.firstDay ?? null,
+                last_day: c.lastDay ?? null,
+                days_held: c.daysHeld ?? null,
+                days_partial: c.daysPartial,
+                days_missing: c.daysMissing,
             },
             freshness: null,
             notes: [

package/dist/tools/kev_recent.js

@@ -7,7 +7,7 @@ const MAX_VENDOR = 128;
 const MAX_CURSOR = 128;
 const KEV_RECENT_METHOD = "EchelonGraph's copy of the CISA KEV catalog: CISA's feed is polled every 5 minutes and each entry is written onto its CVE's record; rows are read from those records, newest kev_added_date first.";
 const KEV_RECENT_COVERAGE = "CISA KEV catalog";
-const KEV_RECENT_DESCRIPTION = "The CVEs CISA has added to its Known Exploited Vulnerabilities (KEV) catalog, newest first, from EchelonGraph's copy of that catalog, which polls CISA's feed every 5 minutes. Each row in kev gives cve_id, kev_added_date (CISA's dateAdded), kev_due_date, kev_vendor, kev_product, kev_vuln_name and kev_ransomware (known ransomware-campaign use), EchelonGraph's severity, cvss_v3_score, epss_score, epss_percentile and eg_kev_tier for the CVE, and our_first_seen_kev, when EchelonGraph's poller first recorded the CVE entering the catalog (null where no such record exists). Filter by since and until (YYYY-MM-DD, inclusive, on kev_added_date; an RFC 3339 timestamp, such as the kev_added_date 2024-04-12T00:00:00Z that CVE records carry, is read as the date written in it, with the time and offset dropped, and anything else is refused), ransomware, and vendor (an exact, case-insensitive match on kev_vendor); page with limit (1 to 200, default 50) and cursor, passing back the previous page's next_cursor with the same filters. Rows within one date are ordered by cve_id. total counts the CVEs matching the filters; kev_listed_total counts every CVE EchelonGraph holds as KEV-listed, and catalog.catalog_count is CISA's own count in the catalog last fetched, so a gap between the two is entries not yet in EchelonGraph's CVE table, which no page returns. CISA's requiredAction and shortDescription are not returned. Its structured result carries state (measured), measured_at (our last successful fetch of CISA's feed, null when the API does not give it), method, coverage (the CISA KEV catalog: total, returned, kev_listed_total, catalog_count, limit, has_more), freshness (last_successful_fetch_at, catalog_version, date_released) 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 KEV_RECENT_DESCRIPTION = "The CVEs CISA has added to its Known Exploited Vulnerabilities (KEV) catalog, newest first, from EchelonGraph's copy of that catalog, which polls CISA's feed every 5 minutes. Each row in kev gives cve_id, kev_added_date (CISA's dateAdded), kev_due_date, kev_vendor, kev_product, kev_vuln_name and kev_ransomware (known ransomware-campaign use), EchelonGraph's severity, cvss_v3_score, epss_score, epss_percentile and eg_kev_tier for the CVE, and our_first_seen_kev, when EchelonGraph's poller first recorded the CVE entering the catalog (null where no such record exists). Filter by since and until (YYYY-MM-DD, inclusive, on kev_added_date), ransomware, and vendor (an exact, case-insensitive match on kev_vendor); page with limit (1 to 200, default 50) and cursor, passing back the previous page's next_cursor with the same filters. total counts the CVEs matching the filters; kev_listed_total counts every CVE EchelonGraph holds as KEV-listed, and catalog.catalog_count is CISA's own count in the catalog last fetched, so a gap between the two is entries not yet in EchelonGraph's CVE table, which no page returns. CISA's requiredAction, shortDescription and notes are not in these rows: each CVE's own record carries them, verbatim and labelled as CISA's. Its structured result's measured_at is our last successful fetch of CISA's feed (null when the API does not give it), coverage counts the CISA KEV catalog (total, returned, kev_listed_total, catalog_count, limit, has_more) and freshness gives last_successful_fetch_at, catalog_version and date_released." +
     " " +
     TEXT_BUDGET_DESCRIPTION +
     " Cut, each row keeps fewer fields, cve_id, kev_added_date, kev_vendor and kev_ransomware at least, or rows are left out, and next_cursor still continues after the last row of the page, not of the text.";
@@ -28,7 +28,7 @@ const KEVRow = z.looseObject({
     our_first_seen_kev: opt(z.string()).describe("When EchelonGraph's poller first recorded the CVE entering the catalog; null where no such record exists."),
 });
 const Data = z.looseObject({
-    kev: z.array(KEVRow).optional(),
+    kev: z.array(KEVRow).optional().describe("Newest kev_added_date first; rows within one date are ordered by cve_id."),
     count: opt(z.number()),
     total: opt(z.number()),
     kev_listed_total: opt(z.number()),
@@ -215,8 +215,8 @@ export function registerKevRecent(server, d) {
         title: "Recent CISA KEV additions",
         description: KEV_RECENT_DESCRIPTION,
         inputSchema: z.object({
-            since: z.string().optional().describe("earliest kev_added_date to include, YYYY-MM-DD (an RFC 3339 timestamp is read as the date written in it)"),
-            until: z.string().optional().describe("latest kev_added_date to include, YYYY-MM-DD (an RFC 3339 timestamp is read as the date written in it)"),
+            since: z.string().optional().describe("earliest kev_added_date to include, YYYY-MM-DD (an RFC 3339 timestamp is read as the date written in it, with the time and offset dropped; anything else is refused)"),
+            until: z.string().optional().describe("latest kev_added_date to include, YYYY-MM-DD (an RFC 3339 timestamp is read as the date written in it, with the time and offset dropped; anything else is refused)"),
             ransomware: z.boolean().optional().describe("true: only CVEs with known ransomware-campaign use; false: only those without"),
             vendor: z.string().optional().describe("CISA vendorProject, an exact case-insensitive match, e.g. 'Microsoft'"),
             limit: z.number().int().min(1).max(KEV_RECENT_MAX_LIMIT).optional().describe("page size (default 50, max 200)"),

package/dist/tools/manifests/common.js

@@ -0,0 +1,48 @@
+// What every manifest reader (#2835) returns, and the purl builders they share.
+//
+// A reader turns one file's text into the purls it pins (one per dependency entry it can resolve
+// to a single registry version) and the entries it cannot check, each with a reason. Nothing is
+// guessed: a range is not narrowed to a version, a branch is not resolved to a tag, and an entry
+// that names a local path or a VCS checkout is not matched against registry advisories, whose
+// versions it need not share. Each such entry is listed, never dropped.
+//
+// purls follow the purl spec (github.com/package-url/purl-spec, PURL-TYPES.rst), and the shape
+// tier1-cloud-scanner/sca/scanner.go purlFor emits: the type, each name segment percent-encoded
+// (a scope's '@' as %40), '@', the version as the file states it (Go keeps its leading v). The
+// backend reads them with url.PathUnescape (core-backend internal/cve/matchbatch.go
+// purlNameVersion) and normalises names on lookup (pkgmatch.go), so the case a file uses is kept.
+// Why an entry was not sent to the API. Each is not clean: the entry was not checked at all.
+//   version_unpinned    the entry gives a range or a wildcard, not one version (django>=4, ==1.4.*);
+//   version_unresolved  the entry names no single registry version: none is given, a branch is
+//                       named (composer dev-main), or the version the build selects cannot be read
+//                       from this file (a go.mod require of an excluded version);
+//   local_path          the dependency is a directory, file or workspace member, not a registry
+//                       release (a go.mod replace to ./x, an npm link, a Cargo path crate);
+//   vcs_source          the dependency is a VCS checkout (git+, a GIT section), whose code need not
+//                       match the registry release of the same version;
+//   unsupported_line    a line or entry this reader does not take: another file it includes
+//                       (-r, -c), a direct URL, an option, a registry other than the ecosystem's
+//                       public one, or text it cannot read.
+export const NOT_CHECKED_REASONS = ["version_unpinned", "version_unresolved", "local_path", "vcs_source", "unsupported_line"];
+// A file the reader cannot read at all (not JSON, not TOML): the reason, said to the caller.
+export class Unreadable extends Error {
+}
+// The most characters of a line or value a not_checked entry repeats.
+const SPEC_MAX = 200;
+export const specOf = (s) => {
+    const t = s.trim();
+    return t.length > SPEC_MAX ? `${t.slice(0, SPEC_MAX - 1)}…` : t;
+};
+// One purl segment, percent-encoded as the purl spec asks; '+' is left as it is (Go's
+// +incompatible, a PyPI local version), which url.PathUnescape reads back unchanged.
+export const seg = (s) => encodeURIComponent(s).replace(/%2B/g, "+");
+// A hierarchical name (a Go module path, an npm @scope/name, a Packagist vendor/name): each
+// '/'-separated segment encoded, the separators kept.
+export const segPath = (s) => s.split("/").map(seg).join("/");
+export const purlOf = (type, name, version) => `pkg:${type}/${segPath(name)}@${seg(version)}`;
+// PEP 503: a PyPI name lowercased, each run of '-', '_' and '.' one '-' (the purl spec's pypi rule).
+export const pep503 = (name) => name.toLowerCase().replace(/[-_.]+/g, "-");
+// A version a purl can carry: non-empty, no whitespace.
+export const usableVersion = (v) => typeof v === "string" && v.trim() !== "" && !/\s/.test(v.trim());
+export const isObj = (v) => v !== null && typeof v === "object" && !Array.isArray(v);
+export const emptyParsed = () => ({ pinned: [], not_checked: [], skipped: 0, notes: [] });