🛡️ CVE MCP Server

Inteligência de segurança com IA ao seu alcance — 28 ferramentas + um orquestrador triage_cve de chamada única, 24 fontes de dados, um protocolo.

Um servidor Model Context Protocol (MCP) de nível de produção que transforma o Claude em um analista de segurança de espectro completo. Em vez de gerenciar 15+ abas no navegador entre NVD, EPSS, CISA KEV, Shodan, VirusTotal e GreyNoise, faça uma pergunta ao Claude e receba inteligência correlacionada em segundos. Construído com Python, FastMCP, httpx, aiosqlite, Pydantic v2 e defusedxml.

O problema: Fazer a triagem de um único CVE significa consultar o NVD por pontuações CVSS, o EPSS por probabilidade de exploração, o CISA KEV por status de exploração ativa, o GitHub por patches e o VirusTotal por associações de malware — e depois correlacionar tudo mentalmente. Para 50 CVEs, é um dia inteiro perdido.

A solução: O CVE MCP Server dá ao Claude acesso direto a 28 ferramentas de segurança em 24 APIs — com o orquestrador de chamada única triage_cve na frente. Pergunte "Devemos corrigir o CVE-2024-3400?" e o Claude consulta todas as fontes relevantes em paralelo, calcula uma pontuação de risco composta (com uma substituição forçada do CISA KEV) e entrega uma recomendação priorizada com evidências.

🌍 GARS-2026 — Pesquisa Global de Prontidão para IA Agêntica

Estou conduzindo um estudo acadêmico global que mede o quão preparados os profissionais de segurança, desenvolvedores e equipes empresariais realmente estão para a IA agêntica — servidores MCP, chamadas de ferramentas, governança e fluxos de trabalho com humanos no circuito.

Se você usa este repositório, sua resposta seria um ponto de dados genuinamente valioso.

📋 Responda à pesquisa (10 min): Pesquisa

• 60 perguntas · Anônimo · Supervisionado pela SRH Berlin
• Você ganha 50 Casky Tokens para acesso antecipado ao casky.ai
• Resultados publicados em acesso aberto sob CC-BY 4.0

📑 Índice

• Arquitetura
• Catálogo de ferramentas
• Instalação
• Configuração das chaves de API
• Configuração
• Início rápido
• Exemplos de uso
• Explicação da pontuação de risco
• Fontes de dados
• Executando os testes
• Análise aprofundada da arquitetura
• Segurança e privacidade
• Solução de problemas
• Roadmap e limitações conhecidas
• Contribuindo
• Licença

🏗️ Arquitetura```

┌─────────────────────────────────────────────────────────────────────┐ │ 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 │ └──────────────┘ └──────────────┘ └──────────────┘

Todo o tráfego é **HTTPS somente de saída** — nenhuma porta de entrada é aberta. As chaves de API são carregadas de variáveis de ambiente e nunca são registradas em logs. Endereços IP privados/internos são bloqueados em todas as ferramentas de consulta.

---

## 🔍 Catálogo de ferramentas (28 ferramentas)

### ⭐ Orquestração (v0.2.0) — comece aqui

| Ferramenta | Descrição | Chave de API necessária | Exemplo de uso |
|------|-------------|-----------------|---------------|
| `triage_cve` | Triagem em uma única chamada que distribui NVD + EPSS + CISA KEV (+ PoC público para `depth != "quick"`) simultaneamente, calcula a pontuação de risco composta com um override rígido de KEV, recorre ao VulnCheck NVD++ quando o NVD do NIST está limitado e, em `depth="deep"`, emite a decisão de gate do SSVC v2 | Grátis / Sem chave (chave recomendada) | `triage_cve("CVE-2021-44228", depth="deep")` |

> **Também exposto via primitivas MCP** — Resources: `kev://catalog`, `epss://scores/{cve_id}`, `manifest://tool-hash` (SHA-256 sobre a superfície de ferramentas registrada, para detecção de adulteração). Prompts: `patch_decision`, `compare_and_prioritize`, `dependency_triage`.

### Inteligência Central de Vulnerabilidades (8 ferramentas)

