Cve MCP Server

🛡️ CVE MCP Server

触手可及的 AI 驱动安全情报 —— 27 个工具、21 个数据源、一个协议。

一个生产级的 Model Context Protocol (MCP) 服务器，可将 Claude 变成一个全谱系的安全分析师。无需在 NVD、EPSS、CISA KEV、Shodan、VirusTotal 和 GreyNoise 等平台上同时打开 15+ 个浏览器标签页——只需向 Claude 提一个问题，就能在几秒内获得关联后的综合情报。基于 Python、FastMCP、httpx、aiosqlite、Pydantic v2 和 defusedxml 构建。

痛点： 对单个 CVE 进行分诊，需要在 NVD 查询 CVSS 评分、在 EPSS 查询利用概率、在 CISA KEV 查询主动利用状态、在 GitHub 查询补丁、在 VirusTotal 查询恶意软件关联——然后还得在脑中做关联分析。面对 50 个 CVE？一天的工时就这样没了。

解决方案： CVE MCP Server 让 Claude 直接访问横跨 21 个 API 的 27 个安全工具。问一句"我们应该修补 CVE-2024-3400 吗？"，Claude 就会并行查询所有相关数据源、计算综合风险评分，并给出带证据的优先级建议。

---

🌍 GARS-2026 —— 全球智能体 AI 就绪度调查

我正在开展一项全球性学术研究，用于衡量安全专业人士、开发者和企业团队对智能体 AI（Agentic AI）——即 MCP 服务器、工具调用、治理以及人在回路（human-in-the-loop）工作流——的实际就绪程度。

如果你使用本仓库，你的回答将是一个极具价值的样本数据点。

📋 参与调查（10 分钟）： Survey

• 60 道问题 · 匿名 · 由 SRH Berlin 监督
• 你将获得 50 个 Casky Tokens，可用于抢先体验 casky.ai
• 结果将以 CC-BY 4.0 协议开放获取发布

---

📑 目录

• 架构
• 工具清单
• 安装
• API 密钥配置
• 配置
• 快速开始
• 使用示例
• 风险评分详解
• 数据源
• 运行测试
• 架构深入解析
• 安全与隐私
• 故障排查
• 路线图与已知限制
• 贡献指南
• 许可证

---

🏗️ 架构

┌─────────────────────────────────────────────────────────────────────┐
│                        Claude Desktop / Claude Code                 │
│                         (MCP Client via stdio)                      │
└──────────────────────────────┬──────────────────────────────────────┘
                               │ Model Context Protocol (stdio)
                               ▼
┌─────────────────────────────────────────────────────────────────────┐
│                        CVE MCP Server (Python)                      │
│  ┌─────────────┐  ┌──────────────┐  ┌───────────────┐              │
│  │  27 MCP      │  │  Composite   │  │  SQLite Cache │              │
│  │  Tools       │  │  Risk Engine │  │  + Audit Log  │              │
│  └──────┬──────┘  └──────┬───────┘  └───────┬───────┘              │
│         │                │                   │                      │
│  ┌──────┴────────────────┴───────────────────┴──────┐               │
│  │              Async HTTP Client (httpx)            │               │
│  │         Rate Limiter · Response Cache             │               │
│  └──────────────────────┬───────────────────────────┘               │
└─────────────────────────┼───────────────────────────────────────────┘
                          │ HTTPS (outbound only)
          ┌───────────────┼───────────────────────────┐
          ▼               ▼                           ▼
┌──────────────┐ ┌──────────────┐            ┌──────────────┐
│ VULNERABILITY│ │   NETWORK    │            │   THREAT     │
│ INTELLIGENCE │ │ INTELLIGENCE │            │ INTELLIGENCE │
├──────────────┤ ├──────────────┤            ├──────────────┤
│ NVD API 2.0  │ │ AbuseIPDB    │            │ VirusTotal   │
│ EPSS / FIRST │ │ GreyNoise v3 │            │ MalwareBazaar│
│ CISA KEV     │ │ Shodan       │            │ ThreatFox    │
│ OSV.dev      │ │ CIRCL PDNS   │            │ Ransomwhere  │
│ GitHub GHSA  │ │              │            │ AlienVault   │
│ MITRE ATT&CK │ │              │            │ URLScan.io   │
└──────────────┘ └──────────────┘            └──────────────┘

