<p align="center">
  <img src="docs/banner.png" alt="CVE MCP Server — One Server. All Vulnerability Intelligence." width="100%">
</p>

# cve-mcp-server

Realtime CVE intelligence over the Model Context Protocol. Gives an LLM one place
to look up a vulnerability and get **details, exploitation signals, and public
proof-of-concepts**  aggregated from five authoritative sources:

| Source | What it provides |
| --- | --- |
| **NIST NVD** (API v2.0) | Description, CVSS v2/v3.1/v4 scores + vectors, CWE weaknesses, affected-product CPEs, references |
| **CISA KEV** | Confirmed active-exploitation status, remediation due dates, ransomware-use flag |
| **FIRST.org EPSS** | Probability a CVE is exploited in the next 30 days (+ percentile) |
| **GitHub Security Advisories** | Package-level impact: ecosystem, vulnerable version ranges, first patched version |
| **nomi-sec PoC-in-GitHub + Exploit-DB** | Public proof-of-concept repos (ranked by stars) and exploit references, with optional repo-content retrieval |
| **Metasploit + Nuclei** | Packaged, ready-to-run tooling: Metasploit modules (Rapid7, with reliability rank) and Nuclei templates (ProjectDiscovery) referencing the CVE |

## Tools

| Tool | Purpose |
| --- | --- |
| `cve_triage` | **Prioritization verdict** fusing CVSS + EPSS + KEV + PoC into ACT NOW → LOW. |
| `cve_batch_triage` | Triage up to 25 CVEs in one call, returned ranked by priority (turn a scan/findings list into a fix-first queue). |
| `cve_watchlist` | Vendor/product digest: recently published CVEs + that vendor's CISA KEV entries in one call. |
| `cve_get_details` | Full enriched detail for one CVE (NVD + KEV + EPSS, with triage banner). |
| `cve_search` | Search NVD by keyword, CPE, severity, KEV status, date range. |
| `cve_recent` | Recently published CVEs (realtime monitoring, up to 120-day look-back). |
| `cve_get_pocs` | Discover public PoC / exploit references for a CVE. |
| `cve_fetch_poc_code` | Fetch a PoC repo's file listing + README. |
| `cve_get_exploit_tooling` | Packaged Metasploit modules + Nuclei templates for a CVE (with run strings). |
| `cve_get_kev` | CISA KEV single lookup or catalog browse. |
| `cve_get_epss` | EPSS scores for one or many CVEs. |
| `cve_get_advisories` | GitHub Security Advisories for a CVE. |

All tools are read-only and support `response_format: "markdown"` (default) or `"json"`.

## Setup

Requires Node.js 18+.

```bash
npm install
npm run build
```

### Optional environment variables

All are optional but recommended — they raise rate limits and coverage:

- `NVD_API_KEY` — [request one here](https://nvd.nist.gov/developers/request-an-api-key) (NVD throttles hard without it).
- `GITHUB_TOKEN` — any GitHub PAT; raises the GitHub API limit for advisories and PoC fetching.
- `TRANSPORT` — `stdio` (default) or `http`.
- `PORT` — HTTP port when `TRANSPORT=http` (default `3000`, bound to `127.0.0.1`).

## Connecting a client

### Claude Code

```bash
claude mcp add cve --env NVD_API_KEY=xxx --env GITHUB_TOKEN=ghp_xxx -- node /home/k4p/cve-mcp-server/dist/index.js
```

### Claude Desktop (`claude_desktop_config.json`)

```json
{
  "mcpServers": {
    "cve": {
      "command": "node",
      "args": ["/home/k4p/cve-mcp-server/dist/index.js"],
      "env": {
        "NVD_API_KEY": "your-nvd-key",
        "GITHUB_TOKEN": "ghp_your_token"
      }
    }
  }
}
```

## Example prompts

- "Tell me everything about Log4Shell, including whether it's actively exploited."
- "What critical CVEs were published this week that are in the CISA KEV catalog?"
- "Find public PoCs for CVE-2024-3400 and show me what's in the top repo."
- "Is there a Metasploit module or Nuclei template for EternalBlue?"
- "Rank CVE-2021-44228, CVE-2023-23397, and CVE-2024-3400 by EPSS exploitation likelihood."
- "Here are 12 CVEs from last night's scan — triage them and tell me what to patch first."
- "What's new for Fortinet this month, and which of theirs are actively exploited?"
- "Which Maven packages does CVE-2021-44228 affect and in what version was it fixed?"

## Safety note

PoC and exploit tools surface **already-public** security research artifacts and are
intended for authorized defensive testing, detection engineering, and vulnerability
triage. `cve_fetch_poc_code` retrieves repository contents (file listing + README,
size-bounded) and `cve_get_exploit_tooling` links to public Metasploit/Nuclei source;
use them only against targets you are authorized to test.

## Triage scoring

`cve_triage` (and the banner on `cve_get_details`) turns four signals into one verdict:

| Priority | Trigger |
| --- | --- |
| 🔴 **ACT NOW** | In CISA KEV (confirmed exploited), or composite score ≥ 85 |
| 🟠 **HIGH** | Score ≥ 70 |
| 🟡 **ELEVATED** | Score ≥ 50 |
| 🔵 **MODERATE** | Score ≥ 30 |
| ⚪ **LOW** | Score < 30 |

Composite score (0-100): CVSS contributes up to 50, EPSS up to 40, and **exploit availability up
to 15**. Availability is a gradient (strongest signal wins, not additive): a weaponized Metasploit
exploit module → 15, other packaged tooling (auxiliary module / Nuclei template) → 12, a public
PoC → 10, none → 0. KEV membership hard-pins to 100. Each verdict comes with a plain-English
rationale — including an explicit "severe on paper but low real-world signal → deprioritize" note
when CVSS is high but EPSS/KEV/PoC/tooling are all cold.

## Resilience

- **Retries with backoff** on `429/502/503/504` and network blips (honors `Retry-After`) — so
  NVD's strict unauthenticated rate limit doesn't fail a triage mid-run.
- **CVE-detail lookups cached 15 min** in-process (the same CVE is queried repeatedly across
  `cve_get_details` / `cve_triage` / `cve_get_pocs`).

## Evaluations

`evals/` holds a 10-question suite (`cve-mcp-evals.xml`, mcp-builder format) plus a
ground-truth checker that asserts each answer is still retrievable from the live
sources:

```bash
npm run verify:evals
```

See [`evals/README.md`](evals/README.md) for details. Answers are chosen to be stable
over time (CVSS/CWE, KEV dates, GHSA patched versions, classic Metasploit paths).

## Notes

- The CISA KEV catalog is cached in-process for one hour to avoid re-downloading the
  full feed on every call.
- The Metasploit metadata (~11 MB) and Nuclei CVE index (~2 MB) feeds are fetched once
  and cached in-process for six hours, then indexed by CVE for instant lookups.
- NVD caps date-range queries at 120 days; `cve_recent` clamps to that.
- Responses are truncated at 25,000 characters; use pagination or `json` format for more.