# @pipeworx/circl-vulnerability-lookup

Vulnerability records from CIRCL's Vulnerability-Lookup service, which resolves
one id against several upstream feeds at once — MITRE CVE, NVD, GitHub Security
Advisories, PySec and vendor CSAF advisories.

Part of [Pipeworx](https://pipeworx.io) — an MCP gateway connecting AI agents to 1679+ live data sources.

## Tools

- `circl_vuln(id, include_raw?)` — one vulnerability by id. Accepts `CVE-`,
  `GHSA-`, `PYSEC-` and vendor advisory ids alike. Returns a normalised summary
  (title, description, CVSS score/vector, affected products, references, dates)
  plus the untouched upstream record.
- `circl_vuln_search(vendor, product, limit?)` — every vulnerability recorded
  against a CPE vendor/product pair, newest first, tagged with the feed each
  record came from.
- `circl_vuln_recent(limit?)` — the most recently published or updated records
  across every aggregated feed.

## Auth

Keyless.

## Data sources

- <https://vulnerability.circl.lu/api/vulnerability/{id}> — one record by id.
- <https://vulnerability.circl.lu/api/search/{vendor}/{product}> — search.
- <https://vulnerability.circl.lu/api/last/{n}> — recent records.

Operated by CIRCL (Computer Incident Response Center Luxembourg).

## Traps

- **An unknown id answers `{}` with HTTP 200.** That is a silent zero — parsed
  naively it reads as a successful empty record. `circl_vuln` throws a named
  miss instead.
- **The real paths are not the ones the names suggest.** Search is
  `/api/search/{vendor}/{product}` and the recent feed is `/api/last/{n}`.
  `/api/vulnerability/search/...` and `/api/vulnerability/last` are both 404.
- **Records arrive in three different schemas**, and one `/api/last` response
  mixes all three:
  - CVE JSON 5.x — `cveMetadata` + `containers.cna`
  - OSV — `id` / `details` / `affected` / `severity`
  - CSAF — `document` / `product_tree` / `vulnerabilities`
  `summarize()` normalises the shared fields across all three; `raw` keeps the
  original. Do not assume `containers.cna` exists.
- **CVSS lives under a version-specific key** (`cvssV3_1`, `cvssV4_0`, …) inside
  `containers.cna.metrics[]`, so the code scans the metric objects rather than
  reaching for a fixed path. OSV records carry only a vector string in
  `severity[].score`, with no numeric base score.
- **Vendor/product are matched against CPE strings**, not marketing names — use
  `microsoft`/`windows_10`, not `Microsoft Windows 10`.
- **CIRCL rate-limits by source IP**, and publishes the limits at
  <https://vulnerability.circl.lu/.well-known/api-policy.json>: **20 requests
  per minute** anonymously, 40 with an `X-API-KEY`. It *does* send
  `Retry-After` (observed: 59) plus `X-RateLimit-Limit`/`-Remaining`/`-Reset`,
  and the 429 error here quotes it. This pack is keyless and stays inside the
  anonymous bucket — one tool call is one upstream request. If we ever need the
  higher tier, it is a header, not a rebuild.
- **The 429 is per backend worker, not global.** Measured 2026-09-17: three
  consecutive anonymous requests from one IP reported `x-ratelimit-remaining`
  of **0, then 19, then 3**, and one URL kept 429-ing while the next id
  answered 200 instantly. So a 429 here frequently says nothing about your
  actual usage — `circlJson()` retries up to 3 times before surfacing it. Do
  not read a single 429 as "we are being throttled".

## Related packs

`nvd` (NVD directly, platform-keyed) and `osv` (OSV.dev, open-source package
advisories) cover single upstreams. This pack is the cross-feed id resolver: use
it when you have an id and do not know which body published it.

## Quick Start

Add to your MCP client (Claude Desktop, Cursor, Windsurf, etc.):

```json
{
  "mcpServers": {
    "circl-vulnerability-lookup": {
      "url": "https://gateway.pipeworx.io/circl-vulnerability-lookup/mcp"
    }
  }
}
```

### What this endpoint actually serves

`tools/list` at `https://gateway.pipeworx.io/circl-vulnerability-lookup/mcp` returns the tools in the table
above **plus the shared Pipeworx meta-tools** — `ask_pipeworx`,
`discover_tools`, `search_within`, `remember`/`recall` and the rest of the
gateway-wide set. So the tool count you see is larger than this table: a
single-pack endpoint currently lists roughly 30 shared tools alongside the
pack's own. The connection's `initialize` response states its exact scope, and
is the authoritative answer for a given day.

This is deliberate, not multiplexing by accident. The meta-tools are what let a
scoped connection answer a question this pack does not cover — via
`ask_pipeworx`, which routes across the whole catalog — without you adding a
second MCP server. There is currently no way to mount a pack endpoint without
them; if the extra schemas cost you more context than the routing is worth,
connect to the full gateway once rather than to several pack endpoints.

Or connect to the full Pipeworx gateway to get every pack's tools listed
directly, instead of just this one's:

```json
{
  "mcpServers": {
    "pipeworx": {
      "url": "https://gateway.pipeworx.io/mcp"
    }
  }
}
```

Both URLs reach the same gateway and the same 1679+ data sources. The
only difference is which pack's tools are listed **directly**; `ask_pipeworx`
reaches all of them from either one.

## No MCP client? Call it over HTTP

```bash
curl -X POST https://gateway.pipeworx.io/v1/tools/circl_vuln \
  -H 'Content-Type: application/json' \
  -d '{"id":"CVE-2014-0160","include_raw":false}'
```

No account needed for the first calls. Inspect any tool: `GET https://gateway.pipeworx.io/v1/tools/circl_vuln`. Find one: `POST https://gateway.pipeworx.io/v1/tools/search_packs` with `{"query":"..."}`.

## Standalone (no gateway account)

This package also runs as a local stdio MCP server — no Pipeworx account, no
gateway round-trip:

```json
{
  "mcpServers": {
    "circl-vulnerability-lookup": {
      "command": "npx",
      "args": ["-y", "@pipeworx/mcp-circl-vulnerability-lookup"]
    }
  }
}
```

Or run it directly to confirm it starts:

```bash
npx -y @pipeworx/mcp-circl-vulnerability-lookup
```

It speaks MCP over stdin/stdout and answers `initialize`/`tools/list`/`tools/call`
for **only** this pack's tools — none of the shared meta-tools the gateway
connection above adds. Same source, same tools, no ask_pipeworx routing.

## Using with ask_pipeworx

Instead of calling tools directly, you can ask questions in plain English —
this works on the pack endpoint above as well as on the full gateway:

```
ask_pipeworx({ question: "your question about Circl Vulnerability Lookup data" })
```

The gateway picks the right tool and fills the arguments automatically.

## More

- [Docs and guides](https://pipeworx.io/docs)
- [pipeworx.io](https://pipeworx.io)

## License

MIT