所有流量均为仅限出站的 HTTPS —— 不开放任何入站端口。API 密钥从环境变量加载，绝不写入日志。所有查询工具均屏蔽私有/内部 IP 地址。

---

🔍 工具清单（27 个工具）

核心漏洞情报（8 个工具）

工具	描述	是否需要 API 密钥	使用示例
lookup_cve	从 NVD 获取详细的 CVE 记录，包括 CVSS 评分、CWE、受影响产品、参考链接和时间线	免费 / 无需密钥（建议配置密钥）	lookup_cve("CVE-2024-3400")
search_cves	按关键词、产品名称、严重程度或日期范围在 NVD 中搜索 CVE	免费 / 无需密钥（建议配置密钥）	search_cves(keyword="Apache Log4j", severity="CRITICAL")
get_epss_score	获取一个或多个 CVE 的 EPSS 利用概率（0–1）及百分位排名	免费 / 无需密钥	get_epss_score("CVE-2024-3400")
check_kev_status	检查某个 CVE 是否出现在 CISA 的已知被利用漏洞（Known Exploited Vulnerabilities）目录中	免费 / 无需密钥	check_kev_status("CVE-2021-44228")
get_cvss_details	解析并逐项说明 CVSS v3.1 向量字符串	免费 / 无需密钥	get_cvss_details("CVSS:3.1/AV:N/AC:L/PR:N/UI:N/S:C/C:H/I:H/A:H")
get_cwe_info	从内置数据库中按 CWE ID 查询通用缺陷枚举（Common Weakness Enumeration）详情	免费 / 无需密钥	get_cwe_info("CWE-79")
get_cve_references	提取并分类某个 CVE 的所有参考链接（补丁、公告、漏洞利用）	免费 / 无需密钥（建议配置密钥）	get_cve_references("CVE-2023-44487")
bulk_cve_lookup	单次调用批量获取最多 20 个 CVE 的详情，并进行并行丰富化处理	免费 / 无需密钥（建议配置密钥）	bulk_cve_lookup(["CVE-2024-3400", "CVE-2023-44487"])

漏洞利用与攻击情报（4 个工具）

工具	描述	是否需要 API 密钥	使用示例
search_exploits	在 GitHub 中搜索公开的概念验证（PoC）漏洞利用及利用代码仓库	GITHUB_TOKEN（可选）	search_exploits("CVE-2024-3400")
get_mitre_techniques	将 CVE 或 CWE 映射到相关的 MITRE ATT&CK 技术、战术和缓解措施	免费 / 无需密钥	get_mitre_techniques("CVE-2021-44228")
check_poc_availability	跨多个数据源判断某个 CVE 是否存在已知的概念验证代码	GITHUB_TOKEN（可选）	check_poc_availability("CVE-2024-3400")
get_attack_patterns	检索与 CWE 或 CVE 关联的 CAPEC 攻击模式详情	免费 / 无需密钥	get_attack_patterns("CWE-89")

阶段 3：高级风险与报告（4 个工具）

工具	描述	是否需要 API 密钥	使用示例
calculate_risk_score	基于 CVSS、EPSS、KEV 状态和 PoC 可用性，计算 0–100 的综合风险评分	免费 / 无需密钥（建议配置密钥）	calculate_risk_score("CVE-2024-3400")
generate_risk_report	为一个或多个 CVE 生成带建议的格式化高管安全报告	免费 / 无需密钥（建议配置密钥）	generate_risk_report(["CVE-2024-3400", "CVE-2023-44487"])
prioritize_cves	按综合风险评分对 CVE 列表进行排序，用于分诊优先级判定	免费 / 无需密钥（建议配置密钥）	prioritize_cves(["CVE-2024-3400", "CVE-2023-4966", "CVE-2023-44487"])
get_trending_cves	基于高 EPSS 评分和近期 KEV 新增项，检索热门 CVE	免费 / 无需密钥	get_trending_cves(days=7, min_epss=0.5)

