Skip to content
Back to search

cve-mcp-server

Production-grade MCP server giving Claude 27 security intelligence tools across 21 APIs — CVE lookup, EPSS scoring, CISA KEV, MITRE ATT&CK, Shodan, VirusTotal, and more.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/mukul975--cve-mcp-server/badge.svg)](/listings/mukul975--cve-mcp-server)

HTML

<a href="/listings/mukul975--cve-mcp-server"><img src="/api/listings/mukul975--cve-mcp-server/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Prerequisites

- **Python 3.10+** (3.11 or 3.12 recommended) - **pip** or **uv** package manager - **Git** for cloning the repository - A terminal with access to environment variables

Step-by-step setup

# 1. Clone the repository
git clone https://github.com/mukul975/cve-mcp-server.git
cd cve-mcp-server

# 2. Create and activate a virtual environment
python -m venv venv

# macOS / Linux:
source venv/bin/activate

# Windows (PowerShell):
.\venv\Scripts\Activate.ps1

# Windows (CMD):
venv\Scripts\activate.bat

# 3. Install dependencies
pip install -e .

# 4. Copy and configure environment variables
cp .env.example .env
# Edit .env with your API keys (see API Keys Setup section below)

# 5. Verify the server starts
python -m cve_mcp.server

Using uv (faster alternative)

git clone https://github.com/mukul975/cve-mcp-server.git
cd cve-mcp-server
uv venv
source .venv/bin/activate  # or .venv\Scripts\activate on Windows
uv pip install -e .
cp .env.example .env

With test dependencies

pip install -e ".[test]"

---

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 769 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # 🛡️ CVE MCP Server
  2. ![CVE MCP Server](assets/banner.png)
  3. **AI-powered security intelligence at your fingertips — 28 tools + a one-call `triage_cve` orchestrator, 24 data sources, one protocol.**
  4. [![GARS-2026 Survey](https://img.shields.io/badge/GARS--2026-Take%20the%20Survey-E8B84B?style=for-the-badge&logo=googleforms&logoColor=black)](https://mahipal.engineer/survey?utm_source=github_badge&utm_medium=readme&utm_campaign=gars2026)
  5. [![Python 3.10+](https://img.shields.io/badge/Python-3.10%2B-3776AB?style=flat-square&logo=python&logoColor=white)](https://python.org)
  6. [![License: MIT](https://img.shields.io/badge/License-MIT-green?style=flat-square)](LICENSE)
  7. [![MCP Compatible](https://img.shields.io/badge/MCP-Compatible-blue?style=flat-square)](https://modelcontextprotocol.io)
  8. [![Security Tool](https://img.shields.io/badge/Security-Intelligence-red?style=flat-square&logo=shield)](https://github.com/mukul975/cve-mcp-server)
  9. [![FastMCP](https://img.shields.io/badge/FastMCP-Python-00d4ff?style=flat-square)](https://gofastmcp.com)
  10. A production-grade **Model Context Protocol (MCP) server** that turns Claude into a full-spectrum security analyst. Instead of juggling 15+ browser tabs across NVD, EPSS, CISA KEV, Shodan, VirusTotal, and GreyNoise, ask Claude one question and get correlated intelligence in seconds. Built with Python, FastMCP, httpx, aiosqlite, Pydantic v2, and defusedxml.
  11. **The problem:** Triaging a single CVE means querying NVD for CVSS scores, EPSS for exploitation probability, CISA KEV for active exploitation status, GitHub for patches, and VirusTotal for malware associations — then mentally correlating everything. For 50 CVEs, that's an entire day lost.
  12. **The solution:** CVE MCP Server gives Claude direct access to 28 security tools across 24 APIs — fronted by the **`triage_cve`** one-call orchestrator. Ask "Should we patch CVE-2024-3400?" and Claude fans out to every relevant source in parallel, calculates a composite risk score (with a CISA KEV hard override), and delivers a prioritized recommendation with evidence.
  13. ---
  14. ## 🌍 GARS-2026 — Global Agentic AI Readiness Survey
  15. I'm running a global academic study measuring how ready security professionals,
  16. developers, and enterprise teams actually are for agentic AI — MCP servers,
  17. tool calling, governance, and human-in-the-loop workflows.
  18. **If you use this repo, your response would be a genuinely valuable data point.**
  19. 📋 **Take the survey (10 min):**
  20. [Survey](https://mahipal.engineer/survey?utm_source=github_repo&utm_medium=readme&utm_campaign=gars2026)
  21. - 60 questions · Anonymous · Supervised by SRH Berlin
  22. - You get **50 Casky Tokens** for early access to [casky.ai](https://casky.ai)
  23. - Results published open access under CC-BY 4.0
  24. ---
  25. ## 📑 Table of contents
  26. - [Architecture](#-architecture)
  27. - [Tool catalog](#-tool-catalog-28-tools)
  28. - [Installation](#-installation)
  29. - [API keys setup](#-api-keys-setup)
  30. - [Configuration](#%EF%B8%8F-configuration)
  31. - [Quick start](#-quick-start)
  32. - [Usage examples](#-usage-examples)
  33. - [Risk score explained](#-risk-score-explained)
  34. - [Data sources](#-data-sources)
  35. - [Running tests](#-running-tests)
  36. - [Architecture deep dive](#-architecture-deep-dive)
  37. - [Security and privacy](#-security-and-privacy)
  38. - [Troubleshooting](#-troubleshooting)
  39. - [Roadmap and known limitations](#-roadmap-and-known-limitations)
  40. - [Contributing](#-contributing)
  41. - [License](#-license)
  42. ---
  43. ## 🏗️ Architecture
  44. ```
  45. ┌─────────────────────────────────────────────────────────────────────┐
  46. │ Claude Desktop / Claude Code │
  47. │ (MCP Client via stdio) │
  48. └──────────────────────────────┬──────────────────────────────────────┘
  49. │ Model Context Protocol (stdio)
  50. ▼
  51. ┌─────────────────────────────────────────────────────────────────────┐
  52. │ CVE MCP Server (Python) │
  53. │ ┌─────────────┐ ┌──────────────┐ ┌───────────────┐ │
  54. │ │ 27 MCP │ │ Composite │ │ SQLite Cache │ │
  55. │ │ Tools │ │ Risk Engine │ │ + Audit Log │ │
  56. │ └──────┬──────┘ └──────┬───────┘ └───────┬───────┘ │
  57. │ │ │ │ │
  58. │ ┌──────┴────────────────┴───────────────────┴──────┐ │
  59. │ │ Async HTTP Client (httpx) │ │
  60. │ │ Rate Limiter · Response Cache │ │
  61. │ └──────────────────────┬───────────────────────────┘ │
  62. └─────────────────────────┼───────────────────────────────────────────┘
  63. │ HTTPS (outbound only)
  64. ┌───────────────┼───────────────────────────┐
  65. ▼ ▼ ▼
  66. ┌──────────────┐ ┌──────────────┐ ┌──────────────┐
  67. │ VULNERABILITY│ │ NETWORK │ │ THREAT │
  68. │ INTELLIGENCE │ │ INTELLIGENCE │ │ INTELLIGENCE │
  69. ├──────────────┤ ├──────────────┤ ├──────────────┤
  70. │ NVD API 2.0 │ │ AbuseIPDB │ │ VirusTotal │
  71. │ EPSS / FIRST │ │ GreyNoise v3 │ │ MalwareBazaar│
  72. │ CISA KEV │ │ Shodan │ │ ThreatFox │
  73. │ OSV.dev │ │ CIRCL PDNS │ │ Ransomwhere │
  74. │ GitHub GHSA │ │ │ │ AlienVault │
  75. │ MITRE ATT&CK │ │ │ │ URLScan.io │
  76. └──────────────┘ └──────────────┘ └──────────────┘
  77. ```
  78. All traffic is **outbound HTTPS only** — no inbound ports are opened. API keys are loaded from environment variables and never logged. Private/internal IP addresses are blocked from all lookup tools.
  79. ---
  80. ## 🔍 Tool catalog (28 tools)
  81. ### ⭐ Orchestration (v0.2.0) — start here
  82. | Tool | Description | API Key Required | Example Usage |
  83. |------|-------------|-----------------|---------------|
  84. | `triage_cve` | One-call triage that fans out NVD + EPSS + CISA KEV (+ public PoC for `depth != "quick"`) concurrently, computes the composite risk score with a KEV hard override, falls back to VulnCheck NVD++ when NIST NVD is throttled, and on `depth="deep"` emits the SSVC v2 gated decision | Free / No key (key recommended) | `triage_cve("CVE-2021-44228", depth="deep")` |
  85. > **Also exposed via MCP primitives** — Resources: `kev://catalog`, `epss://scores/{cve_id}`, `manifest://tool-hash` (SHA-256 over the registered tool surface, for tamper detection). Prompts: `patch_decision`, `compare_and_prioritize`, `dependency_triage`.
  86. ### Core Vulnerability Intelligence (8 tools)
  87. | Tool | Description | API Key Required | Example Usage |
  88. |------|-------------|-----------------|---------------|
  89. | `lookup_cve` | Fetch detailed CVE record from NVD including CVSS scores, CWEs, affected products, references, and timeline | Free / No key (key recommended) | `lookup_cve("CVE-2024-3400")` |
  90. | `search_cves` | Search NVD for CVEs by keyword, product name, severity, or date range | Free / No key (key recommended) | `search_cves(keyword="Apache Log4j", severity="CRITICAL")` |
  91. | `get_epss_score` | Get EPSS exploitation probability (0–1) and percentile for one or more CVEs | Free / No key | `get_epss_score("CVE-2024-3400")` |
  92. | `check_kev_status` | Check whether a CVE appears in CISA's Known Exploited Vulnerabilities catalog | Free / No key | `check_kev_status("CVE-2021-44228")` |
  93. | `get_cvss_details` | Parse and explain a CVSS v3.1 vector string with per-metric breakdown | Free / No key | `get_cvss_details("CVSS:3.1/AV:N/AC:L/PR:N/UI:N/S:C/C:H/I:H/A:H")` |
  94. | `get_cwe_info` | Look up Common Weakness Enumeration details by CWE ID from embedded database | Free / No key | `get_cwe_info("CWE-79")` |
  95. | `get_cve_references` | Extract and categorize all reference links for a CVE (patches, advisories, exploits) | Free / No key (key recommended) | `get_cve_references("CVE-2023-44487")` |
  96. | `bulk_cve_lookup` | Batch-fetch details for up to 20 CVEs in a single call with parallel enrichment | Free / No key (key recommended) | `bulk_cve_lookup(["CVE-2024-3400", "CVE-2023-44487"])` |
  97. ### Exploit & Attack Intelligence (4 tools)
  98. | Tool | Description | API Key Required | Example Usage |
  99. |------|-------------|-----------------|---------------|
  100. | `search_exploits` | Search GitHub for public proof-of-concept exploits and exploit code repositories | `GITHUB_TOKEN` (optional) | `search_exploits("CVE-2024-3400")` |
  101. | `get_mitre_techniques` | Map a CVE or CWE to relevant MITRE ATT&CK techniques, tactics, and mitigations | Free / No key | `get_mitre_techniques("CVE-2021-44228")` |
  102. | `check_poc_availability` | Determine if known proof-of-concept code exists for a CVE across multiple sources | `GITHUB_TOKEN` (optional) | `check_poc_availability("CVE-2024-3400")` |
  103. | `get_attack_patterns` | Retrieve CAPEC attack pattern details associated with a CWE or CVE | Free / No key | `get_attack_patterns("CWE-89")` |
  104. ### Phase 3: Advanced Risk & Reporting (4 tools)
  105. | Tool | Description | API Key Required | Example Usage |
  106. |------|-------------|-----------------|---------------|
  107. | `calculate_risk_score` | Compute composite 0–100 risk score using CVSS, EPSS, KEV status, and PoC availability | Free / No key (key recommended) | `calculate_risk_score("CVE-2024-3400")` |
  108. | `generate_risk_report` | Generate a formatted executive security report for one or more CVEs with recommendations | Free / No key (key recommended) | `generate_risk_report(["CVE-2024-3400", "CVE-2023-44487"])` |
  109. | `prioritize_cves` | Rank a list of CVEs by composite risk score for triage prioritization | Free / No key (key recommended) | `prioritize_cves(["CVE-2024-3400", "CVE-2023-4966", "CVE-2023-44487"])` |
  110. | `get_trending_cves` | Retrieve trending CVEs based on high EPSS scores and recent KEV additions | Free / No key | `get_trending_cves(days=7, min_epss=0.5)` |
  111. ### Network Intelligence (4 tools)
  112. | Tool | Description | API Key Required | Example Usage |
  113. |------|-------------|-----------------|---------------|
  114. | `lookup_ip_reputation` | Check IP address abuse history and confidence score via AbuseIPDB | `ABUSEIPDB_API_KEY` | `lookup_ip_reputation("185.220.101.34")` |
  115. | `check_ip_noise` | Query GreyNoise for IP scan/attack activity, classification, and associated CVEs | `GREYNOISE_API_KEY` | `check_ip_noise("185.220.101.34")` |
  116. | `shodan_host_lookup` | Get open ports, services, banners, and vulnerabilities for an IP via Shodan | `SHODAN_API_KEY` | `shodan_host_lookup("8.8.8.8")` |
  117. | `passive_dns_lookup` | Retrieve historical DNS resolution data for a domain from CIRCL Passive DNS | `CIRCL_PDNS_USER` + `CIRCL_PDNS_PASSWORD` | `passive_dns_lookup("example.com")` |
  118. ### Threat Intelligence (4 tools)
  119. | Tool | Description | API Key Required | Example Usage |
  120. |------|-------------|-----------------|---------------|
  121. | `virustotal_lookup` | Analyze file hashes, URLs, domains, or IPs against 70+ antivirus engines | `VIRUSTOTAL_API_KEY` | `virustotal_lookup(hash="44d88612fea8a8f36de82e1278abb02f")` |
  122. | `search_malware` | Search MalwareBazaar for malware samples by hash, tag, or signature | `ABUSECH_AUTH_KEY` (optional) | `search_malware(tag="Emotet")` |
  123. | `search_iocs` | Query ThreatFox for Indicators of Compromise linked to malware families | `ABUSECH_AUTH_KEY` (optional) | `search_iocs(malware="CobaltStrike")` |
  124. | `check_ransomware` | Look up ransomware payment addresses and transaction data from Ransomwhere | Free / No key | `check_ransomware(address="bc1q...")` |
  125. ### DevSecOps (3 tools)
  126. | Tool | Description | API Key Required | Example Usage |
  127. |------|-------------|-----------------|---------------|
  128. | `scan_dependencies` | Scan package names and versions against OSV.dev for known vulnerabilities | Free / No key | `scan_dependencies(ecosystem="PyPI", packages={"requests": "2.28.0"})` |
  129. | `scan_github_advisories` | Search GitHub Security Advisories by ecosystem, package, or severity | `GITHUB_TOKEN` (optional) | `scan_github_advisories(ecosystem="pip", package="django")` |
  130. | `urlscan_check` | Submit a URL for scanning or retrieve previous scan results from URLScan.io | `URLSCAN_API_KEY` | `urlscan_check("https://suspicious-site.com")` |
  131. ---
  132. ## 📦 Installation
  133. ### Prerequisites
  134. - **Python 3.10+** (3.11 or 3.12 recommended)
  135. - **pip** or **uv** package manager
  136. - **Git** for cloning the repository
  137. - A terminal with access to environment variables
  138. ### Step-by-step setup
  139. ```bash
  140. # 1. Clone the repository
  141. git clone https://github.com/mukul975/cve-mcp-server.git
  142. cd cve-mcp-server
  143. # 2. Create and activate a virtual environment
  144. python -m venv venv
  145. # macOS / Linux:
  146. source venv/bin/activate
  147. # Windows (PowerShell):
  148. .\venv\Scripts\Activate.ps1
  149. # Windows (CMD):
  150. venv\Scripts\activate.bat
  151. # 3. Install dependencies
  152. pip install -e .
  153. # 4. Copy and configure environment variables
  154. cp .env.example .env
  155. # Edit .env with your API keys (see API Keys Setup section below)
  156. # 5. Verify the server starts
  157. python -m cve_mcp.server
  158. ```
  159. ### Using uv (faster alternative)
  160. ```bash
  161. git clone https://github.com/mukul975/cve-mcp-server.git
  162. cd cve-mcp-server
  163. uv venv
  164. source .venv/bin/activate # or .venv\Scripts\activate on Windows
  165. uv pip install -e .
  166. cp .env.example .env
  167. ```
  168. ### With test dependencies
  169. ```bash
  170. pip install -e ".[test]"
  171. ```
  172. ---
  173. ## 🔑 API keys setup
  174. API keys are organized by priority — get the **Tier 1** keys first for maximum coverage with free tools, then progressively add Tier 2 and Tier 3 as needed.
  175. ### Tier 1: High priority (free, instant access, maximum coverage)
  176. | ENV Variable | Enables | How to Get | Free Tier Limits | Required? |
  177. |-------------|---------|-----------|-----------------|-----------|
  178. | `NVD_API_KEY` | 10× faster NVD lookups (50 req/30s vs 5) | [Request at nvd.nist.gov](https://nvd.nist.gov/developers/request-an-api-key) | **50 requests per 30 seconds** | Optional but strongly recommended |
  179. | `GITHUB_TOKEN` | GitHub Advisory search + exploit PoC search | [Create PAT at github.com/settings/tokens](https://github.com/settings/tokens) | **5,000 requests/hour** | Optional (60/hr without) |
  180. ### Tier 2: Recommended (free accounts, significant value)
  181. | ENV Variable | Enables | How to Get | Free Tier Limits | Required? |
  182. |-------------|---------|-----------|-----------------|-----------|
  183. | `ABUSEIPDB_KEY` | IP reputation lookups | [Register at abuseipdb.com](https://www.abuseipdb.com/register) | **1,000 checks/day** | Required for IP tools |
  184. | `VIRUSTOTAL_KEY` | File/URL/domain/IP malware scanning | [Sign up at virustotal.com](https://www.virustotal.com/gui/join-us) | **500 lookups/day, 4/min** | Required for VT tools |
  185. | `GREYNOISE_API_KEY` | IP noise/scan activity intelligence | [Sign up at viz.greynoise.io](https://viz.greynoise.io/signup) | **50 queries/week** (community) | Required for GreyNoise tools |
  186. | `SHODAN_KEY` | Host/port/service reconnaissance | [Register at account.shodan.io](https://account.shodan.io) | Basic host lookups (free tier) | Required for Shodan tools |
  187. ### Tier 3: Optional (extended intelligence)
  188. | ENV Variable | Enables | How to Get | Free Tier Limits | Required? |
  189. |-------------|---------|-----------|-----------------|-----------|
  190. | `URLSCAN_KEY` | URL scanning and website analysis | [Sign up at urlscan.io](https://urlscan.io/user/signup) | **5,000 public scans/day** | Optional |
  191. | `CIRCL_PDNS_USER` | CIRCL Passive DNS lookups | [Request access at circl.lu](https://www.circl.lu/services/passive-dns/) | Partner access only | Optional |
  192. | `CIRCL_PDNS_PASS` | CIRCL Passive DNS authentication | Provided with CIRCL registration | Partner access only | Optional |
  193. > **⚡ Zero-key start:** Eight tools work without any API key — EPSS, CISA KEV, OSV.dev, MITRE ATT&CK, CWE lookups, CVSS parsing, Ransomwhere, and NVD (at reduced rate). You can start using the server immediately and add keys progressively.
  194. ---
  195. ## ⚙️ Configuration
  196. ### Environment variables (.env.example)
  197. ```env
  198. # NVD API key — free at https://nvd.nist.gov/developers/request-an-api-key
  199. # Without key: 5 req/30s | With key: 50 req/30s
  200. NVD_API_KEY=
  201. # GitHub token — increases rate limit from 60/hr to 5000/hr (no scopes needed)
  202. GITHUB_TOKEN=
  203. # Threat intelligence keys (all optional — tools degrade gracefully without them)
  204. ABUSEIPDB_KEY= # https://www.abuseipdb.com/account/api
  205. VIRUSTOTAL_KEY= # https://www.virustotal.com/gui/join-us
  206. URLSCAN_KEY= # https://urlscan.io/user/signup
  207. SHODAN_KEY= # https://account.shodan.io/register
  208. # GreyNoise — uses /v3/ip/{ip} endpoint (NOT the deprecated /v3/community)
  209. GREYNOISE_API_KEY= # https://viz.greynoise.io/signup
  210. # CIRCL Passive DNS — requires partner registration
  211. CIRCL_PDNS_USER=
  212. CIRCL_PDNS_PASS=
  213. # Optional overrides
  214. CACHE_DB_PATH= # defaults to ~/.cve-mcp/cache.db
  215. AUDIT_LOG_PATH= # defaults to ~/.cve-mcp/audit.log
  216. REQUEST_TIMEOUT=30 # HTTP timeout in seconds
  217. MAX_RETRIES=3 # retries on transient errors
  218. ```
  219. ### Claude Desktop configuration
  220. **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
  221. **Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
  222. ```json
  223. {
  224. "mcpServers": {
  225. "cve-mcp": {
  226. "command": "python",
  227. "args": ["-m", "cve_mcp.server"],
  228. "cwd": "/absolute/path/to/cve-mcp-server",
  229. "env": {
  230. "NVD_API_KEY": "your-key-here",
  231. "GITHUB_TOKEN": "ghp_xxxxxxxxxxxxxxxxxxxx",
  232. "ABUSEIPDB_KEY": "your-abuseipdb-key",
  233. "GREYNOISE_API_KEY": "your-greynoise-key",
  234. "SHODAN_KEY": "your-shodan-key"
  235. }
  236. }
  237. }
  238. }
  239. ```
  240. > ⚠️ **Important:** Always use **absolute paths**. Fully quit Claude Desktop (Cmd+Q / Alt+F4) after changing the config — reloading is not enough.
  241. ### Claude Code configuration
  242. ```bash
  243. # Basic setup
  244. claude mcp add cve-mcp -- python -m cve_mcp.server
  245. # With environment variables (repeat -e for each key)
  246. claude mcp add cve-mcp -e NVD_API_KEY=your_key -e VULNCHECK_TOKEN=your_token -- python -m cve_mcp.server
  247. # Or just run from the project directory — python-dotenv auto-loads .env on startup
  248. # Verify it's connected
  249. claude mcp list
  250. ```
  251. ---
  252. ## 🚀 Quick start
  253. ### Step 1: Install (2 minutes)
  254. ```bash
  255. git clone https://github.com/mukul975/cve-mcp-server.git
  256. cd cve-mcp-server
  257. python -m venv venv && source venv/bin/activate
  258. pip install -e .
  259. ```
  260. ### Step 2: Test with free tools first
  261. No `.env` file needed. Add the server to Claude Desktop or Claude Code and try:
  262. > **"What is CVE-2021-44228? Is it actively exploited?"**
  263. Claude will use `lookup_cve` (NVD), `get_epss_score` (EPSS), and `check_kev` (CISA KEV) — all free, no keys required.
  264. > **"Scan these Python packages for vulnerabilities: requests 2.28.0, flask 2.2.0, django 3.2.0"**
  265. ### Step 3: Add your first key for 10× performance
  266. ```bash
  267. echo 'NVD_API_KEY=your-key-here' > .env
  268. ```
  269. Request a free NVD key at [nvd.nist.gov](https://nvd.nist.gov/developers/request-an-api-key) — instant via email, increases rate limit from **5 to 50 requests per 30 seconds**.
  270. ### Step 4: Full power mode
  271. Once you've added Tier 1 and Tier 2 keys:
  272. > **"Calculate the risk score for CVE-2024-3400 and tell me if we should patch immediately."**
  273. ---
  274. ## 💬 Usage examples
  275. ### Scenario 1: "Should we patch Log4Shell immediately?"
  276. > **You:** Analyze if CVE-2021-44228 (Log4Shell) needs immediate patching. Give me the risk score and your recommendation.
  277. Claude orchestrates multiple tools behind the scenes:
  278. ```
  279. → lookup_cve("CVE-2021-44228")
  280. CVSS 3.1: 10.0 (CRITICAL) | AV:N/AC:L/PR:N/UI:N/S:C/C:H/I:H/A:H
  281. → get_epss_score("CVE-2021-44228")
  282. EPSS: 0.97531 (97.5%) | Percentile: 99.99%
  283. → check_kev("CVE-2021-44228")
  284. ✅ IN CISA KEV — Added 2021-12-10 | Known ransomware use: Yes
  285. → check_poc_exists("CVE-2021-44228")
  286. ✅ WEAPONIZED — 300+ public PoC repositories found
  287. → calculate_risk_score("CVE-2021-44228")
  288. Risk Score: 97/100 (CRITICAL) | Urgency: PATCH IMMEDIATELY
  289. ```
  290. **Claude's response:** "CVE-2021-44228 scores **97/100 (CRITICAL)**. Remote code execution in Apache Log4j, CVSS 10.0, 97.5% EPSS probability, confirmed active exploitation in CISA KEV including ransomware campaigns, 300+ public exploits. **Patch immediately.**"
  291. ### Scenario 2: "Scan my Python requirements.txt"
  292. > **You:** Scan these dependencies: requests==2.28.0, flask==2.2.0, django==3.2.0, pillow==9.0.0, cryptography==37.0.0
  293. ```
  294. → scan_dependencies(ecosystem="PyPI", packages={...})
  295. Found 12 vulnerabilities across 4 packages
  296. ```
  297. **Claude's response:** "Found **12 vulnerabilities** across your packages. **Immediate action:** Django 3.2.0 (3 critical CVEs including SQL injection), Pillow 9.0.0 (heap overflow), cryptography 37.0.0 (OpenSSL chain). Upgrade to: django>=4.2.16, pillow>=10.3.0, cryptography>=42.0.0."
  298. ### Scenario 3: "Investigate a suspicious IP"
  299. > **You:** Investigate suspicious IP 185.220.101.34 — is it malicious?
  300. ```
  301. → check_ip_reputation("185.220.101.34")
  302. AbuseIPDB Confidence: 100% | Reports: 4,832 | ISP: Tor Exit Node
  303. → check_ip_noise("185.220.101.34")
  304. GreyNoise: MALICIOUS | Tags: [Tor Exit Node, Web Scanner]
  305. CVEs targeted: CVE-2024-3400, CVE-2023-46805
  306. → shodan_host_lookup("185.220.101.34")
  307. Open ports: 22, 80, 443, 9001 | OS: Linux
  308. ```
  309. **Claude's response:** "**185.220.101.34 is a known Tor exit node** rated 100% malicious by AbuseIPDB with 4,832 abuse reports. GreyNoise confirms active scanning for CVE-2024-3400 (Palo Alto) and CVE-2023-46805 (Ivanti). **Recommendation: Block at firewall.**"
  310. ### Scenario 4: "Generate an executive security report"
  311. > **You:** Generate an executive security report for: CVE-2024-3400, CVE-2023-44487, CVE-2023-4966, CVE-2024-21887
  312. ```
  313. → compare_cves([...])
  314. Compiles: NVD, EPSS, KEV, PoC availability, MITRE ATT&CK mapping
  315. Generates: Ranked risk table, remediation timeline, executive summary
  316. ```
  317. ---
  318. ## 📊 Risk score explained
  319. The `calculate_risk_score` tool produces a **composite risk score from 0 to 100** by weighting four independent signals.
  320. ### The formula
  321. ```
  322. Risk Score = (CVSS × 0.20) + (EPSS × 0.35) + (KEV × 0.30) + (PoC × 0.15)
  323. ```
  324. | Component | Weight | What It Captures |
  325. |-----------|--------|-----------------|
  326. | **CVSS v3.1 Base Score** | 20% | Theoretical worst-case severity |
  327. | **EPSS Probability** | 35% | Statistical likelihood of exploitation in the next 30 days |
  328. | **CISA KEV Status** | 30% | Confirmed active exploitation in the wild |
  329. | **PoC Availability** | 15% | Public exploit code lowers the barrier for attackers |
  330. ### Boost multipliers
  331. - **KEV + active PoC** → ×1.15
  332. - **CVSS ≥ 9.0 + EPSS > 0.7** → ×1.10
  333. - **Published < 7 days ago** → ×1.05
  334. Score is capped at 100.
  335. ### Risk Scoring — v1 (2026-06)
  336. The numeric scorer is **scoring_version `1.0`** (surfaced in `triage_cve`, `calculate_risk_score`, and `health_check`). The linear weighted sum above is the v1 default for the *numeric* score, with one hard override:
  337. - **CISA KEV hard override:** a KEV-listed CVE is confirmed exploited in the wild, the single strongest exploitation signal. Its label can never be lower than **CRITICAL** and its score is clamped to **≥ 76**, regardless of CVSS/EPSS. (A KEV CVE with a low CVSS and low EPSS still returns CRITICAL / 76.)
  338. - CVSS is treated as a **severity** signal, not an exploitation-likelihood signal (per Allodi & Massacci 2014); EPSS and KEV carry the exploitation signal.
  339. - An experimental **SSVC v2** gated decision (CISA Deployer model → `Act` / `Attend` / `Track*` / `Track`) is available via `triage_cve(depth="deep")` as a qualitative, explainable alternative to the 0–100 number.
  340. | Score | Label | Recommended Action |
  341. |-------|-------|--------------------|
  342. | **0 – 25** | **LOW** | Schedule for next maintenance window |
  343. | **26 – 50** | **MEDIUM** | Patch within 30 days per SLA |
  344. | **51 – 75** | **HIGH** | Patch within 7 days; escalate to team lead |
  345. | **76 – 100** | **CRITICAL** | **Patch within 24–48 hours.** Emergency change window. |
  346. ### Why these weights?
  347. **EPSS gets the highest weight (35%)** because it's the single best predictor of actual exploitation — far better than CVSS alone. A CVSS 10.0 with EPSS 0.01 is theoretically dangerous but practically unlikely. **KEV at 30%** is ground truth: confirmed exploitation, not a prediction. **CVSS at 20%** captures severity context for new CVEs with insufficient EPSS data. **PoC at 15%** reflects that public exploits dramatically accelerate real-world attacks.
  348. ---
  349. ## 🆕 What's new in v0.2.0
  350. - **`triage_cve` orchestrator** — one tool call that fans out NVD + EPSS + CISA KEV (+ public PoC discovery for `depth != "quick"`) concurrently, computes the composite risk score, and returns a clean report. `depth` is `quick` / `standard` (default) / `deep`; **`deep`** additionally emits the SSVC v2 gated decision.
  351. - **New upstream sources** — VulnCheck NVD++ (a transparent NVD fallback used automatically inside `triage_cve` when NIST NVD is unreachable/throttled), CIRCL hashlookup, and the HIBP Pwned Passwords range API.
  352. - **KEV hard-override scoring** + **`scoring_version`** — KEV-listed CVEs are always CRITICAL (score ≥ 76); the scoring version is reported in `triage_cve` and `health_check`.
  353. - **HTTP transport** — set `MCP_TRANSPORT=http` to serve streamable-HTTP on `HOST:PORT` (default `0.0.0.0:8000`, stateless) instead of stdio. Ships with a `Dockerfile`.
  354. - **Resources & prompts** — resources `kev://catalog`, `epss://scores/{cve_id}`, and `manifest://tool-hash` (SHA-256 over the registered tool surface); prompts `patch_decision`, `compare_and_prioritize`, and `dependency_triage`.
  355. - **Security posture** — the server never registers a sampling handler / never issues `sampling/createMessage` (Unit 42 MCP-sampling attack vector); new outbound paths are scheme/host-allowlisted.
  356. ---
  357. ## 🌐 Data sources
  358. | # | Source | Data Provided | Auth | Rate Limit (Free) |
  359. |---|--------|--------------|------|-------------------|
  360. | 1 | **NVD** | CVE details, CVSS, CWEs, CPEs | `apiKey` header (optional) | 5 req/30s (50 with key) |
  361. | 2 | **EPSS** | Exploitation probability and percentiles | None | 1,000 req/min |
  362. | 3 | **CISA KEV** | Actively exploited CVE catalog | None | Static file |
  363. | 4 | **OSV.dev** | Open-source package vulnerabilities | None | No published limit |
  364. | 5 | **GitHub Advisories** | GHSA advisories, patches, affected versions | `Bearer` token | 60/hr (5,000 with PAT) |
  365. | 6 | **MITRE ATT&CK** | TTPs, techniques, mitigations | None | No published limit |
  366. | 7 | **AbuseIPDB** | IP abuse confidence, reports, ISP, geo | `Key` header | 1,000 checks/day |
  367. | 8 | **GreyNoise** | IP noise/scan activity, classification | `key` header | 50 queries/week |
  368. | 9 | **Shodan** | Open ports, services, banners, CVEs | `key` query param | Basic lookups |
  369. | 10 | **VirusTotal** | Multi-AV scan results, reputation | `x-apikey` header | 500/day, 4/min |
  370. | 11 | **MalwareBazaar** | Malware samples, hashes, signatures | `Auth-Key` header | Fair use |
  371. | 12 | **ThreatFox** | IOCs linked to malware families | `Auth-Key` header | Fair use |
  372. | 13 | **Ransomwhere** | Ransomware BTC addresses and transactions | None | No published limit |
  373. | 14 | **URLScan.io** | URL scanning, screenshots, DOM | `API-Key` header | 5,000 public scans/day |
  374. | 15 | **CIRCL PDNS** | Historical passive DNS records | HTTP Basic Auth | Partner access |
  375. | 16 | **GitHub Code Search** | Exploit PoC repository search | `Bearer` token | Shared with GHSA limits |
  376. | 17 | **Exploit-DB** | Public exploit database CSV | None | No published limit |
  377. | 18 | **Nuclei Templates** | Community detection templates | None | No published limit |
  378. | 19 | **MSRC** | Microsoft security advisories | None | No published limit |
  379. | 20 | **Red Hat Security** | Red Hat CVE advisories | None | No published limit |
  380. | 21 | **Ubuntu Security** | Ubuntu CVE tracker | None | No published limit |
  381. | 22 | **VulnCheck NVD++** | NVD-schema CVE records (transparent NVD fallback) | `Bearer` token (free Community) | Per VulnCheck Community tier |
  382. | 23 | **CIRCL hashlookup** | Known-good file metadata (NSRL + others), `hashlookup:trust` | None | Best-effort |
  383. | 24 | **HIBP Pwned Passwords** | Breached-password counts via k-anonymity range API | None | No hard limit |
  384. ---
  385. ## 🧪 Running tests
  386. ```bash
  387. # Run the full test suite
  388. pytest tests/ -v
  389. # Run specific test files
  390. pytest tests/test_validators.py tests/test_risk_scorer.py -v
  391. # Run with coverage
  392. pytest tests/ -v --cov=src/cve_mcp --cov-report=term-missing
  393. ```
  394. ### Test with the MCP Inspector
  395. ```bash
  396. npx @modelcontextprotocol/inspector python -m cve_mcp.server
  397. ```
  398. Opens at `http://localhost:6274` — interactively test each tool, view input schemas, and inspect response formats.
  399. ### What tests cover
  400. - **Unit tests:** Risk score calculation, CVSS vector parsing, input validation
  401. - **Integration tests:** Tool registration, parameter validation, error handling for missing keys
  402. - **Cache tests:** SQLite cache writes, TTL expiration, cache hit/miss
  403. - **Security tests:** Private IP blocking, XML bomb protection (defusedxml), input sanitization
  404. ---
  405. ## 🏛️ Architecture deep dive
  406. ### File structure
  407. ```
  408. src/cve_mcp/
  409. ├── server.py # FastMCP server — all 27 @mcp.tool() definitions
  410. ├── config.py # Environment config and API base URLs
  411. ├── models.py # Pydantic models (CVERecord, KEVEntry, EPSSScore, ...)
  412. ├── audit.py # Rotating audit log (50MB, 5 backups)
  413. ├── api/
  414. │ ├── nvd_client.py # NVD REST API v2.0
  415. │ ├── osv_client.py # OSV.dev package vulnerability API
  416. │ ├── epss_client.py # FIRST EPSS API
  417. │ ├── kev_client.py # CISA KEV catalog
  418. │ ├── ip_intel.py # AbuseIPDB + GreyNoise
  419. │ ├── domain_intel.py # crt.sh + CIRCL passive DNS
  420. │ ├── shodan_client.py # Shodan host intelligence
  421. │ ├── hash_intel.py # MalwareBazaar + VirusTotal
  422. │ ├── url_safety.py # URLScan.io
  423. │ ├── malware_intel.py # ThreatFox IOC lookup
  424. │ ├── ransomware_intel.py# Ransomwhere Bitcoin address lookup
  425. │ ├── exploit_intel.py # GitHub PoC/exploit search
  426. │ ├── vendor_advisory.py # MSRC + Red Hat + Ubuntu advisories
  427. │ ├── attack_mapping.py # MITRE ATT&CK STIX mapping
  428. │ ├── cve_timeline.py # CVE event timeline builder
  429. │ ├── dependency_scan.py # OSV-based dependency scanning
  430. │ ├── poc_checker.py # GitHub + Exploit-DB + Nuclei PoC search
  431. │ ├── report_generator.py# Vuln report + CVE comparison matrix
  432. │ └── rate_limiter.py # Token bucket rate limiter for NVD
  433. ├── cache/
  434. │ └── sqlite_cache.py # Async SQLite cache with per-key TTL
  435. └── utils/
  436. ├── validators.py # CVE ID normalization, IP/hash validation
  437. └── risk_scorer.py # Composite risk score computation
  438. ```
  439. ### Caching strategy
  440. | Resource | TTL |
  441. |----------|-----|
  442. | CVE records (NVD) | 1 hour |
  443. | EPSS scores | 6 hours |
  444. | KEV catalog | 1 hour |
  445. | IP / domain intel | 1 hour |
  446. | Exploit-DB CSV | 24 hours |
  447. | ATT&CK STIX data | 24 hours |
  448. | Ransomware intel | 24 hours |
  449. ### Audit log
  450. Every tool invocation is logged to `~/.cve-mcp/audit.log`:
  451. ```json
  452. {
  453. "timestamp": "2026-04-14T10:23:45.123Z",
  454. "tool": "lookup_cve",
  455. "parameters": {"cve_id": "CVE-2024-3400"},
  456. "duration_ms": 342,
  457. "cache_hit": false,
  458. "status": "ok"
  459. }
  460. ```
  461. API keys and response payloads are **never written to audit logs**.
  462. ---
  463. ## 🔐 Security and privacy
  464. ### What data leaves your machine
  465. - **Outbound HTTPS only** — no inbound ports opened, no telemetry
  466. - CVE IDs, IPs, hashes, domains, and package names are sent to respective APIs for lookup
  467. - API responses are cached locally in SQLite — cached data stays on your machine
  468. ### Private IP blocking
  469. All network intelligence tools block private and reserved IP ranges before any external API call:
  470. - `10.0.0.0/8`, `172.16.0.0/12`, `192.168.0.0/16` (RFC 1918)
  471. - `127.0.0.0/8` (loopback), `169.254.0.0/16` (link-local)
  472. - `::1`, `fc00::/7` (IPv6 private)
  473. ### API key protection
  474. - Keys loaded from environment variables only — never hardcoded
  475. - `.env` is gitignored
  476. - Keys never logged, cached, or included in audit entries
  477. ### XML safety
  478. `defusedxml` is used for all XML parsing to prevent XML bomb attacks (billion laughs, XXE injection).
  479. ---
  480. ## 🔧 Troubleshooting
  481. ### Server won't start
  482. ```bash
  483. # Ensure virtual environment is activated and package is installed
  484. pip install -e .
  485. python --version # must be 3.10+
  486. ```
  487. **Claude Desktop doesn't show the hammer icon (🔨)**
  488. - Check for JSON syntax errors (no trailing commas) in your config
  489. - Use **absolute paths** — relative paths silently fail
  490. - Fully quit Claude Desktop (Cmd+Q / Alt+F4) and restart
  491. ### NVD rate limited
  492. ```bash
  493. # Add your free NVD API key to .env
  494. NVD_API_KEY=your-key-here
  495. # https://nvd.nist.gov/developers/request-an-api-key
  496. ```
  497. The server queues excess requests automatically, but with a key you get 10× throughput.
  498. ### GreyNoise 401 Unauthorized
  499. ```bash
  500. # Verify your key works:
  501. curl -H "key: YOUR_KEY" https://api.greynoise.io/v3/ip/8.8.8.8
  502. # The server uses /v3/ip/{ip} — NOT the deprecated /v3/community endpoint
  503. ```
  504. ### Windows encoding issues
  505. ```powershell
  506. $env:PYTHONUTF8 = "1"
  507. $env:PYTHONIOENCODING = "utf-8"
  508. ```
  509. ---
  510. ## 🗺️ Roadmap and known limitations
  511. ### What the server does NOT do
  512. - **No active scanning** — intelligence/lookup only, does not probe your infrastructure
  513. - **No write operations** — reads from external APIs only (except URLScan submissions)
  514. - **No CVSS v4.0 scoring** — built-in calculator handles v3.1 only; NVD-provided v4.0 scores are displayed but not recalculated
  515. ### Known API limitations
  516. - NVD returns max **2,000 results per query**
  517. - EPSS scores for brand-new CVEs (< 24 hours old) may not exist yet
  518. - CISA KEV updates on US business days only
  519. - GreyNoise community tier: **50 queries/week**
  520. - VirusTotal free tier: **4 requests/minute**
  521. - CIRCL PDNS requires manual registration and approval
  522. - Ransomwhere has a **90-day embargo** on new addresses
  523. ### Planned improvements
  524. - CVSS v4.0 local calculator
  525. - Webhook/alerting for KEV additions and EPSS score changes on a CVE watchlist
  526. - STIX 2.1 export for SIEM integration
  527. - Docker container with zero-install deployment
  528. - Streamable HTTP transport (MCP SSE)
  529. - Additional sources: Censys, SecurityTrails, VulnCheck
  530. ---
  531. ## 🤝 Contributing
  532. Contributions are welcome.
  533. ### Adding a new tool
  534. 1. Add the tool function in `server.py` with the `@mcp.tool()` decorator
  535. 2. Add input validation in `utils/validators.py`
  536. 3. Implement the API client in `api/`
  537. 4. Add tests in `tests/`
  538. 5. Update this README
  539. ```python
  540. @mcp.tool()
  541. async def my_new_tool(param: str, ctx: Context = None) -> str:
  542. """
  543. One-line description for Claude to know when to use this tool.
  544. Args:
  545. param: Description of the parameter
  546. """
  547. app = _get_app(ctx)
  548. # validate → cache check → API call → cache write → audit → return
  549. ```
  550. ### Testing requirements
  551. - All new tools must have at least one offline test with mocked responses
  552. - Risk score changes must include formula verification test cases
  553. - Network tools must include a test verifying private IP blocking
  554. - All tests must pass: `pytest tests/ -v`
  555. ---
  556. ## 📄 License
  557. MIT License — see [LICENSE](LICENSE) for details.
  558. ```
  559. Copyright (c) 2025-2026 Mahipal Jangra (mukul975)
  560. ```
  561. ---
  562. <p align="center">
  563. Built with 🔐 by <a href="https://github.com/mukul975">Mahipal Jangra</a> · Berlin, Germany<br>
  564. <em>Turning security intelligence into conversation.</em>
  565. </p>

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.