| Ferramenta | Descrição | Chave de API necessária | Exemplo de uso |
|------|-------------|-----------------|---------------|
| `lookup_cve` | Buscar registro detalhado de CVE no NVD, incluindo pontuações CVSS, CWEs, produtos afetados, referências e linha do tempo | Grátis / Sem chave (chave recomendada) | `lookup_cve("CVE-2024-3400")` |
| `search_cves` | Pesquisar CVEs no NVD por palavra-chave, nome do produto, severidade ou intervalo de datas | Grátis / Sem chave (chave recomendada) | `search_cves(keyword="Apache Log4j", severity="CRITICAL")` |
| `get_epss_score` | Obter probabilidade de exploração EPSS (0–1) e percentil para um ou mais CVEs | Grátis / Sem chave | `get_epss_score("CVE-2024-3400")` |
| `check_kev_status` | Verificar se um CVE aparece no catálogo de Vulnerabilidades Exploradas Conhecidas (KEV) da CISA | Grátis / Sem chave | `check_kev_status("CVE-2021-44228")` |
| `get_cvss_details` | Analisar e explicar uma string de vetor CVSS v3.1 com detalhamento por métrica | Grátis / Sem chave | `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` | Consultar detalhes da Common Weakness Enumeration pelo ID de CWE no banco de dados embutido | Grátis / Sem chave | `get_cwe_info("CWE-79")` |
| `get_cve_references` | Extrair e categorizar todos os links de referência de um CVE (correções, avisos, exploits) | Grátis / Sem chave (chave recomendada) | `get_cve_references("CVE-2023-44487")` |
| `bulk_cve_lookup` | Buscar em lote detalhes de até 20 CVEs em uma única chamada com enriquecimento paralelo | Grátis / Sem chave (chave recomendada) | `bulk_cve_lookup(["CVE-2024-3400", "CVE-2023-44487"])` |

### Inteligência de Exploits e Ataques (4 ferramentas)

| Ferramenta | Descrição | Chave de API necessária | Exemplo de uso |
|------|-------------|-----------------|---------------|
| `search_exploits` | Pesquisar no GitHub por exploits públicos de prova de conceito e repositórios de código de exploit | `GITHUB_TOKEN` (opcional) | `search_exploits("CVE-2024-3400")` |
| `get_mitre_techniques` | Mapear um CVE ou CWE para técnicas, táticas e mitigações relevantes do MITRE ATT&CK | Grátis / Sem chave | `get_mitre_techniques("CVE-2021-44228")` |
| `check_poc_availability` | Determinar se existe código de prova de conceito conhecido para um CVE em múltiplas fontes | `GITHUB_TOKEN` (opcional) | `check_poc_availability("CVE-2024-3400")` |
| `get_attack_patterns` | Recuperar detalhes de padrões de ataque CAPEC associados a uma CWE ou CVE | Grátis / Sem chave | `get_attack_patterns("CWE-89")` |

### Fase 3: Risco Avançado e Relatórios (4 ferramentas)

| Ferramenta | Descrição | Chave de API necessária | Exemplo de uso |
|------|-------------|-----------------|---------------|
| `calculate_risk_score` | Calcular pontuação de risco composta de 0–100 usando CVSS, EPSS, status KEV e disponibilidade de PoC | Grátis / Sem chave (chave recomendada) | `calculate_risk_score("CVE-2024-3400")` |
| `generate_risk_report` | Gerar um relatório executivo de segurança formatado para um ou mais CVEs com recomendações | Grátis / Sem chave (chave recomendada) | `generate_risk_report(["CVE-2024-3400", "CVE-2023-44487"])` |
| `prioritize_cves` | Classificar uma lista de CVEs por pontuação de risco composta para priorização de triagem | Grátis / Sem chave (chave recomendada) | `prioritize_cves(["CVE-2024-3400", "CVE-2023-4966", "CVE-2023-44487"])` |
| `get_trending_cves` | Recuperar CVEs em tendência com base em pontuações EPSS altas e adições recentes ao KEV | Grátis / Sem chave | `get_trending_cves(days=7, min_epss=0.5)` |

### Inteligência de Rede (4 ferramentas)

