🛡️ CVE MCP Server

Intelligence di sicurezza basata sull'AI a portata di mano — 28 strumenti + un orchestratore monochiamata triage_cve, 24 sorgenti di dati, un unico protocollo.

Un server Model Context Protocol (MCP) di livello produttivo che trasforma Claude in un analista di sicurezza a tutto spettro. Invece di destreggiarti tra 15+ schede del browser su NVD, EPSS, CISA KEV, Shodan, VirusTotal e GreyNoise, poni una sola domanda a Claude e ottieni intelligence correlata in pochi secondi. Realizzato con Python, FastMCP, httpx, aiosqlite, Pydantic v2 e defusedxml.

Il problema: Fare il triage di una singola CVE significa interrogare NVD per i punteggi CVSS, EPSS per la probabilità di sfruttamento, CISA KEV per lo stato di sfruttamento attivo, GitHub per le patch e VirusTotal per le associazioni con malware — per poi correlare tutto mentalmente. Per 50 CVE, si perde un'intera giornata.

La soluzione: CVE MCP Server offre a Claude accesso diretto a 28 strumenti di sicurezza su 24 API — con l'orchestratore monochiamata triage_cve in prima linea. Chiedi "Dovremmo applicare la patch per CVE-2024-3400?" e Claude interroga in parallelo ogni sorgente pertinente, calcola un punteggio di rischio composito (con sovrascrittura rigida di CISA KEV) e fornisce una raccomandazione prioritaria con prove a sostegno.

🌍 GARS-2026 — Indagine globale sulla prontezza all'AI agentica

Sto conducendo uno studio accademico globale che misura quanto professionisti della sicurezza, sviluppatori e team aziendali siano realmente pronti per l'AI agentica — server MCP, chiamate agli strumenti, governance e flussi di lavoro con supervisione umana.

Se utilizzi questo repository, la tua risposta sarebbe un punto dati davvero prezioso.

📋 Partecipa al sondaggio (10 min): Sondaggio

• 60 domande · Anonimo · Supervisionato da SRH Berlin
• Ricevi 50 Casky Token per l'accesso anticipato a casky.ai
• Risultati pubblicati ad accesso aperto sotto CC-BY 4.0

📑 Indice dei contenuti

• Architettura
• Catalogo degli strumenti
• Installazione
• Configurazione delle chiavi API
• Configurazione
• Avvio rapido
• Esempi di utilizzo
• Spiegazione del punteggio di rischio
• Sorgenti di dati
• Esecuzione dei test
• Approfondimento sull'architettura
• Sicurezza e privacy
• Risoluzione dei problemi
• Roadmap e limitazioni note
• Contribuire
• Licenza

🏗️ Architettura```

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

Tutto il traffico è **solo HTTPS in uscita** — nessuna porta in ingresso viene aperta. Le chiavi API vengono caricate dalle variabili d'ambiente e non vengono mai registrate nei log. Gli indirizzi IP privati/interni sono bloccati da tutti gli strumenti di lookup.

---

## 🔍 Catalogo degli strumenti (28 strumenti)

### ⭐ Orchestrazione (v0.2.0) — inizia qui

| Tool | Descrizione | Chiave API richiesta | Esempio di utilizzo |
|------|-------------|-----------------|---------------|
| `triage_cve` | Triage in una singola chiamata che distribuisce in parallelo NVD + EPSS + CISA KEV (+ PoC pubblici per `depth != "quick"`), calcola il punteggio di rischio composito con un override rigido KEV, ripiega su VulnCheck NVD++ quando NIST NVD è limitato e, con `depth="deep"`, emette la decisione gated SSVC v2 | Gratis / Nessuna chiave (chiave consigliata) | `triage_cve("CVE-2021-44228", depth="deep")` |

> **Anche esposto tramite primitive MCP** — Risorse: `kev://catalog`, `epss://scores/{cve_id}`, `manifest://tool-hash` (SHA-256 sulla superficie strumentale registrata, per il rilevamento di manomissioni). Prompt: `patch_decision`, `compare_and_prioritize`, `dependency_triage`.

### Intelligence di base sulle vulnerabilità (8 strumenti)

