gautamvarmadatla/mcpsafetywarden
Servidor proxy que envuelve servidores MCP con perfilado de comportamiento, escaneo de seguridad, control de riesgos y ejecución segura. Detecta inyección de indicaciones, metadatos de herramientas maliciosos, inyección de argumentos, riesgos de código fuente y exposición de credenciales.
[!IMPORTANT] La seguridad de MCP es un área de investigación activa. Encuestas recientes catalogan muchas categorías de amenazas específicas del protocolo que abarcan envenenamiento de herramientas, inyección de prompts, ataques de "rug-pull", compromiso de la cadena de suministro, exfiltración de credenciales y ataques de composición en todo el ciclo de vida del servidor. Ver Securing the MCP (OpenReview), Landscape & Threats (arXiv), When MCP Servers Attack (arXiv) y MCP-38 Taxonomy (arXiv).
Úsalo como proxy para añadir filtrado de seguridad a cualquier servidor MCP, o apúntalo a un servidor que no poseas y ejecuta una auditoría de seguridad completa sin realizar una sola llamada a una herramienta.
Fig 1. Dos modos de operación: proxy y auditoría
Perfilado de comportamiento: Clase de efecto, seguridad de reintentos, destructividad. Asistido por LLM (Anthropic, OpenAI, Gemini, Ollama) con respaldo basado en reglas. Estadísticas observadas (latencia p50/p95, tasa de fallos, tamaño de salida) actualizadas tras cada llamada proxy.
Escaneo de seguridad: mcpsafety+ pipeline de cinco etapas (Reconocimiento, Planificador, Hacker, Auditor, Supervisor). Cisco AI Defense (AST/YARA). Snyk (análisis de metadatos). Las integraciones con Kali y Burp Suite enriquecen el pipeline con datos reales de red y sondas a nivel HTTP. Escaneo de código fuente desde GitHub con detección de entropía, AST, flujo de datos "taint" y detección de "rug-pull".
Fig 2. Pipeline de cinco etapas de mcpsafety+, activado cuando se ejecuta una auditoría de seguridad completa en cualquier servidor MCP
Ejecución segura: Escaneo de argumentos (más de 20 categorías de ataque, segunda pasada con LLM). Escaneo de inyección de salida en dos capas. Filtrado de riesgos con alternativas y políticas por herramienta. Detección de deriva en cada llamada y comprobación independiente.
Fig 3. Pipeline de ejecución segura: las cinco comprobaciones por las que pasa cada llamada de herramienta proxy
CLI: 24 subcomandos, menú interactivo de riesgos, bandera --json en cada comando, --yes para CI.
Qué detecta
Sin una clave, el wrapper opera solo en modo basado en reglas: clasificación de herramientas con menor confianza, escaneo de inyección solo con expresiones regulares, sin alternativas en el filtro de riesgos, sin pipeline mcpsafety+. Para una configuración completamente local, ejecuta Ollama, configura OLLAMA_MODEL y pasa explícitamente --provider ollama (Ollama no se detecta automáticamente).
[!NOTE] Servidores stdio que requieren configuración local (servidores
stdioque necesitan configuración local antes de iniciarse: archivos de configuración faltantes, credenciales, directorios de datos o dependencias específicas del SO) no pueden ser inspeccionados por el wrapper; el descubrimiento de herramientas fallará y se almacenarán 0 herramientas. Aún puedes ejecutar un escaneo de seguridad completo del código fuente sin iniciar el servidor pasando--github-urlascan/onboard, o el parámetrogithub_urlasecurity_scan_server. El pipeline mcpsafety+ obtendrá y analizará el código fuente directamente desde GitHub. Los servidoressseystreamable_httpno se ven afectados.
pip install mcpsafetywarden
Con todos los extras opcionales:
pip install "mcpsafetywarden[all]"
O extras específicos:
pip install "mcpsafetywarden[anthropic,snyk]"
Desde el código fuente:
git clone https://github.com/gautamvarmadatla/mcpsafetywarden
cd mcpsafetywarden
pip install .
La base de datos SQLite se crea automáticamente en la primera ejecución en el directorio de datos de usuario de la plataforma (~/.local/share/mcpsafetywarden/ en Linux, ~/Library/Application Support/mcpsafetywarden/ en macOS, %APPDATA%\mcpsafetywarden\ en Windows). Sobrescribe con MCP_DB_PATH.
Protección de credenciales (automática, no requiere acción)
Los valores secretos pasados a register_server o onboard_server (tokens Bearer, claves API en headers o env) se detectan automáticamente y se reemplazan con identificadores opacos cref_ antes de que nada toque el contexto del modelo. La credencial real se almacena cifrada en la base de datos y se resuelve silenciosamente en el momento de la conexión. El modelo, el historial de conversación y los registros solo ven cref_<id>.
Opcional: cifrado en reposo para credenciales almacenadas
pip install cryptography
python -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())"
Establece la clave impresa como MCP_DB_ENCRYPTION_KEY antes de iniciar el servidor. Esto cifra tanto las credenciales del servidor como los valores cref_ en reposo.
Toda la configuración se realiza mediante variables de entorno.
| Variable | Valor por defecto | Propósito |
|---|---|---|
MCP_TRANSPORT | stdio | Modo de transporte: stdio, sse o streamable_http |
MCP_HOST | 127.0.0.1 | Dirección de enlace para transportes HTTP |
MCP_PORT | 8000 | Puerto de enlace para transportes HTTP |
MCP_AUTH_TOKEN | (sin definir) | Token Bearer para autenticación de transporte HTTP |
MCP_DB_ENCRYPTION_KEY | (sin definir) | Clave Fernet para cifrar credenciales almacenadas en reposo |
ANTHROPIC_API_KEY | (sin definir) | Habilita Anthropic como proveedor de LLM |
OPENAI_API_KEY | (sin definir) | Habilita OpenAI como proveedor de LLM |
GEMINI_API_KEY o GOOGLE_API_KEY | (sin definir) | Habilita Gemini como proveedor de LLM (se prefiere GEMINI_API_KEY) |
OLLAMA_MODEL | (sin definir) | Nombre del modelo para Ollama (ej. llama3.1) |
OLLAMA_BASE_URL | http://localhost:11434/v1 | URL base de la API de Ollama |
SNYK_TOKEN | (sin definir) | Habilita la detección de inyección de prompts Snyk E001 |
MCP_SCANNER_API_KEY | (sin definir) | Clave del motor ML en la nube de Cisco AI Defense |
MCP_SCANNER_LLM_API_KEY | (sin definir) | Clave LLM para análisis AST interno de Cisco |
MCP_DB_PATH | (sin definir) | Sobrescribe la ruta del archivo de base de datos SQLite |
MCP_GRAPH_POLICY | warn | Aplicación del grafo en safe_tool_call: (desactivado), (adjuntar contexto de riesgo a la respuesta), (bloquear herramientas de radio de explosión crítico/alto a menos que ) |
Nota de seguridad: Nunca confirmes claves API ni la clave de cifrado. El wrapper elimina sus propios secretos de los entornos de los procesos hijo antes de iniciar servidores stdio.
Añade el 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 cada servidor con el wrapper antes de usarlo:
mcpsafetywarden register filesystem --transport stdio \
--command npx \
--args '["-y", "@modelcontextprotocol/server-filesystem", "/Users/yourname/Documents"]'
Para una configuración de puerta de enlace obligatoria donde todas las llamadas a herramientas deben pasar por el wrapper, consulta docs/DEPLOYMENT.md.
Consulta docs/TOOLS.md para la referencia completa de herramientas.
| Herramienta | Qué hace |
|---|---|
onboard_server | Registrar + inspeccionar + escanear seguridad en una sola llamada |
register_server | Registrar un servidor; opcionalmente inspeccionar automáticamente |
inspect_server | Actualizar la lista de herramientas y perfiles |
check_server_drift | Detectar deriva de esquema y lista de herramientas respecto a la línea base almacenada |
list_servers | Listar todos los servidores registrados |
list_server_tools | Listar herramientas en un servidor con perfiles resumidos |
preflight_tool_call | Evaluación de riesgos sin ejecución |
safe_tool_call | Ejecutar con filtrado de riesgos y alternativas |
get_tool_profile | Perfil de comportamiento completo con estadísticas observadas |
get_retry_policy | Recomendaciones de reintentos y tiempo de espera |
suggest_safer_alternative | Alternativas más seguras ordenadas por LLM |
run_replay_test | Prueba de idempotencia (llama a la herramienta dos veces) |
security_scan_server | Auditoría de seguridad en vivo (mcpsafety+, Cisco, Snyk) |
scan_all_servers | Pipeline mcpsafety+ en todos los servidores registrados |
get_security_scan | Último informe de escaneo almacenado |
set_tool_policy | Política permanente de permitir/bloquear para una herramienta |
get_run_history | Historial de ejecución reciente de una herramienta |
ping_server | Comprobación de accesibilidad con latencia |
discover_servers | Escanear el sistema de archivos en busca de configuraciones de clientes MCP y extraer entradas de servidores |
onboard_discovered_servers |
24 subcomandos que cubren las 25 herramientas MCP. Cada comando admite --json para salida legible por máquina y --yes / -y para omitir mensajes de confirmación.
Consulta docs/CLI.md para la referencia completa con banderas y ejemplos.
Kali Linux MCP, Burp Suite MCP y Snyk se integran automáticamente una vez registrados. Kali enriquece la etapa de Reconocimiento y ping_server con datos reales de nmap/traceroute. Burp añade sondeo HTTP sin procesar, callbacks fuera de banda y evidencia de proxy. Snyk analiza los metadatos de las herramientas para cadenas de inyección, suplantación de herramientas, secretos codificados y otras 16 comprobaciones.
Consulta docs/INTEGRATIONS.md para instrucciones de configuración.
Instala en modo editable:
pip install -e ".[all]"
Ejecuta el servidor y observa los registros:
mcpsafetywarden-server 2>server.log
Cada módulo usa logging.getLogger(__name__). El servidor no llama a logging.basicConfig por sí mismo; configura el registro en tu punto de entrada antes de importar.
pytest tests/ -v
Establece una clave de API de LLM para incluir pruebas asistidas por LLM; sin una, se omiten automáticamente. Consulta docs/TESTING.md para la verificación paso a paso de clasificación, escaneo de inyección, filtrado de riesgos y aplicación de políticas.
| Documento | Contenido |
|---|---|
| docs/TOOLS.md | Referencia completa de las 25 herramientas MCP |
| docs/CLI.md | Subcomandos de CLI, banderas y ejemplos |
| docs/INTEGRATIONS.md | Configuración de Kali, Burp Suite y Snyk |
| docs/DEPLOYMENT.md | Despliegue en stdio, HTTP, contenedor y puerta de enlace |
| docs/TROUBLESHOOTING.md | Errores comunes y soluciones |
| docs/SECURITY.md | Detalles sobre secretos, autenticación, aislamiento y escaneo |
| docs/TESTING.md | Pasos de verificación para cada funcionalidad |
| docs/COMPARISON.md | Comparación con herramientas relacionadas |
| docs/ROADMAP.md | Funcionalidades planificadas |
Consulta CONTRIBUTING.md para los estándares de código y las pautas de solicitudes de extracción.
Apache License 2.0. Consulta LICENSE para más detalles.
offwarnblockapproved=TrueGITHUB_TOKEN | (sin definir) | Token de acceso personal de GitHub para escaneo de código fuente (aumenta el límite de tasa de 60 a 5000 solicitudes/hora) |
| Registrar servidores descubiertos en lote |
get_risk_graph | Construir o consultar el grafo de riesgos del inventario (servidores, herramientas, hallazgos, clientes agente) |
explain_tool_risk | Recorrer rutas de riesgo para una herramienta: radio de explosión, riesgos de composición, etiquetas MITRE, acción recomendada |
explain_client_risk | Analizar riesgos entre servidores para todos los servidores bajo un mismo cliente agente |
analyze_cve_blast_radius | Informar CVEs que afectan a múltiples servidores bajo el mismo cliente |
export_graph | Exportar grafo de riesgos como JSON o diagrama Mermaid |