echelongraph-mcp 1.0.3 → 2.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 EchelonGraph
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -19,9 +19,9 @@ API call a tool needs to answer.
 |---|---|
 | `cve_summary` | Counts of active CVEs by severity, and when the feed was last updated. |
 | `search_cves` | Search/filter CVEs (severity, min CVSS, text, sort) with EchelonGraph scores. |
-| `get_cve` | Full detail for one CVE (CVSS v3/v4, EG score, EPSS, KEV+ransomware, GHSA, CWE, references). |
+| `get_cve` | Full record for one CVE: CVSS v3 and (when scored) v4, the EchelonGraph score and its confidence, EPSS, CISA-KEV status and known ransomware use, the GitHub GHSA id, references, and its published, modified and `updated_at` times. |
 | `cve_exposure` | Internet-exposure footprint for a CVE: exposed service count (distinct ip:port, the `exposed_hosts` field) + country/product breakdown, from the KEV-exposure radar. |
-| `exposure_radar` | Aggregate totals across the exposure radars: shadow AI; services running CISA-KEV CVEs; 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, which is not a pure read (on Redis it names its client; on ClickHouse its query lands in the server's query log); leaked credentials. |
+| `exposure_radar` | Aggregate totals across the exposure radars: services running CISA-KEV CVEs; 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, which is not a pure read (on Redis it names its client; on ClickHouse its query lands in the server's query log); leaked credentials; shadow AI. Every number is labelled by what it counts, and a field the tool cannot label is left out and named. |
 
 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.
@@ -40,8 +40,9 @@ Shodan InternetDB refreshes `last_seen` without re-reading the banner, so a patc
 stay counted while its port stays open.
 
 The unit is a service, not a machine. Shodan returns one banner per port and the radar keys
-each observation on ip:port, so a machine answering on two ports counts twice. The API field
-keeps its name, `exposed_hosts`, and so does `distinct_hosts` in the radar totals.
+each observation on ip:port, so a machine answering on two ports counts twice. The API's field
+names are kept (`exposed_hosts` here; `distinct_hosts`, `ransomware_hosts` and each ranked
+row's count in `exposure_radar`), but every one of them counts ip:port services.
 
 The radar only looks for its **tracked** set of CVEs, so a zero means different things:
 
@@ -52,7 +53,79 @@ The radar only looks for its **tracked** set of CVEs, so a zero means different
 | no `tracked` field | The API did not say whether the CVE is in the tracked set: an older API, or the radar cannot decide (for example a CISA-KEV or high-EPSS CVE in a tracked product with 0 services on record). 0 exposed services on record, with no claim either way. |
 | HTTP 400, or an id that is not `CVE-YYYY-NNNN…` | An error result tagged `invalid_input`; nothing was looked up. |
 
-### How `exposure_radar` counts shadow AI
+### How `exposure_radar` counts
+
+`exposure_radar` relays each radar's answer cut to the fields it can label, and its note labels
+every number by what it counts. A field this version does not know is left out and the note
+names it, whether it is a total or a field inside a ranked row; so is a known field in an
+unexpected shape, and a list with one malformed row is left out whole, since a partial list
+reads as a complete one. `kev_exposure`, `exposed_databases` and `leaked_credentials` also
+carry `generated_at`, when the API computed their totals, and, when the API can tell,
+`last_run_at`: when that radar last completed a check (each table below says what a completed
+check is for that radar).
+
+`last_run_at` is a timestamp, not a count. It is recorded for the radar as a whole, not for
+the server instance that answered, in UTC to the second. It moves only at the end of a cycle
+whose reads succeeded, so a cycle that read nothing leaves it where it was. It is not the time
+of every record a radar's numbers count: those cover everything still on record, not only what
+the last check found. Nor is it `generated_at`, which is only when the API recomputed the
+totals. The API omits `last_run_at` when it has no completed check on record or cannot read
+it; the result then carries none, and the note says nothing about it. When it is there, the
+note gives it as, for example, "kev_exposure last completed check: 2026-09-27T03:12:44Z".
+
+#### `kev_exposure`
+
+Every count is over the services the KEV-exposure radar keeps: a Shodan banner whose version
+maps to a CISA-KEV-listed CVE (see "How `cve_exposure` counts").
+
+| Field | What it counts |
+|---|---|
+| `kev_exposure.distinct_hosts` | Distinct ip:port services, not machines, with at least one CISA-KEV-listed CVE on record. A machine answering on two ports counts twice. |
+| `kev_exposure.ransomware_hosts` | The services among them with at least one ransomware-linked KEV CVE (one whose KEV entry notes known use in ransomware campaigns). |
+| `kev_exposure.kev_cves_exposed` | Distinct CISA-KEV-listed CVEs with at least one service on record. |
+| `kev_exposure.ransomware_cves` | The ransomware-linked CVEs among them. |
+| `kev_exposure.correlations` | Service×CVE pairs, not services: a service with three KEV CVEs counts three times. |
+| `kev_exposure.top_products`, `kev_exposure.top_countries`, `kev_exposure.top_cves` | Up to 12 products, 10 countries and 12 CVEs, ranked by distinct ip:port services. |
+| `kev_exposure.top_cves[].cvss_v3_score`, `kev_exposure.top_cves[].epss_score` | Scores, not counts: the highest CVSS v3 base score and EPSS probability (0 to 1) recorded on that CVE's observations. |
+| `kev_exposure.trend` | Service×CVE pairs, not services, by the week (starting Monday) in which each pair was first recorded, over the last 12 weeks. Only pairs still on record are counted, so earlier weeks read low. |
+| `kev_exposure.newest_kev` | The 15 CVEs that EchelonGraph's CVE records most recently mark as CISA-KEV-listed (by `added_date`), each with an `exposure_state` (below). |
+| `kev_exposure.newest_kev[].exposed_hosts` | Only on a row whose `exposure_state` is `exposed` (or `measured_zero`): distinct ip:port services on record with that CVE. |
+| `kev_exposure.newest_kev[].cvss_v3_score`, `kev_exposure.newest_kev[].epss_score` | Scores, not counts: the CVE record's CVSS v3 base score and EPSS probability (0 to 1), absent when the record has none. |
+| `kev_exposure.last_run_at` | A timestamp, not a count: when the radar last completed a check, a cycle in which its Shodan search answered at least one query (others may have failed) and its list of services due for a re-check was read. A cycle that skipped the search for want of Shodan query credits, or whose reads failed, does not move it. |
+
+A `newest_kev` row's `exposure_state` says whether its count is a measurement:
+
+| `exposure_state` | What it means |
+|---|---|
+| `exposed` | The radar has services on record with this CVE, and `exposed_hosts` counts them. |
+| `not_assessed` | **NOT ASSESSED**: the answer holds no measurement for this CVE, so no count is relayed. The API answers 0 for every CVE the radar holds no service for, whether or not the radar looks for that CVE at all, and it never marks a CVE as tracked with 0 services, so that 0 is not a measurement. `cve_exposure` says per CVE whether it is in the radar's tracked set. |
+| `measured_zero` | Only if the API ever marks a row `tracked: true` with 0 services: a zero in the radar's sample, not an internet-wide zero. If it marks a row `tracked: false`, that row is `not_assessed` whatever its count. |
+
+#### `exposed_databases`
+
+| Field | What it counts |
+|---|---|
+| `exposed_databases.distinct_hosts` | Distinct ip:port services, not machines, that EchelonGraph's check confirmed answering without authentication: data stores and observability UIs alike. |
+| `exposed_databases.engines` | Distinct engine types among them (for example `redis` or `grafana`). |
+| `exposed_databases.top_engines`, `exposed_databases.top_countries` | Up to 15 engines and 10 countries, ranked by those services. |
+| `exposed_databases.pii_likely`, `exposed_databases.pci_likely` | Services whose schema names pass a high-confidence gate for personal data, or for payment-card data. The names are index, database, table or field names in the Shodan or LeakIX banner or in the check's response, never record values; the gate passes one unambiguous term (such as `ssn` or `cardholder`) or two distinct indicators. It is a precision-first schema gate, not a census: a service whose names do not pass it is not counted, whatever it holds, so the other services are not shown to hold no such data. |
+| `exposed_databases.last_run_at` | A timestamp, not a count: when the radar last completed a check, a cycle in which its Shodan search, or the LeakIX fallback, answered at least one query (others may have failed), its list of services due for a re-check was read, and the scan opt-out register could be consulted. A cycle that searched nothing, or whose reads failed, does not move it. |
+
+#### `leaked_credentials`
+
+| Field | What it counts |
+|---|---|
+| `leaked_credentials.total` | (repository, secret) pairs, not distinct secrets: a secret committed to three repositories counts three times. |
+| `leaked_credentials.distinct_secrets` | Each secret once. |
+| `leaked_credentials.distinct_repos` | Public GitHub repositories with at least one. |
+| `leaked_credentials.top_providers`, `leaked_credentials.top_types` | Up to 15 providers and secret types, ranked by (repository, secret) pairs. |
+| `leaked_credentials.last_run_at` | A timestamp, not a count: when the radar last completed a check, a cycle that read the public GitHub event stream (fetches of some of the commits it lists may have failed). A cycle whose read of that stream failed does not move it. |
+
+None of them is validated. Each is a credential-shaped string in a public commit that passed
+EchelonGraph's filters, at most structurally checked (a checksum or format decode), and never
+tested against its provider, so none of these is a count of working credentials.
+
+#### `shadow_ai`
 
 The shadow-AI radar's answer mixes numbers that count exposed services with numbers that count
 every observation. So `exposure_radar` regroups it by what each number counts, and its note
@@ -78,7 +151,7 @@ yet verified, whose hostname no longer resolves, or whose service no longer answ
 
 The tool relays no number it cannot label. A stats field this version does not know is left
 out, and the note names it; so is a count in an unexpected shape. A ranked row carries only
-its name and its count.
+its name and its count, and a field added to one is named too.
 
 ## What a result means
 
@@ -89,8 +162,9 @@ outage for an all-clear:
   note saying the call succeeded, which base URL answered, and what it found. When the
   feed genuinely holds nothing for the query the note says so in words ("we looked and
   found nothing … not a lookup failure"), because a measured zero is a measurement. The
-  exception to verbatim is `exposure_radar`'s `shadow_ai`: its counts are regrouped as above,
-  and its `poller` block carries only `running` and `last_run_at`, or is dropped when it
+  exception to verbatim is `exposure_radar`: each radar is cut to the fields listed above, and
+  each `kev_exposure.newest_kev` row gains an `exposure_state`. Its `shadow_ai` counts are
+  regrouped as above, and its `poller` block carries only `running` and `last_run_at`, or is dropped when it
   carries no real completion time. The block's other fields describe the server instance that
   answered, not the radar. Its `last_run_at` is when the radar's leader last
   completed a Certificate Transparency (crt.sh) cycle, and its `running` is true only when
@@ -107,9 +181,87 @@ outage for an all-clear:
   cause (status code or error kind), the path, and the base URL, and says it is not a
   finding. A failure is never rendered as a success with null fields.
 
+Both shapes also carry a structured result, below. The text blocks are the same as in 1.x, so
+a client that reads only `content` sees what it always saw.
+
+## Structured results
+
+Since 2.0.0 every result, success or failure, carries `structuredContent`, and every tool
+declares its shape as an `outputSchema` in `tools/list`, with a title and the annotations
+`readOnlyHint: true`, `destructiveHint: false`, `idempotentHint: true` and
+`openWorldHint: true` (hints, which a client treats as untrusted).
+
+| Field | What it holds |
+|---|---|
+| `state` | `measured`, `not_assessed`, `failed` or `invalid_input` (below). |
+| `measured_at` | When the underlying observation was made, as the API states it. `null` when the answer does not say or holds no observation; never the Go zero time. |
+| `method` | How the numbers were produced. `null` on a failure. |
+| `coverage` | What the answer covers, where the tool can say: `in_scope` for `cve_exposure`, the list's own account of its count for `search_cves`, and the radars that answered for `exposure_radar`. |
+| `freshness` | The producing radar's last completed check (`last_run_at`), where the API serves one; `null` where it serves none. |
+| `notes` | The caveats, one sentence each: what the envelope itself needs saying, then the note from the text block. |
+| `data` | On a success only: the same JSON as the first text block. |
+| `error` | On a failure only: `kind`, `path`, `status` and `message`. |
+
+| `state` | What it means |
+|---|---|
+| `measured` | A measurement of what was asked. An exposure count is `measured` only when the answer dates it (`measured_at`) and says how it was produced (`method`). |
+| `not_assessed` | The answer holds no dated measurement of what was asked, so no number in it is a finding: the radar does not look for this CVE, the answer does not say whether it does, or the answer does not say when what it counts was observed. |
+| `failed` | The lookup did not complete. Not a finding. |
+| `invalid_input` | The input was refused, by this server or by the API, so nothing was looked up. Not a finding. |
+
+Every field comes from what the API sends; where the API does not say, the field is `null` and
+a note says so. Per tool:
+
+- `cve_summary` is `measured`, and its `measured_at` is `summary.last_updated`, the newest
+  modification time among the active CVE records it counts.
+- `search_cves` is `measured`, with `measured_at` `null`: each record carries its own times. Its
+  `coverage` repeats the list's `total`, `total_counted`, `total_is_lower_bound`,
+  `search_relaxed`, `limit` and `offset`, and adds `returned`, the rows in the page. When
+  `total_counted` is false the total is not a count, and the note does not call it one.
+- `get_cve` is `measured`, and its `measured_at` is the record's `updated_at`, when EchelonGraph
+  last wrote it.
+- `cve_exposure` is `measured` only for services on record with a real `last_seen`, which is its
+  `measured_at`. Every other answer is `not_assessed`, a tracked zero included, since a zero has
+  no observation to date it. `exposure_state` is `exposed`, `measured_zero`, `not_assessed` or
+  `tracking_unknown`, the cases of "How `cve_exposure` counts", and `coverage.in_scope` is the
+  API's `tracked`.
+- `exposure_radar` is `not_assessed` with `measured_at` `null`: every radar answered, but no
+  stats answer says when the services or records it counts were observed, so no count is
+  presented as a dated measurement. Its numbers keep the labels above. `freshness` holds each
+  radar's `last_run_at` where the API serves one, and for `shadow_ai` also `running`.
+
+The CVE feed tools' `freshness` is `null`: the feed's answers carry no time at which its
+pollers last completed a poll for the feed as a whole.
+
+A success whose fields do not fit the tool's `outputSchema` (a field of a type the schema does
+not allow) is returned as a failure with `error.kind` `unexpected_shape`, never relayed. A
+field the API adds later is still relayed by the four tools that relay the API's JSON, and
+`exposure_radar` leaves it out and names it, as above.
+
+## Protocol versions
+
+The server answers both eras of the Model Context Protocol on stdio:
+
+- **2026-07-28**: a client that opens with `server/discover` receives a DiscoverResult listing
+  `2026-07-28`, the tools capability and the server instructions, and then sends each request
+  with the per-request `_meta` envelope.
+- **2025 and earlier**: a client that opens with `initialize`, as every 1.x SDK client does,
+  negotiates `2025-11-25`, `2025-06-18`, `2025-03-26` or `2024-11-05`; a version the server does
+  not know is answered with `2025-11-25`.
+
+The first message of a connection picks its era. The DiscoverResult lists only `2026-07-28`,
+as the SDK builds it: the 2025-era versions are reached through `initialize`. Both handshakes
+carry the package's name and version (`serverInfo`), and every API request carries them in its
+User-Agent, `echelongraph-mcp/<version>`.
+
+Both handshakes also carry the server instructions: the data is public; what `state`,
+`measured_at` and `freshness` mean; that exposure numbers are aggregate counts of ip:port
+services, not an internet-wide census; and that Shodan data is Shodan's.
+
 ## Install
 
-Add it to your MCP client's config. It runs via `npx` — no global install needed.
+Requires Node.js 20 or later. Add it to your MCP client's config. It runs via `npx` — no global
+install needed.
 
 ### Claude Desktop
 
@@ -156,13 +308,18 @@ services does EchelonGraph's radar have on record for it?"*
 ```bash
 npm install
 npm run build      # tsc → dist/
-npm test           # build, then behavioural tests against a stub API (no network needed)
+npm test           # build, then the behavioural suite over both protocol eras, against a stub API (no network needed)
 npm run smoke      # spawn the server + call cve_exposure against the production API
 ```
 
 `npm run smoke` calls the production API with this package's User-Agent, so its requests are
 counted as external MCP adoption. `npm test` never leaves the machine.
 
+`npm test` runs the suite once over a 2026-07-28 `server/discover` and once over a 2025-06-18
+`initialize`, plus the era tests. To run it against an installed package rather than `dist/`,
+set `ECHELONGRAPH_MCP_BIN` to that package's `echelongraph-mcp` bin: the tests then run the bin
+directly, as `npx` does, and read that package's own files.
+
 ## License
 
 The code is MIT-licensed.