| Ferramenta | Descrição | Chave de API necessária | Exemplo de uso |
|------|-------------|-----------------|---------------|
| `lookup_ip_reputation` | Verificar histórico de abuso de endereço IP e pontuação de confiança via AbuseIPDB | `ABUSEIPDB_API_KEY` | `lookup_ip_reputation("185.220.101.34")` |
| `check_ip_noise` | Consultar GreyNoise por atividade de varredura/ataque de IP, classificação e CVEs associados | `GREYNOISE_API_KEY` | `check_ip_noise("185.220.101.34")` |
| `shodan_host_lookup` | Obter portas abertas, serviços, banners e vulnerabilidades de um IP via Shodan | `SHODAN_API_KEY` | `shodan_host_lookup("8.8.8.8")` |
| `passive_dns_lookup` | Recuperar dados históricos de resolução DNS de um domínio do CIRCL Passive DNS | `CIRCL_PDNS_USER` + `CIRCL_PDNS_PASSWORD` | `passive_dns_lookup("example.com")` |

### Inteligência de Ameaças (4 ferramentas)

| Ferramenta | Descrição | Chave de API necessária | Exemplo de uso |
|------|-------------|-----------------|---------------|
| `virustotal_lookup` | Analisar hashes de arquivos, URLs, domínios ou IPs em mais de 70 mecanismos antivírus | `VIRUSTOTAL_API_KEY` | `virustotal_lookup(hash="44d88612fea8a8f36de82e1278abb02f")` |
| `search_malware` | Pesquisar amostras de malware no MalwareBazaar por hash, tag ou assinatura | `ABUSECH_AUTH_KEY` (opcional) | `search_malware(tag="Emotet")` |
| `search_iocs` | Consultar o ThreatFox por Indicadores de Comprometimento vinculados a famílias de malware | `ABUSECH_AUTH_KEY` (opcional) | `search_iocs(malware="CobaltStrike")` |
| `check_ransomware` | Consultar endereços de pagamento de ransomware e dados de transação do Ransomwhere | Grátis / Sem chave | `check_ransomware(address="bc1q...")` |

### DevSecOps (3 ferramentas)

| Ferramenta | Descrição | Chave de API necessária | Exemplo de uso |
|------|-------------|-----------------|---------------|
| `scan_dependencies` | Verificar nomes e versões de pacotes no OSV.dev em busca de vulnerabilidades conhecidas | Grátis / Sem chave | `scan_dependencies(ecosystem="PyPI", packages={"requests": "2.28.0"})` |
| `scan_github_advisories` | Pesquisar GitHub Security Advisories por ecossistema, pacote ou severidade | `GITHUB_TOKEN` (opcional) | `scan_github_advisories(ecosystem="pip", package="django")` |
| `urlscan_check` | Enviar uma URL para varredura ou recuperar resultados anteriores de varredura do URLScan.io | `URLSCAN_API_KEY` | `urlscan_check("https://suspicious-site.com")` |

---

## 📦 Instalação

### Pré-requisitos

- **Python 3.10+** (3.11 ou 3.12 recomendado)
- Gerenciador de pacotes **pip** ou **uv**
- **Git** para clonar o repositório
- Um terminal com acesso a variáveis de ambiente

### Configuração passo a passo```bash
# 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

Usando uv (alternativa mais rápida)```bash

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

### Com dependências de teste```bash
pip install -e ".[test]"

🔑 Configuração de chaves de API

As chaves de API são organizadas por prioridade — obtenha primeiro as chaves do Nível 1 para cobertura máxima com ferramentas gratuitas e, em seguida, adicione progressivamente os Níveis 2 e 3 conforme necessário.

Nível 1: Prioridade alta (gratuito, acesso instantâneo, cobertura máxima)

Nível 2: Recomendado (contas gratuitas, valor significativo)

Nível 3: Opcional (inteligência estendida)

⚡ Início sem chaves: Oito ferramentas funcionam sem nenhuma chave de API — EPSS, CISA KEV, OSV.dev, MITRE ATT&CK, consultas CWE, análise de CVSS, Ransomwhere e NVD (com taxa reduzida). Você pode começar a usar o servidor imediatamente e adicionar chaves progressivamente.

⚙️ Configuração