网络情报（4 个工具）

工具	描述	是否需要 API 密钥	使用示例
lookup_ip_reputation	通过 AbuseIPDB 检查 IP 地址的滥用历史及置信度评分	ABUSEIPDB_API_KEY	lookup_ip_reputation("185.220.101.34")
check_ip_noise	向 GreyNoise 查询 IP 的扫描/攻击活动、分类及关联 CVE	GREYNOISE_API_KEY	check_ip_noise("185.220.101.34")
shodan_host_lookup	通过 Shodan 获取某个 IP 的开放端口、服务、banner 和漏洞信息	SHODAN_API_KEY	shodan_host_lookup("8.8.8.8")
passive_dns_lookup	从 CIRCL Passive DNS 检索某个域名的历史 DNS 解析数据	CIRCL_PDNS_USER + CIRCL_PDNS_PASSWORD	passive_dns_lookup("example.com")

威胁情报（4 个工具）

工具	描述	是否需要 API 密钥	使用示例
virustotal_lookup	用 70+ 家杀毒引擎分析文件哈希、URL、域名或 IP	VIRUSTOTAL_API_KEY	virustotal_lookup(hash="44d88612fea8a8f36de82e1278abb02f")
search_malware	在 MalwareBazaar 中按哈希、标签或签名搜索恶意软件样本	ABUSECH_AUTH_KEY（可选）	search_malware(tag="Emotet")
search_iocs	向 ThreatFox 查询与恶意软件家族关联的妥协指标（IOC）	ABUSECH_AUTH_KEY（可选）	search_iocs(malware="CobaltStrike")
check_ransomware	从 Ransomwhere 查询勒索软件支付地址及交易数据	免费 / 无需密钥	check_ransomware(address="bc1q...")

DevSecOps（3 个工具）

工具	描述	是否需要 API 密钥	使用示例
scan_dependencies	依据 OSV.dev 扫描包名称和版本，检查已知漏洞	免费 / 无需密钥	scan_dependencies(ecosystem="PyPI", packages={"requests": "2.28.0"})
scan_github_advisories	按生态系统、包名或严重程度搜索 GitHub 安全公告	GITHUB_TOKEN（可选）	scan_github_advisories(ecosystem="pip", package="django")
urlscan_check	提交 URL 进行扫描，或从 URLScan.io 检索已有的扫描结果	URLSCAN_API_KEY	urlscan_check("https://suspicious-site.com")

---

📦 安装

前置要求

• Python 3.10+（推荐 3.11 或 3.12）
• pip 或 uv 包管理器
• Git（用于克隆仓库）
• 可访问环境变量的终端

逐步安装

# 1. 克隆仓库
git clone https://github.com/mukul975/cve-mcp-server.git
cd cve-mcp-server

# 2. 创建并激活虚拟环境
python -m venv venv

# macOS / Linux:
source venv/bin/activate

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

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

# 3. 安装依赖
pip install -e .

# 4. 复制并配置环境变量
cp .env.example .env
# 编辑 .env，填入你的 API 密钥（见下方 API 密钥配置章节）

# 5. 验证服务器可以启动
python -m cve_mcp.server

使用 uv（更快的替代方案）

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

带测试依赖安装

pip install -e ".[test]"

---

🔑 API 密钥配置

API 密钥按优先级组织——先获取 Tier 1 密钥，用免费工具获得最大覆盖率，随后按需逐步添加 Tier 2 和 Tier 3。

Tier 1：高优先级（免费、即时可用、覆盖率最大）

环境变量	启用功能	获取方式	免费额度限制	是否必需
NVD_API_KEY	使 NVD 查询提速 10 倍（50 次/30 秒 vs 5 次）	在 nvd.nist.gov 申请	每 30 秒 50 次请求	可选，但强烈建议配置
GITHUB_TOKEN	GitHub 安全公告搜索 + 漏洞利用 PoC 搜索	在 github.com/settings/tokens 创建 PAT	每小时 5,000 次请求	可选（无令牌为 60 次/小时）

