CVE Risk 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

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)

python -m cve_risk_mcp --stdio

Run (JSON CLI mode)

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

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

NDJSON output

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

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.

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.

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)

{"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.