echelongraph-mcp 2.3.4 → 2.5.0

package/dist/tools/epss_history.js

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

package/dist/tools/get_cwe.js

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

package/dist/tools/kev_recent.js

@@ -0,0 +1,190 @@
+import * as z from "zod";
+const TOOL = "kev_recent";
+const PATH = "/api/v1/public/kev/recent";
+export const KEV_RECENT_MAX_LIMIT = 200;
+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), 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 opt = (t) => t.nullable().optional();
+const KEVRow = z.looseObject({
+    cve_id: opt(z.string()),
+    kev_added_date: opt(z.string()),
+    kev_due_date: opt(z.string()),
+    kev_vendor: opt(z.string()),
+    kev_product: opt(z.string()),
+    kev_vuln_name: opt(z.string()),
+    kev_ransomware: opt(z.boolean()),
+    severity: opt(z.string()),
+    cvss_v3_score: opt(z.number()),
+    epss_score: opt(z.number()),
+    epss_percentile: opt(z.number()),
+    eg_kev_tier: opt(z.number()),
+    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(),
+    count: opt(z.number()),
+    total: opt(z.number()),
+    kev_listed_total: opt(z.number()),
+    limit: opt(z.number()),
+    next_cursor: opt(z.string()),
+    order: opt(z.string()),
+    filters: opt(z.looseObject({})),
+    catalog: opt(z.looseObject({
+        source: opt(z.string()),
+        feed_url: opt(z.string()),
+        last_successful_fetch_at: opt(z.string()),
+        catalog_version: opt(z.string()),
+        date_released: opt(z.string()),
+        catalog_count: opt(z.number()),
+    })),
+    method: opt(z.string()),
+    notes: opt(z.array(z.string())),
+    generated_at: opt(z.string()),
+});
+const Coverage = z.strictObject({
+    catalog: z.literal(KEV_RECENT_COVERAGE),
+    total: z.number().nullable().describe("CVEs matching the filters."),
+    returned: z.number().nullable().describe("Rows in this page."),
+    kev_listed_total: z.number().nullable().describe("Every CVE EchelonGraph holds as KEV-listed."),
+    catalog_count: z.number().nullable().describe("CISA's own count, in the catalog last fetched."),
+    limit: z.number().nullable(),
+    has_more: z.boolean().nullable().describe("Whether next_cursor names a further page."),
+});
+const Freshness = z.strictObject({
+    last_successful_fetch_at: z.string().nullable().describe("When CISA last answered our poll of its feed: a 200 we applied, or a 304 Not Modified."),
+    catalog_version: z.string().nullable(),
+    date_released: z.string().nullable(),
+});
+// Inputs this side refuses before any request, with the reason.
+const DATE = /^\d{4}-\d{2}-\d{2}$/;
+const isDate = (s) => DATE.test(s) && new Date(`${s}T00:00:00Z`).toISOString().slice(0, 10) === s;
+// A header value must be visible ASCII: fetch refuses others, and that refusal would read as an outage.
+const PRINTABLE = /^[\x20-\x7e]+$/;
+function headersFor(a) {
+    const h = {};
+    const since = a.since?.trim();
+    const until = a.until?.trim();
+    if (since) {
+        if (!isDate(since))
+            return { why: "since must be a date, YYYY-MM-DD" };
+        h["X-EG-Since"] = since;
+    }
+    if (until) {
+        if (!isDate(until))
+            return { why: "until must be a date, YYYY-MM-DD" };
+        h["X-EG-Until"] = until;
+    }
+    if (since && until && since > until)
+        return { why: "since must not be after until" };
+    if (a.ransomware !== undefined)
+        h["X-EG-Ransomware"] = String(a.ransomware);
+    const vendor = a.vendor?.trim();
+    if (vendor) {
+        if (vendor.length > MAX_VENDOR || !PRINTABLE.test(vendor))
+            return { why: `vendor must be at most ${MAX_VENDOR} printable ASCII characters` };
+        h["X-EG-Vendor"] = vendor;
+    }
+    if (a.limit !== undefined)
+        h["X-EG-Limit"] = String(a.limit);
+    const cursor = a.cursor?.trim();
+    if (cursor) {
+        if (cursor.length > MAX_CURSOR || !/^[A-Za-z0-9_-]+$/.test(cursor))
+            return { why: "cursor must be a next_cursor this tool returned" };
+        h["X-EG-Cursor"] = cursor;
+    }
+    return { headers: h };
+}
+const at = (o, ...keys) => keys.reduce((v, k) => (v !== null && typeof v === "object" ? v[k] : undefined), o);
+const num = (o, ...k) => {
+    const v = at(o, ...k);
+    return typeof v === "number" && Number.isFinite(v) ? v : null;
+};
+const str = (o, ...k) => {
+    const v = at(o, ...k);
+    return typeof v === "string" && v ? v : null;
+};
+const realInstant = (s) => s !== null && Date.parse(s) > 0;
+async function kevRecent(d, a) {
+    try {
+        const h = headersFor(a);
+        if ("why" in h)
+            return d.badInput(TOOL, h.why);
+        const r = await d.api(PATH, { headers: h.headers });
+        if (!r.ok)
+            return d.failed(TOOL, r);
+        const rowsV = at(r.data, "kev");
+        const rows = Array.isArray(rowsV) ? rowsV : null;
+        const total = num(r.data, "total");
+        const listed = num(r.data, "kev_listed_total");
+        const catCount = num(r.data, "catalog", "catalog_count");
+        const fetchedRaw = str(r.data, "catalog", "last_successful_fetch_at");
+        const fetched = realInstant(fetchedRaw) ? fetchedRaw : null;
+        const version = str(r.data, "catalog", "catalog_version");
+        const released = str(r.data, "catalog", "date_released");
+        const next = str(r.data, "next_cursor");
+        const said = [d.okHead(TOOL, r.status)];
+        if (total === 0) {
+            said.push("No CVE in EchelonGraph's copy of the CISA KEV catalog matched these filters: a measured empty result, not a lookup failure.");
+        }
+        else if (rows && rows.length === 0) {
+            said.push(`This page is empty: the cursor is past the last of the ${total ?? "matching"} rows.`);
+        }
+        else if (rows) {
+            const first = rows[0];
+            const newest = typeof first?.cve_id === "string" && typeof first?.kev_added_date === "string" ? ` The first is ${first.cve_id}, added by CISA on ${first.kev_added_date}.` : "";
+            said.push(`${total === null ? "The API did not say how many CVEs match" : `${total} CVEs in EchelonGraph's copy of the CISA KEV catalog match`}; ${rows.length} are in this page, newest kev_added_date first.${newest}`);
+        }
+        if (rows && rows.length > 0)
+            said.push(next ? "More rows follow: call again with cursor set to next_cursor and the same filters." : "This is the last page.");
+        said.push(fetched
+            ? `EchelonGraph last fetched CISA's feed successfully at ${fetched}${version ? `, catalog version ${version}` : ""}.`
+            : "The API gave no time for EchelonGraph's last successful fetch of CISA's feed, so how fresh this list is is unknown, not stale.");
+        if (catCount !== null && listed !== null && catCount > listed) {
+            said.push(`CISA's catalog as last fetched counts ${catCount} entries and EchelonGraph holds ${listed} CVEs as KEV-listed, so ${catCount - listed} are not in its CVE table yet and no page returns them.`);
+        }
+        return d.succeeded(r.data, said.join(" "), {
+            state: "measured",
+            measured_at: fetched,
+            method: KEV_RECENT_METHOD,
+            coverage: {
+                catalog: KEV_RECENT_COVERAGE,
+                total,
+                returned: rows ? rows.length : null,
+                kev_listed_total: listed,
+                catalog_count: catCount,
+                limit: num(r.data, "limit"),
+                has_more: rows ? next !== null : null,
+            },
+            freshness: { last_successful_fetch_at: fetched, catalog_version: version, date_released: released },
+            notes: [
+                fetched
+                    ? "measured_at is EchelonGraph's last successful fetch of CISA's feed, the time this copy of the catalog was last confirmed."
+                    : "measured_at is null: the answer does not give EchelonGraph's last successful fetch of CISA's feed.",
+            ],
+        });
+    }
+    catch (e) {
+        return d.crashed(TOOL, e);
+    }
+}
+// Registers the tool on a server built by index.ts's createServer.
+export function registerKevRecent(server, d) {
+    const output = d.envelopeSchema({ data: Data, coverage: Coverage, freshness: Freshness });
+    server.registerTool("kev_recent", {
+        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"),
+            until: z.string().optional().describe("latest kev_added_date to include, YYYY-MM-DD"),
+            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)"),
+            cursor: z.string().optional().describe("next_cursor from the previous page"),
+        }),
+        outputSchema: output,
+        annotations: d.annotations,
+    }, async (a) => d.checked(TOOL, output, await kevRecent(d, a)));
+}