Scanner di sicurezza unificato per server MCP con modalità config, pentest e repo-scan. Genera report SARIF per l'integrazione CI/CD, rileva segreti, vulnerabilità e configurazioni errate tramite analizzatori token e LLM.
MCP X-Ray è una soluzione unificata open-source di scansione di sicurezza e penetration testing per server Model Context Protocol (MCP). Genera report SARIF pronti per la produzione per una perfetta integrazione con strumenti di sicurezza e pipeline CI/CD. I risultati della scansione possono essere opzionalmente caricati su Traceforce Atlas per una gestione e un monitoraggio centralizzati della sicurezza. Atlas ha oltre 600 MCP nel suo registro, fornendo un database completo di valutazione della sicurezza per l'ecosistema MCP.
# Clona il repository
git clone https://github.com/traceforce/mcp-xray
cd mcp-xray
# Installa le dipendenze necessarie (buf, ecc.)
make install-dependencies
# Compila tutto (genera il codice protobuf e compila il binario)
# Il binario verrà creato come `mcpxray` nella directory corrente
make all
Scansiona le configurazioni MCP per problemi di sicurezza; esegui prima del pentest per stabilire una baseline.
# Scansiona un file di configurazione MCP specifico (usa token analyzer per impostazione predefinita)
./mcpxray config-scan /path/to/mcp/config.json
# Scansiona automaticamente tutti i percorsi di configurazione MCP noti per Cursor, Claude e Windsurf.
# Posizioni note dei file di configurazione (relative alla home directory):
# ~/.cursor/mcp.json (Cursor)
# ~/Library/Application Support/Claude/claude_desktop_config.json (Claude Desktop)
# ~/.codeium/windsurf/mcp_config.json (Windsurf)
./mcpxray config-scan --scan-known-configs
# Usa l'analizzatore LLM per un'analisi più estesa e approfondita
./mcpxray config-scan /path/to/mcp/config.json --analyzer-type llm --llm-model claude-3-5-sonnet-20241022
# Specifica un file di output personalizzato
./mcpxray config-scan /path/to/mcp/config.json --output custom-report.sarif.json
Capacità di rilevamento:
Esegue piani di test di sicurezza effettuando chiamate reali agli strumenti dei server MCP. Sono necessari LLM per eseguire il pentest. Eseguire prima dell'effettivo deployment in produzione.
# Esegui il pentest con piano di test generato automaticamente (richiede modello LLM)
./mcpxray pentest /path/to/mcp/config.json --llm-model claude-sonnet-4-5
# Usa un file YAML di piano di test personalizzato
./mcpxray pentest /path/to/mcp/config.json --test-plan /path/to/test-plan.yaml --llm-model claude-sonnet-4-5
Capacità di rilevamento: Esecuzione di codice, SSRF, path traversal, bypass dell'autorizzazione, input injection, divulgazione di informazioni e vulnerabilità DoS
Scansiona il codebase per vulnerabilità; usa quando possiedi o puoi modificare il codice.
# Scansiona la directory corrente
./mcpxray repo-scan
# Scansiona un repository specifico
./mcpxray repo-scan /path/to/repository
# Specifica un file di output personalizzato
./mcpxray repo-scan --output custom-report.sarif.json
Capacità di rilevamento:
MCP X-Ray genera report in formato SARIF (Static Analysis Results Interchange Format), ampiamente supportato da strumenti di sicurezza e piattaforme CI/CD.
Carica i risultati della scansione su Traceforce Atlas per una gestione, reportistica e tracciamento centralizzati nel tempo. Aggiungi il flag --upload a qualsiasi comando di scansione. Usa --clean-up per rimuovere i file generati dopo il caricamento riuscito.
Variabili d'ambiente richieste:
TRACEFORCE_CLIENT_IDTRACEFORCE_CLIENT_SECRETQueste credenziali possono essere scaricate dalla pagina delle impostazioni dell'interfaccia di Atlas.
# Carica i risultati della scansione della configurazione
./mcpxray config-scan /path/to/mcp/config.json --upload
# Carica con pulizia
./mcpxray config-scan /path/xia-add-registry-imageto/mcp/config.json --upload --clean-up
# Carica i risultati del pentest
./mcpxray pentest /path/to/mcp/config.json --llm-model claude-sonnet-4-5 --upload
Esempi di output di scansione sono disponibili in examples/findings/.
Esempi di file di configurazione MCP sono disponibili nella directory examples/mcp_configs/.
Un esempio di server MCP è disponibile nella directory examples/mcp_server/:
mcp_server.py: Server FastMCP che utilizza il trasporto streamable-httpmcp.json: File di configurazione per connettersi al serverREADME.md: Istruzioni per configurare e scansionare il serverMCP X-Ray fornisce due metodi per analizzare la sicurezza degli strumenti:
Il token analyzer utilizza il pattern matching basato su regole per rilevare rapidamente problemi di sicurezza nelle descrizioni degli strumenti. È veloce, non richiede chiavi API e funziona offline. Il token analyzer utilizza due tipi di regole:
internal/configscan/tokenanalyzer/token_rules.yaml. Ogni regola specifica:
internal/yararules/unsafe_patterns.yar. Queste regole rilevano pattern di comandi di sistema non sicuri.Utilizzo:
mcpxray config-scan --analyzer-type token
L'LLM analyzer utilizza modelli linguistici di grandi dimensioni per un'analisi semantica approfondita delle descrizioni degli strumenti, fornendo approfondimenti di sicurezza più completi.
Utilizzo:
mcpxray config-scan --analyzer-type llm --llm-model <model-name>
Per impostazione predefinita, lo strumento di pentest utilizza un LLM per generare automaticamente piani di test basati sugli strumenti disponibili dai server MCP. I piani di test possono anche essere personalizzati e forniti come file YAML. I piani di test sono file YAML contenenti casi di test con argomenti di input e output attesi.
Comportamento predefinito (piano di test generato da LLM):
./mcpxray pentest /path/to/mcp/config.json --llm-model claude-sonnet-4-5
Piano di test personalizzato:
./mcpxray pentest /path/to/mcp/config.json --test-plan /path/to/test-plan.yaml --llm-model claude-sonnet-4-5
MCP X-Ray supporta i seguenti provider LLM per l'analisi degli strumenti:
claude-sonnet-4-5ANTHROPIC_API_KEYgpt-5OPENAI_API_KEYarn:aws:bedrock: e contengono llamaarn:aws:bedrock:<region>:<account-id>:inference-profile/us.meta.llama3-2-1b-instruct-v1:0Per l'analisi degli strumenti basata su LLM, configura le credenziali API del tuo LLM:
export ANTHROPIC_API_KEY=la-tua-chiave-api
export OPENAI_API_KEY=la-tua-chiave-api
Ogni provider richiede la propria variabile d'ambiente specifica. Lo strumento rileva automaticamente quale provider utilizzare in base al nome del modello.
Per i modelli AWS Bedrock, configura le credenziali AWS utilizzando uno dei metodi standard dell'AWS SDK:
# Opzione 1: Variabili d'ambiente
export AWS_ACCESS_KEY_ID=il-tuo-access-key
export AWS_SECRET_ACCESS_KEY=il-tuo-secret-key
export AWS_REGION=us-east-1
# Opzione 2: File delle credenziali AWS (~/.aws/credentials)
# Opzione 3: Ruolo IAM (quando si esegue su EC2/ECS/Lambda)
MCP X-Ray utilizza l'AWS SDK che caricherà automaticamente le credenziali dall'ambiente, dal file delle credenziali o dal ruolo IAM.
I contributi sono benvenuti! Assicurati che: