echelongraph-mcp 2.3.3 → 2.4.0

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

package/dist/tools/vendor_advisories.js

@@ -0,0 +1,316 @@
+// The vendor-advisory tools (#2719): vendor_advisories_for_cve, get_vendor_advisory and
+// search_vendor_advisories, over core-backend's /api/v1/public/vendor-advisories routes
+// (internal/cve/vendoradv/handler.go: ByCVE, Detail, List).
+//
+// What these answers are. EchelonGraph polls vendors' own advisory feeds on a schedule and
+// stores each advisory as the vendor published it (vendor_advisories, migration 063). A row
+// carries two dates that mean different things, and every tool relays both:
+// vendor_published_at is the date the vendor gives, our_first_seen_at is when EchelonGraph
+// first recorded the advisory. withdrawn is the vendor rescinding its own advisory; the list
+// and the search leave such advisories out, the per-CVE lookup and the detail keep them, and
+// the note names each one. Advisories of a vendor feed EchelonGraph has disabled are left out
+// of all three. None of the answers carries a time at which the pollers last completed a poll,
+// so freshness is null.
+//
+// The search term never travels in a URL (#1983). search_vendor_advisories sends it in the
+// X-EG-Advisory-Search header, percent-encoded, which the API reads first (handler.go
+// listSearch); the URL carries only the filters. An API that does not read that header answers
+// the UNSEARCHED list, so the tool requires the answer's search_applied to be true whenever it
+// sent a term, and fails otherwise rather than relay the whole list as the search's matches.
+// The term is never written into a note, an error or a log either.
+//
+// The other two put a CVE ID, a vendor slug and a vendor advisory ID in the path: identifiers
+// the routes are keyed on, refused locally unless they have an identifier's shape, so no free
+// text reaches a URL through them.
+//
+// Logic only: the envelope, the failure contract and the API call are index.ts's, handed in as
+// a VendorAdvisoryKit so this file cannot drift from them.
+import * as z from "zod";
+// core-backend vendoradv.SearchHeader.
+export const VENDOR_ADVISORY_SEARCH_HEADER = "X-EG-Advisory-Search";
+// handler.go List caps the search at 100 bytes; a longer term would be cut, possibly inside a
+// character, so it is refused here instead.
+const SEARCH_MAX_BYTES = 100;
+// store.go ListAdvisoriesByCVE: LIMIT 20, newest first.
+const BY_CVE_CAP = 20;
+const CVE_ID = /^CVE-\d{4}-\d{4,}$/i;
+// vendors.slug's CHECK constraint (migration 063).
+const VENDOR_SLUG = /^[a-z0-9](?:[a-z0-9-]*[a-z0-9])?$/;
+// No control characters (a header or log line could carry them), at most 200 characters.
+const ADVISORY_ID = /^[^\x00-\x1f\x7f]{1,200}$/;
+const METHOD = "EchelonGraph's vendor-advisory feed: advisories as each vendor published them in its own feed (for example Microsoft MSRC, Red Hat, Cisco, Palo Alto Networks and GitHub GHSA), each feed polled on a schedule; advisories of a feed EchelonGraph has disabled are left out.";
+const NO_FRESHNESS = "freshness is null: these answers carry no time at which the vendor-advisory pollers last completed a poll.";
+const DATES = "vendor_published_at is the date the vendor gives for the advisory; our_first_seen_at is when EchelonGraph first recorded it, which is not the vendor's date.";
+const LIST_MEASURED_AT = "measured_at is null: a list of advisories has no single observation time; each row carries vendor_published_at and our_first_seen_at.";
+const ONLY_POLLED = "Only the vendor feeds EchelonGraph polls are covered, so an advisory a vendor published elsewhere is not in this answer.";
+const realInstant = (s) => typeof s === "string" && Date.parse(s) > 0;
+const field = (o, k) => (o !== null && typeof o === "object" ? o[k] : undefined);
+const num = (o, k) => {
+    const v = field(o, k);
+    return typeof v === "number" && Number.isFinite(v) ? v : undefined;
+};
+const str = (o, k) => {
+    const v = field(o, k);
+    return typeof v === "string" && v ? v : undefined;
+};
+const rowsOf = (o) => {
+    const v = field(o, "advisories");
+    return Array.isArray(v) ? v : undefined;
+};
+const plural = (n, one, many) => (n === 1 ? one : many);
+// Each withdrawn row named by vendor and id: report it as withdrawn, never as a current advisory.
+function withdrawnNote(rows) {
+    const w = rows.flatMap((r, i) => (field(r, "withdrawn") === true ? [`${str(r, "vendor") ?? "?"}/${str(r, "vendor_advisory_id") ?? `advisories[${i}]`}`] : []));
+    if (!w.length)
+        return "";
+    return ` WITHDRAWN: ${w.length} of these ${rows.length} ${plural(rows.length, "advisory", "advisories")} ${plural(w.length, "was", "were")} withdrawn (rescinded) by ${plural(w.length, "its", "their")} vendor (withdrawn true): ${w.join(", ")}. Report ${plural(w.length, "it", "them")} as withdrawn, not as a current advisory.`;
+}
+// ── Output schemas ──
+const opt = (t) => t.nullable().optional();
+const DATE_FIELDS = {
+    vendor_published_at: opt(z.string()).describe("The date the vendor gives for the advisory."),
+    our_first_seen_at: opt(z.string()).describe("When EchelonGraph first recorded the advisory; not the vendor's date."),
+    withdrawn: opt(z.boolean()).describe("true: the vendor withdrew (rescinded) this advisory; report it as withdrawn."),
+};
+const AdvisoryRow = z.looseObject({
+    advisory_id: opt(z.string()),
+    vendor: opt(z.string()),
+    vendor_display_name: opt(z.string()),
+    vendor_advisory_id: opt(z.string()),
+    cve_ids: opt(z.array(z.string())),
+    title: opt(z.string()),
+    severity: opt(z.string()),
+    cvss_v3_score: opt(z.number()),
+    summary: opt(z.string()),
+    affected_products: opt(z.array(z.string())),
+    ...DATE_FIELDS,
+});
+// Shared by the three descriptions. Top-level consts, so the site's tool-claims check
+// (marketing-site/lib/mcpToolClaims.test.ts) can fold the descriptions to their text.
+const DATES_DESCRIPTION = "Each advisory carries vendor_published_at (the vendor's date), our_first_seen_at (when EchelonGraph first recorded it) and withdrawn (true: the vendor rescinded it; the note names each such advisory).";
+const ENVELOPE_DESCRIPTION = "Its structured result carries state (measured), measured_at, method, coverage, freshness (null: the answer carries no poll-completion time) 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.";
+export function registerVendorAdvisoryTools(server, kit) {
+    const FOR_CVE_OUTPUT = kit.envelopeSchema({
+        data: z.looseObject({ cve_id: opt(z.string()), advisories: opt(z.array(AdvisoryRow)), total: opt(z.number()) }),
+        coverage: z.strictObject({
+            returned: z.number().nullable().describe("The advisories in this answer."),
+            cap: z.number().describe("The most the API returns for one CVE, newest first."),
+            at_cap: z.boolean().nullable().describe("true: the answer is full, so the vendor feeds may hold more advisories for this CVE than it lists."),
+        }),
+        freshness: null,
+    });
+    const DETAIL_OUTPUT = kit.envelopeSchema({
+        data: AdvisoryRow.extend({
+            description: opt(z.string()),
+            known_cve_ids: opt(z.array(z.string())).describe("The CVE IDs of cve_ids that have a record in EchelonGraph's CVE feed."),
+            remediation: opt(z.string()),
+            references: z.unknown().optional(),
+            vendor_modified_at: opt(z.string()),
+            withdrawn_at: opt(z.string()),
+            withdrawn_reason: opt(z.string()),
+        }),
+        coverage: null,
+        freshness: null,
+    });
+    const SEARCH_OUTPUT = kit.envelopeSchema({
+        data: z.looseObject({
+            advisories: opt(z.array(AdvisoryRow)),
+            total: opt(z.number()),
+            limit: opt(z.number()),
+            offset: opt(z.number()),
+            search_applied: opt(z.boolean()).describe("Whether a free-text search filtered this answer."),
+        }),
+        coverage: z.strictObject({
+            total: z.number().nullable(),
+            returned: z.number().nullable(),
+            limit: z.number().nullable(),
+            offset: z.number().nullable(),
+            search_applied: z.boolean().nullable(),
+        }),
+        freshness: null,
+    });
+    // ── vendor_advisories_for_cve ──
+    async function forCVE(cveArg) {
+        const tool = "vendor_advisories_for_cve";
+        const raw = cveArg.trim();
+        if (!raw)
+            return kit.badInput(tool, "cve_id is required");
+        if (!CVE_ID.test(raw))
+            return kit.badInput(tool, "cve_id must be a CVE ID such as CVE-2024-21412");
+        const cve = raw.toUpperCase();
+        try {
+            const r = await kit.api(`/api/v1/public/vendor-advisories/by-cve/${encodeURIComponent(cve)}`);
+            if (!r.ok)
+                return kit.failed(tool, r);
+            const rows = rowsOf(r.data);
+            const returned = rows?.length ?? null;
+            const atCap = returned === null ? null : returned >= BY_CVE_CAP;
+            const env = {
+                state: "measured",
+                measured_at: null,
+                method: METHOD,
+                coverage: { returned, cap: BY_CVE_CAP, at_cap: atCap },
+                freshness: null,
+                notes: [LIST_MEASURED_AT, NO_FRESHNESS, DATES],
+            };
+            const head = kit.okHead(tool, r.status);
+            if (returned === 0) {
+                return kit.succeeded(r.data, `${head} No vendor advisory on record names ${cve}: a measured empty result, EchelonGraph was queried successfully and found nothing (we looked and found nothing). This is not a lookup failure. ${ONLY_POLLED}`, env);
+            }
+            if (rows === undefined)
+                return kit.succeeded(r.data, head, env);
+            const cap = atCap ? ` The API returns at most ${BY_CVE_CAP} advisories for one CVE, newest first, and this answer is full (at_cap true), so there may be more.` : "";
+            return kit.succeeded(r.data, `${head} ${rows.length} vendor ${plural(rows.length, "advisory names", "advisories name")} ${cve}.${cap}${withdrawnNote(rows)} ${ONLY_POLLED}`, env);
+        }
+        catch (e) {
+            return kit.crashed(tool, e);
+        }
+    }
+    // ── get_vendor_advisory ──
+    async function detail(vendorArg, idArg) {
+        const tool = "get_vendor_advisory";
+        const vendor = vendorArg.trim();
+        const id = idArg.trim();
+        if (!vendor)
+            return kit.badInput(tool, "vendor is required");
+        if (!VENDOR_SLUG.test(vendor) || vendor.length > 64)
+            return kit.badInput(tool, "vendor must be a vendor slug such as microsoft, redhat or github, as the advisory's vendor field gives it");
+        if (!id)
+            return kit.badInput(tool, "advisory_id is required");
+        if (!ADVISORY_ID.test(id))
+            return kit.badInput(tool, "advisory_id must be the vendor's advisory ID (vendor_advisory_id), at most 200 characters, with no control characters");
+        try {
+            const r = await kit.api(`/api/v1/public/vendor-advisories/${encodeURIComponent(vendor)}/${encodeURIComponent(id)}`);
+            if (!r.ok)
+                return kit.failed(tool, r);
+            const firstSeen = field(r.data, "our_first_seen_at");
+            const cveIDs = field(r.data, "cve_ids");
+            const known = field(r.data, "known_cve_ids");
+            const env = {
+                state: "measured",
+                measured_at: realInstant(firstSeen) ? firstSeen : null,
+                method: METHOD,
+                coverage: null,
+                freshness: null,
+                notes: [
+                    realInstant(firstSeen)
+                        ? "measured_at is our_first_seen_at: when EchelonGraph first recorded this advisory."
+                        : "measured_at is null: the answer carries no real our_first_seen_at.",
+                    NO_FRESHNESS,
+                    DATES,
+                ],
+            };
+            const shown = `${str(r.data, "vendor") ?? vendor}/${str(r.data, "vendor_advisory_id") ?? id}`;
+            const withdrawn = field(r.data, "withdrawn") === true
+                ? ` WITHDRAWN: the vendor withdrew (rescinded) ${shown} (withdrawn true${realInstant(field(r.data, "withdrawn_at")) ? `, withdrawn_at ${field(r.data, "withdrawn_at")}` : ""}). Report it as withdrawn, not as a current advisory.`
+                : "";
+            const cves = Array.isArray(cveIDs) && Array.isArray(known) && cveIDs.length > known.length
+                ? ` Of the ${cveIDs.length} CVE IDs it lists (cve_ids), ${known.length} ${plural(known.length, "has", "have")} a record in EchelonGraph's CVE feed (known_cve_ids); the others have no record there yet, which does not mean they are not CVEs.`
+                : "";
+            return kit.succeeded(r.data, `${kit.okHead(tool, r.status)} Returned the advisory ${shown}.${withdrawn}${cves}`, env);
+        }
+        catch (e) {
+            return kit.crashed(tool, e);
+        }
+    }
+    async function search(a) {
+        const tool = "search_vendor_advisories";
+        const query = (a.query ?? "").trim();
+        if (Buffer.byteLength(query, "utf8") > SEARCH_MAX_BYTES)
+            return kit.badInput(tool, `query is longer than the API's ${SEARCH_MAX_BYTES}-byte search limit`);
+        const vendor = (a.vendor ?? "").trim();
+        if (vendor && (!VENDOR_SLUG.test(vendor) || vendor.length > 64))
+            return kit.badInput(tool, "vendor must be a vendor slug such as microsoft, redhat or github");
+        try {
+            const q = new URLSearchParams();
+            if (vendor)
+                q.set("vendor", vendor);
+            if (a.severity)
+                q.set("severity", a.severity);
+            if (a.has_cve !== undefined)
+                q.set("has_cve", String(a.has_cve));
+            q.set("limit", String(a.limit ?? 20));
+            q.set("offset", String(a.offset ?? 0));
+            // The term in the header only, never the URL (#1983).
+            const headers = query ? { [VENDOR_ADVISORY_SEARCH_HEADER]: encodeURIComponent(query) } : {};
+            const path = `/api/v1/public/vendor-advisories?${q.toString()}`;
+            const r = await kit.api(path, { headers });
+            if (!r.ok)
+                return kit.failed(tool, r);
+            const applied = field(r.data, "search_applied");
+            if (query && applied !== true) {
+                return kit.failed(tool, {
+                    ok: false,
+                    kind: "unexpected_shape",
+                    path,
+                    status: r.status,
+                    detail: `the answer does not say the search was applied (search_applied is ${applied === undefined ? "absent" : JSON.stringify(applied)}: an API that does not read the ${VENDOR_ADVISORY_SEARCH_HEADER} header answers the unsearched list), so it is not relayed as the search's matches`,
+                });
+            }
+            const rows = rowsOf(r.data);
+            const total = num(r.data, "total");
+            const env = {
+                state: "measured",
+                measured_at: null,
+                method: METHOD,
+                coverage: {
+                    total: total ?? null,
+                    returned: rows?.length ?? null,
+                    limit: num(r.data, "limit") ?? null,
+                    offset: num(r.data, "offset") ?? null,
+                    search_applied: typeof applied === "boolean" ? applied : null,
+                },
+                freshness: null,
+                notes: [
+                    LIST_MEASURED_AT,
+                    NO_FRESHNESS,
+                    DATES,
+                    "Advisories their vendor withdrew are left out of this list (withdrawn advisories stay reachable through get_vendor_advisory and vendor_advisories_for_cve).",
+                ],
+            };
+            const head = kit.okHead(tool, r.status);
+            const what = query ? "The search matched" : "The list holds";
+            if (total === 0) {
+                return kit.succeeded(r.data, `${head} ${what} 0 vendor advisories: a measured empty result, EchelonGraph was queried successfully and nothing matched these filters (we looked and found nothing). This is not a lookup failure. ${ONLY_POLLED}`, env);
+            }
+            if (total === undefined)
+                return kit.succeeded(r.data, head, env);
+            const page = rows === undefined ? "" : `; ${rows.length} returned in this page (offset ${num(r.data, "offset") ?? a.offset ?? 0})`;
+            return kit.succeeded(r.data, `${head} ${what} ${total} vendor ${plural(total, "advisory", "advisories")}${page}.`, env);
+        }
+        catch (e) {
+            return kit.crashed(tool, e);
+        }
+    }
+    server.registerTool("vendor_advisories_for_cve", {
+        title: "Vendor advisories for one CVE",
+        description: `The vendor-published advisories that name one CVE, newest first, at most 20: for each, vendor, vendor_display_name, vendor_advisory_id, title, severity and cvss_v3_score where the vendor gives them. Covers the vendor feeds EchelonGraph polls, for example Microsoft MSRC, Red Hat, Cisco, Palo Alto Networks and GitHub GHSA; an empty answer means none of those names the CVE. ${DATES_DESCRIPTION} Pass a CVE ID like CVE-2024-21412. coverage gives returned, cap and at_cap (true: the answer is full, so there may be more). measured_at is null. ${ENVELOPE_DESCRIPTION}`,
+        inputSchema: z.object({ cve_id: z.string().describe("a CVE ID, e.g. CVE-2024-21412") }),
+        outputSchema: FOR_CVE_OUTPUT,
+        annotations: kit.annotations,
+    }, async ({ cve_id }) => kit.checked("vendor_advisories_for_cve", FOR_CVE_OUTPUT, await forCVE(cve_id)));
+    server.registerTool("get_vendor_advisory", {
+        title: "Vendor advisory detail",
+        description: `One vendor advisory in full, by vendor and the vendor's advisory ID (the vendor and vendor_advisory_id fields of a row from search_vendor_advisories or vendor_advisories_for_cve): title, description, severity, cvss_v3_score, cve_ids and known_cve_ids (those with a record in EchelonGraph's CVE feed), affected_products, remediation, references, vendor_modified_at, and withdrawn_at and withdrawn_reason when the vendor withdrew it. ${DATES_DESCRIPTION} measured_at is our_first_seen_at. ${ENVELOPE_DESCRIPTION}`,
+        inputSchema: z.object({
+            vendor: z.string().describe("the vendor slug, e.g. microsoft, redhat, github"),
+            advisory_id: z.string().describe("the vendor's advisory ID, e.g. RHSA-2024:1234 or GHSA-xxxx-xxxx-xxxx"),
+        }),
+        outputSchema: DETAIL_OUTPUT,
+        annotations: kit.annotations,
+    }, async ({ vendor, advisory_id }) => kit.checked("get_vendor_advisory", DETAIL_OUTPUT, await detail(vendor, advisory_id)));
+    server.registerTool("search_vendor_advisories", {
+        title: "Search vendor advisories",
+        description: `Search or list vendor-published advisories, newest first. query is matched case-insensitively as a substring of each advisory's title, description, vendor name, vendor_advisory_id, affected_products and cve_ids; filter by vendor (slug), by severity band, and by whether the advisory names any CVE ID. Advisories their vendor withdrew are left out. Returns advisories, each with vendor, vendor_advisory_id, title, severity, cvss_v3_score, cve_ids, summary and affected_products where present, and the answer's total, limit, offset and search_applied. ${DATES_DESCRIPTION} The query is sent in a request header, never in the URL. coverage repeats total, limit, offset and search_applied, and gives returned, the rows in this page. measured_at is null. ${ENVELOPE_DESCRIPTION}`,
+        inputSchema: z.object({
+            query: z.string().optional().describe("free text, at most 100 bytes: a product, an advisory ID, a CVE ID or a keyword, e.g. 'exchange server'"),
+            vendor: z.string().optional().describe("a vendor slug, e.g. microsoft, redhat, github"),
+            severity: z.enum(["Critical", "High", "Medium", "Low"]).optional().describe("one severity band"),
+            has_cve: z.boolean().optional().describe("true: only advisories naming a CVE; false: only those naming none"),
+            limit: z.number().int().min(1).max(50).optional().describe("page size (default 20, max 50)"),
+            offset: z.number().int().min(0).max(10000).optional().describe("rows to skip (default 0)"),
+        }),
+        outputSchema: SEARCH_OUTPUT,
+        annotations: kit.annotations,
+    }, async (a) => kit.checked("search_vendor_advisories", SEARCH_OUTPUT, await search(a)));
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "echelongraph-mcp",
-  "version": "2.3.3",
+  "version": "2.4.0",
   "mcpName": "io.echelongraph/echelongraph-mcp",
   "description": "EchelonGraph CVE and internet-exposure data as an MCP server: CVEs with EchelonGraph multi-source scores, CISA-KEV and EPSS, plus a per-CVE internet-exposure footprint derived from Shodan data. Shodan data is owned by Shodan, which holds its copyright (© Shodan). Free and keyless, for Claude, Cursor and any MCP client.",
   "type": "module",
@@ -15,8 +15,10 @@
   "scripts": {
     "build": "tsc",
     "start": "node dist/index.js",
+    "start:http": "node dist/http.js",
     "smoke": "node test/smoke.mjs",
-    "test": "npm run build && node --test test/*.test.mjs"
+    "test": "npm run build && node --test test/*.test.mjs synthetic/*.test.mjs",
+    "synthetic": "node synthetic/run.mjs"
   },
   "keywords": [
     "mcp",

package/server.json

@@ -8,12 +8,18 @@
     "url": "https://github.com/echelongraph/echelongraph-mcp",
     "source": "github"
   },
-  "version": "2.3.3",
+  "version": "2.4.0",
+  "remotes": [
+    {
+      "type": "streamable-http",
+      "url": "https://mcp.echelongraph.io/mcp"
+    }
+  ],
   "packages": [
     {
       "registryType": "npm",
       "identifier": "echelongraph-mcp",
-      "version": "2.3.3",
+      "version": "2.4.0",
       "transport": {
         "type": "stdio"
       },