Tier 2：推荐（免费账户，价值显著）

环境变量	启用功能	获取方式	免费额度限制	是否必需
ABUSEIPDB_KEY	IP 信誉查询	在 abuseipdb.com 注册	每天 1,000 次检查	IP 工具必需
VIRUSTOTAL_KEY	文件/URL/域名/IP 恶意软件扫描	在 virustotal.com 注册	每天 500 次查询，每分钟 4 次	VT 工具必需
GREYNOISE_API_KEY	IP 噪音/扫描活动情报	在 viz.greynoise.io 注册	每周 50 次查询（社区版）	GreyNoise 工具必需
SHODAN_KEY	主机/端口/服务侦察	在 account.shodan.io 注册	基础主机查询（免费版）	Shodan 工具必需

Tier 3：可选（扩展情报）

环境变量	启用功能	获取方式	免费额度限制	是否必需
URLSCAN_KEY	URL 扫描与网站分析	在 urlscan.io 注册	每天 5,000 次公开扫描	可选
CIRCL_PDNS_USER	CIRCL Passive DNS 查询	在 circl.lu 申请访问	仅限合作伙伴访问	可选
CIRCL_PDNS_PASS	CIRCL Passive DNS 身份认证	随 CIRCL 注册一起提供	仅限合作伙伴访问	可选

⚡ 零密钥启动： 有八个工具无需任何 API 密钥即可使用——EPSS、CISA KEV、OSV.dev、MITRE ATT&CK、CWE 查询、CVSS 解析、Ransomwhere 以及 NVD（限速模式）。你可以立即开始使用服务器，并逐步添加密钥。

---

⚙️ 配置

环境变量（.env.example）

# NVD API key — free at https://nvd.nist.gov/developers/request-an-api-key
# Without key: 5 req/30s  |  With key: 50 req/30s
NVD_API_KEY=

# GitHub token — increases rate limit from 60/hr to 5000/hr (no scopes needed)
GITHUB_TOKEN=

# Threat intelligence keys (all optional — tools degrade gracefully without them)
ABUSEIPDB_KEY=       # https://www.abuseipdb.com/account/api
VIRUSTOTAL_KEY=      # https://www.virustotal.com/gui/join-us
URLSCAN_KEY=         # https://urlscan.io/user/signup
SHODAN_KEY=          # https://account.shodan.io/register

# GreyNoise — uses /v3/ip/{ip} endpoint (NOT the deprecated /v3/community)
GREYNOISE_API_KEY=   # https://viz.greynoise.io/signup

# CIRCL Passive DNS — requires partner registration
CIRCL_PDNS_USER=
CIRCL_PDNS_PASS=

# Optional overrides
CACHE_DB_PATH=       # defaults to ~/.cve-mcp/cache.db
AUDIT_LOG_PATH=      # defaults to ~/.cve-mcp/audit.log
REQUEST_TIMEOUT=30   # HTTP timeout in seconds
MAX_RETRIES=3        # retries on transient errors

Claude Desktop 配置

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "cve-mcp": {
      "command": "python",
      "args": ["-m", "cve_mcp.server"],
      "cwd": "/absolute/path/to/cve-mcp-server",
      "env": {
        "NVD_API_KEY": "your-key-here",
        "GITHUB_TOKEN": "ghp_xxxxxxxxxxxxxxxxxxxx",
        "ABUSEIPDB_KEY": "your-abuseipdb-key",
        "GREYNOISE_API_KEY": "your-greynoise-key",
        "SHODAN_KEY": "your-shodan-key"
      }
    }
  }
}

⚠️ 重要提示： 请务必使用绝对路径。修改配置后需完全退出 Claude Desktop（Cmd+Q / Alt+F4）再重启——仅重新加载是不够的。

Claude Code 配置

# Basic setup
claude mcp add cve-mcp -- python -m cve_mcp.server

# With environment variables (repeat -e for each key)
claude mcp add cve-mcp -e NVD_API_KEY=your_key -e VULNCHECK_TOKEN=your_token -- python -m cve_mcp.server
# Or just run from the project directory — python-dotenv auto-loads .env on startup