| Tool | Descrizione | Chiave API richiesta | Esempio di utilizzo |
|------|-------------|-----------------|---------------|
| `lookup_cve` | Recupera la scheda CVE dettagliata da NVD, inclusi punteggi CVSS, CWE, prodotti interessati, riferimenti e cronologia | Gratis / Nessuna chiave (chiave consigliata) | `lookup_cve("CVE-2024-3400")` |
| `search_cves` | Cerca in NVD le CVE per parola chiave, nome del prodotto, gravità o intervallo di date | Gratis / Nessuna chiave (chiave consigliata) | `search_cves(keyword="Apache Log4j", severity="CRITICAL")` |
| `get_epss_score` | Ottieni la probabilità di sfruttamento EPSS (0–1) e il percentile per una o più CVE | Gratis / Nessuna chiave | `get_epss_score("CVE-2024-3400")` |
| `check_kev_status` | Verifica se una CVE è presente nel catalogo Known Exploited Vulnerabilities di CISA | Gratis / Nessuna chiave | `check_kev_status("CVE-2021-44228")` |
| `get_cvss_details` | Analizza e spiega una stringa vettoriale CVSS v3.1 con ripartizione per metrica | Gratis / Nessuna chiave | `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` | Cerca i dettagli Common Weakness Enumeration per ID CWE nel database integrato | Gratis / Nessuna chiave | `get_cwe_info("CWE-79")` |
| `get_cve_references` | Estrae e categorizza tutti i link di riferimento per una CVE (patch, advisory, exploit) | Gratis / Nessuna chiave (chiave consigliata) | `get_cve_references("CVE-2023-44487")` |
| `bulk_cve_lookup` | Recupera in batch i dettagli di fino a 20 CVE in una singola chiamata con arricchimento parallelo | Gratis / Nessuna chiave (chiave consigliata) | `bulk_cve_lookup(["CVE-2024-3400", "CVE-2023-44487"])` |

### Intelligence su exploit e attacchi (4 strumenti)

| Tool | Descrizione | Chiave API richiesta | Esempio di utilizzo |
|------|-------------|-----------------|---------------|
| `search_exploits` | Cerca su GitHub exploit proof-of-concept pubblici e repository di codice exploit | `GITHUB_TOKEN` (opzionale) | `search_exploits("CVE-2024-3400")` |
| `get_mitre_techniques` | Associa una CVE o CWE alle tecniche, tattiche e mitigazioni MITRE ATT&CK pertinenti | Gratis / Nessuna chiave | `get_mitre_techniques("CVE-2021-44228")` |
| `check_poc_availability` | Determina se esiste codice proof-of-concept noto per una CVE in più fonti | `GITHUB_TOKEN` (opzionale) | `check_poc_availability("CVE-2024-3400")` |
| `get_attack_patterns` | Recupera i dettagli dei pattern di attacco CAPEC associati a una CWE o CVE | Gratis / Nessuna chiave | `get_attack_patterns("CWE-89")` |

### Fase 3: Rischio avanzato e reporting (4 strumenti)

| Tool | Descrizione | Chiave API richiesta | Esempio di utilizzo |
|------|-------------|-----------------|---------------|
| `calculate_risk_score` | Calcola un punteggio di rischio composito da 0 a 100 utilizzando CVSS, EPSS, stato KEV e disponibilità di PoC | Gratis / Nessuna chiave (chiave consigliata) | `calculate_risk_score("CVE-2024-3400")` |
| `generate_risk_report` | Genera un report di sicurezza esecutivo formattato per una o più CVE con raccomandazioni | Gratis / Nessuna chiave (chiave consigliata) | `generate_risk_report(["CVE-2024-3400", "CVE-2023-44487"])` |
| `prioritize_cves` | Classifica un elenco di CVE in base al punteggio di rischio composito per la prioritizzazione del triage | Gratis / Nessuna chiave (chiave consigliata) | `prioritize_cves(["CVE-2024-3400", "CVE-2023-4966", "CVE-2023-44487"])` |
| `get_trending_cves` | Recupera le CVE di tendenza in base a punteggi EPSS elevati e recenti aggiunte KEV | Gratis / Nessuna chiave | `get_trending_cves(days=7, min_epss=0.5)` |

### Intelligence di rete (4 strumenti)

| Tool | Descrizione | Chiave API richiesta | Esempio di utilizzo |
|------|-------------|-----------------|---------------|
| `lookup_ip_reputation` | Controlla la cronologia degli abusi dell'indirizzo IP e il punteggio di confidenza tramite AbuseIPDB | `ABUSEIPDB_API_KEY` | `lookup_ip_reputation("185.220.101.34")` |
| `check_ip_noise` | Interroga GreyNoise per attività di scansione/attacco IP, classificazione e CVE associate | `GREYNOISE_API_KEY` | `check_ip_noise("185.220.101.34")` |
| `shodan_host_lookup` | Ottieni porte aperte, servizi, banner e vulnerabilità per un IP tramite Shodan | `SHODAN_API_KEY` | `shodan_host_lookup("8.8.8.8")` |
| `passive_dns_lookup` | Recupera i dati storici di risoluzione DNS per un dominio da CIRCL Passive DNS | `CIRCL_PDNS_USER` + `CIRCL_PDNS_PASSWORD` | `passive_dns_lookup("example.com")` |

### Intelligence sulle minacce (4 strumenti)

| Tool | Descrizione | Chiave API richiesta | Esempio di utilizzo |
|------|-------------|-----------------|---------------|
| `virustotal_lookup` | Analizza hash di file, URL, domini o IP con oltre 70 motori antivirus | `VIRUSTOTAL_API_KEY` | `virustotal_lookup(hash="44d88612fea8a8f36de82e1278abb02f")` |
| `search_malware` | Cerca campioni di malware su MalwareBazaar per hash, tag o firma | `ABUSECH_AUTH_KEY` (opzionale) | `search_malware(tag="Emotet")` |
| `search_iocs` | Interroga ThreatFox per gli Indicator of Compromise collegati a famiglie di malware | `ABUSECH_AUTH_KEY` (opzionale) | `search_iocs(malware="CobaltStrike")` |
| `check_ransomware` | Cerca indirizzi di pagamento ransomware e dati di transazione da Ransomwhere | Gratis / Nessuna chiave | `check_ransomware(address="bc1q...")` |

### DevSecOps (3 strumenti)

| Tool | Descrizione | Chiave API richiesta | Esempio di utilizzo |
|------|-------------|-----------------|---------------|
| `scan_dependencies` | Analizza nomi e versioni dei pacchetti rispetto a OSV.dev per vulnerabilità note | Gratis / Nessuna chiave | `scan_dependencies(ecosystem="PyPI", packages={"requests": "2.28.0"})` |
| `scan_github_advisories` | Cerca GitHub Security Advisories per ecosistema, pacchetto o gravità | `GITHUB_TOKEN` (opzionale) | `scan_github_advisories(ecosystem="pip", package="django")` |
| `urlscan_check` | Invia un URL per la scansione o recupera i risultati di scansioni precedenti da URLScan.io | `URLSCAN_API_KEY` | `urlscan_check("https://suspicious-site.com")` |

---

## 📦 Installazione

### Prerequisiti

- **Python 3.10+** (si consigliano 3.11 o 3.12)
- **pip** o **uv** come gestore di pacchetti
- **Git** per clonare il repository
- Un terminale con accesso alle variabili d'ambiente

### Configurazione passo-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

Utilizzare uv (alternativa più veloce)```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

### Con le dipendenze di test```bash
pip install -e ".[test]"

🔑 Configurazione delle chiavi API

Le chiavi API sono organizzate per priorità: ottieni prima le chiavi Tier 1 per la massima copertura con strumenti gratuiti, poi aggiungi gradualmente Tier 2 e Tier 3 secondo necessità.

Tier 1: Priorità alta (gratuite, accesso immediato, copertura massima)

Tier 2: Consigliate (account gratuiti, valore significativo)

Tier 3: Opzionali (intelligence estesa)

⚡ Avvio senza chiavi: Otto strumenti funzionano senza alcuna chiave API — EPSS, CISA KEV, OSV.dev, MITRE ATT&CK, lookup CWE, parsing CVSS, Ransomwhere e NVD (a velocità ridotta). Puoi iniziare a usare il server immediatamente e aggiungere le chiavi in modo progressivo.

⚙️ Configurazione

Variabili d'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

### Configurazione di 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: Usa sempre percorsi assoluti. Esci completamente da Claude Desktop (Cmd+Q / Alt+F4) dopo aver modificato la configurazione — ricaricare non basta.

Configurazione di 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

---

## 🚀 Avvio rapido

### Passaggio 1: Installazione (2 minuti)```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 .

Passaggio 2: prova prima gli strumenti gratuiti

Non serve alcun file .env. Aggiungi il server a Claude Desktop o Claude Code e prova:

"Cos'è CVE-2021-44228? È sfruttato attivamente?"

Claude userà lookup_cve (NVD), get_epss_score (EPSS) e check_kev (CISA KEV) — tutti gratuiti, senza bisogno di chiavi.

"Scansiona questi pacchetti Python per vulnerabilità: requests 2.28.0, flask 2.2.0, django 3.2.0"

Passaggio 3: aggiungi la tua prima chiave per prestazioni 10×```bash

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

Richiedi una chiave NVD gratuita su [nvd.nist.gov](https://nvd.nist.gov/developers/request-an-api-key) — immediata via email, aumenta il limite di richieste da **5 a 50 richieste ogni 30 secondi**.

### Passaggio 4: Modalità potenza completa

Una volta aggiunte le chiavi Tier 1 e Tier 2:

> **"Calcola il punteggio di rischio per CVE-2024-3400 e dimmi se dobbiamo applicare la patch immediatamente."**

---

## 💬 Esempi di utilizzo

### Scenario 1: "Dobbiamo applicare la patch per Log4Shell immediatamente?"

> **Tu:** Analizza se CVE-2021-44228 (Log4Shell) richiede una patch immediata. Dammi il punteggio di rischio e la tua raccomandazione.

Claude orchestra più strumenti dietro le quinte:```
→ 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

Risposta di Claude: "Il CVE-2021-44228 ottiene un punteggio di 97/100 (CRITICO). Esecuzione remota di codice in Apache Log4j, CVSS 10.0, probabilità EPSS del 97.5%, sfruttamento attivo confermato nel CISA KEV incluse campagne ransomware, oltre 300 exploit pubblici. Applicare la patch immediatamente."

Scenario 2: "Scansiona il mio requirements.txt di Python"

Tu: Scansiona queste dipendenze: 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

**Risposta di Claude:** "Trovate **12 vulnerabilità** nei tuoi pacchetti. **Azione immediata:** Django 3.2.0 (3 CVE critici tra cui SQL injection), Pillow 9.0.0 (heap overflow), cryptography 37.0.0 (catena OpenSSL). Aggiorna a: django>=4.2.16, pillow>=10.3.0, cryptography>=42.0.0."

### Scenario 3: "Indaga su un IP sospetto"

> **Tu:** Indaga sull'IP sospetto 185.220.101.34 — è malevolo?```
→ 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

Risposta di Claude: "185.220.101.34 è un noto nodo di uscita Tor valutato 100% dannoso da AbuseIPDB con 4,832 segnalazioni di abuso. GreyNoise conferma scansioni attive per CVE-2024-3400 (Palo Alto) e CVE-2023-46805 (Ivanti). Raccomandazione: bloccare sul firewall."

Scenario 4: "Genera un report di sicurezza esecutivo"

Tu: Genera un report di sicurezza esecutivo per: 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

---

## 📊 Spiegazione del punteggio di rischio

Lo strumento `calculate_risk_score` produce un **punteggio di rischio composito da 0 a 100** ponderando quattro segnali indipendenti.

### La formula```
Risk Score = (CVSS × 0.20) + (EPSS × 0.35) + (KEV × 0.30) + (PoC × 0.15)

Moltiplicatori boost

• KEV + PoC attivo → ×1.15
• CVSS ≥ 9.0 + EPSS > 0.7 → ×1.10
• Pubblicato meno di 7 giorni fa → ×1.05

Il punteggio è limitato a un massimo di 100.

