mcpshield

Una correzione drop-in per la falla di command-injection negli MCP stdio non ancora corretta (famiglia CVE-2026-30623, segnalata da OX Security nell'aprile 2026 come "by design" -- nessuna patch SDK in arrivo). Basta importare una riga e ogni server MCP stdio avviato dalla tua app Python viene validato in command/args/env prima ancora che il sistema operativo crei un processo.

Se sei nuovo qui, leggi prima Scope, poi Installazione e Per iniziare ti proteggeranno in meno di due minuti.

Indice

• Stato del progetto
• Scope
• Installazione
• Per iniziare
  • Opzione A: auto-patch (host MCP Python)
  • Opzione B: controllo statico (qualsiasi linguaggio, zero esecuzione)
  • Opzione C: supervisore di avvio (host non Python)
• Cosa viene bloccato e cosa riceve un avviso
• Le vie di fuga
• Riferimento CLI
• Limitazioni note
• Struttura del progetto
• Sviluppo

Stato del progetto

Pre-1.0, in sviluppo attivo.

• Motore di validazione, auto-patch e CLI (check/launch/rules) sono implementati e coperti da una suite di test automatici che viene eseguita contro i binari reali installati sulla macchina di test (python, node, npx) -- non mock -- inclusa una vera handshake MCP end-to-end attraverso una fixture di server reale avviato, e un vero test a livello di sottoprocesso per launch.
• Non ancora su PyPI -- vedi Installazione.
• Vedi SECURITY.md per sapere esattamente cosa è coperto e cosa no.

Scope

In scope: validazione di un avvio di server MCP stdio (command + args + env) prima che raggiunga il livello di creazione dei processi del sistema operativo, in particolare per chiudere il percorso di injection di comandi/argomenti descritto in SECURITY.md.

Esplicitamente fuori scope: scansione dei tool dichiarati di un server per capacità rischiose (è un problema diverso -- vedi AgentGuard), sandboxing del processo avviato e trasporti MCP non stdio (SSE/HTTP).

Installazione

git clone <questo-repo>
cd mcpshield
pip install -e .          # CLI principale: solo click + rich
pip install -e ".[mcp]"   # se vuoi anche l'auto-patch Python (richiede l'SDK `mcp`)

Verifica che funzioni:

mcpshield --version
mcpshield --help

Per iniziare

Opzione A: auto-patch (host MCP Python)

Se la tua app è scritta in Python e costruisce StdioServerParameters / chiama direttamente mcp.client.stdio.stdio_client, aggiungi un import all'inizio assoluto del tuo entrypoint -- prima che qualsiasi altro import carichi mcp.client.stdio:

import mcpshield.autopatch  # import con side-effect; deve essere il primo

from mcp import ClientSession, StdioServerParameters
from mcp.client.stdio import stdio_client
# ... usa stdio_client esattamente come prima -- ora è validato

Un avvio non sicuro ora solleva mcpshield.core.errors.UnsafeConfigurationError (un sottotipo di ValueError) invece di creare mai un processo.

Opzione B: controllo statico (qualsiasi linguaggio, zero esecuzione)

Controlla un file di configurazione in stile mcpServers senza eseguire nulla:

mcpshield check claude_desktop_config.json

+---------------------------------------------------------------+
| Server           | Status  | Command | Detail                 |
|------------------+---------+---------+------------------------|
| filesystem       | OK      | npx     | -                      |
| evil-server      | BLOCKED | npx     | Argument '...' contains|
|                  |         |         | shell metacharacter    |
+---------------------------------------------------------------+

  1 ok, 0 warned, 1 blocked

Esce con codice non-zero se qualcosa è BLOCKED (aggiungi --strict per fallire anche con WARN) -- inseriscilo direttamente in CI.

Opzione C: supervisore di avvio (host non Python)

Per un client MCP (Node, Java, Rust, ...) che non può usare l'auto-patch Python, punta la sua configurazione a mcpshield invece che al comando reale:

{
  "command": "mcpshield",
  "args": ["launch", "--", "npx", "-y", "some-mcp-server"]
}

launch valida e poi esegue il comando reale con lo stesso stdin/stdout che il tuo client MCP si aspetta (passthrough trasparente) -- oppure rifiuta con un errore chiaro se l'avvio non è sicuro.

Cosa viene bloccato e cosa riceve un avviso

I binari nativi ricevono controlli sugli argomenti più permissivi perché eseguono direttamente con exec -- non c'è una shell che ri-parse la lista degli argomenti. I comandi interpretabili dalla shell (più comunemente npx.cmd/npx.bat su Windows) ricevono controlli rigorosi perché è esattamente il meccanismo sfruttato dalla CVE sottostante.

Le vie di fuga

Entrambe sono opt-in deliberati, per singolo valore -- mai un flag generico "disabilita i controlli":

• allow_raw_args=["--some-value-with-a-pipe"] (libreria) esenta specifici valori di argomenti che hai rivisto e di cui ti fidi.
• allow_env=["SOME_VAR"] consente a una variabile d'ambiente normalmente rimossa di passare senza modifiche.

Riferimento CLI

Limitazioni note

• Non ancora su PyPI -- l'installazione richiede git clone.
• L'auto-patch corregge solo mcp.client.stdio.stdio_client come risolto al momento della patch. Il codice che ha già un proprio riferimento (tramite from mcp.client.stdio import stdio_client eseguito prima di import mcpshield.autopatch) lo bypasserà -- importa sempre prima mcpshield.autopatch.
• Il controllo dei metacaratteri di shell è basato su una denylist, applicata solo quando il comando risolto viene rilevato come interpretabile dalla shell. Non è un parser completo della grammatica shell -- vedi SECURITY.md per il confine esatto dello scope.
• check risolve i comandi usando la macchina su cui viene eseguito. Una configurazione che verrebbe risolta diversamente sulla macchina in cui è effettivamente distribuita (un PATH diverso, strumenti installati diversi) potrebbe riportare risultati diversi.

Struttura del progetto

mcpshield/
  autopatch.py           # fix con import a una riga per host MCP Python
  core/
    validate.py           # il motore di validazione (check su command/args/env)
    rules.py               # dati per blocklist/allowlist
    errors.py               # UnsafeConfigurationError
  cli/
    main.py
    commands/ (check.py, launch.py, rules.py)
tests/
  fixtures/                 # server MCP benigno reale + configurazioni di esempio/maligne

Sviluppo

pip install -e ".[dev,mcp]"
pytest

La suite di test valida contro i binari reali python/node/npx installati sulla macchina su cui viene eseguita (risolti nello stesso modo in cui li risolve il motore stesso) e include una vera handshake MCP end-to-end attraverso una fixture di server reale avviato -- non mock.