# Verify it's connected
claude mcp list

---

🚀 快速开始

步骤 1：安装（2 分钟）

git clone https://github.com/mukul975/cve-mcp-server.git
cd cve-mcp-server
python -m venv venv && source venv/bin/activate
pip install -e .

步骤 2：先用免费工具测试

无需 .env 文件。将服务器添加到 Claude Desktop 或 Claude Code，然后试试：

"CVE-2021-44228 是什么？它正在被积极利用吗？"

Claude 将使用 lookup_cve（NVD）、get_epss_score（EPSS）和 check_kev（CISA KEV）——全部免费、无需密钥。

"扫描以下 Python 包是否存在漏洞：requests 2.28.0、flask 2.2.0、django 3.2.0"

步骤 3：添加第一个密钥，性能提升 10 倍

echo 'NVD_API_KEY=your-key-here' > .env

在 nvd.nist.gov 申请免费 NVD 密钥——邮件即时发送，可将速率限制从每 30 秒 5 次提升至 50 次。

步骤 4：全功率模式

配置好 Tier 1 和 Tier 2 密钥后：

"计算 CVE-2024-3400 的风险评分，并告诉我是否应立即修补。"

---

💬 使用示例

场景 1："我们应该立即修补 Log4Shell 吗？"

你： 分析 CVE-2021-44228（Log4Shell）是否需要立即修补。给我风险评分和你的建议。

Claude 会在幕后编排多个工具：

→ lookup_cve("CVE-2021-44228")
  CVSS 3.1: 10.0 (CRITICAL) | AV:N/AC:L/PR:N/UI:N/S:C/C:H/I:H/A:H

→ get_epss_score("CVE-2021-44228")
  EPSS: 0.97531 (97.5%) | Percentile: 99.99%

→ check_kev("CVE-2021-44228")
  ✅ IN CISA KEV — Added 2021-12-10 | Known ransomware use: Yes

→ check_poc_exists("CVE-2021-44228")
  ✅ WEAPONIZED — 300+ public PoC repositories found

→ calculate_risk_score("CVE-2021-44228")
  Risk Score: 97/100 (CRITICAL) | Urgency: PATCH IMMEDIATELY

Claude 的回复： "CVE-2021-44228 得分 97/100（严重）。Apache Log4j 中的远程代码执行漏洞，CVSS 10.0，EPSS 利用概率 97.5%，已确认在 CISA KEV 中被积极利用（包括勒索软件攻击活动），存在 300+ 个公开漏洞利用。请立即修补。"

场景 2："扫描我的 Python requirements.txt"

你： 扫描这些依赖项：requests==2.28.0、flask==2.2.0、django==3.2.0、pillow==9.0.0、cryptography==37.0.0

→ scan_dependencies(ecosystem="PyPI", packages={...})
  Found 12 vulnerabilities across 4 packages

Claude 的回复： "在你的包中发现 12 个漏洞。立即行动： Django 3.2.0（3 个严重 CVE，包括 SQL 注入）、Pillow 9.0.0（堆溢出）、cryptography 37.0.0（OpenSSL 链式漏洞）。请升级至：django>=4.2.16、pillow>=10.3.0、cryptography>=42.0.0。"

场景 3："调查一个可疑 IP"

你： 调查可疑 IP 185.220.101.34 —— 它是恶意的吗？

→ check_ip_reputation("185.220.101.34")
  AbuseIPDB Confidence: 100% | Reports: 4,832 | ISP: Tor Exit Node

→ check_ip_noise("185.220.101.34")
  GreyNoise: MALICIOUS | Tags: [Tor Exit Node, Web Scanner]
  CVEs targeted: CVE-2024-3400, CVE-2023-46805

→ shodan_host_lookup("185.220.101.34")
  Open ports: 22, 80, 443, 9001 | OS: Linux

