traceforce/mcp-xrayEscáner de seguridad unificado para servidores MCP con modos de configuración, pentest y escaneo de repositorios. Genera informes SARIF para integración CI/CD, detecta secretos, vulnerabilidades y configuraciones erróneas mediante analizadores de tokens y LLM.
MCP X-Ray es una solución unificada de código abierto para escaneo de seguridad y pruebas de penetración para servidores Model Context Protocol (MCP). Genera informes SARIF listos para producción para una integración sin problemas con herramientas de seguridad y pipelines CI/CD. Los resultados del escaneo se pueden cargar opcionalmente a Traceforce Atlas para una gestión y seguimiento centralizados de la seguridad. Atlas tiene más de 600 MCPs en su registro, proporcionando una base de datos integral de evaluación de seguridad para el ecosistema MCP.
# Clone the repository
git clone https://github.com/traceforce/mcp-xray
cd mcp-xray
# Install required dependencies (buf, etc.)
make install-dependencies
# Build everything (generates protobuf code and builds the binary)
# The binary will be created as `mcpxray` in the current directory
make all
Escanea configuraciones MCP en busca de problemas de seguridad; ejecútelo antes de la prueba de penetración para establecer una línea base de su configuración.
# Scan a specific MCP config file (uses token analyzer by default)
./mcpxray config-scan /path/to/mcp/config.json
# Scan all known MCP config paths automatically for Cursor, Claude and Windsurf.
# Known config locations (relative to 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
# Use LLM analyzer for more extensive and deepr analysis
./mcpxray config-scan /path/to/mcp/config.json --analyzer-type llm --llm-model claude-3-5-sonnet-20241022
# Specify custom output file
./mcpxray config-scan /path/to/mcp/config.json --output custom-report.sarif.json
Capacidades de detección:
Ejecuta planes de prueba de seguridad realizando llamadas reales a herramientas contra servidores MCP. Se requieren LLMs para ejecutar la prueba de penetración. Ejecútelo antes del despliegue real en producción.
# Run pentest with auto-generated test plan (requires LLM model)
./mcpxray pentest /path/to/mcp/config.json --llm-model claude-sonnet-4-5
# Use a custom test plan YAML file
./mcpxray pentest /path/to/mcp/config.json --test-plan /path/to/test-plan.yaml --llm-model claude-sonnet-4-5
Capacidades de detección: Ejecución de código, SSRF, path traversal, omisión de autorización, inyección de entrada, divulgación de información y vulnerabilidades DoS
Escanea el código fuente en busca de vulnerabilidades; úselo cuando sea propietario o pueda modificar el código.
# Scan current directory
./mcpxray repo-scan
# Scan a specific repository
./mcpxray repo-scan /path/to/repository
# Specify custom output file
./mcpxray repo-scan --output custom-report.sarif.json
Capacidades de detección:
MCP X-Ray genera informes en formato SARIF (Static Analysis Results Interchange Format), que es ampliamente compatible con herramientas de seguridad y plataformas CI/CD.
Cargue los resultados del escaneo a Traceforce Atlas para una gestión, generación de informes y seguimiento centralizados de la seguridad a lo largo del tiempo. Agregue la opción --upload a cualquier comando de escaneo. Use --clean-up para eliminar los archivos generados después de una carga exitosa.
Variables de entorno requeridas:
TRACEFORCE_CLIENT_IDTRACEFORCE_CLIENT_SECRETEstas credenciales se pueden descargar desde la página de configuración en la interfaz de Atlas.
# Upload config scan results
./mcpxray config-scan /path/to/mcp/config.json --upload
# Upload with cleanup
./mcpxray config-scan /path/xia-add-registry-imageto/mcp/config.json --upload --clean-up
# Upload pentest results
./mcpxray pentest /path/to/mcp/config.json --llm-model claude-sonnet-4-5 --upload
Los resultados de escaneo de ejemplo están disponibles en examples/findings/.
Los archivos de configuración MCP de ejemplo están disponibles en el directorio examples/mcp_configs/.
Un servidor MCP de ejemplo está disponible en el directorio examples/mcp_server/:
mcp_server.py: FastMCP servidor usando transporte streamable-httpmcp.json: Archivo de configuración para conectarse al servidorREADME.md: Instrucciones para configurar y escanear el servidorMCP X-Ray proporciona dos métodos para analizar la seguridad de las herramientas:
El token analyzer utiliza coincidencia de patrones basada en reglas para detectar rápidamente problemas de seguridad en las descripciones de herramientas. Es rápido, no requiere claves API y funciona sin conexión. El token analyzer utiliza dos tipos de reglas:
internal/configscan/tokenanalyzer/token_rules.yaml. Cada regla especifica:
internal/yararules/unsafe_patterns.yar. Estas reglas detectan patrones de comandos inseguros del sistema.Uso:
mcpxray config-scan --analyzer-type token
El LLM analyzer utiliza modelos de lenguaje grandes para un análisis semántico profundo de las descripciones de herramientas, proporcionando información de seguridad más completa.
Uso:
mcpxray config-scan --analyzer-type llm --llm-model <model-name>
Por defecto, la herramienta de pentest utiliza un LLM para generar automáticamente planes de prueba basados en las herramientas disponibles de los servidores MCP. Los planes de prueba también se pueden personalizar y proporcionar como archivos YAML. Los planes de prueba son archivos YAML que contienen casos de prueba con argumentos de entrada y salidas esperadas.
Comportamiento predeterminado (plan de prueba generado por LLM):
./mcpxray pentest /path/to/mcp/config.json --llm-model claude-sonnet-4-5
Plan de prueba personalizado:
./mcpxray pentest /path/to/mcp/config.json --test-plan /path/to/test-plan.yaml --llm-model claude-sonnet-4-5
MCP X-Ray admite los siguientes proveedores de LLM para el análisis de herramientas:
claude-sonnet-4-5ANTHROPIC_API_KEYgpt-5OPENAI_API_KEYarn:aws:bedrock: y contienen llamaarn:aws:bedrock:<region>:<account-id>:inference-profile/us.meta.llama3-2-1b-instruct-v1:0Para el análisis de herramientas basado en LLM, configure sus credenciales de API de LLM:
export ANTHROPIC_API_KEY=your-api-key
export OPENAI_API_KEY=your-api-key
Cada proveedor requiere su propia variable de entorno específica. La herramienta detecta automáticamente qué proveedor usar según el nombre del modelo.
Para modelos de AWS Bedrock, configure las credenciales de AWS utilizando uno de los métodos estándar del SDK de AWS:
# Option 1: Environment variables
export AWS_ACCESS_KEY_ID=your-access-key
export AWS_SECRET_ACCESS_KEY=your-secret-key
export AWS_REGION=us-east-1
# Option 2: AWS credentials file (~/.aws/credentials)
# Option 3: IAM role (when running on EC2/ECS/Lambda)
MCP X-Ray utiliza el SDK de AWS que cargará automáticamente las credenciales del entorno, el archivo de credenciales o el rol IAM.
¡Las contribuciones son bienvenidas! Asegúrese de que: