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.