Claude 的回复： "185.220.101.34 是一个已知的 Tor 出口节点，被 AbuseIPDB 评为 100% 恶意，有 4,832 条滥用举报。GreyNoise 确认其正在主动扫描 CVE-2024-3400（Palo Alto）和 CVE-2023-46805（Ivanti）。建议：在防火墙层面封禁。"

场景 4："生成一份高管安全报告"

你： 为以下 CVE 生成一份高管安全报告：CVE-2024-3400、CVE-2023-44487、CVE-2023-4966、CVE-2024-21887

→ compare_cves([...])
  Compiles: NVD, EPSS, KEV, PoC availability, MITRE ATT&CK mapping
  Generates: Ranked risk table, remediation timeline, executive summary

---

📊 风险评分详解

calculate_risk_score 工具通过加权四个独立信号，产出 0 到 100 的综合风险评分。

公式

Risk Score = (CVSS × 0.20) + (EPSS × 0.35) + (KEV × 0.30) + (PoC × 0.15)

组成要素	权重	所反映的内容
CVSS v3.1 基础分	20%	理论上的最坏情况严重程度
EPSS 概率	35%	未来 30 天内被利用的统计可能性
CISA KEV 状态	30%	已确认在野积极利用
PoC 可用性	15%	公开漏洞利用代码降低了攻击者的门槛

增益乘数

• KEV + 活跃 PoC → ×1.15
• CVSS ≥ 9.0 + EPSS > 0.7 → ×1.10
• 发布时间 < 7 天 → ×1.05

评分上限为 100。

风险等级

分数	等级	建议操作
0 – 25	低	安排到下一个维护窗口处理
26 – 50	中	按 SLA 在 30 天内修补
51 – 75	高	7 天内修补；升级至团队负责人
76 – 100	严重	在 24–48 小时内修补。 启动紧急变更窗口。

为什么采用这些权重？

EPSS 获得最高权重（35%），因为它是预测实际利用的最佳单一指标——远优于仅靠 CVSS。一个 CVSS 10.0 但 EPSS 仅 0.01 的漏洞，理论上有威胁，但实际被利用的可能性很低。KEV 占 30% 是事实依据：已确认的利用，而非预测。CVSS 占 20% 为 EPSS 数据不足的新 CVE 提供严重程度上下文。PoC 占 15% 反映公开漏洞利用会大幅加速真实世界的攻击。

---

🌐 数据源

#	数据源	提供的数据	认证	速率限制（免费）
1	NVD	CVE 详情、CVSS、CWE、CPE	apiKey 请求头（可选）	5 次/30 秒（带密钥 50 次）
2	EPSS	利用概率及百分位	无	1,000 次/分钟
3	CISA KEV	积极利用 CVE 目录	无	静态文件
4	OSV.dev	开源包漏洞	无	未公布限制
5	GitHub Advisories	GHSA 公告、补丁、受影响版本	Bearer 令牌	60 次/小时（带 PAT 5,000 次）
6	MITRE ATT&CK	TTP、技术、缓解措施	无	未公布限制
7	AbuseIPDB	IP 滥用置信度、举报、ISP、地理位置	Key 请求头	每天 1,000 次检查
8	GreyNoise	IP 噪音/扫描活动、分类	key 请求头	每周 50 次查询
9	Shodan	开放端口、服务、banner、CVE	key 查询参数	基础查询
10	VirusTotal	多引擎扫描结果、信誉	x-apikey 请求头	每天 500 次，每分钟 4 次
11	MalwareBazaar	恶意软件样本、哈希、签名	Auth-Key 请求头	合理使用
12	ThreatFox	关联恶意软件家族的 IOC	Auth-Key 请求头	合理使用
13	Ransomwhere	勒索软件 BTC 地址及交易	无	未公布限制
14	URLScan.io	URL 扫描、截图、DOM	API-Key 请求头	每天 5,000 次公开扫描
15	CIRCL PDNS	历史被动 DNS 记录	HTTP Basic Auth	合作伙伴访问
16	GitHub Code Search	漏洞利用 PoC 仓库搜索	Bearer 令牌	与 GHSA 限制共享
17	Exploit-DB	公开漏洞利用数据库 CSV	无	未公布限制
18	Nuclei Templates	社区检测模板	无	未公布限制
19	MSRC	微软安全公告	无	未公布限制
20	Red Hat Security	红帽 CVE 公告	无	未公布限制
21	Ubuntu Security	Ubuntu CVE 追踪器	无	未公布限制

---

🧪 运行测试

# Run the full test suite
pytest tests/ -v

# Run specific test files
pytest tests/test_validators.py tests/test_risk_scorer.py -v

# Run with coverage
pytest tests/ -v --cov=src/cve_mcp --cov-report=term-missing

使用 MCP Inspector 测试

npx @modelcontextprotocol/inspector python -m cve_mcp.server

在 http://localhost:6274 打开 —— 可交互式测试每个工具、查看输入 schema 并检查响应格式。

测试覆盖范围

• 单元测试： 风险评分计算、CVSS 向量解析、输入校验
• 集成测试： 工具注册、参数校验、密钥缺失时的错误处理
• 缓存测试： SQLite 缓存写入、TTL 过期、缓存命中/未命中
• 安全测试： 私有 IP 屏蔽、XML 炸弹防护（defusedxml）、输入净化

---

🏛️ 架构深入解析

文件结构

src/cve_mcp/
├── server.py              # FastMCP server — all 27 @mcp.tool() definitions
├── config.py              # Environment config and API base URLs
├── models.py              # Pydantic models (CVERecord, KEVEntry, EPSSScore, ...)
├── audit.py               # Rotating audit log (50MB, 5 backups)
├── api/
│   ├── nvd_client.py      # NVD REST API v2.0
│   ├── osv_client.py      # OSV.dev package vulnerability API
│   ├── epss_client.py     # FIRST EPSS API
│   ├── kev_client.py      # CISA KEV catalog
│   ├── ip_intel.py        # AbuseIPDB + GreyNoise
│   ├── domain_intel.py    # crt.sh + CIRCL passive DNS
│   ├── shodan_client.py   # Shodan host intelligence
│   ├── hash_intel.py      # MalwareBazaar + VirusTotal
│   ├── url_safety.py      # URLScan.io
│   ├── malware_intel.py   # ThreatFox IOC lookup
│   ├── ransomware_intel.py# Ransomwhere Bitcoin address lookup
│   ├── exploit_intel.py   # GitHub PoC/exploit search
│   ├── vendor_advisory.py # MSRC + Red Hat + Ubuntu advisories
│   ├── attack_mapping.py  # MITRE ATT&CK STIX mapping
│   ├── cve_timeline.py    # CVE event timeline builder
│   ├── dependency_scan.py # OSV-based dependency scanning
│   ├── poc_checker.py     # GitHub + Exploit-DB + Nuclei PoC search
│   ├── report_generator.py# Vuln report + CVE comparison matrix
│   └── rate_limiter.py    # Token bucket rate limiter for NVD
├── cache/
│   └── sqlite_cache.py    # Async SQLite cache with per-key TTL
└── utils/
    ├── validators.py       # CVE ID normalization, IP/hash validation
    └── risk_scorer.py      # Composite risk score computation

缓存策略

资源	TTL
CVE 记录（NVD）	1 小时
EPSS 评分	6 小时
KEV 目录	1 小时
IP / 域名情报	1 小时
Exploit-DB CSV	24 小时
ATT&CK STIX 数据	24 小时
勒索软件情报	24 小时

审计日志

每次工具调用都会记录到 ~/.cve-mcp/audit.log：

{
  "timestamp": "2026-04-14T10:23:45.123Z",
  "tool": "lookup_cve",
  "parameters": {"cve_id": "CVE-2024-3400"},
  "duration_ms": 342,
  "cache_hit": false,
  "status": "ok"
}

API 密钥和响应负载绝不会写入审计日志。

---

🔐 安全与隐私

离开你机器的数据

• 仅限出站 HTTPS —— 不开放入站端口，无遥测
• CVE ID、IP、哈希、域名和包名会发送至相应 API 进行查询
• API 响应会本地缓存到 SQLite —— 缓存数据始终留在你的机器上

