mukul975/cve-mcp-server

# 🛡️ CVE MCP 服务器  **AI 驱动的安全情报触手可及 —— 27 种工具，21 个数据源，一个协议。** [](https://python.org) [](LICENSE) [](https://modelcontextprotocol.io) [](https://github.com/mukul975/cve-mcp-server) [](https://gofastmcp.com) 一款生产级别的 **模型上下文协议 (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 服务器为 Claude 提供对 27 种安全工具和 21 个 API 的直接访问。询问“是否应该修补 CVE-2024-3400？”，Claude 将并行查询所有相关来源，计算复合风险评分，并给出带有证据的优先级建议。 --- ## 📑 目录 - [架构](#架构) - [工具目录](#-tool-catalog-27-tools) - [安装](#安装) - [API 密钥配置](#-api-keys-setup) - [配置](#配置) - [快速开始](#快速开始) - [使用示例](#-usage-examples) - [风险评分详解](#-risk-score-explained) - [数据源](#-data-sources) - [运行测试](#-running-tests) - [深度架构解析](#-architecture-deep-dive) - [安全与隐私](#-security-and-privacy) - [故障排除](#-troubleshooting) - [路线图与已知限制](#-roadmap-and-known-limitations) - [贡献](#-contributing) - [许可证](#-license) --- ## 🏗️ 架构 ``` ┌─────────────────────────────────────────────────────────────────────┐ │ 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 的已知被利用漏洞目录中 | 免费 / 无密钥 | `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 的通用弱点枚举详情 | 免费 / 无密钥 | `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 上的公开漏洞利用代码和代码仓库 | `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")` | ### 高级风险与报告（4 种工具） | 工具 | 描述 | 需要 API 密钥 | 示例用法 | |------|------|-----------------|---------------| | `calculate_risk_score` | 基于 CVSS、EPSS、KEV 状态和漏洞利用代码可用性计算 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("185220.101.34")` | | `shodan_host_lookup` | 通过 Shodan 获取主机的开放端口、服务、横幅及漏洞信息 | `SHODAN_API_KEY` | `shodan_host_lookup("8.8.8.8")` | | `passive_dns_lookup` | 从 CIRCL 被动 DNS 获取域名的历史解析数据 | `CIRCL_PDNS_USER` + `CIRCL_PDNS_PASSWORD` | `passive_dns_lookup("example.com")` | ### 威胁情报（4 种工具） | 工具 | 描述 | 需要 API 密钥 | 示例用法 | |------|------|-----------------|---------------| | `virustotal_lookup` | 对文件哈希、URL、域名或 IP 地址进行 70 多种杀毒引擎分析 | `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** 用于克隆仓库 - 可访问环境变量的终端 ### 分步安装 ``` # 克隆仓库 git clone https://github.com/mukul975/cve-mcp-server.git cd cve-mcp-server # 创建并激活虚拟环境 python -m venv venv # macOS / Linux: source venv/bin/activate # Windows (PowerShell): .\venv\Scripts\Activate.ps1 # Windows (CMD): venv\Scripts\activate.bat # 安装依赖项 pip install -e . # 复制并配置环境变量 cp .env.example .env # 使用您的 API 密钥编辑 .env（请参阅下方“API 密钥设置”部分） # 验证服务器是否启动 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 # or .venv\Scripts\activate on Windows 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` | 10 倍加速的 NVD 查询（50 请求/30 秒） | [在 nvd.nist.gov 申请](https://nvd.nist.gov/developers/request-an-api-key) | **每 30 秒 50 次请求** | 可选但强烈推荐 | | `GITHUB_TOKEN` | GitHub 安全公告 + 漏洞利用 PoC 搜索 | [在 github.com/settings/tokens 创建](https://github.com/settings/tokens) | **每小时 5,000 次请求** | 可选（无密钥时每小时 60 次） | ### Tier 2：推荐（免费账户，价值显著） | 环境变量 | 启用功能 | 获取方式 | 免费限制 | 是否必需 | |----------|----------|----------|----------|----------| | `ABUSEIPDB_KEY` | IP 信誉查询 | [在 abuseipdb.com 注册](https://www.abuseipdb.com/register) | **每天 1,000 次检查** | 使用 IP 工具必需 | | `VIRUSTOTAL_KEY` | 文件/URL/域名/IP 恶意软件扫描 | [在 virustotal.com 注册](https://www.virustotal.com/gui/join-us) | **每天 500 次查询，每分钟 4 次** | 使用 VT 工具必需 | | `GREYNOISE_API_KEY` | IP 噪声/扫描活动情报 | [在 viz.greynoise.io 注册](https://viz.greynoise.io/signup) | **每周 50 次查询**（社区版） | 使用 GreyNoise 工具必需 | | `SHODAN_KEY` | 主机/端口/服务侦察 | [在 account.shodan.io 注册](https://account.shodan.io) | 基础主机查询（免费层） | 使用 Shodan 工具必需 | ### Tier 3：可选（扩展情报） | 环境变量 | 启用功能 | 获取方式 | 免费限制 | 是否必需 | |----------|----------|----------|----------|----------| | `URLSCAN_KEY` | URL 扫描与网站分析 | [在 urlscan.io 注册](https://urlscan.io/user/signup) | **每天 5,000 次公开扫描** | 可选 | | `CIRCL_PDNS_USER` | CIRCL 被动 DNS 查询 | [在 circl.lu 申请](https://www.circl.lu/services/passive-dns/) | 仅合作伙伴 | 可选 | | `CIRCL_PDNS_PASS` | CIRCL 被动 DNS 认证 | 注册后提供 | 仅合作伙伴 | 可选 | --- ## ⚙️ 配置 ### 环境变量示例（.env.example） ``` # NVD API 密钥 — 免费获取于 https://nvd.nist.gov/developers/request-an-api-key # 无密钥：5 req/30s | 有密钥：50 req/30s NVD_API_KEY= # GitHub 令牌 — 将速率限制从 60/hr 提升至 5000/hr（无需作用域） GITHUB_TOKEN= # 威胁情报密钥（均为可选 — 工具在缺少时会优雅降级） 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 — 使用 /v3/ip/{ip} 端点（NOT 已废弃的 /v3/community） GREYNOISE_API_KEY= # https://viz.greynoise.io/signup # CIRCL 被动 DNS — 需要合作伙伴注册 CIRCL_PDNS_USER= CIRCL_PDNS_PASS= # 可选覆盖 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 Code 配置 ``` # 基础设置 claude mcp add cve-mcp -- python -m cve_mcp.server # 使用来自 .env 文件的环境变量 claude mcp add cve-mcp --env-file .env -- python -m cve_mcp.server # 验证连接 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，然后尝试： Claude 将使用 `lookup_cve`（NVD）、`get_epss_score`（EPSS）和 `check_kev`（CISA KEV）——全部免费，无需密钥。 ### 步骤 3：添加首个密钥以获得 10 倍性能提升 ``` echo 'NVD_API_KEY=your-key-here' > .env ``` 申请一个免费的 NVD 密钥，访问 [nvd.nist.gov](https://nvd.nist.gov/developers/request-an-api-key) —— 即时通过邮件获取，将速率限制从 **5 提升至 50 次请求/30 秒**。 ### 步骤 4：完整模式 添加 Tier 1 和 Tier 2 密钥后，即可获得完整功能。 --- ## 💬 使用示例 ### 场景 1：“是否应立即修补 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” ``` → 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：“分析一个可疑” ``` → 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：“生成一份安全主管报告” ``` → 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% | 真实世界中已被利用 | | **漏洞利用代码可用性** | 15% | 公开 PoC 降低攻击门槛 | ### 增强乘数 - **KEV + 活跃漏洞利用** → ×1.15 - **CVSS ≥ 9.0 且 EPSS > 0.7** → ×1.10 - **发布于 7 天内** → ×1.05 评分上限为 100。 ### 风险标签 | 评分 | 标签 | 建议操作 | |------|------|----------| | **0 – 25** | **低** | 在下一个维护窗口中安排修复 | | **26 – 50** | **中** | 在 30 天 SLA 内修补 | | **51 – 75** | **高** | 在 7 天内修补；升级给团队负责人 | | **76 – 100** | **严重** | **在 24–48 小时内修补。** 紧急变更窗口。 | ### 权重依据 **EPSS 占最高权重（35%）**，因为它是预测实际利用的最佳指标——比 CVSS 单独使用更准确。CVSS 10.0 但 EPSS 0.01 的漏洞理论上危险但实际可能性低。**KEV 占 30%** 是真实证据：确认已被利用，而非预测。**CVSS 占 20%** 用于捕捉新漏洞的严重性背景（此时 EPSS 数据可能不足）。**漏洞利用代码占 15%**，反映公开 PoC 会显著加速实际攻击。 --- ## 🌐 数据源 | # | 来源 | 提供数据 | 认证 | 免费限制 | |---|------|----------|------|----------| | 1 | **NVD** | CVE 详情、CVSS、CWE、受影响的组件、引用、时间线 | `apiKey` 头部（可选） | 每 30 秒 5 次请求（使用密钥 50 次） | | 2 | **EPSS** | 利用概率及百分位 | 无 | 每分钟 1,000 次 | | 3 | **CISA KEV** | 已知被利用漏洞目录 | 无 | 静态文件 | | 4 | **OSV.dev** | 开源软件包漏洞 | 无 | 无公开限制 | | 5 | **GitHub 安全公告** | GHSA 公告、补丁、受影响的版本 | `Bearer` 令牌 | 每小时 60 次（个人访问令牌 5,000 次） | | 6 | **MITRE ATT&CK** | TTPs、技术、缓解措施 | 无 | 无限制 | | 7 | **AbuseIPDB** | IP 滥用置信度、报告、ISP、地理位置 | `Key` 头部 | 每天 1,000 次检查 | | 8 | **GreyNoise** | IP 噪声/扫描活动、分类 | `key` 头部 | 每周 50 次查询（社区版） | | 9 | **Shodan** | 开放端口、服务、横幅、漏洞 | `key` 查询参数 | 基础查询免费 | | 10 | **VirusTotal** | 多引擎扫描结果、信誉 | `x-apikey` 头部 | 每天 500 次，每分钟 4 次 | | 11 | **MalwareBazaar** | 恶意软件样本、哈希、签名 | `Auth-Key` 头部 | 合理使用 | | 12 | **ThreatFox** | 与恶意软件家族相关的 IOC | `Auth-Key` 头部 | 合理使用 | | 13 | **Ransomwhere** | 勒索软件比特币地址及交易数据 | 无 | 无限制 | | 14 | **URLScan.io** | URL 扫描、截图、DOM | `API-Key` 头部 | 每天 5,000 次公开扫描 | | 15 | **CIRCL PDNS** | 历史被动 DNS 记录 | HTTP 基本认证 | 合作伙伴访问 | | 16 | **GitHub 代码搜索** | 漏洞利用 PoC 仓库搜索 | `Bearer` 令牌 | 与 GHSA 限制共享 | | 17 | **Exploit-DB** | 公开漏洞利用数据库 CSV | 无 | 无限制 | | 18 | **Nuclei 模板** | 社区检测模板 | 无 | 无限制 | | 19 | **MSRC** | 微软安全公告 | 无 | 无限制 | | 20 | **Red Hat 安全** | Red Hat CVE 公告 | 无 | 无限制 | | 21 | **Ubuntu 安全** | Ubuntu CVE 跟踪 | 无 | 无限制 | --- ## 🧪 运行测试 ``` # 运行完整测试套件 pytest tests/ -v # 运行特定测试文件 pytest tests/test_validators.py tests/test_risk_scorer.py -v # 运行覆盖率测试 pytest tests/ -v --cov=src/cve_mcp --cov-report=term-missing ``` ### 使用 MCP Inspector ``` npx @modelcontextprotocol/inspector python -m cve_mcp.server ``` 在 `http://localhost:6274` 打开 —— 交互式测试每个工具，查看输入模式和响应格式。 ### 测试覆盖范围 - **单元测试**：风险评分计算、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 炸弹攻击（十亿大笑、XXE 注入）。 --- ## 🔧 故障排除 ### 服务器无法启动 ``` # 确保虚拟环境已激活且包已安装 pip install -e . python --version # must be 3.10+ ``` **Claude Desktop 未显示锤子图标（🔨）** - 检查配置文件中的 JSON 语法错误（不要有尾随逗号） - 使用**绝对路径**——相对路径会静默失败 - 完全退出 Claude Desktop（Cmd+Q / Alt+F4）并重新启动 ### NVD 限流 ``` # 添加您的免费 NVD API 密钥到 .env NVD_API_KEY=your-key-here # https://nvd.nist.gov/developers/request-an-api-key ``` 服务器会自动排队超额请求；使用密钥可获得 10 倍吞吐量。 ### GreyNoise 401 未授权 ``` # 验证密钥是否生效： curl -H "key: YOUR_KEY" https://api.greynoise.io/v3/ip/8.8.8.8 # 服务器使用 /v3/ip/{ip} — NOT 已废弃的 /v3/community 端点 ``` ### Windows 编码问题 ``` $env:PYTHONUTF8 = "1" $env:PYTHONIOENCODING = "utf-8" ``` --- ## 🗺️ 路线图与已知限制 ### 服务器不执行的操作 - **无主动扫描** —— 仅情报查询，不探测你的基础设施 - **无写入操作** —— 仅从外部 API 读取（URLScan 提交除外） - **无 CVSS v4.0 本地计算** —— 内置计算器仅支持 v3.1；NVD 提供的 v4.0 分数会显示但不会重新计算 ### 已知 API 限制 - NVD 单次查询最多返回 **2,000 条结果** - EPSS 评分对于 **24 小时内的新 CVE** 可能尚不存在 - CISA KEV 仅在工作日更新 - GreyNoise 社区版：**每周 50 次查询** - VirusTotal 免费版：**每分钟 4 次请求** - CIRCL PDNS 需手动注册并获得批准 - Ransomwhere 对新地址有 **90 天禁运** ### 计划改进 - CVSS v4.0 本地计算器 - Webhook/告警功能（KEV 新增与 EPSS 评分变化监控） - STIX 2.1 导出以集成 SIEM - 零安装 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) ```

使用 🔐 构建 · 由 Mahipal Jangra（柏林，德国）开发
将安全情报转化为对话。

标签：aiosqlite, Ask搜索, CISA KEV, Claude集成, Cloudflare, CVE查询, defusedxml, EPSS评分, FastMCP, GreyNoise, httpx, MCP服务器, MITRE ATT&CK, Pydantic, Python, SEO, VirusTotal, 优先级推荐, 威胁情报, 安全分析师, 安全情报, 开发者工具, 无后门, 模型上下文协议, 漏洞分析, 生产级, 网络安全, 自动化关联, 路径探测, 运行时操纵, 逆向工具, 隐私保护, 风险评分