Variáveis de ambiente (.env.example)```env

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

### Configuração do Claude Desktop

**macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
**Windows:** `%APPDATA%\Claude\claude_desktop_config.json````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"
      }
    }
  }
}

⚠️ Importante: Sempre use caminhos absolutos. Saia completamente do Claude Desktop (Cmd+Q / Alt+F4) após alterar a configuração — recarregar não é suficiente.

Configuração do Claude Code```bash

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

---

## 🚀 Início rápido

### Etapa 1: Instalar (2 minutos)```bash
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 .

Passo 2: Teste primeiro com ferramentas gratuitas

Nenhum arquivo .env é necessário. Adicione o servidor ao Claude Desktop ou ao Claude Code e tente:

"O que é CVE-2021-44228? Está sendo explorado ativamente?"

O Claude usará lookup_cve (NVD), get_epss_score (EPSS) e check_kev (CISA KEV) — todos gratuitos, sem necessidade de chaves.

"Analise estes pacotes Python em busca de vulnerabilidades: requests 2.28.0, flask 2.2.0, django 3.2.0"

Passo 3: Adicione sua primeira chave para desempenho 10×```bash

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

Solicite uma chave NVD gratuita em [nvd.nist.gov](https://nvd.nist.gov/developers/request-an-api-key) — instantânea via e-mail, aumenta o limite de taxa de **5 para 50 solicitações por 30 segundos**.

### Passo 4: Modo de potência máxima

Depois de adicionar as chaves do Nível 1 e do Nível 2:

> **"Calcule a pontuação de risco para CVE-2024-3400 e me diga se devemos aplicar o patch imediatamente."**

---

## 💬 Exemplos de uso

### Cenário 1: "Devemos aplicar o patch do Log4Shell imediatamente?"

> **Você:** Analise se CVE-2021-44228 (Log4Shell) precisa de patch imediato. Dê-me a pontuação de risco e sua recomendação.

O Claude orquestra várias ferramentas nos bastidores:```
→ 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

Resposta do Claude: "CVE-2021-44228 pontua 97/100 (CRÍTICO). Execução remota de código no Apache Log4j, CVSS 10.0, probabilidade EPSS de 97,5%, exploração ativa confirmada no CISA KEV incluindo campanhas de ransomware, mais de 300 exploits públicos. Aplique o patch imediatamente."

Cenário 2: "Escanear meu requirements.txt do Python"

Você: Escanee estas dependências: 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

**Resposta do Claude:** "Encontrei **12 vulnerabilidades** em seus pacotes. **Ação imediata:** Django 3.2.0 (3 CVEs críticos, incluindo injeção de SQL), Pillow 9.0.0 (estouro de heap), cryptography 37.0.0 (cadeia OpenSSL). Atualize para: django>=4.2.16, pillow>=10.3.0, cryptography>=42.0.0."

### Cenário 3: "Investigar um IP suspeito"

> **Você:** Investigue o IP suspeito 185.220.101.34 — é malicioso?```
→ 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

Resposta do Claude: "185.220.101.34 é um nó de saída Tor conhecido avaliado como 100% malicioso pelo AbuseIPDB com 4.832 relatórios de abuso. O GreyNoise confirma varredura ativa para CVE-2024-3400 (Palo Alto) e CVE-2023-46805 (Ivanti). Recomendação: Bloquear no firewall."

Cenário 4: "Gerar um relatório de segurança executivo"

Você: Gere um relatório de segurança executivo para: 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

---

## 📊 Explicação da pontuação de risco

A ferramenta `calculate_risk_score` produz uma **pontuação de risco composta de 0 a 100** ao ponderar quatro sinais independentes.

### A fórmula```
Risk Score = (CVSS × 0.20) + (EPSS × 0.35) + (KEV × 0.30) + (PoC × 0.15)

Multiplicadores de reforço

• KEV + PoC ativo → ×1.15
• CVSS ≥ 9.0 + EPSS > 0.7 → ×1.10
• Publicado há menos de 7 dias → ×1.05

A pontuação é limitada a 100.

Pontuação de Risco — v1 (2026-06)

O avaliador numérico é scoring_version 1.0 (exposto em triage_cve, calculate_risk_score e health_check). A soma ponderada linear acima é o padrão v1 para a pontuação numérica, com uma substituição forçada:

• Substituição forçada por CISA KEV: um CVE listado no KEV é confirmado como explorado em produção, o sinal de exploração mais forte. Seu rótulo nunca pode ser inferior a CRÍTICO e sua pontuação é limitada a ≥ 76, independentemente de CVSS/EPSS. (Um CVE KEV com CVSS baixo e EPSS baixo ainda retorna CRÍTICO / 76.)
• O CVSS é tratado como um sinal de gravidade, não como um sinal de probabilidade de exploração (conforme Allodi & Massacci 2014); EPSS e KEV carregam o sinal de exploração.
• Uma decisão experimental controlada por SSVC v2 (modelo CISA Deployer → Act / Attend / Track* / Track) está disponível via triage_cve(depth="deep") como uma alternativa qualitativa e explicável ao número de 0 a 100.

Por que esses pesos?

EPSS recebe o maior peso (35%) porque é o melhor preditor individual de exploração real — muito melhor que o CVSS sozinho. Um CVSS 10.0 com EPSS 0.01 é teoricamente perigoso, mas praticamente improvável. KEV com 30% é a verdade de base: exploração confirmada, não uma previsão. CVSS com 20% captura o contexto de gravidade para CVEs novos com dados insuficientes de EPSS. PoC com 15% reflete que explorações públicas aceleram dramaticamente ataques no mundo real.

🆕 Novidades na v0.2.0

• Orquestrador triage_cve — uma única chamada de ferramenta que distribui NVD + EPSS + CISA KEV (+ descoberta pública de PoC para depth != "quick") concorrentemente, calcula a pontuação de risco composta e retorna um relatório claro. depth é quick / standard (padrão) / deep; deep adicionalmente emite a decisão controlada por SSVC v2.
• Novas fontes upstream — VulnCheck NVD++ (um fallback transparente do NVD usado automaticamente dentro do triage_cve quando o NIST NVD está inacessível/limitado), CIRCL hashlookup e a API de intervalo Pwned Passwords da HIBP.
• Pontuação com substituição forçada por KEV + scoring_version — CVEs listados no KEV são sempre CRÍTICOS (pontuação ≥ 76); a versão da pontuação é reportada em triage_cve e health_check.
• Transporte HTTP — defina MCP_TRANSPORT=http para servir HTTP com streaming em (padrão , sem estado) em vez de stdio. Inclui um .

🌐 Fontes de dados

🧪 Executando testes```bash

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

### Teste com o MCP Inspector```bash
npx @modelcontextprotocol/inspector python -m cve_mcp.server

Abre em http://localhost:6274 — teste interativamente cada ferramenta, veja os esquemas de entrada e inspecione os formatos de resposta.

O que os testes cobrem

• Testes unitários: Cálculo da pontuação de risco, análise de vetores CVSS, validação de entrada
• Testes de integração: Registro de ferramentas, validação de parâmetros, tratamento de erros para chaves ausentes
• Testes de cache: Gravações de cache SQLite, expiração de TTL, acerto/erro de cache
• Testes de segurança: Bloqueio de IP privado, proteção contra bombas XML (defusedxml), sanitização de entrada

🏛️ Análise aprofundada da arquitetura

Estrutura de arquivos```

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

### Estratégia de cache

| Recurso | TTL |
|----------|-----|
| Registros CVE (NVD) | 1 hora |
| Pontuações EPSS | 6 horas |
| Catálogo KEV | 1 hora |
| Intel de IP / domínio | 1 hora |
| CSV do Exploit-DB | 24 horas |
| Dados STIX do ATT&CK | 24 horas |
| Intel de ransomware | 24 horas |

### Log de auditoria

Cada invocação de ferramenta é registrada em `~/.cve-mcp/audit.log`:```json
{
  "timestamp": "2026-04-14T10:23:45.123Z",
  "tool": "lookup_cve",
  "parameters": {"cve_id": "CVE-2024-3400"},
  "duration_ms": 342,
  "cache_hit": false,
  "status": "ok"
}

Chaves de API e payloads de resposta nunca são gravados nos logs de auditoria.

🔐 Segurança e privacidade

Quais dados saem da sua máquina

