CVE Risk MCP Server

# CVE Risk MCP Server

MCP server for CVE lookups, KEV enrichment, and “what should I patch first?” ranking. It
implements the MCP `tools/list` + `tools/call` flow over stdio and returns structured risk
assessments per CVE.

## Features

- CVE detail lookups with parsed CVSS v3/v4 metrics.
- CISA KEV feed enrichment (primary + mirror fallback).
- EPSS-style risk scoring with reasons and a priority label.
- Batch ranking for patch queues.

## Tools

- `cve_lookup`
  - Inputs: `cve_id`, `include_kev`, `include_epss`
  - Output: CVE summary + KEV status + risk score
- `cve_rank`
  - Inputs: `cve_ids`, `include_kev`, `include_epss`, `fail_fast`
  - Output: ranked list (highest risk first)
- `cve_patch_first`
  - Inputs: `cve_ids`, `top_n`, `include_kev`, `include_epss`, `fail_fast`
  - Output: ranked list + top-N recommendations
- `cve_status`
  - Inputs: none
  - Output: upstream status + cache stats (timestamps + last error summary)
- `cve_config`
  - Inputs: none
  - Output: effective runtime config (URLs, cache, scoring, batch limits)
- `cve_refresh`
  - Inputs: `cve_ids`, `include_epss`, `refresh_kev`
  - Output: cache warm/refresh summary
- `cve_export`
  - Inputs: `cve_ids`, `include_kev`, `include_epss`, `include_markdown`, `fail_fast`
  - Output: ranked list + optional markdown summary

## Quickstart

```bash
make setup
make check
```

## Reliability knobs

- `--retries` and `--retry-backoff-seconds` control bounded retries for transient HTTP failures (429/5xx + network errors).
- `Retry-After` supports both delta-seconds and HTTP-date response headers.
- `--print-effective-config` prints resolved settings and their source (CLI/config/env/built-ins) to debug precedence.
- `--cve-timeout`, `--kev-timeout`, and `--epss-timeout` override the shared `--timeout` for per-source control.
- `--config` (TOML) centralizes defaults. Precedence: CLI flags > config > env > built-ins.
- MCP and JSON CLI responses now include structured error data for upstream failures.
- Batch flows (`cve_rank`, `cve_patch_first`, `cve_export`) are fail-soft and return per-item `errors` without dropping successful results.
- KEV/EPSS enrichment is best-effort: enrichment failures are recorded in `errors`, but results are still returned with missing enrichment fields.
- Optional strict batch mode is available via `fail_fast` (MCP tool arg) or `--fail-fast` (JSON CLI).
- `--max-batch-size` limits how many unique CVEs a batch request can process (0 disables).
- `--max-parallel` controls controlled parallelism for batch CVE lookups (default: 1).
- `--cache-dir` enables a persistent on-disk cache for CVE/KEV/EPSS responses (env: `CVE_RISK_CACHE_DIR`).
- `--offline` disables all network fetches and uses cache-only mode (requires `--cache-dir`).
- Lookup/rank/patch/export/refresh responses include a `cache` block when stale cache entries are served in offline mode (`cache.served_stale=true` with per-source details).
- CVE IDs are validated and batch inputs are de-duplicated before upstream calls.
- CVE parsing tolerates legacy schema variants (alternate CVSS and reference fields).
- Structured errors include remediation hints (e.g., respect `Retry-After` on 429s).
- `--epss-weight` (or env `CVE_RISK_EPSS_WEIGHT`) calibrates how strongly EPSS influences the risk score (default: 1.0).
- `--kev-floor` (env `CVE_RISK_KEV_FLOOR`) and `--kev-boost` (env `CVE_RISK_KEV_BOOST`) calibrate the KEV scoring behavior.
- `--age-recent-days` / `--age-recent-boost` (env `CVE_RISK_AGE_RECENT_DAYS` / `CVE_RISK_AGE_RECENT_BOOST`) calibrate the "new CVE" boost.
- `--age-old-days` / `--age-old-penalty` (env `CVE_RISK_AGE_OLD_DAYS` / `CVE_RISK_AGE_OLD_PENALTY`) calibrate the "old CVE" penalty.
- `cve_status` includes cache metadata plus request/latency counters, stale-cache counters, and rolling-window latency percentiles (`request_count`, `success_count`, `error_count`, `stale_served_count`, `avg_latency_ms`, `last_latency_ms`, `p50_latency_ms`, `p95_latency_ms`, `latency_sample_count`, `latency_window_size`) per source.
- stdio MCP mode emits structured JSON logs to stderr (configurable via `--mcp-log-level`).

## Operations

See `docs/OPERATIONS.md` for a small operator runbook (interpreting `cve_status`, common remediation).

## Run (stdio MCP server)

```bash
python -m cve_risk_mcp --stdio
```

## Run (JSON CLI mode)

```bash
cve-risk-mcp lookup CVE-2023-23397 --pretty
cve-risk-mcp rank CVE-2023-23397 CVE-2021-44228 --pretty
cve-risk-mcp rank CVE-2023-23397 CVE-2021-44228 --fail-fast --pretty
cve-risk-mcp patch-first CVE-2023-23397 CVE-2021-44228 --top-n 1 --pretty
cve-risk-mcp status --pretty
cve-risk-mcp refresh --no-refresh-kev --pretty
cve-risk-mcp export CVE-2023-23397 CVE-2021-44228 --include-markdown --pretty
```

## Config file (optional)

Use `--config` to set defaults in a TOML file. See `cve-risk-mcp.example.toml` for a starting point.

## Output to file

```bash
cve-risk-mcp lookup CVE-2023-23397 --output out.json --pretty
```

## NDJSON output

```bash
cve-risk-mcp rank CVE-2023-23397 CVE-2021-44228 --format ndjson
```

When batch errors exist, NDJSON output appends structured `{"error": ...}` records after ranked items.

## Load CVEs from file

```bash
cve-risk-mcp rank --cve-file cves.txt --format ndjson
cve-risk-mcp patch-first --cve-file cves.txt --top-n 3 --format json
cve-risk-mcp export --cve-file cves.txt --include-markdown --format json
```

## Load CVEs from stdin (batch commands)

When no positional CVEs and no `--cve-file` are provided, `rank`, `patch-first`, and `export` will read from stdin.

```bash
cat cves.txt | cve-risk-mcp rank --format ndjson
cat trivy.json | cve-risk-mcp patch-first --top-n 5 --format json
```

`--cve-file` also supports extracting CVE IDs from common scanner JSON outputs (auto-detected): Grype JSON, Trivy JSON, and OSV-Scanner JSON.

```bash
cve-risk-mcp rank --cve-file grype.json --format ndjson
cve-risk-mcp patch-first --cve-file trivy.json --top-n 5 --format json
```
## Example (tools/call)

```json
{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"cve_lookup","arguments":{"cve_id":"CVE-2023-23397"}}}
```

## Data sources

- CVE data: CIRCL Vulnerability Lookup API.
- KEV data: CISA Known Exploited Vulnerabilities feed (primary URL) with
  fallback to the official CISA GitHub mirror.
- EPSS data (optional): FIRST EPSS API.

## Notes

- No authentication: intended for local or controlled environments.
- All outbound network calls are GETs to the configured APIs.