私有 IP 屏蔽

所有网络情报工具在发起任何外部 API 调用前，都会屏蔽私有及保留 IP 段：

• 10.0.0.0/8、172.16.0.0/12、192.168.0.0/16（RFC 1918）
• 127.0.0.0/8（回环）、169.254.0.0/16（链路本地）
• ::1、fc00::/7（IPv6 私有）

API 密钥保护

• 密钥仅从环境变量加载 —— 绝不在代码中硬编码
• .env 已被 gitignore
• 密钥绝不被记录、缓存或写入审计条目

XML 安全

所有 XML 解析均使用 defusedxml，以防止 XML 炸弹攻击（billion laughs、XXE 注入）。

---

🔧 故障排查

服务器无法启动

# Ensure virtual environment is activated and package is installed
pip install -e .
python --version  # must be 3.10+

Claude Desktop 不显示锤子图标（🔨）

• 检查配置中是否存在 JSON 语法错误（不要有尾随逗号）
• 使用绝对路径 —— 相对路径会静默失败
• 完全退出 Claude Desktop（Cmd+Q / Alt+F4）并重启

NVD 被限速

# Add your free NVD API key to .env
NVD_API_KEY=your-key-here
# https://nvd.nist.gov/developers/request-an-api-key

服务器会自动排队处理超量的请求，但配置密钥后即可获得 10 倍吞吐量。

GreyNoise 401 未授权

# Verify your key works:
curl -H "key: YOUR_KEY" https://api.greynoise.io/v3/ip/8.8.8.8
# The server uses /v3/ip/{ip} — NOT the deprecated /v3/community endpoint

Windows 编码问题

$env:PYTHONUTF8 = "1"
$env:PYTHONIOENCODING = "utf-8"

---

🗺️ 路线图与已知限制

服务器不做什么

• 无主动扫描 —— 仅做情报/查询，不会探测你的基础设施
• 无写操作 —— 只读外部 API（URLScan 提交除外）
• 不支持 CVSS v4.0 评分 —— 内置计算器仅处理 v3.1；NVD 提供的 v4.0 分数会展示但不重新计算

已知 API 限制

• NVD 单次查询最多返回 2,000 条结果
• 全新 CVE（不足 24 小时）可能尚无 EPSS 评分
• CISA KEV 仅在美国工作日更新
• GreyNoise 社区版：每周 50 次查询
• VirusTotal 免费版：每分钟 4 次请求
• CIRCL PDNS 需要手动注册并经审批
• Ransomwhere 对新地址设有 90 天禁运期

计划中的改进

• CVSS v4.0 本地计算器
• 针对 CVE 观察列表的 KEV 新增项和 EPSS 评分变动的 Webhook/告警
• 用于 SIEM 集成的 STIX 2.1 导出
• 零安装部署的 Docker 容器
• 可流式 HTTP 传输（MCP SSE）
• 更多数据源：Censys、SecurityTrails、VulnCheck

---

🤝 贡献指南

欢迎贡献代码。

添加新工具

1. 在 server.py 中通过 @mcp.tool() 装饰器添加工具函数
2. 在 utils/validators.py 中添加输入校验
3. 在 api/ 中实现 API 客户端
4. 在 tests/ 中添加测试
5. 更新本 README

@mcp.tool()
async def my_new_tool(param: str, ctx: Context = None) -> str:
    """
    One-line description for Claude to know when to use this tool.

    Args:
        param: Description of the parameter
    """
    app = _get_app(ctx)
    # validate → cache check → API call → cache write → audit → return

测试要求

• 所有新工具必须至少有一个使用模拟响应的离线测试
• 风险评分变更必须包含公式验证测试用例
• 网络工具必须包含一个验证私有 IP 屏蔽的测试
• 所有测试必须通过：pytest tests/ -v

---

📄 许可证

MIT License —— 详见 LICENSE。

Copyright (c) 2025-2026 Mahipal Jangra (mukul975)

---

Built with 🔐 by Mahipal Jangra · Berlin, Germany
Turning security intelligence into conversation.