gautamvarmadatla/mcpsafetywarden
Server proxy che avvolge i server MCP con profilazione comportamentale, scansione di sicurezza, controllo dei rischi ed esecuzione sicura. Rileva l'iniezione di prompt, metadati di strumenti malevoli, iniezione di argomenti, rischi del codice sorgente ed esposizione di credenziali.
MCP Safety Warden è un server proxy che avvolge qualsiasi server MCP e aggiunge profilazione comportamentale, scansione di sicurezza, gating del rischio ed esecuzione sicura ai suoi strumenti.
[!IMPORTANTE] La sicurezza MCP è un'area di ricerca attiva. Recenti studi catalogano numerose categorie di minacce specifiche del protocollo, che spaziano da avvelenamento degli strumenti, iniezione di prompt, attacchi rug-pull, compromissione della supply chain, esfiltrazione di credenziali e attacchi di composizione lungo l'intero ciclo di vita del server. Vedi Securing the MCP (OpenReview), Landscape & Threats (arXiv), When MCP Servers Attack (arXiv) e MCP-38 Taxonomy (arXiv).
Utilizzalo come proxy per aggiungere gating di sicurezza a qualsiasi server MCP, oppure puntalo verso un server che non possiedi ed esegui un audit di sicurezza completo senza effettuare alcuna chiamata a uno strumento.
Fig. 1. Due modalità operative: proxy e audit
Profilazione comportamentale: Classe di effetto, sicurezza di ripetizione, distruttività. Assistita da LLM (Anthropic, OpenAI, Gemini, Ollama) con fallback basato su regole. Statistiche osservate (latenza p50/p95, tasso di fallimento, dimensione output) aggiornate dopo ogni chiamata proxy.
Scansione di sicurezza: pipeline mcpsafety+ a cinque fasi (Recon, Planner, Hacker, Auditor, Supervisor). Cisco AI Defense (AST/YARA). Snyk (analisi dei metadati). Le integrazioni con Kali e Burp Suite arricchiscono la pipeline con dati di rete reali e sonde a livello HTTP. Scansione del codice sorgente da GitHub con rilevamento di entropia, AST, flusso di taint e rug-pull.
Fig. 2. Pipeline mcpsafety+ a cinque fasi, attivata quando si esegue un audit di sicurezza completo su qualsiasi server MCP
Esecuzione sicura: Scansione degli argomenti (20+ categorie di attacco, secondo passaggio LLM). Scansione dell'iniezione di output a due livelli. Gating del rischio con alternative e policy per strumento. Rilevamento della deriva (drift) su ogni chiamata e controllo autonomo.
Fig. 3. Pipeline di esecuzione sicura: i cinque controlli che ogni chiamata proxy a uno strumento deve superare
CLI: 24 sottocomandi, menu interattivo del rischio, flag --json su ogni comando, --yes per CI.
Cosa rileva
Senza una chiave, il wrapper opera solo in modalità basata su regole: classificazione degli strumenti con minore confidenza, scansione delle iniezioni solo con regex, nessuna alternativa nel gate di rischio, nessuna pipeline mcpsafety+. Per una configurazione completamente locale, esegui Ollama, imposta OLLAMA_MODEL e passa --provider ollama esplicitamente (Ollama non viene rilevato automaticamente).
[!NOTA] I server stdio che richiedono configurazione locale (server
stdioche necessitano di configurazione locale prima di avviarsi – file di configurazione mancanti, credenziali, directory di dati o dipendenze specifiche del sistema operativo) non possono essere ispezionati dal wrapper – la scoperta degli strumenti fallirà e verranno archiviati 0 strumenti. Puoi comunque eseguire una scansione di sicurezza completa del codice sorgente senza avviare il server passando--github-urlascan/onboard, o il parametrogithub_urlasecurity_scan_server. La pipeline mcpsafety+ recupererà e analizzerà il sorgente direttamente da GitHub. I serversseestreamable_httpnon sono interessati.
pip install mcpsafetywarden
Con tutti gli extra opzionali:
pip install "mcpsafetywarden[all]"
Oppure extra specifici:
pip install "mcpsafetywarden[anthropic,snyk]"
Dal sorgente:
git clone https://github.com/gautamvarmadatla/mcpsafetywarden
cd mcpsafetywarden
pip install .
Il database SQLite viene creato automaticamente al primo avvio nella directory dei dati utente della piattaforma (~/.local/share/mcpsafetywarden/ su Linux, ~/Library/Application Support/mcpsafetywarden/ su macOS, %APPDATA%\mcpsafetywarden\ su Windows). Sovrascrivi con MCP_DB_PATH.
Protezione delle credenziali (automatica, nessuna azione richiesta)
I valori segreti passati a register_server o onboard_server (token Bearer, chiavi API in headers o env) vengono automaticamente rilevati e sostituiti con identificatori opachi cref_ prima che qualsiasi cosa tocchi il contesto del modello. La credenziale reale viene archiviata crittografata nel database e risolta silenziosamente al momento della connessione. Il modello, la cronologia delle conversazioni e i log vedono solo cref_<id>.
Opzionale: crittografia a riposo per le credenziali archiviate
pip install cryptography
python -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())"
Imposta la chiave stampata come MCP_DB_ENCRYPTION_KEY prima di avviare il server. Questo crittografa sia le credenziali del server che i valori cref_ a riposo.
Tutta la configurazione avviene tramite variabili d'ambiente.
| Variabile | Default | Scopo |
|---|---|---|
MCP_TRANSPORT | stdio | Modalità di trasporto: stdio, sse o streamable_http |
MCP_HOST | 127.0.0.1 | Indirizzo di bind per i trasporti HTTP |
MCP_PORT | 8000 | Porta di bind per i trasporti HTTP |
MCP_AUTH_TOKEN | (non impostato) | Token Bearer per l'autenticazione del trasporto HTTP |
MCP_DB_ENCRYPTION_KEY | (non impostato) | Chiave Fernet per crittografare le credenziali archiviate a riposo |
ANTHROPIC_API_KEY | (non impostato) | Abilita Anthropic come provider LLM |
OPENAI_API_KEY | (non impostato) | Abilita OpenAI come provider LLM |
GEMINI_API_KEY o GOOGLE_API_KEY | (non impostato) | Abilita Gemini come provider LLM (GEMINI_API_KEY preferito) |
OLLAMA_MODEL | (non impostato) | Nome del modello per Ollama (es. llama3.1) |
OLLAMA_BASE_URL | http://localhost:11434/v1 | URL base dell'API Ollama |
SNYK_TOKEN | (non impostato) | Abilita il rilevamento di iniezione di prompt Snyk E001 |
MCP_SCANNER_API_KEY | (non impostato) | Chiave del motore ML cloud Cisco AI Defense |
MCP_SCANNER_LLM_API_KEY | (non impostato) | Chiave LLM per l'analisi AST interna di Cisco |
MCP_DB_PATH | (non impostato) | Sovrascrive il percorso del file del database SQLite |
MCP_GRAPH_POLICY | warn | Applicazione del grafo in safe_tool_call: (disabilitato), (allega contesto di rischio alla risposta), (blocco rigido degli strumenti critici/ad alto raggio di danno a meno che ) |
Nota di sicurezza: Non committare mai chiavi API o la chiave di crittografia. Il wrapper rimuove i propri segreti dagli ambienti dei processi figlio prima di avviare i server stdio.
Aggiungi il wrapper a claude_desktop_config.json:
{
"mcpServers": {
"mcpsafetywarden": {
"command": "mcpsafetywarden-server",
"args": [],
"env": {
"ANTHROPIC_API_KEY": "sk-ant-...",
"MCP_DB_ENCRYPTION_KEY": "<generated_fernet_key>"
}
},
"filesystem": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users/yourname/Documents"]
}
}
}
Registra ogni server con il wrapper prima dell'uso:
mcpsafetywarden register filesystem --transport stdio \
--command npx \
--args '["-y", "@modelcontextprotocol/server-filesystem", "/Users/yourname/Documents"]'
Per una configurazione gateway obbligatoria in cui tutte le chiamate agli strumenti devono passare attraverso il wrapper, vedi docs/DEPLOYMENT.md.
Vedi docs/TOOLS.md per il riferimento completo agli strumenti.
| Strumento | Cosa fa |
|---|---|
onboard_server | Registra + ispeziona + scansiona la sicurezza in una sola chiamata |
register_server | Registra un server; opzionalmente auto-ispeziona |
inspect_server | Aggiorna lista strumenti e profili |
check_server_drift | Rileva deriva di schema e lista strumenti rispetto alla baseline archiviata |
list_servers | Elenca tutti i server registrati |
list_server_tools | Elenca gli strumenti su un server con profili riassuntivi |
preflight_tool_call | Valutazione del rischio senza esecuzione |
safe_tool_call | Esecuzione con gating del rischio e alternative |
get_tool_profile | Profilo comportamentale completo con statistiche osservate |
get_retry_policy | Raccomandazioni su ripetizione e timeout |
suggest_safer_alternative | Alternative più sicure ordinate da LLM |
run_replay_test | Test di idempotenza (chiama lo strumento due volte) |
security_scan_server | Audit di sicurezza live (mcpsafety+, Cisco, Snyk) |
scan_all_servers | Pipeline mcpsafety+ su tutti i server registrati |
get_security_scan | Ultimo report di scansione archiviato |
set_tool_policy | Policy permanente di consentire/bloccare per uno strumento |
get_run_history | Cronologia esecuzioni recenti per uno strumento |
ping_server | Controllo di raggiungibilità con latenza |
discover_servers | Scansiona il filesystem per configurazioni client MCP ed estrae voci server |
onboard_discovered_servers | Registra in blocco i server scoperti |
24 sottocomandi che coprono tutti i 25 strumenti MCP. Ogni comando supporta --json per output leggibile dalla macchina e --yes / -y per saltare le richieste di conferma.
Vedi docs/CLI.md per il riferimento completo con flag ed esempi.
Kali Linux MCP, Burp Suite MCP e Snyk si integrano automaticamente una volta registrati. Kali arricchisce la fase Recon e ping_server con dati reali di nmap/traceroute. Burp aggiunge probing HTTP grezzo, callback out-of-band e prove proxy. Snyk analizza i metadati degli strumenti per stringhe di iniezione, shadowing di strumenti, segreti hardcoded e altri 16 controlli.
Vedi docs/INTEGRATIONS.md per le istruzioni di configurazione.
Installa in modalità modificabile:
pip install -e ".[all]"
Esegui il server e osserva i log:
mcpsafetywarden-server 2>server.log
Ogni modulo utilizza logging.getLogger(__name__). Il server non chiama logging.basicConfig da solo – configura il logging nel tuo punto di ingresso prima di importare.
pytest tests/ -v
Imposta una chiave API LLM per includere i test assistiti da LLM; senza di essa vengono saltati automaticamente. Vedi docs/TESTING.md per la verifica passo passo di classificazione, scansione delle iniezioni, gating del rischio e applicazione delle policy.
| Documento | Contenuti |
|---|---|
| docs/TOOLS.md | Riferimento completo per tutti i 25 strumenti MCP |
| docs/CLI.md | Sottocomandi CLI, flag ed esempi |
| docs/INTEGRATIONS.md | Configurazione di Kali, Burp Suite e Snyk |
| docs/DEPLOYMENT.md | Distribuzione stdio, HTTP, contenitore e gateway |
| docs/TROUBLESHOOTING.md | Errori comuni e soluzioni |
| docs/SECURITY.md | Dettagli su segreti, autenticazione, isolamento e scansione |
| docs/TESTING.md | Passi di verifica per ogni funzionalità |
| docs/COMPARISON.md | Confronto con strumenti correlati |
| docs/ROADMAP.md | Funzionalità pianificate |
Vedi CONTRIBUTING.md per gli standard del codice e le linee guida per le pull request.
Apache License 2.0. Vedi LICENSE per i dettagli.
offwarnblockapproved=TrueGITHUB_TOKEN | (non impostato) | Token di accesso personale GitHub per la scansione del codice sorgente (aumenta il limite di richieste da 60 a 5.000 all'ora) |
get_risk_graph |
| Costruisce o interroga il grafo dei rischi dell'inventario (server, strumenti, risultati, agenti client) |
explain_tool_risk | Percorsi di rischio per uno strumento: raggio di danno, rischi di composizione, tag MITRE, azione raccomandata |
explain_client_risk | Analizza i rischi cross-server per tutti i server sotto un unico agente client |
analyze_cve_blast_radius | Segnala CVE che colpiscono più server sotto lo stesso client |
export_graph | Esporta il grafo dei rischi come JSON o diagramma Mermaid |