echelongraph-mcp 2.6.5 → 2.6.7

package/CHANGELOG.md

@@ -6,6 +6,146 @@ with a provenance attestation by the release workflow of
 [github.com/echelongraph/echelongraph-mcp](https://github.com/echelongraph/echelongraph-mcp),
 from the commit tagged `v<version>`.
 
+## 2.6.7 — 2026-10-05
+
+- Tool descriptions now state facts only: no reporting instructions to the model and no references
+  to other tools, for the Anthropic MCP Directory policy ("Tool descriptions contain no
+  instructions about model behavior, other tools, or external instruction sources, and no hidden
+  or encoded text"). Tool behavior, results and their notes are unchanged. Reworded:
+  - get_cve, search_cves: "The note labels each such CVE NOT YET SCORED: report it that way, never
+    as a score of 0." now reads "The note labels each such CVE NOT YET SCORED, which is not a score
+    of 0."
+  - cve_summary: summary.rejected's "report them as withdrawn records, never as vulnerabilities"
+    now reads "they are withdrawn records, none of them a vulnerability"; summary.none's "report
+    those CVEs as not yet scored, not as CVEs rated None" now reads "and names those CVEs not yet
+    scored, not CVEs rated None".
+  - get_vendor_advisory: "(the vendor and vendor_advisory_id fields of a row from
+    search_vendor_advisories or vendor_advisories_for_cve)" now reads "(the vendor and
+    vendor_advisory_id of a vendor advisory row)".
+  - exposure_radar: "and cve_exposure says per CVE whether the radar tracks it" now reads "and this
+    answer does not say whether the radar tracks that CVE: tracking is answered per CVE".
+  - epss_history: "Never interpolate it into a daily series." now reads "A daily series
+    interpolated from it holds values EchelonGraph never recorded, so the series is never a daily
+    series."
+  - check_affected: "Read assessed before count: … a count of 0 there must never be reported as
+    not affected" now reads "count depends on assessed: … a count of 0 there is not a finding of
+    not affected"; the outputSchema description of assessed, "Read first.", now reads "count
+    depends on it.".
+  - vendor_advisories_for_cve, get_vendor_advisory, search_vendor_advisories: the outputSchema
+    description of withdrawn, "report it as withdrawn", now reads "so it is a withdrawn advisory,
+    not a current one".
+- test/description-policy.test.mjs lists the tools over stdio and fails if any title, description
+  or input/output schema description names another tool, matches a model-directed imperative
+  pattern, or carries zero-width, bidi or control characters or a base64-looking run.
+
+## 2.6.6 — 2026-10-05
+
+- Correction to 2.6.5 (#2775). Its entry says: "On the hosted endpoint it is the client going away
+  (its own timeout, a closed tab): every API call of that request is cancelled". That was not true
+  of the hosted endpoint. Cloud Run does not pass a client's disconnect on to a container it
+  speaks HTTP/1.1 to ("When you use HTTP/1.1 on Cloud Run, client disconnect events are not
+  propagated to the Cloud Run container",
+  <https://docs.cloud.google.com/run/docs/troubleshooting>). In production on 2026-10-05, four
+  `check_sbom` calls had their client abort after 0.4 s or 1.5 s. Each was logged `status` 200
+  with `client_closed` false and ran to its end, 2.0 to 5.3 s. Together they held both large-body
+  slots, so a large body sent 1 s later was answered 503. The same page says HTTP/2 does pass the
+  disconnect on. So `dist/http.js` now serves HTTP/2 cleartext (h2c) when `MCP_H2C=1`, and the
+  hosted deployment sets it together with Cloud Run's `--use-http2`. With that flag, Cloud Run
+  speaks only h2c to the container. The server acts on a reset stream the moment it arrives, with
+  any error code including `NO_ERROR`: the API calls are cancelled, `check_sbom` sends no further
+  batch and ends a `Retry-After` wait, the large-body slot is freed, and the `mcp_request` line
+  says `status` 499 with `client_closed` true. What Cloud Run forwards is only partly measured.
+  On test deployments with `--use-http2` on 2026-10-05, ordinary calls, sessions and `/health`
+  were all answered over h2c. A client that stopped reading a streamed answer had its stream reset
+  by Cloud Run 15 s in (`rst_code` 2), and that was logged 499. A client that aborts mid-call
+  before any answer was not observed, because every probe call was answered first, so whether
+  Cloud Run forwards that reset at once is not yet shown. Until it is, an abandoned call may still
+  run to its end, a `check_sbom` call for at most its 50-second budget, holding its slot. A new line, `mcp_client_gone`,
+  records when the server learned the client went: `after_ms` from the request's start, whether
+  the answer had started (`answer_started`), and an HTTP/2 stream's `rst_code`. It holds nothing
+  of the request. Run yourself, `dist/http.js` speaks HTTP/1.1 as before. With `MCP_H2C=1` it
+  speaks h2c with prior knowledge only, and an HTTP/1.1 request gets no answer.
+- README, "Privacy: what is sent where": the hosted endpoint's paragraph now also says what the API logs
+  of the calls it makes for you (#2797): each under your address, with its URL path (for a CVE, CWE or
+  advisory lookup, the ID), and not its query string, the header-carried terms or which purls. The
+  privacy policy's new Section 11, https://echelongraph.io/privacy#hosted-mcp-endpoint , says the same.
+- `exposure_radar` relays and labels `mcp_servers.withheld_opted_out` (#2822): how many hostnames
+  whose owner opted out of scanning the API left out of every other `mcp_servers` number. Such a
+  hostname is not checked again while the opt-out stands, so its last verdict cannot be re-checked;
+  the API now withholds it from the MCP-server counts as its unparameterised AI-exposure answer
+  already did. An answer without the field, from an API that predates it, counted those hostnames,
+  and the note says so instead of reading the absence as 0; a value that is not a whole number is
+  left out and named.
+- Claude Desktop in one click (#2815). From this release on, every GitHub release of
+  [github.com/echelongraph/echelongraph-mcp](https://github.com/echelongraph/echelongraph-mcp/releases)
+  carries `echelongraph-mcp.mcpb`, a Claude Desktop extension: open it and choose Install. It needs
+  no Node.js on your machine, since Claude Desktop runs it with the Node.js it ships, and no JSON to edit.
+  The README's Claude Desktop section links it as "Install in Claude Desktop", ahead of the custom
+  connector and the `npx` setup. The release workflow builds it from the release tag, the same tag
+  the npm package is published from: `listings/mcpb/build.sh` validates the manifest with the pinned
+  MCPB CLI and packs. Then, on a separate read-only runner that never ran the MCPB CLI,
+  `listings/mcpb/check-bundle.mjs` refuses a bundle that holds a top-level file `build.sh` does not
+  stage, a symlink, or a file where `build.sh` stages a directory; that lacks the icon or entry point
+  its manifest names, or `node_modules/`; whose `package.json`, `LICENSE`, `README.md` or `dist/` is not the tested npm
+  tarball's, byte for byte (a file changed, missing or added); whose `node_modules/` adds or changes
+  a file a production install from the lockfile does not have; that is at another version; or whose
+  own server, started with `PATH`, `HOME` and `ECHELONGRAPH_API_BASE` only (none of the caller's
+  `NODE_PATH`, `NODE_OPTIONS` or other variables), does not list the
+  manifest's 14 tools with their titles. npm publishes only after that check passes, so a manifest
+  or bundle defect stops the release before npm has the version. A separate job, which runs no
+  dependency code, signs the checked bundle with a SLSA build-provenance attestation (Sigstore,
+  keyless), attaches it and its Sigstore bundle to the release, each on its own, and checks the
+  file the release serves with `gh attestation verify`. To check a download yourself:
+  `gh attestation verify echelongraph-mcp.mcpb --repo echelongraph/echelongraph-mcp`.
+  Releases up to 2.6.5 carry no bundle.
+- Repository only, not in the package: `listings/mcpb/check-bundle.mjs` and
+  `test/mcpb-release.test.mjs`; `test/mcp-stdio-client.mjs` takes a `cwd`.
+- `sbom_review` reads the advisory interval in `check_sbom`'s `match_reason` by its closing
+  bracket, without the hedge of 2.6.5 and earlier. `[A, B)` is a fixed bound: B, the first version the advisory
+  records as not affected, is given as the fixed version (`[A, ∞)` names none). `[A, B] (B is the
+  last affected version, not a fix)` is an OSV `last_affected` bound: B is still affected and the
+  range records no fix, so neither B nor any version at or below it is given as a fixed version.
+  The bracket alone decides: a cut text clips `match_reason` to 200 characters, which can drop the
+  words after it for a long package name, and where it is clipped before the closing bracket
+  (`[A, B…`), no fixed version is taken from that `match_reason`.
+  Through 2.6.5 core-backend rendered both bounds as `[A, B)`, so the prompt gave B only as "the
+  end of that interval"; core-backend now renders a `last_affected` bound closed (#2830). This
+  wording assumes the API serves the new rendering: it is released after core-backend is deployed.
+- `cve_intel` relays `fixed_branches` on each `affected_packages` row: every affected range of the
+  package on record, each with `introduced` and `fixed` (the range's fix) or, where no fix is on
+  record, `last_affected` (never in a field named fixed), and with `advisory_id` (the OSV record that
+  published the range) and `source` (the loader's label for that record), from core-backend's
+  `/api/v1/public/cves/:id/enrichment` since #2817. Ranges that name their record are in the order
+  the record lists them; ranges loaded before the record was stored (both null) are oldest first.
+  `fixed_branches` is null where a package's ranges were never loaded, and `[]` where no version
+  range is on record (none in the advisory, only commit ranges, or more than are stored), which is
+  not a finding that no fix exists. `fixed_version` is one range's fix per package,
+  kept for compatibility: for CVE-2021-44228 production served log4j-core 2.12.2 alone (2026-10-04),
+  the fix for 2.4 to 2.12.1, older than an affected 2.14.1, while the advisory
+  (GHSA-jfh8-c2jp-5v3q) gives three ranges, fixed in 2.3.1, 2.12.2 and 2.15.0. The description says
+  how to pick the range for an installed version, and the note counts the rows with more than one
+  range, and those with no range on record (`fixed_branches` null, or `[]` beside a `fixed_version`),
+  where `fixed_version` is all the answer holds. An API older than #2817 is said to be one (#2817).
+- `triage_cve`'s patch line gives each affected range with its fix from `fixed_branches`, and
+  `fixed_version` only for a package without them; `sbom_review` gives a component the fix of the
+  `fixed_branches` range that holds its installed version (log4j-core 2.14.1: 2.15.0), after the
+  advisory interval in `check_sbom`'s `match_reason`, and `fixed_version` only for a package without
+  `fixed_branches` (#2817).
+- `vendor_advisories_for_cve`, `search_vendor_advisories` and `get_vendor_advisory` relay each
+  vendor's `held_since`, which the coverage API now serves: the start of the window EchelonGraph has
+  read the vendor's advisories from, before which an advisory may not be held.
+  `vendors_not_fully_held` reads it, not the earliest held advisory. For a vendor with no history read
+  the earliest held advisory is not where its window begins: Cisco's poller first read the advisories
+  Cisco had changed in the last 90 days, Red Hat's and GitHub's the last 7, so an older advisory the
+  vendor revised later is held while the ones published beside it are not. Cisco's earliest held
+  advisory is dated 2024-10-23 and Red Hat's 2009-02-04, so CVE-2025-20188 left out Cisco and
+  CVE-2014-0160 left out Red Hat, and their empty answers read as the vendor having published nothing;
+  both are listed now. GitHub is now listed too for any CVE ID year that begins before the start of
+  its first poll's 7-day window (`held_since`), not only for years up to that of its earliest held
+  advisory (2017). Against an API without `held_since`, a vendor is taken as held from its earliest
+  advisory only when its history read is complete, and otherwise listed, its window written "not known
+  to be without a gap" (#2803).
+
 ## 2.6.5 — 2026-10-05
 
 2.6.4 was tagged and never published: its Release run failed `test/http-memory.test.mjs` on Node 24,

package/README.md

@@ -34,21 +34,32 @@ API call a tool needs to answer.
 ## Quick start
 
 The local server runs through `npx` and needs Node.js 20 or later; nothing is installed
-globally. Add one of the blocks below to your client, restart it, then ask: *"Is
+globally. Claude Desktop's one-click extension, below, needs neither. Add one of the blocks below to your client, restart it, then ask: *"Is
 CVE-2023-44487 actively exploited, and how many exposed services does EchelonGraph's radar
 have on record for it?"*
 
 ### Claude Desktop
 
-Two ways in. The first needs nothing installed; the second runs the server on your machine.
+Three ways in. The first two need no Node.js: a one-click extension that runs the server on your
+machine, and a custom connector to the hosted endpoint. The third runs the server through `npx`.
 
-**1. Custom connector (no install).** Claude Desktop uses your claude.ai account's connectors:
+**1. [Install in Claude Desktop](https://github.com/echelongraph/echelongraph-mcp/releases/latest/download/echelongraph-mcp.mcpb)
+(one click, no Node.js).** The link downloads `echelongraph-mcp.mcpb`, a Claude Desktop extension.
+Open it, or in Claude Desktop choose Settings → Extensions → Advanced settings → Install Extension
+and pick it, then choose **Install**. Claude Desktop runs the server with the Node.js it ships and
+writes its own configuration: no PATH and no JSON to edit. To update, install the next release's
+bundle the same way. Every new release on GitHub carries the bundle (releases up to 2.6.5 do not),
+built from the release's tag by the workflow that publishes the npm package, and signed with a SLSA
+build-provenance attestation. To check a download:
+`gh attestation verify echelongraph-mcp.mcpb --repo echelongraph/echelongraph-mcp`.
+
+**2. Custom connector (no install).** Claude Desktop uses your claude.ai account's connectors:
 Customize → Connectors → **+ Add** → **Add custom connector**. Name it `EchelonGraph`, paste
 `https://mcp.echelongraph.io/mcp`, choose **No sign in**, and add it. No Node.js, no PATH and no
 JSON to edit. A connector added on claude.ai shows up in Claude Desktop too, and the plan rules
 are claude.ai's (see "Remote (no install)" below).
 
-**2. Local server through `npx`.**
+**3. Local server through `npx`.**
 
 1. **Check Node.js.** In Terminal (macOS) or PowerShell (Windows), run `node -v`. It must print
    `v20` or later. If it prints an older version or `command not found`, install the LTS release
@@ -228,7 +239,7 @@ The example questions are ones a client can answer with that tool alone.
 | `epss_history` | EPSS change history for one CVE | How one CVE's EPSS score has changed, as EchelonGraph recorded it: one point per recorded change (`series_kind` `change_only`), never a daily series, with the value now and `series_starts_at`, when recording began; before it a missing point means not recorded, not unchanged. | *How has CVE-2023-44487's EPSS score changed, as EchelonGraph recorded it?* |
 | `check_affected` | Am I affected? (product or package at a version) | Whether a product (its NVD CPE product token) or a registry package (`ecosystem` and `package`) at a given version is affected by known CVEs, from the matcher behind echelongraph.io/am-i-affected: `assessed` first (false: not evaluated, with `not_assessed_reason`, and a count of 0 then is not "not affected"), the matching CVEs with `kev_listed`, `ransomware`, `epss_score`, `effective_score` and `score_assessed`, and advisories it cannot decide counted as `undetermined_count`, never as safe. What you look up travels in request headers, never in the URL. | *Is openssl 3.0.0 affected by known CVEs? Is lodash 4.17.15 on npm?* |
 | `check_sbom` | Check an SBOM against the advisory corpus | A dependency list checked against EchelonGraph's advisory corpus (OSV.dev records), one verdict per component: `affected`, `not_affected`, `undetermined` or `not_assessed`, each with its `not_assessed_reason`. Pass up to 2,000 distinct purls, or a CycloneDX JSON or SPDX JSON document: the purls are read from it by the MCP server and only they are sent to the API, in POST bodies of at most 200 each, one after another; the document itself is not sent on. Run from npm, the server is on your machine; over the hosted endpoint (`mcp.echelongraph.io`) it is EchelonGraph's, and the document is the request body. When the API's per-component rate limit answers 429, the tool waits the `Retry-After` it names, within 50 seconds per call; past that it answers what it has, with the purls not sent counted in `coverage.not_sent`, the reason in `coverage.not_sent_reason`, and the list in `data.not_sent_purls`, never dropped silently. A deb, apk or rpm purl without a `distro` qualifier naming its release is not assessed (`distro_release_unknown`): EchelonGraph does not guess a release. Only `not_affected` is clean. No ranking, no score. | *Check this CycloneDX SBOM against the advisory corpus.* |
-| `cve_intel` | CVE weakness, exploits and packages | Weakness, public exploit code, affected packages and fixed versions for one CVE, from EchelonGraph's per-CVE enrichment: `cwes`, `exploits` (at most 10, verified first) with `exploits_total`, `exploits_capped`, `exploits_by_kind` and `exploits_by_status`, `affected_packages`, `fixed_versions` and `timeline`. `verified_status` is the label stored with each reference, not a guarantee that the exploit works. An empty `exploits` list is not evidence that no public exploit exists; a section the API could not read is named in `coverage.sections_failed`, never relayed as an empty list. | *Is there public exploit code for CVE-2021-44228, and which versions fix it?* |
+| `cve_intel` | CVE weakness, exploits and packages | Weakness, public exploit code, affected packages and fixed versions for one CVE, from EchelonGraph's per-CVE enrichment: `cwes`, `exploits` (at most 10, verified first) with `exploits_total`, `exploits_capped`, `exploits_by_kind` and `exploits_by_status`, `affected_packages`, `fixed_versions` and `timeline`. Each `affected_packages` row carries `fixed_branches`, every affected range of the package with its fix (`introduced`, and `fixed` or, where no fix is on record, `last_affected`), each naming the OSV record that published it (`advisory_id`, `source`) and in that record's order: an installed version's fix is the `fixed` of the range that holds it, compared in the ecosystem's version order. `fixed_version` is one range's fix, kept for compatibility, not the fix for every range (CVE-2021-44228's log4j-core: 2.12.2, the fix for 2.4 to 2.12.1, while 2.14.1's range is fixed in 2.15.0); `fixed_branches` is null where a package's ranges were never loaded, and `[]` where no version range is on record, which is not a finding that no fix exists. `verified_status` is the label stored with each reference, not a guarantee that the exploit works. An empty `exploits` list is not evidence that no public exploit exists; a section the API could not read is named in `coverage.sections_failed`, never relayed as an empty list. | *Is there public exploit code for CVE-2021-44228, and which versions fix it?* |
 | `get_cwe` | CWE and its CVEs | One CWE (weakness class) and the CVEs classified under it: `name` and `description` from the MITRE CWE catalog EchelonGraph embeds, `total`, and one page of 50 `cves`, ordered as `order` states (CISA-KEV-listed first, then EchelonGraph score). A `total` of 0 says that no CVE in EchelonGraph's feed is classified under that CWE, not that none exists. | *Which CVEs are classified under CWE-79, CISA-KEV-listed first?* |
 | `vendor_advisories_for_cve` | Vendor advisories for one CVE | The vendor-published advisories (Microsoft MSRC, Red Hat, Cisco, Palo Alto Networks, GitHub GHSA and the other feeds EchelonGraph polls) that name one CVE, newest first, at most 20. | *Which vendor advisories name CVE-2024-3400?* |
 | `get_vendor_advisory` | Vendor advisory detail | One vendor advisory in full: description, severity, `cve_ids` and the subset with a CVE record here (`known_cve_ids`), `affected_products`, `remediation` and `references`. | *Show one of those advisories in full: affected products, remediation and references.* |
@@ -238,6 +249,18 @@ The three vendor-advisory tools relay `vendor_published_at` (the vendor's date),
 (when EchelonGraph first recorded the advisory) and `withdrawn` (the vendor rescinded it; the note
 names each one, and the search leaves them out).
 
+Each also relays every vendor's window in `coverage` (`vendor_windows`, or `vendor_window` for the
+detail): the advisories held, the earliest and latest `vendor_published_at` among them,
+`held_since` and `history_backfill`. `held_since` is the start of the window EchelonGraph has read the
+vendor's advisories from: one published before it may not be held. For a vendor with no history read (`history_backfill`
+`not_supported`) it can be years after the earliest advisory held: Cisco's poller first read the
+advisories Cisco had changed in the last 90 days, Red Hat's and GitHub's the last 7, so an older
+advisory the vendor revised later is held while the ones published beside it are not.
+`vendor_advisories_for_cve` lists in `vendors_not_fully_held` each vendor with no advisory in the
+answer of which EchelonGraph holds none, whose `held_since` is after 1 January of the CVE ID's year
+or not known, or whose history is still being read: no advisory from such a vendor is not a finding
+that it published none.
+
 Every figure is as fresh as the schedule that refreshes it. The CVE feed is polled from its
 sources on a schedule; each radar refreshes on its own.
 
@@ -443,8 +466,9 @@ feed, matched by hostname pattern; no Shodan data is used. Each is checked by Ec
 identified MCP probe: a `server/discover` request, and `initialize` only if that is refused. It
 never sends `tools/call`. The answer is counts and timestamps only, with no hostname, version or
 server name, and the tool repeats no string it carries but its timestamps. Each hostname is
-counted once, by its latest verdict on record, and EchelonGraph's own control servers are left
-out. The unit is a hostname, not an ip:port service.
+counted once, by its latest verdict on record. EchelonGraph's own control servers are left
+out, and so is every hostname whose owner opted out of scanning, since it is not checked again
+while the opt-out stands and its last verdict cannot be re-checked. The unit is a hostname, not an ip:port service.
 
 | Field | What it counts |
 |---|---|
@@ -454,6 +478,7 @@ out. The unit is a hostname, not an ip:port service.
 | `mcp_servers.pending_readjudication` | Verdicts decided by a rule EchelonGraph has since replaced and not yet re-checked under the current rules. They are in neither `mcp_servers.protected` nor `mcp_servers.not_assessed`. |
 | `mcp_servers.not_assessed` | The rest, whose protection the radar could not assess. Not assessed does not mean unprotected. `mcp_servers.not_assessed_by_reason` puts each of them in exactly one bucket (below). |
 | `mcp_servers.own_controls_excluded` | EchelonGraph's own control servers, left out of every other `mcp_servers` number. |
+| `mcp_servers.withheld_opted_out` | Hostnames whose owner opted out of scanning, left out of every other `mcp_servers` number. Such a hostname is not checked again while the opt-out stands, so its last verdict cannot be re-checked; the API's unparameterised answer withholds the same hostnames under the same name. An answer that does not carry this field (an API that predates it) counted them, and the note says so. |
 | `mcp_servers.window.from`, `mcp_servers.window.to` | Timestamps, not counts: when the oldest and the newest of the verdicts counted were last checked. The counts are each hostname's latest verdict, not one sweep at one time. With no verdict counted there is no window. |
 | `mcp_servers.last_run_at` | A timestamp, not a count: when the AI-exposure radar, which checks other AI services as well as MCP servers, last completed a check (a cycle whose reads succeeded and whose scan opt-out register answered). It is not the time of every verdict counted. |
 | `mcp_servers.enabled` | Whether the API reports the radar running: true when a check completed within 45 minutes of its answer. |
@@ -544,10 +569,10 @@ never "not affected", and each figure cites its `measured_at`. A prompt makes no
 
 | Prompt | Arguments | What it asks the model to do |
 |---|---|---|
-| `triage_cve` | `cve_id` | `get_cve` (with CISA's due date, `kev_due_date`, when the CVE is KEV-listed), `cve_intel`, `vendor_advisories_for_cve`, `epss_history` and `cve_exposure`, then a decision template: exploited, likelihood, reachable, patch, deadline, decision. The patch line gives `cve_intel`'s `fixed_version` as what it records for the package, one per package (the advisory's last range's), never as the fix for every affected branch, and points to `get_cve`'s references tagged Vendor Advisory or Patch for a branch's fix. |
+| `triage_cve` | `cve_id` | `get_cve` (with CISA's due date, `kev_due_date`, when the CVE is KEV-listed), `cve_intel`, `vendor_advisories_for_cve`, `epss_history` and `cve_exposure`, then a decision template: exploited, likelihood, reachable, patch, deadline, decision. The patch line gives each affected range with its fix from `cve_intel`'s `fixed_branches`; where a package has none, it gives `fixed_version` as what `cve_intel` records for the package, one per package (the advisory's last range's as a rule), never as the fix for every affected branch, and points to `get_cve`'s references tagged Vendor Advisory or Patch for a branch's fix. |
 | `kev_weekly_brief` | `days` (1 to 365, default 7) | Work out the start date from `days`, page through `kev_recent` from it 50 rows a page, and write a brief grouped by vendor with ransomware flags and due dates. |
 | `am_i_affected` | `product`, or `ecosystem` and `package`; `version` | `check_affected`, read `assessed` before `count`, with the not-assessed wording. |
-| `sbom_review` | `sbom` (CycloneDX or SPDX JSON text, up to 5,000,000 characters) | Pass the document to `check_sbom` (and, once more, the purls a rate limit or the time budget left unsent: `data.not_sent_purls`, or, where the text cuts that list, the document's purls from the position and in the order its note gives), read each component's ecosystem, package and version from its purl, as `check_sbom` maps them (every purl type it maps, and `deb`, `apk`, `alpine` and `rpm` by a `distro` qualifier naming a Debian, Ubuntu or Alpine release; any other is unknown, and given no fixed version), look up each affected CVE with `get_cve` and `cve_intel`, and write a fix list ordered by CISA-KEV listing, then EPSS, then score, each key stated. A fixed version is given where it is above the component's installed version: the advisory interval in `check_sbom`'s `match_reason` first, else `cve_intel`'s `fixed_version`, which is one per package (the advisory's last range's) and need not be the fix on the component's branch; otherwise the line says the results give no fixed version for that branch and points to the CVE's advisory. |
+| `sbom_review` | `sbom` (CycloneDX or SPDX JSON text, up to 5,000,000 characters) | Pass the document to `check_sbom` (and, once more, the purls a rate limit or the time budget left unsent: `data.not_sent_purls`, or, where the text cuts that list, the document's purls from the position and in the order its note gives), read each component's ecosystem, package and version from its purl, as `check_sbom` maps them (every purl type it maps, and `deb`, `apk`, `alpine` and `rpm` by a `distro` qualifier naming a Debian, Ubuntu or Alpine release; any other is unknown, and given no fixed version), look up each affected CVE with `get_cve` and `cve_intel`, and write a fix list ordered by CISA-KEV listing, then EPSS, then score, each key stated. A fixed version is given where it is above the component's installed version: the advisory interval in `check_sbom`'s `match_reason` first (B of `[A, B)`, a fixed bound; the B of `[A, B]`, read by its closing bracket alone, is the last affected version, still affected, and neither it nor any version at or below it is given; an interval clipped before its closing bracket gives none), else the `fixed` of the `cve_intel` `fixed_branches` range that holds the installed version, else, for a package without `fixed_branches`, `cve_intel`'s `fixed_version`, which is one per package (the advisory's last range's) and need not be the fix on the component's branch; otherwise the line says the results give no fixed version for that branch and points to the CVE's advisory. |
 
 ## Resources
 
@@ -631,7 +656,7 @@ pretty-printed and whole. The same answer is always cut the same way. The `cve:/
 resource cuts its `data` as `get_cve`'s first text block is cut, and says so in a note starting
 `DATA CUT`. The prompts ask only for what the text keeps: `kev_weekly_brief` reads `kev_recent`
 50 rows a page, which the text holds whole; `triage_cve` reads CISA's due date from `get_cve`;
-and `sbom_review` reads fixed versions from `cve_intel`.
+and `sbom_review` reads fixed versions from `cve_intel`, the fix of each affected range in `fixed_branches`.
 
 ## Structured results
 
@@ -768,7 +793,11 @@ only those to the API, and neither logs nor keeps the document. To keep the docu
 machine, run the npm package, or pass `check_sbom` the purls. When a client passes the
 per-client limit it logs that client's address key. It passes your client's public address to
 the API, in a header the API trusts only with a token it checks, so the API's rate limit counts
-you and not the hosted service.
+you and not the hosted service. The API's access line then records each of those calls under
+your address (an IPv6 address by its /64) with its URL path: for a CVE, CWE or advisory lookup,
+the ID you asked about. It does not record the query string or the header-carried terms above
+(for `search_cves`, whether a term was given and its length, not the term), and of `check_sbom`'s
+purls it records how many, not which.
 
 EchelonGraph's privacy policy: <https://echelongraph.io/privacy>.
 
@@ -808,6 +837,16 @@ instance serves at most 64 requests at once; the next waits up to 10 seconds for
 and is then answered the same way. A `subscriptions/listen` stream, which stays open until its
 client leaves, is not one of the 64.
 
+A call whose client goes away (its own timeout, a closed tab) is stopped only once the server
+learns of it. Its API calls are then cancelled, `check_sbom` sends no further batch, and its
+large-body slot is freed. Over HTTP/1.1, Cloud Run does not pass a client's disconnect on to the
+server at all (<https://docs.cloud.google.com/run/docs/troubleshooting>). The hosted endpoint
+speaks HTTP/2 to Cloud Run, where the same page says a disconnect is passed on. Measured on
+2026-10-05, Cloud Run reset the stream of a client that stopped reading its answer 15 s in, and the
+call was logged as a client that closed. Whether a client that aborts mid-call is passed on at once
+has not been observed yet. Until it is, an abandoned `check_sbom` call may run for up to its
+50-second budget and hold its slot that long.
+
 ## Configuration
 
 The npm package (stdio):
@@ -835,6 +874,7 @@ It reads the three variables above and:
 | `MCP_LARGE_BODY_SLOTS` | `2` | How many bodies over `MCP_MAX_BODY_BYTES` it reads and serves at once; past that, 503 with `Retry-After`. |
 | `MCP_MAX_IN_FLIGHT` | `64` | How many requests it serves at once, not counting `subscriptions/listen` streams; the next, its body read, waits. |
 | `MCP_ADMISSION_WAIT_MS` | `10000` | How long a request waits to be served before it is answered 503 with `Retry-After`. |
+| `MCP_H2C` | unset | `1`: serve HTTP/2 cleartext (h2c, prior knowledge) instead of HTTP/1.1, as Cloud Run's `--use-http2` requires; an HTTP/1.1 request then gets no answer. Over h2c, a stream the client resets stops its call. |
 | `ECHELONGRAPH_FORWARD_TOKEN`, `ECHELONGRAPH_FORWARD_HOST`, `MCP_REQUIRE_FORWARD_TOKEN` | unset | EchelonGraph's hosted deployment only: the token with which it names each client to the API. Leave them unset when you run it yourself; the API then counts every request as coming from your server. |
 
 ## Develop

package/dist/http.js

@@ -13,6 +13,17 @@
 //   GET /health   liveness. Not /healthz: Cloud Run's front end reserves paths ending in "z"
 //                 and answers them itself, so a /healthz would never reach this process.
 //
+// HTTP/1.1 by default; HTTP/2 cleartext (h2c, prior knowledge) ONLY when MCP_H2C=1 (#2775). Cloud
+// Run tells a container that its client went away only over HTTP/2 or a WebSocket ("When you use
+// HTTP/1.1 on Cloud Run, client disconnect events are not propagated to the Cloud Run container",
+// https://docs.cloud.google.com/run/docs/troubleshooting): over HTTP/1.1 its front end reads the
+// whole answer itself, so an abandoned call ran to its end, holding its large-body slot. With
+// `--use-http2` Cloud Run sends the container h2c and nothing else, and a client that goes resets
+// its stream, which this server acts on at once (serveMcp). But on a canary of 2026-10-05 that reset
+// came only when the answer was written, 15 and 34 s in, not when the client went:
+// mcp_client_gone (after_ms, answer_started) is how production shows which. The flag and
+// MCP_H2C=1 go together (deploy-all.sh mcp-remote): either one alone answers no request at all.
+//
 // No auth: the endpoint serves only public data (MCP makes authorization optional), and the
 // server's instructions say what it is. The edge rules — Origin policy, per-client limit, body
 // cap, what is logged — are in httpPolicy.ts, each with its reasoning.
@@ -22,6 +33,7 @@
 // waf/mcpforward.go, #2212). MCP_REQUIRE_FORWARD_TOKEN=1 (set by deploy-all.sh) makes a missing
 // token fatal at start-up, because without it every remote user would share one API budget.
 import http from "node:http";
+import http2 from "node:http2";
 import v8 from "node:v8";
 import { createMcpHandler } from "@modelcontextprotocol/server";
 import { forwardToken, markHttpEntrypoint, requestSettled, SYNTHETIC_UA_FAMILY, withClient } from "./runtime.js";
@@ -49,6 +61,9 @@ const ADMISSION_WAIT_MS = positiveInt(process.env.MCP_ADMISSION_WAIT_MS, DEFAULT
 // A large body's wait for a slot is not queued: the client is told to come back. Nor is a
 // request that waited ADMISSION_WAIT_MS for admission.
 const BUSY_RETRY_AFTER_SEC = 5;
+// #2775: serve h2c instead of HTTP/1.1 (see the top of this file). Exactly "1": anything else is
+// HTTP/1.1, the default for a local run and for every test that does not ask.
+const H2C = process.env.MCP_H2C === "1";
 const MCP_PATH = "/mcp";
 const HEALTH_PATH = "/health";
 // One JSON object per line on stdout: Cloud Logging reads `severity` and `message`.
@@ -87,8 +102,17 @@ const PREFLIGHT_HEADERS = {
     "Access-Control-Max-Age": "600",
 };
 const HOP_BY_HOP = new Set(["host", "connection", "content-length", "transfer-encoding", "keep-alive", "upgrade", "expect"]);
+// HTTP/2 has no connection-specific headers (RFC 9113 8.2.2): Node drops them from an h2 answer
+// with a warning, so they are never set on one. A refusal's "Connection: close" (the rest of the
+// body is discarded unread) is the stream's own end there.
+const CONNECTION_SPECIFIC = new Set(["connection", "keep-alive", "proxy-connection", "transfer-encoding", "upgrade"]);
+function forProtocol(res, headers) {
+    if (!(res instanceof http2.Http2ServerResponse))
+        return headers;
+    return Object.fromEntries(Object.entries(headers).filter(([k]) => !CONNECTION_SPECIFIC.has(k.toLowerCase())));
+}
 function send(res, status, body, headers = {}) {
-    res.writeHead(status, { "Content-Type": "application/json", "Cache-Control": "no-store", ...headers });
+    res.writeHead(status, forProtocol(res, { "Content-Type": "application/json", "Cache-Control": "no-store", ...headers }));
     res.end(body);
 }
 function readBody(req) {
@@ -133,8 +157,14 @@ function readBody(req) {
             chunks.push(chunk);
         });
         req.on("end", () => {
+            if (done)
+                return;
+            done = true;
+            resolve({ body: Buffer.concat(chunks), slot });
+        });
+        req.on("close", () => {
             if (!done)
-                resolve({ body: Buffer.concat(chunks), slot });
+                stop("gone");
         });
         req.on("error", (e) => {
             if (done)
@@ -179,11 +209,35 @@ async function serveMcp(req, res, pathname) {
     // #2775: the client has gone when the response closes before it has finished. That aborts the
     // request: its wait for admission, the SDK's handling of it (which cancels the tool's call), and
     // its API calls (runtime.ts requestSignal).
+    // Over h2c the response of a reset stream closes marked finished (node:http2's compatibility
+    // API ends it), so there the stream itself is watched, from the moment the reset arrives:
+    // 'aborted' (a reset before the answer was written, any error code) and a 'close' before this
+    // server ended its answer (a reset with NO_ERROR emits no 'aborted').
+    // mcp_client_gone says WHEN this server learned it: after_ms from the request's start, and
+    // whether its answer had started (answer_started). On 2026-10-05 a canary behind Cloud Run's
+    // --use-http2 logged its aborted calls 499 only when their answers were written, 15 and 34 s
+    // in: this line tells a reset that arrived then from one that arrived early and was not acted on
+    // (the access line's duration_ms is when the call actually stopped).
     const gone = new AbortController();
+    const t0 = Date.now();
+    const h2stream = res.stream;
+    const clientWent = () => {
+        if (gone.signal.aborted)
+            return;
+        gone.abort();
+        log("INFO", "mcp_client_gone", { after_ms: Date.now() - t0, answer_started: res.headersSent, rst_code: h2stream?.rstCode ?? null });
+    };
     res.on("close", () => {
-        if (!res.writableFinished)
-            gone.abort();
+        if (!res.writableFinished || h2stream?.aborted)
+            clientWent();
     });
+    if (h2stream) {
+        h2stream.once("aborted", clientWent);
+        h2stream.once("close", () => {
+            if (!res.writableEnded)
+                clientWent();
+        });
+    }
     // The body is read BEFORE the request waits for admission (#2773), so a client that uploads
     // slowly holds its socket, and a large body its large-body slot, as before admission existed,
     // never one of the MAX_IN_FLIGHT places every other request needs. What a waiting request holds
@@ -203,6 +257,8 @@ async function serveMcp(req, res, pathname) {
                     return { status: 499, refused: "client_closed", clientClosed: true };
                 throw e;
             }
+            if (read === "gone")
+                return { status: 499, refused: "client_closed", clientClosed: true };
             if (read === "too_large")
                 return tooLarge(res, cors);
             if (read === "busy") {
@@ -259,7 +315,8 @@ async function serveMcp(req, res, pathname) {
 async function relay(req, res, pathname, method, cors, client, body, gone, work) {
     const headers = new Headers();
     for (const [k, v] of Object.entries(req.headers)) {
-        if (v === undefined || HOP_BY_HOP.has(k))
+        // ":method", ":path", ":authority", ":scheme": an h2 request's pseudo-headers, which a Request cannot carry.
+        if (v === undefined || HOP_BY_HOP.has(k) || k.startsWith(":"))
             continue;
         for (const one of Array.isArray(v) ? v : [v])
             headers.append(k, one);
@@ -279,7 +336,7 @@ async function relay(req, res, pathname, method, cors, client, body, gone, work)
     response.headers.forEach((v, k) => {
         out[k] = v;
     });
-    res.writeHead(response.status, out);
+    res.writeHead(response.status, forProtocol(res, out));
     if (response.body) {
         for await (const chunk of response.body)
             res.write(chunk);
@@ -290,7 +347,7 @@ async function relay(req, res, pathname, method, cors, client, body, gone, work)
         return { status: 499, body, clientPublic, clientClosed: true };
     return { status: response.status, body, clientPublic };
 }
-const server = http.createServer((req, res) => {
+function onRequest(req, res) {
     const start = process.hrtime.bigint();
     // The path only: a query string is never read, kept or logged.
     let pathname = "/";
@@ -341,7 +398,15 @@ const server = http.createServer((req, res) => {
             res.end();
         finish({ status: 500 });
     });
-});
+}
+// #2775: with MCP_H2C=1, node:http2's compatibility API, whose request and response carry the
+// IncomingMessage / ServerResponse members used above. Where they differ the code says so:
+// pseudo-headers (relay), connection-specific headers (forProtocol), a stream reset mid-upload
+// (readBody "gone"). A stream reset after that closes the response unfinished, which aborts
+// `gone` in serveMcp exactly as a closed HTTP/1.1 socket does.
+const server = H2C
+    ? http2.createServer((req, res) => onRequest(req, res))
+    : http.createServer(onRequest);
 // #2773: the heap V8 may grow to, and the memory the container allows (0 when none is known). A
 // heap allowed past the container's memory is collected only when the kernel kills the instance:
 // Dockerfile.http caps it, and this says when a process was started without that cap. It can say
@@ -362,6 +427,7 @@ server.listen(PORT, () => {
     const addr = server.address();
     log("INFO", "mcp_remote_listening", {
         port: typeof addr === "object" && addr ? addr.port : PORT,
+        protocol: H2C ? "h2c" : "http/1.1",
         name: NAME,
         version: VERSION,
         api_base: SHOWN_BASE,

package/dist/index.js

@@ -1567,8 +1567,9 @@ function readShadowAI(sa) {
 //
 // core-backend/internal/aiexposure (handler.go MCPPublicCounts, store.go): the AI-exposure
 // radar's MCP rows, one per hostname, each counted once by its latest verdict on record, with
-// EchelonGraph's own control servers left out and counted in own_controls_excluded. Counts,
-// timestamps and one constant (service "mcp"); no hostname, version or server name.
+// EchelonGraph's own control servers left out and counted in own_controls_excluded, and every
+// hostname whose owner opted out of scanning left out and counted in withheld_opted_out (#2822).
+// Counts, timestamps and one constant (service "mcp"); no hostname, version or server name.
 //   total                   protected + pending_readjudication + not_assessed
 //   protected               the /mcp endpoint answered 401/403 and its RFC 9728 protected-resource
 //                           metadata validated (prm.go); prm_via divides exactly these rows by
@@ -1581,6 +1582,12 @@ function readShadowAI(sa) {
 //                           (a challenge recorded before #2312), no_http_answer, not_identified_as_mcp
 //   era, transport          divide every counted row; a row written before #2314 recorded an era
 //                           is not_measured (era.go says what each value rests on)
+//   withheld_opted_out      hostnames a verified scan opt-out covered when the radar last reached
+//                           them (store.go opted_out_at, #2363): not re-checked while it stands, so
+//                           their last verdict is frozen, and in no other count (#2822). The unparameterised
+//                           answer withholds the same rows under the same key. An API older than
+//                           #2822 carries no such field and counted those rows; the note says so
+//                           rather than reading the absence as 0.
 //   window                  from/to: the oldest and newest last-check time over the counted rows
 //   enabled, last_run_at    exactly as the unparameterised answer computes them: the AI-exposure
 //                           radar's fleet-wide liveness and last completed check, over every AI
@@ -1636,7 +1643,7 @@ const MCP_PARTITIONS = {
 };
 const MCP_PARTITION_NAMES = Object.keys(MCP_PARTITIONS);
 const MCP_INSTANTS = ["last_run_at", "counted_at"];
-const MCP_KNOWN = new Set(["service", ...MCP_HEADLINE, ...MCP_PARTITION_NAMES, "own_controls_excluded", "window", "enabled", ...MCP_INSTANTS]);
+const MCP_KNOWN = new Set(["service", ...MCP_HEADLINE, ...MCP_PARTITION_NAMES, "own_controls_excluded", "withheld_opted_out", "window", "enabled", ...MCP_INSTANTS]);
 // What each challenge reason code says (prm.go prmReasonCodes), for the note.
 const MCP_CHALLENGE_MEANS = {
     resource_mismatch: "the document's resource is absent or not identical to the server's identifier",
@@ -1704,6 +1711,12 @@ function readMCPServers(src) {
         data.own_controls_excluded = src.own_controls_excluded;
     else
         unusable.push("own_controls_excluded");
+    // An API older than #2822 carries no withheld_opted_out, and counted those rows (the note says
+    // so); one that carries it in another shape has it left out and named.
+    if (isWhole(src.withheld_opted_out))
+        data.withheld_opted_out = src.withheld_opted_out;
+    else if (src.withheld_opted_out !== undefined)
+        unusable.push("withheld_opted_out");
     // window: from and to, both real instants, from not after to. With no row counted the API has
     // no window to give (null, or from and to null), and none is relayed.
     const w = src.window;
@@ -1752,6 +1765,12 @@ function readMCPServers(src) {
     if (data.own_controls_excluded !== undefined) {
         sentences.push(`mcp_servers.own_controls_excluded (${n("own_controls_excluded")}) counts EchelonGraph's own control servers, which are left out of every other mcp_servers number.`);
     }
+    if (data.withheld_opted_out !== undefined) {
+        sentences.push(`mcp_servers.withheld_opted_out (${n("withheld_opted_out")}) counts hostnames whose owner opted out of EchelonGraph's scanning: they are not checked again while the opt-out stands, so their last verdict cannot be re-checked, and they are left out of every other mcp_servers number.`);
+    }
+    else if (src.withheld_opted_out === undefined) {
+        sentences.push("The answer does not say how many hostnames whose owner opted out of scanning it withheld (mcp_servers.withheld_opted_out), so its counts may include such a hostname's last verdict, which is not re-checked while the opt-out stands.");
+    }
     if (data.window) {
         sentences.push(`mcp_servers.window says when the verdicts counted were last checked: the oldest at ${from} (mcp_servers.window.from) and the newest at ${to} (mcp_servers.window.to), so the counts are each hostname's latest verdict, not one sweep at one time.`);
     }
@@ -1777,11 +1796,11 @@ function readMCPServers(src) {
     return { data, sentences };
 }
 const EXPOSURE_RADAR_DESCRIPTION = `Aggregate totals from EchelonGraph's internet-exposure radars, each refreshed on its own schedule: internet-facing services running actively-exploited (CISA-KEV) CVEs, plus the ransomware-linked subset, derived from Shodan data; unauthenticated data stores and observability UIs, found through Shodan (LeakIX when Shodan query credits run low) and then confirmed by EchelonGraph's own identified check (not a pure read: on Redis it names its client, and on ClickHouse its query is recorded in the server's query log); leaked credentials sampled from public GitHub push events; and shadow AI services found through Certificate Transparency logs and Shodan and then checked by EchelonGraph's identified probes. It also gives MCP-server counts: hostnames named like an MCP server in EchelonGraph's own Certificate Transparency feed (no Shodan data), each counted once by its latest verdict from EchelonGraph's identified MCP probe, which never sends tools/call. Every number in the result is labelled here and in the result's note by what it counts; a field this version cannot label is left out and named in the note. ` +
-    `kev_exposure: kev_exposure.distinct_hosts counts distinct ip:port services, not machines (a machine answering on two ports counts twice), with at least one CISA-KEV-listed CVE on record, and kev_exposure.ransomware_hosts those with a ransomware-linked one; kev_exposure.kev_cves_exposed and kev_exposure.ransomware_cves count distinct CVEs with at least one such service; kev_exposure.correlations counts service×CVE pairs, not services, so a service with three KEV CVEs counts three times. kev_exposure.top_products, kev_exposure.top_countries and kev_exposure.top_cves rank up to 12 products, 10 countries and 12 CVEs by those services; kev_exposure.top_cves[].cvss_v3_score and kev_exposure.top_cves[].epss_score are the highest CVSS v3 base score and EPSS probability recorded on that CVE's observations. kev_exposure.trend counts service×CVE pairs still on record by the week in which each was first recorded, over 12 weeks, so earlier weeks read low. kev_exposure.newest_kev lists the 15 CVEs that EchelonGraph's CVE records most recently mark as CISA-KEV-listed, each with an exposure_state: exposed, where kev_exposure.newest_kev[].exposed_hosts counts distinct ip:port services on record with it; or not_assessed, where the API's answer holds no measurement for that CVE (its 0 is not one) and no count is relayed, and cve_exposure says per CVE whether the radar tracks it. kev_exposure.newest_kev[].cvss_v3_score and kev_exposure.newest_kev[].epss_score are the CVE record's CVSS v3 base score and EPSS probability. ` +
+    `kev_exposure: kev_exposure.distinct_hosts counts distinct ip:port services, not machines (a machine answering on two ports counts twice), with at least one CISA-KEV-listed CVE on record, and kev_exposure.ransomware_hosts those with a ransomware-linked one; kev_exposure.kev_cves_exposed and kev_exposure.ransomware_cves count distinct CVEs with at least one such service; kev_exposure.correlations counts service×CVE pairs, not services, so a service with three KEV CVEs counts three times. kev_exposure.top_products, kev_exposure.top_countries and kev_exposure.top_cves rank up to 12 products, 10 countries and 12 CVEs by those services; kev_exposure.top_cves[].cvss_v3_score and kev_exposure.top_cves[].epss_score are the highest CVSS v3 base score and EPSS probability recorded on that CVE's observations. kev_exposure.trend counts service×CVE pairs still on record by the week in which each was first recorded, over 12 weeks, so earlier weeks read low. kev_exposure.newest_kev lists the 15 CVEs that EchelonGraph's CVE records most recently mark as CISA-KEV-listed, each with an exposure_state: exposed, where kev_exposure.newest_kev[].exposed_hosts counts distinct ip:port services on record with it; or not_assessed, where the API's answer holds no measurement for that CVE (its 0 is not one) and no count is relayed, and this answer does not say whether the radar tracks that CVE: tracking is answered per CVE. kev_exposure.newest_kev[].cvss_v3_score and kev_exposure.newest_kev[].epss_score are the CVE record's CVSS v3 base score and EPSS probability. ` +
     `exposed_databases: exposed_databases.distinct_hosts counts distinct ip:port services the check confirmed answering without authentication, and exposed_databases.engines the distinct engine types among them; exposed_databases.top_engines and exposed_databases.top_countries rank up to 15 engines and 10 countries by those services. exposed_databases.pii_likely and exposed_databases.pci_likely count services whose schema names (never record values) pass a high-confidence, precision-first gate for personal or payment-card data, so a service outside them is not shown to hold no such data. exposed_databases.window.from and exposed_databases.window.to are timestamps, not counts: when EchelonGraph's check last confirmed the oldest and the newest of the services counted, a span of checks made at different times; with a counted service that has no such time on record there is no window. ` +
     `leaked_credentials: leaked_credentials.total counts (repository, secret) pairs, not distinct secrets, so one secret in three repositories counts three times; leaked_credentials.distinct_secrets counts each secret once and leaked_credentials.distinct_repos counts repositories; leaked_credentials.top_providers and leaked_credentials.top_types rank up to 15 providers and secret types by those pairs. None is validated: each is a credential-shaped string that passed EchelonGraph's filters, at most structurally checked and never tested against its provider. leaked_credentials.window.from and leaked_credentials.window.to are timestamps, not counts: when EchelonGraph's detector last found the oldest and the newest of the pairs counted. Each of those three radars also carries generated_at, when the API computed its totals, and, when the API can tell, last_run_at. kev_exposure.last_run_at, exposed_databases.last_run_at and leaked_credentials.last_run_at are timestamps, not counts: each is when that radar last completed a check, a cycle whose reads succeeded, among them a Shodan search (for exposed_databases, or its LeakIX fallback) that answered at least one query, or for leaked_credentials a read of the public GitHub event stream. A cycle that read nothing does not move it, and it is not the time of every record a radar's numbers count, which cover everything still on record, not only what the last check found. A radar whose answer carries no last_run_at has none in the result, and the note says nothing about it. ` +
     `shadow_ai: the result is regrouped by what each number counts. shadow_ai.confirmed_exposed counts services EchelonGraph's probes found answering without an authentication gate (liveness active, or rechecking during a re-check): confirmed_exposed.total is the sum of confirmed_exposed.by_category, and confirmed_exposed.last_24h counts those first recorded in the last 24 h. Of the shadow_ai numbers, only confirmed_exposed counts exposed services. confirmed_exposed.window.from and confirmed_exposed.window.to are timestamps, not counts: when EchelonGraph's verifier ran the probe that last decided the oldest and the newest of those services, a span of probes made at different times. shadow_ai.observed counts every Certificate Transparency or Shodan observation on record, whatever its verification state: its numbers are observed, not exposed. They are observed.total; observed.by_category (the same observations by category); observed.last_24h (those first recorded in the last 24 h); observed.trend_30d (observations per UTC day over the last 30 days); and observed.top_products, observed.top_countries and observed.top_issuers (up to ten products, countries and issuers ranked by observations, where an issuer is the certificate's CA for a Certificate Transparency observation and the hosting operator Shodan reports for a Shodan one). shadow_ai.authentication counts observations by probe outcome: authentication.observed where a probe observed an authentication gate (a 401/403, a login page or an auth marker), and authentication.not_determined where the service answered but no probe could tell. Neither authentication count is part of confirmed_exposed, and observed.total minus confirmed_exposed.total is not a count of secured services. The shadow-AI poller block carries only running and last_run_at: last_run_at is when the radar's leader last completed a Certificate Transparency (crt.sh) cycle, and its running is true only when that was within ${SHADOW_AI_SILENT_AFTER} of the answer. ` +
-    `mcp_servers: counts and timestamps only, no hostname. mcp_servers.total counts hostnames the AI-exposure radar has checked for an MCP server, each once by its latest verdict on record, and not every one is an MCP server; EchelonGraph's own control servers are left out, and mcp_servers.own_controls_excluded counts them. mcp_servers.total is mcp_servers.protected plus mcp_servers.pending_readjudication plus mcp_servers.not_assessed. mcp_servers.protected counts hostnames whose /mcp endpoint asked for credentials and whose OAuth protected-resource metadata validated under RFC 9728; mcp_servers.prm_via divides them by where that document was found: mcp_servers.prm_via.header, mcp_servers.prm_via.wellknown_path and mcp_servers.prm_via.wellknown_root. mcp_servers.pending_readjudication counts verdicts of a rule since replaced, not yet re-checked. mcp_servers.not_assessed counts the rest, whose protection the radar could not assess (not assessed does not mean unprotected), and mcp_servers.not_assessed_by_reason puts each in one bucket. mcp_servers.not_assessed_by_reason.identified_no_challenge holds servers that identified themselves as MCP servers and did not ask for credentials at the handshake. That is normal in MCP: authorization is optional in the spec, and a server can enforce it at tools/call instead, which EchelonGraph never sends, so this bucket is not a finding of exposure. ${MCP_CHALLENGE_REASON_FIELDS} hold endpoints that asked for credentials but whose RFC 9728 metadata did not validate, by why, so none of them is shown to lack protection; mcp_servers.not_assessed_by_reason.challenge_unadjudicated holds endpoints that asked for credentials before that check existed, not yet re-checked. mcp_servers.not_assessed_by_reason.no_http_answer holds hostnames that gave no HTTP answer, and mcp_servers.not_assessed_by_reason.not_identified_as_mcp hostnames whose HTTP answer identified no MCP server. mcp_servers.era divides every counted hostname by protocol era: mcp_servers.era.legacy; mcp_servers.era.dual, a lower bound; mcp_servers.era.modern, not proven modern-only; mcp_servers.era.unknown; and mcp_servers.era.not_measured, recorded before the era probe and not re-checked since. mcp_servers.transport divides them by transport: mcp_servers.transport.streamable_http, mcp_servers.transport.legacy_sse, mcp_servers.transport.unknown and mcp_servers.transport.not_measured. mcp_servers.window.from and mcp_servers.window.to are when the oldest and the newest of the verdicts counted were last checked. mcp_servers.last_run_at is a timestamp, not a count: when the AI-exposure radar, which checks other AI services too, last completed a check; mcp_servers.enabled is whether one completed within ${MCP_ENABLED_WITHIN} of the answer, and mcp_servers.counted_at is when the API read the counts. A partition whose buckets do not add up to the count it divides is left out and named; an answer that does not say it is the MCP-server counts, or whose mcp_servers.total, mcp_servers.protected, mcp_servers.pending_readjudication and mcp_servers.not_assessed are missing or contradict each other, is a failure. ${SHODAN_OWNERSHIP}`;
+    `mcp_servers: counts and timestamps only, no hostname. mcp_servers.total counts hostnames the AI-exposure radar has checked for an MCP server, each once by its latest verdict on record, and not every one is an MCP server; EchelonGraph's own control servers are left out, and mcp_servers.own_controls_excluded counts them; hostnames whose owner opted out of scanning are not checked again while the opt-out stands, so their last verdict is left out too, and mcp_servers.withheld_opted_out counts them. mcp_servers.total is mcp_servers.protected plus mcp_servers.pending_readjudication plus mcp_servers.not_assessed. mcp_servers.protected counts hostnames whose /mcp endpoint asked for credentials and whose OAuth protected-resource metadata validated under RFC 9728; mcp_servers.prm_via divides them by where that document was found: mcp_servers.prm_via.header, mcp_servers.prm_via.wellknown_path and mcp_servers.prm_via.wellknown_root. mcp_servers.pending_readjudication counts verdicts of a rule since replaced, not yet re-checked. mcp_servers.not_assessed counts the rest, whose protection the radar could not assess (not assessed does not mean unprotected), and mcp_servers.not_assessed_by_reason puts each in one bucket. mcp_servers.not_assessed_by_reason.identified_no_challenge holds servers that identified themselves as MCP servers and did not ask for credentials at the handshake. That is normal in MCP: authorization is optional in the spec, and a server can enforce it at tools/call instead, which EchelonGraph never sends, so this bucket is not a finding of exposure. ${MCP_CHALLENGE_REASON_FIELDS} hold endpoints that asked for credentials but whose RFC 9728 metadata did not validate, by why, so none of them is shown to lack protection; mcp_servers.not_assessed_by_reason.challenge_unadjudicated holds endpoints that asked for credentials before that check existed, not yet re-checked. mcp_servers.not_assessed_by_reason.no_http_answer holds hostnames that gave no HTTP answer, and mcp_servers.not_assessed_by_reason.not_identified_as_mcp hostnames whose HTTP answer identified no MCP server. mcp_servers.era divides every counted hostname by protocol era: mcp_servers.era.legacy; mcp_servers.era.dual, a lower bound; mcp_servers.era.modern, not proven modern-only; mcp_servers.era.unknown; and mcp_servers.era.not_measured, recorded before the era probe and not re-checked since. mcp_servers.transport divides them by transport: mcp_servers.transport.streamable_http, mcp_servers.transport.legacy_sse, mcp_servers.transport.unknown and mcp_servers.transport.not_measured. mcp_servers.window.from and mcp_servers.window.to are when the oldest and the newest of the verdicts counted were last checked. mcp_servers.last_run_at is a timestamp, not a count: when the AI-exposure radar, which checks other AI services too, last completed a check; mcp_servers.enabled is whether one completed within ${MCP_ENABLED_WITHIN} of the answer, and mcp_servers.counted_at is when the API read the counts. A partition whose buckets do not add up to the count it divides is left out and named; an answer that does not say it is the MCP-server counts, or whose mcp_servers.total, mcp_servers.protected, mcp_servers.pending_readjudication and mcp_servers.not_assessed are missing or contradict each other, is a failure. ${SHODAN_OWNERSHIP}`;
 // exposure_radar's envelope. Every radar answered, but no stats answer says when the services
 // or records it counts were observed: each count covers everything that radar still holds on
 // record, and the answer carries only generated_at (when the API computed the totals) and
@@ -2106,6 +2125,7 @@ const MCPServersData = z.strictObject({
     ...Object.fromEntries(MCP_HEADLINE.map((k) => [k, Whole])),
     ...Object.fromEntries(MCP_PARTITION_NAMES.map((k) => [k, z.strictObject(Object.fromEntries(MCP_PARTITIONS[k].buckets.map((b) => [b, Whole]))).optional()])),
     own_controls_excluded: Whole.optional(),
+    withheld_opted_out: Whole.optional(),
     window: z.strictObject({ from: Instant, to: Instant }).optional(),
     enabled: z.boolean().optional(),
     ...Object.fromEntries(MCP_INSTANTS.map((k) => [k, Instant.optional()])),
@@ -2176,17 +2196,17 @@ const FEED_ENVELOPE = "Its structured result carries state (measured), measured_
 const CVE_SUMMARY_ENVELOPE = "Its structured result carries state (measured), measured_at, method, coverage, freshness (null: the feed serves no poll-completion time) and notes, with data equal to the API's JSON less each poller field (or the whole poller) the note names as left out; 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.";
 // #2610: what cve_summary says summary.none is (summaryNoneNote), one constant string for the same
 // reason as SCORE_ASSESSED_DESCRIPTION below.
-const SUMMARY_NONE_DESCRIPTION = "summary.none is not a severity rating of None: it counts the active CVEs with no severity band from any source, that is, CVEs not yet scored, and the answer may carry the same count again as summary.unscored. Whenever summary.none is above zero the note says so: report those CVEs as not yet scored, not as CVEs rated None.";
+const SUMMARY_NONE_DESCRIPTION = "summary.none is not a severity rating of None: it counts the active CVEs with no severity band from any source, that is, CVEs not yet scored, and the answer may carry the same count again as summary.unscored. Whenever summary.none is above zero the note says so, and names those CVEs not yet scored, not CVEs rated None.";
 // #2641: what cve_summary says the NVD histogram and summary.rejected are (summaryNVDNote,
 // summaryRejectedNote), constant strings for the same reason. Neither uses the words "any", "not",
 // "rating", "scored", "source" or "yet": the site's #2610 control (marketing-site
 // lib/mcpToolClaims.test.ts) holds that exactly those words of the /pulse/mcp cve_summary row are
 // backed by SUMMARY_NONE_DESCRIPTION alone, and fails if another sentence backs one.
 const SUMMARY_NVD_DESCRIPTION = "summary.nvd_critical, summary.nvd_high, summary.nvd_medium, summary.nvd_low and summary.nvd_none count the same active CVEs as summary.total by NVD's CVSS severity label (v3.x, else v4.0; before NVD's record arrives, or where it gives none, a pre-NVD label from the CVE.org record or a GitHub advisory can stand in): provenance, never EchelonGraph's severity band. summary.nvd_none counts the active CVEs with no Critical, High, Medium or Low label there, CVEs NVD never labelled under CVSS v3 among them, and many of those carry an NVD CVSS v2 score instead: it is neither a count of CVEs rated None nor the count of CVEs with no severity, which is summary.none. Whenever summary.nvd_none is above zero the note says what it counts, with its count.";
-const SUMMARY_REJECTED_DESCRIPTION = "summary.rejected counts the CVE records rejected (withdrawn) by their numbering authority, which summary.total and the other counts above leave out: report them as withdrawn records, never as vulnerabilities.";
+const SUMMARY_REJECTED_DESCRIPTION = "summary.rejected counts the CVE records rejected (withdrawn) by their numbering authority, which summary.total and the other counts above leave out: they are withdrawn records, none of them a vulnerability.";
 // #2535: what search_cves and get_cve say about score_assessed, one constant string, since the
 // site's tool-claims check (marketing-site lib/mcpToolClaims.test.ts) folds only constant strings.
-const SCORE_ASSESSED_DESCRIPTION = "echelongraph_score, echelongraph_severity and echelongraph_risk are EchelonGraph's score only when score_assessed is true. With score_assessed false the CVE is NOT YET SCORED, not scored 0: any of those three it carries (0, NONE, 0) is a placeholder, not a rating, and does not mean the CVE is harmless; the API may leave them out instead, score_confidence is NONE, and score_unassessed_reason says why (a rejected record, withdrawn by its numbering authority, is never scored, and the note says NOT SCORED). The note labels each such CVE NOT YET SCORED: report it that way, never as a score of 0. An answer with no score_assessed (an API older than that field) does not say whether the CVE was scored, the note says so, and a 0 there is not a rating either.";
+const SCORE_ASSESSED_DESCRIPTION = "echelongraph_score, echelongraph_severity and echelongraph_risk are EchelonGraph's score only when score_assessed is true. With score_assessed false the CVE is NOT YET SCORED, not scored 0: any of those three it carries (0, NONE, 0) is a placeholder, not a rating, and does not mean the CVE is harmless; the API may leave them out instead, score_confidence is NONE, and score_unassessed_reason says why (a rejected record, withdrawn by its numbering authority, is never scored, and the note says NOT SCORED). The note labels each such CVE NOT YET SCORED, which is not a score of 0. An answer with no score_assessed (an API older than that field) does not say whether the CVE was scored, the note says so, and a 0 there is not a rating either.";
 // The shared helpers a tool in src/tools/ is handed (#2718), so its file holds its own logic.
 const TOOL_KIT = { api, succeeded, failed, badInput, crashed, checked, okHead, envelopeSchema, annotations: ANNOTATIONS, cveIdArg: CVE_ID_ARG, instant: Instant };
 // One server, built per connection by serveStdio for whichever era the client opens with, and

package/dist/prompts.js

@@ -36,14 +36,17 @@ const text = (t) => ({ messages: [{ role: "user", content: { type: "text", text:
 // Its Patch line (#2817): cve_intel's fixed_version is one value per (CVE, ecosystem, package), the
 // advisory's last range's (core-backend cve/advisory.go UpsertAffectedPackages), and triage_cve has
 // no installed version to hold it against: for CVE-2021-44228 production's cve_intel gives
-// log4j-core 2.12.2 (2026-10-04, 2.6.3), below an affected 2.14.1. So the line gives it as
-// what cve_intel records for the package, never as the fix for every affected branch, and sends
-// the reader to get_cve's references tagged Vendor Advisory or Patch for a branch's fix.
+// log4j-core 2.12.2 (2026-10-04, 2.6.3), below an affected 2.14.1. Since #2817 each
+// affected_packages row also carries fixed_branches, every range with its fix (core-backend
+// cve/fixed_branches.go), so the line gives those, range by range, and gives fixed_version only
+// where a row has no fixed_branches, as what cve_intel records for the package, never as the fix
+// for every affected branch, sending the reader to get_cve's references tagged Vendor Advisory or
+// Patch for a branch's fix.
 export function triageCveText(cve) {
     return [
         `Triage ${cve} using the EchelonGraph MCP tools. Call them in this order, each with cve_id ${cve}:`,
         "1. get_cve: the record. Read score_assessed before echelongraph_score (false: not yet scored, which is not a score of 0); read severity, cvss_v3_score, epss_score and epss_percentile, and the CISA-KEV fields kev_listed, kev_added_date, kev_due_date and kev_ransomware.",
-        "2. cve_intel: weaknesses (cwes), public exploit code (exploits and exploits_total; verified_status is the label stored with each reference, not a guarantee that it works, and an empty list is not evidence that no exploit exists), affected_packages and fixed_versions.",
+        "2. cve_intel: weaknesses (cwes), public exploit code (exploits and exploits_total; verified_status is the label stored with each reference, not a guarantee that it works, and an empty list is not evidence that no exploit exists), affected_packages (each package's affected ranges with their fixes in fixed_branches) and fixed_versions.",
         "3. vendor_advisories_for_cve: the vendor advisories that name it. Call get_vendor_advisory for one whose remediation you need in full.",
         "4. epss_history: how its EPSS score changed, one point per recorded change (series_kind change_only): before series_starts_at a missing point means not recorded, not unchanged.",
         "5. cve_exposure: internet exposure on record. exposure_state says what the count is; exposed_hosts counts distinct ip:port services, not machines; the result is not_assessed with measured_at null, so present any count as undated and on record, and exposure_state not_assessed as not assessed.",
@@ -52,7 +55,7 @@ export function triageCveText(cve) {
         "- Exploited? CISA-KEV listing and its date, known ransomware use, and public exploit code on record.",
         "- Likelihood: EPSS score and percentile, and how it has moved.",
         "- Reachable? exposure_state and the count on record, or not assessed.",
-        `- Patch: fixed versions and vendor advisories; where the results hold none, write "none on record", which is not a finding that no fix exists. cve_intel keeps one fixed_version per ecosystem and package, its advisory's last range's, which need not be the fix for every affected version of the package: give each as the fixed version cve_intel records for that package, never as the fix for every affected branch or the version every install should move to, and for the fix on a given branch point to get_cve's references tagged Vendor Advisory or Patch, where it has them, and to the vendor advisories.`,
+        `- Patch: fixed versions and vendor advisories; where the results hold none, write "none on record", which is not a finding that no fix exists. For each affected package whose cve_intel row carries fixed_branches, give every range with its fix: from introduced ("0" is the first version) up to its fixed, or up to and including last_affected, where no fix is on record for that range; never one range's fix as the fix for every affected branch or the version every install should move to. cve_intel keeps one fixed_version per ecosystem and package, its advisory's last range's as a rule, which need not be the fix for every affected version of the package: where a row has no fixed_branches (null or absent), give fixed_version as the fixed version cve_intel records for that package, never as the fix for every affected branch, and for the fix on a given branch point to get_cve's references tagged Vendor Advisory or Patch, where it has them, and to the vendor advisories.`,
         "- Deadline: get_cve's kev_due_date when the CVE is KEV-listed (CISA's due date for US federal civilian agencies); otherwise write that the results give no CISA deadline.",
         "- Decision: patch now, schedule, or monitor, with a one-line reason drawn from the lines above.",
     ].join("\n");
@@ -90,17 +93,25 @@ export function amIAffectedText(a) {
 // rebuilds them from the document, from the position check_sbom's note gives, in the order it
 // gives (check_sbom.ts READ_ORDER).
 //
-// Fixed versions (#2799 review, #2817). cve_intel's fixed_version is one value per (CVE, ecosystem,
+// Fixed versions (#2799 review, #2817, #2830). cve_intel's fixed_version is one value per (CVE, ecosystem,
 // package), the advisory's last range's (core-backend cve/advisory.go UpsertAffectedPackages), so
 // it need not be the fix for the installed version's branch: for CVE-2021-44228, production's
 // cve_intel gives log4j-core 2.12.2 (2026-10-04, 2.6.3), older than an installed 2.14.1, and
 // check_sbom's matches for 2.14.1 say it "is listed verbatim in the advisory's affected versions",
 // which names no fix. So a fixed version is given only where it is strictly greater than the
 // installed version, and otherwise the line says the results give none for the component's branch
-// and points to the advisory. The advisory interval in a match's match_reason, "[A, B)" (core-backend
-// cve/pkgmatch.go evaluateRegistryRow), is preferred where the text keeps it (its first cut level;
-// a Juice Shop SBOM of 50 components is cut past it); B is the interval's fixed bound, or its
-// last_affected one, which the text does not tell apart, so B is given as the interval's end.
+// and points to the advisory. The advisory interval in a match's match_reason (core-backend
+// cve/pkgmatch.go renderInterval) is preferred where the text keeps it (its first cut level;
+// a Juice Shop SBOM of 50 components is cut past it). Since #2830 its closing bracket carries the
+// bound's meaning: "[A, B)" is a fixed bound, B the first version not affected, so B is given as
+// the fix; "[A, B] (B is the last affected version, not a fix)" is an OSV last_affected bound,
+// B still affected, so B (or any version at or below it) is never given as a fix; "[A, ∞)" has no
+// end on record; a text clipped before the closing bracket ("[A, B…") gives no fix from it.
+// Through 2.6.5 core-backend rendered a last_affected bound as "[A, B)" too, and the prompt
+// hedged B as "the end of that interval". Since #2817 cve_intel's affected_packages rows carry
+// fixed_branches, every range with its fix, so after the match_reason interval the rule reads the
+// range that holds the installed version (2.14.1: [2.13.0, 2.15.0), so 2.15.0), and falls back to
+// fixed_version only for a row without fixed_branches.
 // A cut text keeps index, purl, verdict, not_assessed_reason and cve_ids on a row, not its
 // ecosystem, package or version, so the model reads those from the purl, as core-backend's
 // matcher does (cve/matchbatch.go purlNameVersion, shared/pkg/purlosv): step 2 lists every type
@@ -113,11 +124,11 @@ export function sbomReviewText(sbom) {
         "Review the SBOM below for known vulnerabilities, using the EchelonGraph MCP tools.",
         `1. Call check_sbom with sbom set to the document below, as given. It reads the document's purls and checks up to ${MAX_PURLS} distinct purls per call, sending them in batches of ${MAX_COMPONENTS}; a document with more is refused, not truncated. If it is refused, say why from the result and do not guess at the components. If coverage.not_sent is above 0, the API's rate limit or the call's time budget stopped it early: say how many purls were not sent and coverage.not_sent_reason, and that they are not checked (never clean). After a minute, call check_sbom once more with purls set to the purls not sent, and merge what it returns. data.not_sent_purls lists them; where the note says the first text block cuts not_sent_purls to its first entries, rebuild the list from the document instead, as the note says: the document's distinct purls from the position the note gives on, counted in the order it gives.`,
         "2. Read each component's ecosystem, package and version from its purl, which every row of data.results in the text carries (the leanest cut of the text leaves out the row's own ecosystem, package and version), as check_sbom maps them. A purl is pkg:type/namespace/name@version?qualifiers, each part percent-decoded (%40 is @), its type and distro qualifier in any case. The version is what follows the last @, up to any ? or #. The ecosystem follows from the type: npm is npm, pypi PyPI, maven Maven, golang Go, cargo crates.io, gem RubyGems, nuget NuGet, composer Packagist, hex Hex, pub Pub, swift SwiftURL, hackage Hackage, cran CRAN, bitnami Bitnami, conan ConanCenter and githubact GitHub Actions. For deb, apk, alpine and rpm it is the release the distro qualifier names, which must be one of these three kinds: distro=debian-N is Debian:N, the major release alone (debian-12 and debian-12.5 are Debian:12); distro=ubuntu-V is Ubuntu:V as given (ubuntu-22.04 is Ubuntu:22.04); distro=alpine-X.Y is Alpine:vX.Y, cut to major.minor (alpine-3.20 and alpine-3.20.10 are Alpine:v3.20; alpine-3 names none). For any other type, and a deb, apk, alpine or rpm purl without such a qualifier, the ecosystem is unknown: check_sbom does not check the component (not_assessed, never clean), and the fix list gives no version for it. The package is namespace:name for maven (pkg:maven/org.apache.logging.log4j/log4j-core@2.14.1 is the package org.apache.logging.log4j:log4j-core in Maven, at version 2.14.1), namespace/name for npm, golang, composer, swift and githubact, and the name alone for every other type (pkg:deb/debian/openssl@3.0.15-1~deb12u1?distro=debian-12 is openssl in Debian:12).",
-        "3. For each distinct cve_id on a component whose verdict is affected, call get_cve, to read kev_listed, epss_score, score_assessed, echelongraph_score and cvss_v3_score, and cve_intel, to read fixed_version from its affected_packages and fixed_versions rows for the component's ecosystem and package (package_name). If there are more than 30 distinct CVEs, do this for 30 of them and list the rest as not looked up, unranked.",
+        "3. For each distinct cve_id on a component whose verdict is affected, call get_cve, to read kev_listed, epss_score, score_assessed, echelongraph_score and cvss_v3_score, and cve_intel, to read fixed_branches and fixed_version from its affected_packages rows, and fixed_version from its fixed_versions rows, for the component's ecosystem and package (package_name). If there are more than 30 distinct CVEs, do this for 30 of them and list the rest as not looked up, unranked.",
         ENVELOPE_RULES,
         "Read each component's verdict: not_affected is the one clean verdict; undetermined and not_assessed are not clean, and not_assessed_reason says why (for example distro_release_unknown: a deb, apk or rpm purl without a distro qualifier, which EchelonGraph does not guess).",
         "Then write a prioritised fix list of the affected components. State the ordering keys, in this order: 1. CISA-KEV listed (kev_listed true) first; 2. then EPSS score, highest first; 3. then echelongraph_score where score_assessed is true, else cvss_v3_score, highest first. A CVE with no value for a key sorts after those with one, and its line says which key was missing.",
-        "For each line give the component (purl), its cve_ids, the key values used, and for each CVE a fixed version where the results support one, by this rule. Never give a fixed version that is not strictly greater than the component's installed version (the version in its purl), compared in the ecosystem's version order: release numbers part by part, as numbers, not as text (2.9.1 is below 2.12.2, and 2.12.2 is below 2.14.1); where you are not sure of the order (pre-releases, qualifiers and distro revisions have their own rules), say so and do not give it. Prefer the match's match_reason where the text keeps it: \"falls inside the advisory interval [A, B)\" says the advisory's range that holds the installed version ends at B, which match_reason does not say is a fixed version rather than the range's last affected version, so give B as the end of that interval, quoting it (∞: the range has no end on record). Otherwise give cve_intel's fixed_version for the component's ecosystem and package (or the recorded fix a match_reason names, the same value): cve_intel keeps one fixed_version per package, its advisory's last range's, which need not be the fix on the component's branch, so say so beside it. Where no version meets the rule (\"listed verbatim in the advisory's affected versions\" names none), write that the results give no fixed version for the component's branch, which is not a finding that no fix exists, and point to the CVE's advisory for it: get_cve's references tagged Vendor Advisory or Patch, where it has them.",
+        "For each line give the component (purl), its cve_ids, the key values used, and for each CVE a fixed version where the results support one, by this rule. Never give a fixed version that is not strictly greater than the component's installed version (the version in its purl), compared in the ecosystem's version order: release numbers part by part, as numbers, not as text (2.9.1 is below 2.12.2, and 2.12.2 is below 2.14.1); where you are not sure of the order (pre-releases, qualifiers and distro revisions have their own rules), say so and do not give it. Prefer the match's match_reason where the text keeps it: \"falls inside the advisory interval [A, B)\", closed by a parenthesis, says B is the advisory's fixed version for the range that holds the installed version, so give B as the fixed version, quoting it (\"[A, ∞)\": the range has no end on record and names no fixed version). \"falls inside the advisory interval [A, B]\", closed by a square bracket, says B is the range's last affected version, still affected, and the range records no fix (core-backend adds \"(B is the last affected version, not a fix)\", which a cut text can clip, so the bracket alone decides): never give B, or any version at or below it, as a fixed version. Where the text is cut before the interval's closing bracket (\"[A, B…\", neither \")\" nor \"]\"), it does not say which bound B is: give no fixed version from that match_reason. Otherwise, where cve_intel's affected_packages row for the component's ecosystem and package carries fixed_branches, give the fixed of the range that holds the installed version: at or above its introduced (\"0\" is the first version) and below its fixed, or at or below its last_affected, in the same version order; a range with last_affected and no fixed has no fix on record, and a version in no range is given no fixed version from them; where fixed_branches is there, fixed_version is not used. Where it is not (null or absent), give cve_intel's fixed_version for the component's ecosystem and package (or the recorded fix a match_reason names, the same value): cve_intel keeps one fixed_version per package, its advisory's last range's, which need not be the fix on the component's branch, so say so beside it. Where no version meets the rule (\"listed verbatim in the advisory's affected versions\" names none), write that the results give no fixed version for the component's branch, which is not a finding that no fix exists, and point to the CVE's advisory for it: get_cve's references tagged Vendor Advisory or Patch, where it has them.",
         "After the list, give data.summary's counts, and list the undetermined and not_assessed components with their reasons as not checked, never as clean.",
         "Where the note says that rows of data.results are left out of the first text block, list the components its rows carry, say how many affected components the text leaves out (data.summary.affected, less those listed), and give the undetermined and not_assessed components it leaves out as data.summary's counts, by not_assessed_reason, as not checked, never as clean.",
         "",

package/dist/tools/check_affected.js

@@ -89,7 +89,7 @@ const DATA = z.looseObject({
     ecosystem: opt(z.string()),
     ecosystem_recognised: opt(z.boolean()),
     package: opt(z.string()),
-    assessed: opt(z.boolean()).describe("Read first. true: the lookup evaluated this component. false: it did not, and count 0 says nothing about whether this version is affected."),
+    assessed: opt(z.boolean()).describe("count depends on it. true: the lookup evaluated this component. false: it did not, and count 0 says nothing about whether this version is affected."),
     not_assessed_reason: opt(REASON),
     match_layer: opt(z.string()),
     cve_ids: opt(z.array(z.string())),
@@ -126,7 +126,7 @@ const COVERAGE = z.strictObject({
 // Constant strings, so marketing-site lib/mcpToolClaims.test.ts can fold them should it read
 // this file.
 export const CHECK_AFFECTED_TITLE = "Am I affected? (product or package at a version)";
-export const CHECK_AFFECTED_DESCRIPTION = "Whether a product or package at a given version is affected by known CVEs, from the same matcher as echelongraph.io/am-i-affected. Two lookup paths. The CPE path takes product (the NVD CPE product token, such as openssl or nginx) and version, and returns the CVEs whose NVD CPE match criteria name that product with a version range that includes the version; it matches the token across vendors, so each match names the vendor NVD asserts (cpe_vendor) and whether that vendor was verified (vendor_unknown). The registry path takes ecosystem (npm, PyPI, Maven and other OSV ecosystem names), package and version, and decides each OSV advisory record EchelonGraph holds for that package as affected, not affected or undetermined. Read assessed before count: assessed false means the lookup did not evaluate this component, not_assessed_reason says why (product_not_in_cpe_corpus, package_not_cpe_nameable, candidate_load_pending, candidate_window_truncated, package_not_in_advisory_corpus, no_decidable_advisory), the structured result's state is not_assessed, and a count of 0 there must never be reported as not affected. An advisory whose version range cannot be decided at this version is reported as undetermined (undetermined_count, and up to 50 of them in undetermined), never as safe. The answer also carries match_layer (which path answered), capped (the match list stopped at its cap), candidates_capped (not every candidate CVE was loaded), excluded_count (CPE candidates suppressed by the vendor or platform gate), not_affected_count (advisories decided in your favour) and degraded (the lookup ran out of time). Each match carries cve_id, kev_listed, ransomware, epss_score, effective_score, effective_severity and score_assessed (false: EchelonGraph has not scored the CVE yet, so its echelongraph_score is withheld). Product, version, ecosystem and package travel in request headers, never in the URL. Its structured result carries state (measured only when the answer says assessed true), measured_at (null), method (which matcher answered), coverage (assessed and not_assessed_reason first, then the lookup path and the counts above), freshness (null) and notes, with data equal to the API's JSON." +
+export const CHECK_AFFECTED_DESCRIPTION = "Whether a product or package at a given version is affected by known CVEs, from the same matcher as echelongraph.io/am-i-affected. Two lookup paths. The CPE path takes product (the NVD CPE product token, such as openssl or nginx) and version, and returns the CVEs whose NVD CPE match criteria name that product with a version range that includes the version; it matches the token across vendors, so each match names the vendor NVD asserts (cpe_vendor) and whether that vendor was verified (vendor_unknown). The registry path takes ecosystem (npm, PyPI, Maven and other OSV ecosystem names), package and version, and decides each OSV advisory record EchelonGraph holds for that package as affected, not affected or undetermined. count depends on assessed: assessed false means the lookup did not evaluate this component, not_assessed_reason says why (product_not_in_cpe_corpus, package_not_cpe_nameable, candidate_load_pending, candidate_window_truncated, package_not_in_advisory_corpus, no_decidable_advisory), the structured result's state is not_assessed, and a count of 0 there is not a finding of not affected. An advisory whose version range cannot be decided at this version is reported as undetermined (undetermined_count, and up to 50 of them in undetermined), never as safe. The answer also carries match_layer (which path answered), capped (the match list stopped at its cap), candidates_capped (not every candidate CVE was loaded), excluded_count (CPE candidates suppressed by the vendor or platform gate), not_affected_count (advisories decided in your favour) and degraded (the lookup ran out of time). Each match carries cve_id, kev_listed, ransomware, epss_score, effective_score, effective_severity and score_assessed (false: EchelonGraph has not scored the CVE yet, so its echelongraph_score is withheld). Product, version, ecosystem and package travel in request headers, never in the URL. Its structured result carries state (measured only when the answer says assessed true), measured_at (null), method (which matcher answered), coverage (assessed and not_assessed_reason first, then the lookup path and the counts above), freshness (null) and notes, with data equal to the API's JSON." +
     " " +
     TEXT_BUDGET_DESCRIPTION +
     " Cut, the excluded and undetermined samples keep their first 10 entries, each its cve_id and reason, cve_ids keeps its first 10 (each match carries its cve_id), and each match keeps fewer fields, cve_id, kev_listed, ransomware, epss_score, effective_score and score_assessed at least, so that every match stays in the text.";
@@ -172,7 +172,8 @@ function matchesNote(matches) {
 // description and match_reason, so openssl 3.0.0 (71 matches) was 156,058 characters of text and
 // linux_kernel 5.10.0 (200, the API's cap) 364,408. Past DATA_TEXT_BUDGET each match in the first
 // text block keeps its scores, flags, vendor attribution and match_reason (for a registry match,
-// the advisory interval its version falls inside, which names the fixed version) with the
+// the advisory interval its version falls inside: "[A, B)" names the fixed version B, "[A, B]" the
+// last affected one, #2830) with the
 // description cut to 200 characters; then the same without the description; then only the fields
 // the description promises; then, for a list at the cap, without cpe_vendor and vendor_unknown;
 // and last without effective_severity, the band of effective_score. kev_listed, ransomware,

package/dist/tools/check_sbom.js

@@ -63,7 +63,8 @@ export const CHECK_SBOM_DESCRIPTION = "Check a dependency list against EchelonGr
 // a CVE with its description, so the 50-component Juice Shop document was 112,820 characters of
 // text, and 2,000 purls about 1,200,000. Past DATA_TEXT_BUDGET each row in the first text block
 // keeps its verdict, counts and cve_ids, and each match its scores, flags and match_reason (the
-// advisory interval the version falls inside, which names the fixed version) without the
+// advisory interval the version falls inside: "[A, B)" names the fixed version B, "[A, B]" the last
+// affected one, #2830) without the
 // description; then the same without match_reason; then only index, purl, verdict,
 // not_assessed_reason and cve_ids. When rows must still go, the clean ones (not_affected) leave
 // first, then the not_assessed ones, both counted in data.summary and the note, so the affected

package/dist/tools/cve_intel.js

@@ -24,6 +24,15 @@
 // EXPLOIT_NUCLEI_ENABLED, EXPLOIT_POCGITHUB_ENABLED; core-backend cmd/server/main.go). The answer
 // does not say which ran, so no text here says a source is polled: it names the sources the data
 // model holds, and says coverage depends on which pollers run.
+//
+// Fixed versions (#2817). /enrichment keeps one affected_packages row per (CVE, ecosystem,
+// package), and its fixed_version is one range's fix: the last range's as the advisory was read
+// (core-backend cve/backfill_osv_packages.go summariseAffected). For CVE-2021-44228 production
+// served log4j-core 2.12.2 alone (2026-10-04), the fix for 2.4-2.12.1, below an affected 2.14.1.
+// Since #2817 each row also carries fixed_branches, the fix for every range (core-backend
+// cve/fixed_branches.go, from the version_intervals the matcher evaluates): this tool relays it as
+// sent, its description says how to pick the range for an installed version, and the note counts
+// the rows where fixed_version is not the whole answer.
 import * as z from "zod";
 import { ANNOTATIONS, CVE_ID, NOT_A_FINDING, SHOWN_BASE, api, badInput, boolAt, checked, crashed, envelopeSchema, failed, failure, field, numAt, okHead, opt, strAt, succeeded, } from "../index.js";
 import { TEXT_BUDGET_DESCRIPTION } from "../textBudget.js";
@@ -60,7 +69,8 @@ const API_ROW_LIMIT = { exploits: 10, affected_packages: 50, fixed_versions: 200
 const TIMELINE_RELAYED = 20;
 const CVE_INTEL_METHOD = "EchelonGraph's per-CVE enrichment (GET /api/v1/public/cves/:id/enrichment). cwes: CWE classifications stored from NVD, GitHub (GHSA) and CVE.org records, each with the source that gave it, named from the MITRE CWE catalog EchelonGraph embeds. exploits: public exploit references from EchelonGraph's cve_exploits records, whose data model holds Metasploit modules (metasploit), Exploit-DB entries (exploit_db), nuclei templates (nuclei_template), GitHub proof-of-concept repositories (github_poc) and vendor proofs of concept (vendor_poc), filled by a curated seed and by one poller per automated source, each run only where it is enabled, so which sources are current depends on the deployment. affected_packages and fixed_versions: package-ecosystem advisory data, each row naming its source. timeline: EchelonGraph's enrichment history for the CVE, newest first.";
 const VERIFIED_STATUS_DESCRIPTION = "verified_status is the label stored with each reference: verified for a Metasploit module, for an Exploit-DB entry Exploit-DB marks verified, and for curated seed rows marked so; reported for a public artefact nothing has confirmed works (nuclei templates, GitHub proofs of concept, unverified Exploit-DB entries); unconfirmed where a curated row says so. It is a label from the source, not a guarantee that the exploit works against a given system.";
-export const CVE_INTEL_DESCRIPTION = `Weakness, public exploit code, affected packages and fixed versions for one CVE, from EchelonGraph's per-CVE enrichment. Returns cwes (each cwe_id with its name and source), exploits (each with kind, source_name, source_url, first_seen_at and verified_status; at most 10, verified first) with exploits_total (every reference on record), exploits_capped (true when exploits lists fewer than exploits_total), exploits_by_kind and exploits_by_status, affected_packages (ecosystem, package_name, version_range, fixed_version), fixed_versions (ecosystem, package_name, vulnerable_range, fixed_version) and timeline (the newest enrichment-history rows, with timeline_total). ${VERIFIED_STATUS_DESCRIPTION} An empty exploits list is not evidence that no public exploit exists: it covers only the sources EchelonGraph ingests, and which of them are polled depends on the deployment. A section the API could not read is named in coverage.sections_failed and left out of data, never relayed as an empty list. Vendor advisories, patches, generated summaries, trending signals and historical incidents are not relayed. Pass a CVE ID like CVE-2021-44228. Its structured result carries state (measured), measured_at (null: each row carries its own time), method, coverage (the sections relayed, failed and left out, and per-list counts), freshness (null) and notes, with data, which the first text block holds whole up to 30,000 characters; the result's last text block repeats it without data and without the note's sentences (the text block before it), with which notes ends. ${TEXT_BUDGET_DESCRIPTION}`;
+const FIXED_BRANCHES_DESCRIPTION = 'fixed_branches lists each affected range of the package on record: introduced, and fixed (the range\'s fix) or last_affected (its last affected version, where no fix is on record), each null when absent, with advisory_id (the OSV record that published the range) and source (the loader\'s label for that record), both null on a row loaded before they were stored. Ranges with an advisory_id are in the order their record lists them (records in id order); ranges without one are oldest first. To pick the range for an installed version, compare in the ecosystem\'s version order (release numbers part by part, as numbers: 2.4 is below 2.13.0): the version is in a range when it is at or above introduced ("0" is the first version) and below fixed, or at or below last_affected; that range\'s fixed is the fix for it, and a version in no range is outside every range on record. fixed_branches is null where the package\'s ranges were never loaded, and [] where no version range is on record (the advisory gives none, only commit ranges, or more than are stored), which is not a finding that no fix exists: fixed_version can still name one. fixed_version is one range\'s fix, kept for compatibility (one per package: the range the loader kept, the advisory\'s last as a rule), not the fix for every affected range: for CVE-2021-44228, its advisory gives log4j-core three ranges, and fixed_version 2.12.2 is the fix for the one from 2.4, while the range holding 2.14.1 (from 2.13.0) is fixed in 2.15.0.';
+export const CVE_INTEL_DESCRIPTION = `Weakness, public exploit code, affected packages and fixed versions for one CVE, from EchelonGraph's per-CVE enrichment. Returns cwes (each cwe_id with its name and source), exploits (each with kind, source_name, source_url, first_seen_at and verified_status; at most 10, verified first) with exploits_total (every reference on record), exploits_capped (true when exploits lists fewer than exploits_total), exploits_by_kind and exploits_by_status, affected_packages (ecosystem, package_name, version_range, fixed_version, fixed_branches), fixed_versions (ecosystem, package_name, vulnerable_range, fixed_version: one row per fixed version, with the vulnerable_range it fixes where the source gives one) and timeline (the newest enrichment-history rows, with timeline_total). ${FIXED_BRANCHES_DESCRIPTION} ${VERIFIED_STATUS_DESCRIPTION} An empty exploits list is not evidence that no public exploit exists: it covers only the sources EchelonGraph ingests, and which of them are polled depends on the deployment. A section the API could not read is named in coverage.sections_failed and left out of data, never relayed as an empty list. Vendor advisories, patches, generated summaries, trending signals and historical incidents are not relayed. Pass a CVE ID like CVE-2021-44228. Its structured result carries state (measured), measured_at (null: each row carries its own time), method, coverage (the sections relayed, failed and left out, and per-list counts), freshness (null) and notes, with data, which the first text block holds whole up to 30,000 characters; the result's last text block repeats it without data and without the note's sentences (the text block before it), with which notes ends. ${TEXT_BUDGET_DESCRIPTION}`;
 // ── outputSchema ──
 const Rows = (shape) => z.array(z.looseObject(shape));
 const CountMap = z.record(z.string(), z.number());
@@ -88,7 +98,18 @@ function schemas() {
             ecosystem: opt(z.string()),
             package_name: opt(z.string()),
             version_range: opt(z.string()),
-            fixed_version: opt(z.string()),
+            fixed_version: opt(z.string()).describe("One range's fix, kept for compatibility; not the fix for every affected range: read fixed_branches."),
+            fixed_branches: z
+                .array(z.looseObject({
+                introduced: opt(z.string()).describe('The range\'s lower bound, inclusive; "0" is the first version.'),
+                fixed: opt(z.string()).describe("The range's fix: the first version past it. null where no fix is on record."),
+                last_affected: opt(z.string()).describe("The range's last affected version, inclusive, where no fix is on record; never a fix."),
+                advisory_id: opt(z.string()).describe("The OSV record that published the range (GHSA-…, PYSEC-…, CVE-…); null on a row loaded before it was stored."),
+                source: opt(z.string()).describe("The loader's label for that record (osv_bulk, osv); null on a row loaded before it was stored."),
+            }))
+                .nullable()
+                .optional()
+                .describe(FIXED_BRANCHES_DESCRIPTION),
             dependents_count: opt(z.number()),
             source: opt(z.string()),
         }).optional(),
@@ -170,6 +191,50 @@ function listSentence(name, rows) {
     const cut = rows.length >= limit ? `, the most the API returns per CVE, so there may be more` : "";
     return `${name} lists ${rows.length} row${rows.length === 1 ? "" : "s"}${cut}.`;
 }
+// #2817: where fixed_version is not the whole answer. A row with more than one range in
+// fixed_branches has a fix per range; a row with fixed_branches null has only fixed_version on
+// record, and so does a row with fixed_branches [] and a fixed_version (no version range on
+// record: none in the advisory, only commit ranges, or more than core-backend stores); an answer
+// whose rows carry no fixed_branches is an API older than #2817.
+function branchSentences(rows) {
+    if (rows.length === 0)
+        return [];
+    const named = (r, i) => {
+        const eco = strAt(r, "ecosystem");
+        const pkg = strAt(r, "package_name") ?? `affected_packages[${i}]`;
+        return eco ? `${pkg} (${eco})` : pkg;
+    };
+    const withField = rows.filter((r) => field(r, "fixed_branches") !== undefined);
+    if (withField.length === 0) {
+        return [
+            "No affected_packages row carries fixed_branches (an API older than that field): each row's fixed_version is one range's fix, which need not be the fix for a given installed version.",
+        ];
+    }
+    const out = [];
+    const multi = [];
+    const unknown = [];
+    const noRange = [];
+    rows.forEach((r, i) => {
+        const fb = field(r, "fixed_branches");
+        if (Array.isArray(fb) && fb.length > 1)
+            multi.push(named(r, i));
+        if (fb === null)
+            unknown.push(named(r, i));
+        if (Array.isArray(fb) && fb.length === 0 && strAt(r, "fixed_version"))
+            noRange.push(named(r, i));
+    });
+    const few = (xs) => (xs.length <= 3 ? listed(xs) : `${xs.slice(0, 3).join(", ")} and ${xs.length - 3} more`);
+    if (multi.length) {
+        out.push(`${multi.length} affected_packages row${multi.length === 1 ? " lists" : "s list"} more than one affected range in fixed_branches (${few(multi)}): there, fixed_version is one range's fix, and an installed version's fix is the fixed of the range that holds it.`);
+    }
+    if (unknown.length) {
+        out.push(`${unknown.length} affected_packages row${unknown.length === 1 ? " carries" : "s carry"} fixed_branches null (${few(unknown)}): ${unknown.length === 1 ? "its" : "their"} ranges are not on record, so fixed_version, one range's fix, is all the answer holds, and it need not be the fix for a given installed version.`);
+    }
+    if (noRange.length) {
+        out.push(`${noRange.length} affected_packages row${noRange.length === 1 ? " carries" : "s carry"} fixed_branches [] and a fixed_version (${few(noRange)}): no version range is on record there, which is not a finding that no fix exists, so fixed_version, one range's fix, is all the answer holds, and it need not be the fix for a given installed version.`);
+    }
+    return out;
+}
 // ── The tool ──
 export async function cveIntel(cve_id) {
     const id = cve_id.trim();
@@ -218,6 +283,8 @@ export async function cveIntel(cve_id) {
             const xs = rows(k);
             if (xs)
                 said.push(listSentence(k, xs));
+            if (xs && k === "affected_packages")
+                said.push(...branchSentences(xs));
         }
         const timeline = rows("timeline");
         const apiTimeline = field(d, "timeline");

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. 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. ${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 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}`;
 // 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.

package/dist/tools/vendor_advisories.js

@@ -36,11 +36,21 @@
 // CVE-2024-21412, which both vendors did publish advisories for. core-backend now reads those
 // histories back (vendoradv backfill.go) and serves each vendor's window at
 // /api/v1/public/vendor-advisories/coverage (coverage.go): advisories held, the earliest and latest
-// vendor_published_at among them, and history_backfill. All three tools read it beside their own
-// request and relay it in coverage, and the note says when a CVE's ID year begins before a
-// vendor's earliest held advisory, or a vendor's history is still being read, so an empty answer
-// is never read as "the vendor published none". The window is context, not the answer: when it
-// cannot be read (an API older than the route, a failure), the answer is relayed as before, with
+// vendor_published_at among them, held_since and history_backfill. All three tools read it beside
+// their own request and relay it in coverage, and the note says when a CVE's ID year begins before
+// the date a vendor is held from, or a vendor's history is still being read, so an empty answer
+// is never read as "the vendor published none".
+//
+// held_since, not the earliest held advisory, is where a vendor's window begins (#2803). A vendor
+// with no history read (history_backfill not_supported) is held from its poller's first poll on,
+// and Cisco's and Red Hat's first polls read only what the vendor had CHANGED lately: an old
+// advisory the vendor revised since is held, so the earliest held advisory reached back to 2024
+// for Cisco and 2009 for Red Hat while the advisories published beside it are not held, and
+// CVE-2025-20188 read Cisco as fully held for 2025. coverage.go serves held_since as the start of
+// the window EchelonGraph has read the vendor's advisories from; an API older than that field gives none, and a vendor is
+// then taken as held from its earliest advisory only when its history read is complete.
+//
+// The window is context, not the answer: when it cannot be read (an API older than the route, a failure), the answer is relayed as before, with
 // the windows null and a note saying they are unknown, never failed. The coverage request carries
 // nothing typed: a fixed path, no query, no search header.
 //
@@ -113,6 +123,7 @@ function windowsOf(d) {
                 advisories: num(r, "advisories") ?? null,
                 earliest_vendor_published_at: instantOrNull(r, "earliest_vendor_published_at"),
                 latest_vendor_published_at: instantOrNull(r, "latest_vendor_published_at"),
+                held_since: instantOrNull(r, "held_since"),
                 history_backfill: str(r, "history_backfill") ?? null,
             },
         ];
@@ -120,30 +131,48 @@ function windowsOf(d) {
 }
 const day = (instant) => instant.slice(0, 10);
 const backfilling = (w) => w.history_backfill !== null && BACKFILLING.has(w.history_backfill);
+// #2803: the start of the window a vendor's advisories have been read from: held_since as the API
+// gives it; from an API without it, the earliest held advisory when the vendor's history read is
+// complete (that is the archive's start), else unknown (null).
+const heldFrom = (w) => w.held_since ?? (w.history_backfill === "complete" ? w.earliest_vendor_published_at : null);
+// Whether a vendor's window starts on or before 1 January of a CVE ID's year.
+const heldFromYear = (w, yearStart) => {
+    const from = heldFrom(w);
+    return from !== null && Date.parse(from) <= yearStart;
+};
 // What a note says of one window: what is held, and the history read when it is not done.
 const windowItem = (w, heldOnly) => {
+    const from = heldFrom(w);
+    const to = w.latest_vendor_published_at ? ` to ${day(w.latest_vendor_published_at)}` : "";
     const held = w.earliest_vendor_published_at === null
         ? "none held"
-        : `held ${heldOnly ? "only " : ""}from ${day(w.earliest_vendor_published_at)}${w.latest_vendor_published_at ? ` to ${day(w.latest_vendor_published_at)}` : ""}`;
+        : from === null
+            ? `held from ${day(w.earliest_vendor_published_at)}${to}, not known to be without a gap`
+            : `held ${heldOnly ? "only " : ""}from ${day(from)}${to}${day(w.earliest_vendor_published_at) < day(from) ? `, and before that only in part, the earliest held dated ${day(w.earliest_vendor_published_at)}` : ""}`;
     return `${w.vendor} (${held}${backfilling(w) ? `; history_backfill ${w.history_backfill}` : ""})`;
 };
 // The sentence for windows that could not be read: no "none here" is a finding about a vendor.
 const windowsUnknown = (why) => ` The vendors' coverage windows could not be read (${why}), so this answer cannot say from what date each vendor's advisories are held: no advisory here from a vendor is not a finding that it published none.`;
 // vendor_advisories_for_cve: the vendors with no advisory in the answer that may have published
-// one EchelonGraph does not hold: none held at all, the earliest held dated after 1 January of the
-// year in the CVE ID, or a history still being read.
+// one EchelonGraph does not hold: none held at all, held (held_since) only from after 1 January of
+// the year in the CVE ID or from a date not known, or a history still being read. Never the
+// earliest held advisory: for a vendor with no history read it can be years before held_since
+// (#2803).
 function notFullyHeld(windows, rows, year) {
     const answered = new Set(rows.map((r) => str(r, "vendor")).filter((v) => v !== undefined));
     const yearStart = Date.UTC(year, 0, 1);
-    return windows.filter((w) => !answered.has(w.vendor) && (w.earliest_vendor_published_at === null || Date.parse(w.earliest_vendor_published_at) > yearStart || backfilling(w)));
+    return windows.filter((w) => !answered.has(w.vendor) && (w.earliest_vendor_published_at === null || !heldFromYear(w, yearStart) || backfilling(w)));
 }
 function notFullyHeldNote(cve, year, missing) {
     if (!missing.length)
         return "";
     const k = missing.length;
     const yearStart = Date.UTC(year, 0, 1);
-    const items = missing.map((w) => windowItem(w, w.earliest_vendor_published_at !== null && Date.parse(w.earliest_vendor_published_at) > yearStart));
-    return ` ${cve} is a ${year} CVE ID, and EchelonGraph may not hold every advisory ${plural(k, "1 vendor", `${k} vendors`)} published for it (vendors_not_fully_held): ${items.join("; ")}. An advisory a vendor published before the earliest one EchelonGraph holds is not held, and while history_backfill is in_progress or not_started the vendor's older advisories are still being read, so no advisory here from ${plural(k, "that vendor", "those vendors")} is not a finding that ${plural(k, "it", "they")} published none.`;
+    const items = missing.map((w) => {
+        const from = heldFrom(w);
+        return windowItem(w, from !== null && Date.parse(from) > yearStart);
+    });
+    return ` ${cve} is a ${year} CVE ID, and EchelonGraph may not hold every advisory ${plural(k, "1 vendor", `${k} vendors`)} published for it (vendors_not_fully_held): ${items.join("; ")}. An advisory a vendor published before the date EchelonGraph holds that vendor from (held_since) may not be held, even when an older one is, and while history_backfill is in_progress or not_started the vendor's older advisories are still being read, so no advisory here from ${plural(k, "that vendor", "those vendors")} is not a finding that ${plural(k, "it", "they")} published none.`;
 }
 // search_vendor_advisories and get_vendor_advisory: the vendors whose history is still being read.
 function backfillingNote(windows) {
@@ -158,7 +187,7 @@ 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."),
+    withdrawn: opt(z.boolean()).describe("true: the vendor withdrew (rescinded) this advisory, so it is a withdrawn advisory, not a current one."),
 };
 const AdvisoryRow = z.looseObject({
     advisory_id: opt(z.string()),
@@ -179,8 +208,10 @@ const DATES_DESCRIPTION = "Each advisory carries vendor_published_at (the vendor
 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.";
 // #2729: what a vendor's window is.
 const HISTORY_BACKFILL_DESCRIPTION = "history_backfill: complete (the vendor's published history has been read back as far as its source goes), in_progress or not_started (it is still being read, so the vendor's older advisories are not all held yet), or not_supported (EchelonGraph has no history read for that vendor, so what it holds is what the vendor's feed has carried)";
-const WINDOW_DESCRIPTION = `vendor, advisories (how many EchelonGraph holds from that vendor), earliest_vendor_published_at and latest_vendor_published_at (the earliest and latest vendor_published_at among them, null when none is held) and ${HISTORY_BACKFILL_DESCRIPTION}`;
-const NOT_HELD_DESCRIPTION = "An advisory a vendor published before its earliest_vendor_published_at is not held, so no advisory from a vendor is not a finding that it published none.";
+// #2803: where a vendor's window begins.
+const HELD_SINCE_DESCRIPTION = "held_since (the start of the window EchelonGraph has read that vendor's advisories from, before which an advisory may not be held; null when none is held or the API does not say; for a vendor with no history read it is when its feed was first read from, and can be years after earliest_vendor_published_at, since an older advisory is held when the vendor revised it later, not the ones published beside it)";
+const WINDOW_DESCRIPTION = `vendor, advisories (how many EchelonGraph holds from that vendor), earliest_vendor_published_at and latest_vendor_published_at (the earliest and latest vendor_published_at among them, null when none is held), ${HELD_SINCE_DESCRIPTION} and ${HISTORY_BACKFILL_DESCRIPTION}`;
+const NOT_HELD_DESCRIPTION = "An advisory a vendor published before its held_since may not be held, even when its earliest_vendor_published_at is older, so no advisory from a vendor is not a finding that it published none.";
 // #2728: how a search matches, and its capped total.
 const SEARCH_MATCH_DESCRIPTION = "A query of 3 or more characters is matched case-insensitively as a substring of each advisory's title, description, vendor name, vendor_advisory_id, affected_products and cve_ids (search_match substring). A query of 1 or 2 characters matches whole words only (search_match word): it must equal, ignoring case, a whole word (a run of letters and digits) of one of those, so xz finds xz-utils but not xzibit, and a 1- or 2-character query with any other character, such as c#, matches nothing.";
 const TOTAL_CAPPED_DESCRIPTION = "A search counts at most 1,000 matches: past that, total is 1000 and total_capped is true, which means 1,000 or more (the note writes 1,000+), never exactly 1,000; paging past it still works. Without a query, total is the exact count and total_capped is false.";
@@ -191,8 +222,12 @@ const VendorWindowSchema = z.strictObject({
     earliest_vendor_published_at: z
         .string()
         .nullable()
-        .describe("The earliest vendor_published_at among them; null when none is held. An advisory this vendor published before it is not held."),
+        .describe("The earliest vendor_published_at among them; null when none is held. Not where the window begins: see held_since."),
     latest_vendor_published_at: z.string().nullable().describe("The latest vendor_published_at among them; null when none is held."),
+    held_since: z
+        .string()
+        .nullable()
+        .describe("The start of the window EchelonGraph has read this vendor's advisories from; null when none is held or the API does not say. An advisory this vendor published before it may not be held, even when earliest_vendor_published_at is older."),
     // The four values the API sends today, and any later one as a string: a new state must not turn
     // the answer into a failure.
     history_backfill: z
@@ -233,7 +268,7 @@ export function registerVendorAdvisoryTools(server, kit) {
             vendors_not_fully_held: z
                 .array(z.string())
                 .nullable()
-                .describe("The vendors with no advisory in this answer that may have published one EchelonGraph does not hold: none held, the earliest held dated after 1 January of cve_year, or history_backfill in_progress or not_started. No advisory from them is not a finding that they published none. null when the windows could not be read."),
+                .describe("The vendors with no advisory in this answer that may have published one EchelonGraph does not hold: none held, held_since after 1 January of cve_year or not known, or history_backfill in_progress or not_started. No advisory from them is not a finding that they published none. null when the windows could not be read."),
         }),
         freshness: null,
     });
@@ -473,14 +508,14 @@ export function registerVendorAdvisoryTools(server, kit) {
     }
     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 that none of the advisories EchelonGraph holds from those feeds names the CVE, not that no vendor published one (see vendor_windows and vendors_not_fully_held). ${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); cve_year, the year in the CVE ID; vendor_windows, each vendor's window in what EchelonGraph holds: ${WINDOW_DESCRIPTION}; and vendors_not_fully_held, the vendors with no advisory in the answer of which EchelonGraph holds none, whose earliest held advisory is dated after 1 January of cve_year, or whose history is still being read, which the note names. ${NOT_HELD_DESCRIPTION} vendor_windows and vendors_not_fully_held are null when the windows could not be read, and the note says so. measured_at is null. ${ENVELOPE_DESCRIPTION} ${TEXT_BUDGET_DESCRIPTION}${ROW_CUT_DESCRIPTION}.`,
+        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 that none of the advisories EchelonGraph holds from those feeds names the CVE, not that no vendor published one (see vendor_windows and vendors_not_fully_held). ${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); cve_year, the year in the CVE ID; vendor_windows, each vendor's window in what EchelonGraph holds: ${WINDOW_DESCRIPTION}; and vendors_not_fully_held, the vendors with no advisory in the answer of which EchelonGraph holds none, whose held_since is after 1 January of cve_year or not known, or whose history is still being read, which the note names. ${NOT_HELD_DESCRIPTION} vendor_windows and vendors_not_fully_held are null when the windows could not be read, and the note says so. measured_at is null. ${ENVELOPE_DESCRIPTION} ${TEXT_BUDGET_DESCRIPTION}${ROW_CUT_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} coverage.vendor_window is that vendor's window in what EchelonGraph holds: ${WINDOW_DESCRIPTION}; null when the windows could not be read or carry none for that vendor. measured_at is our_first_seen_at. ${ENVELOPE_DESCRIPTION} ${TEXT_BUDGET_DESCRIPTION}`,
+        description: `One vendor advisory in full, by vendor and the vendor's advisory ID (the vendor and vendor_advisory_id of a vendor advisory row): 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} coverage.vendor_window is that vendor's window in what EchelonGraph holds: ${WINDOW_DESCRIPTION}; null when the windows could not be read or carry none for that vendor. measured_at is our_first_seen_at. ${ENVELOPE_DESCRIPTION} ${TEXT_BUDGET_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"),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "echelongraph-mcp",
-  "version": "2.6.5",
+  "version": "2.6.7",
   "mcpName": "io.echelongraph/echelongraph-mcp",
   "description": "MCP server for CVE lookups: EchelonGraph scores, CISA KEV, EPSS, CWE, exploits, version and SBOM checks, vendor advisories, and per-CVE exposure derived from Shodan data. Shodan data is owned by Shodan, which holds its copyright (© Shodan). Keyless.",
   "type": "module",

package/server.json

@@ -17,7 +17,7 @@
       ]
     }
   ],
-  "version": "2.6.5",
+  "version": "2.6.7",
   "remotes": [
     {
       "type": "streamable-http",
@@ -28,7 +28,7 @@
     {
       "registryType": "npm",
       "identifier": "echelongraph-mcp",
-      "version": "2.6.5",
+      "version": "2.6.7",
       "transport": {
         "type": "stdio"
       },