• Apenas HTTPS de saída — nenhuma porta de entrada aberta, sem telemetria
• IDs de CVE, IPs, hashes, domínios e nomes de pacotes são enviados às respectivas APIs para consulta
• Respostas de API são armazenadas em cache localmente em SQLite — os dados em cache permanecem na sua máquina

Bloqueio de IPs privados

Todas as ferramentas de inteligência de rede bloqueiam faixas de IP privadas e reservadas antes de qualquer chamada de API externa:

• 10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16 (RFC 1918)
• 127.0.0.0/8 (loopback), 169.254.0.0/16 (link-local)
• ::1, fc00::/7 (IPv6 privado)

Proteção de chaves de API

• Chaves carregadas apenas de variáveis de ambiente — nunca embutidas no código
• .env está no gitignore
• Chaves nunca são registradas, armazenadas em cache ou incluídas em entradas de auditoria

Segurança XML

defusedxml é usado para toda a análise XML para prevenir ataques de bombas XML (billion laughs, injeção XXE).

🔧 Solução de problemas

O servidor não inicia```bash

Ensure virtual environment is activated and package is installed

pip install -e . python --version # must be 3.10+

**O Claude Desktop não mostra o ícone de martelo (🔨)**
- Verifique se há erros de sintaxe JSON (sem vírgulas finais) no seu config
- Use **caminhos absolutos** — caminhos relativos falham silenciosamente
- Feche completamente o Claude Desktop (Cmd+Q / Alt+F4) e reinicie

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

O servidor enfileira automaticamente as solicitações em excesso, mas com uma chave você obtém 10× o throughput.

GreyNoise 401 Unauthorized```bash

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

### Problemas de codificação do Windows```powershell
$env:PYTHONUTF8 = "1"
$env:PYTHONIOENCODING = "utf-8"

🗺️ Roadmap e limitações conhecidas

O que o servidor NÃO faz

• Sem varredura ativa — apenas inteligência/consulta, não sonda sua infraestrutura
• Sem operações de escrita — lê apenas de APIs externas (exceto envios ao URLScan)
• Sem pontuação CVSS v4.0 — a calculadora integrada lida apenas com v3.1; as pontuações v4.0 fornecidas pela NVD são exibidas, mas não recalculadas

Limitações conhecidas das APIs

• A NVD retorna no máximo 2.000 resultados por consulta
• Pontuações EPSS para CVEs recém-publicadas (com menos de 24 horas) podem ainda não existir
• A CISA atualiza a KEV apenas em dias úteis dos EUA
• Nível comunitário do GreyNoise: 50 consultas/semana
• Nível gratuito do VirusTotal: 4 requisições/minuto
• O CIRCL PDNS exige registro e aprovação manuais
• A Ransomwhere tem um embargo de 90 dias para novos endereços

Melhorias planejadas

• Calculadora local de CVSS v4.0
• Webhook/alertas para adições à KEV e mudanças na pontuação EPSS em uma lista de observação de CVEs
• Exportação STIX 2.1 para integração com SIEM
• Contêiner Docker com implantação sem instalação
• Streamable HTTP transport (MCP SSE)
• Fontes adicionais: Censys, SecurityTrails, VulnCheck

🤝 Contribuindo

Contribuições são bem-vindas.

Adicionando uma nova ferramenta

1. Adicione a função da ferramenta em server.py com o decorador @mcp.tool()

2. Adicione validação de entrada em utils/validators.py

3. Implemente o cliente de API em api/

4. Adicione testes em tests/

5. Atualize este README```python @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

### Requisitos de teste

- Todas as ferramentas novas devem ter pelo menos um teste offline com respostas simuladas
- Alterações na pontuação de risco devem incluir casos de teste de verificação de fórmula
- Ferramentas de rede devem incluir um teste que verifique o bloqueio de IPs privados
- Todos os testes devem passar: `pytest tests/ -v`

---

## 📄 Licença

Licença MIT — consulte [LICENSE](https://github.com/mukul975/cve-mcp-server/blob/main/LICENSE) para obter detalhes.```
Copyright (c) 2025-2026 Mahipal Jangra (mukul975)

Construído com 🔐 por Mahipal Jangra · Berlim, Alemanha
Transformando inteligência de segurança em conversa.