Punteggio del rischio — v1 (2026-06)

Lo scorer numerico è scoring_version 1.0 (esposto in triage_cve, calculate_risk_score e health_check). La somma pesata lineare sopra è il default v1 per il punteggio numerico, con una hard override:

• CISA KEV hard override: una CVE elencata in KEV è confermata sfruttata in the wild, il singolo segnale di sfruttamento più forte. La sua etichetta non può mai essere inferiore a CRITICAL e il punteggio è bloccato a ≥ 76, indipendentemente da CVSS/EPSS. (Una CVE KEV con CVSS basso e EPSS basso restituisce comunque CRITICAL / 76.)
• CVSS è trattato come un segnale di gravità, non come un segnale di probabilità di sfruttamento (secondo Allodi & Massacci 2014); EPSS e KEV portano il segnale di sfruttamento.
• Una decisione sperimentale SSVC v2 gated (modello CISA Deployer → Act / Attend / Track* / Track) è disponibile tramite triage_cve(depth="deep") come alternativa qualitativa e spiegabile al numero 0–100.

Perché questi pesi?

EPSS ha il peso più alto (35%) perché è il singolo miglior predittore di sfruttamento effettivo — molto meglio del solo CVSS. Un CVSS 10.0 con EPSS 0.01 è teoricamente pericoloso ma praticamente improbabile. KEV al 30% è la verità di base: sfruttamento confermato, non una previsione. CVSS al 20% cattura il contesto di gravità per le nuove CVE con dati EPSS insufficienti. PoC al 15% riflette che gli exploit pubblici accelerano drammaticamente gli attacchi nel mondo reale.

🆕 Cosa c'è di nuovo in v0.2.0

• triage_cve orchestrator — una singola chiamata tool che distribuisce in parallelo NVD + EPSS + CISA KEV (+ scoperta di PoC pubblici per depth != "quick"), calcola il punteggio di rischio composito e restituisce un report pulito. depth può essere quick / standard (default) / deep; deep emette inoltre la decisione gated SSVC v2.
• Nuove fonti upstream — VulnCheck NVD++ (un fallback trasparente per NVD usato automaticamente dentro triage_cve quando il NIST NVD non è raggiungibile/limitato), CIRCL hashlookup e l'API range HIBP Pwned Passwords.
• Scoring con hard-override KEV + scoring_version — le CVE elencate in KEV sono sempre CRITICAL (punteggio ≥ 76); la versione dello scoring è riportata in triage_cve e health_check.
• Trasporto HTTP — imposta MCP_TRANSPORT=http per servire streamable-HTTP su (default , stateless) invece di stdio. Include un .

🌐 Fonti dati

🧪 Esecuzione dei test```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

### Test con l'MCP Inspector```bash
npx @modelcontextprotocol/inspector python -m cve_mcp.server

Si apre all'indirizzo http://localhost:6274 — testa interattivamente ogni strumento, visualizza gli schemi di input e ispeziona i formati di risposta.

Cosa coprono i test

• Test unitari: Calcolo del punteggio di rischio, parsing dei vettori CVSS, validazione degli input
• Test di integrazione: Registrazione degli strumenti, validazione dei parametri, gestione degli errori per chiavi mancanti
• Test della cache: Scritture nella cache SQLite, scadenza TTL, hit/miss della cache
• Test di sicurezza: Blocco degli IP privati, protezione dalle bombe XML (defusedxml), sanitizzazione degli input

🏛️ Approfondimento sull'architettura

Struttura dei file```

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

### Strategia di caching

| Risorsa | TTL |
|----------|-----|
| Record CVE (NVD) | 1 ora |
| Punteggi EPSS | 6 ore |
| Catalogo KEV | 1 ora |
| Intel IP / dominio | 1 ora |
| CSV di Exploit-DB | 24 ore |
| Dati ATT&CK STIX | 24 ore |
| Intel ransomware | 24 ore |

### Registro di controllo

Ogni invocazione dello strumento viene registrata in `~/.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"
}

API keys e payload delle risposte non vengono mai scritti nei log di audit.

🔐 Sicurezza e privacy

Quali dati lasciano la tua macchina

• Solo HTTPS in uscita — nessuna porta in ingresso aperta, nessuna telemetria
• CVE ID, IP, hash, domini e nomi di pacchetti vengono inviati alle rispettive API per la ricerca
• Le risposte API vengono memorizzate nella cache locale in SQLite — i dati in cache rimangono sulla tua macchina

Blocco degli IP privati

Tutti gli strumenti di network intelligence bloccano gli intervalli IP privati e riservati prima di qualsiasi chiamata API esterna:

• 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 privato)

Protezione delle chiavi API

• Chiavi caricate solo da variabili d'ambiente — mai hardcoded
• .env è nel gitignore
• Le chiavi non vengono mai registrate, memorizzate nella cache o incluse nelle voci di audit

Sicurezza XML

defusedxml viene utilizzato per tutto il parsing XML per prevenire attacchi XML bomb (billion laughs, iniezione XXE).

🔧 Risoluzione dei problemi

Il server non si avvia```bash

Ensure virtual environment is activated and package is installed

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

**Claude Desktop non mostra l'icona del martello (🔨)**
- Controlla la presenza di errori di sintassi JSON (niente virgole finali) nella tua configurazione
- Usa **percorsi assoluti** — i percorsi relativi falliscono silenziosamente
- Esci completamente da Claude Desktop (Cmd+Q / Alt+F4) e riavvialo

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

Il server accoda automaticamente le richieste in eccesso, ma con una chiave ottieni una produttività 10×.

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

### Problemi di codifica di Windows```powershell
$env:PYTHONUTF8 = "1"
$env:PYTHONIOENCODING = "utf-8"

🗺️ Roadmap e limitazioni note

Cosa il server NON fa

• Nessuna scansione attiva — solo intelligence/ricerca, non sonda la tua infrastruttura
• Nessuna operazione di scrittura — legge solo da API esterne (tranne gli invii a URLScan)
• Nessuna valutazione CVSS v4.0 — il calcolatore integrato gestisce solo la v3.1; i punteggi v4.0 forniti da NVD vengono visualizzati ma non ricalcolati

Limitazioni note delle API

• NVD restituisce al massimo 2.000 risultati per query
• I punteggi EPSS per le CVE appena pubblicate (meno di 24 ore) potrebbero non esistere ancora
• Aggiornamenti CISA KEV solo nei giorni lavorativi statunitensi
• Livello community di GreyNoise: 50 query/settimana
• Livello gratuito di VirusTotal: 4 richieste/minuto
• CIRCL PDNS richiede registrazione manuale e approvazione
• Ransomwhere applica un embargo di 90 giorni sui nuovi indirizzi

Miglioramenti previsti

• Calcolatore locale CVSS v4.0
• Webhook/avvisi per aggiunte KEV e variazioni dei punteggi EPSS su una watchlist CVE
• Esportazione STIX 2.1 per l'integrazione con SIEM
• Container Docker con distribuzione senza installazione
• Trasporto HTTP streamable (MCP SSE)
• Fonti aggiuntive: Censys, SecurityTrails, VulnCheck

🤝 Contributi

I contributi sono benvenuti.

Aggiunta di un nuovo tool

1. Aggiungi la funzione del tool in server.py con il decorator @mcp.tool()

2. Aggiungi la validazione degli input in utils/validators.py

3. Implementa il client API in api/

4. Aggiungi i test in tests/

5. Aggiorna questo 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

### Requisiti di test

- Tutti i nuovi strumenti devono avere almeno un test offline con risposte simulate (mock)
- Le modifiche al punteggio di rischio devono includere casi di test per la verifica delle formule
- Gli strumenti di rete devono includere un test che verifichi il blocco degli IP privati
- Tutti i test devono passare: `pytest tests/ -v`

---

## 📄 Licenza

Licenza MIT — vedi [LICENSE](https://github.com/mukul975/cve-mcp-server/blob/main/LICENSE) per i dettagli.```
Copyright (c) 2025-2026 Mahipal Jangra (mukul975)

Realizzato con 🔐 da Mahipal Jangra · Berlino, Germania
Trasformare l'intelligence sulla sicurezza in conversazione.