traceforce/mcp-xrayScanner de segurança unificado para servidores MCP com modos de configuração, pentest e varredura de repositórios. Gera relatórios SARIF para integração CI/CD, detecta segredos, vulnerabilidades e más configurações por meio de analisadores de token e LLM.
O MCP X-Ray é uma solução unificada de código aberto para varredura de segurança e testes de penetração em servidores Model Context Protocol (MCP). Ele gera relatórios SARIF prontos para produção, permitindo integração contínua com ferramentas de segurança e pipelines CI/CD. Os resultados da varredura podem ser opcionalmente enviados para o Traceforce Atlas para gerenciamento e rastreamento centralizados de segurança. O Atlas possui mais de 600 MCPs em seu registro, fornecendo um banco de dados abrangente de avaliação de segurança para o ecossistema MCP.
# Clone o repositório
git clone https://github.com/traceforce/mcp-xray
cd mcp-xray
# Instale as dependências necessárias (buf, etc.)
make install-dependencies
# Compile tudo (gera código protobuf e compila o binário)
# O binário será criado como `mcpxray` no diretório atual
make all
Varra arquivos de configuração MCP em busca de problemas de segurança; execute antes do pentest para estabelecer uma linha de base.
# Varrer um arquivo de configuração MCP específico (usa analisador de tokens por padrão)
./mcpxray config-scan /path/to/mcp/config.json
# Varrer automaticamente todos os caminhos conhecidos de configuração MCP para Cursor, Claude e Windsurf.
# Caminhos de configuração conhecidos (relativos ao diretório home):
# ~/.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
# Usar analisador LLM para uma análise mais extensa e profunda
./mcpxray config-scan /path/to/mcp/config.json --analyzer-type llm --llm-model claude-3-5-sonnet-20241022
# Especificar arquivo de saída personalizado
./mcpxray config-scan /path/to/mcp/config.json --output custom-report.sarif.json
Capacidades de Detecção:
Execute planos de teste de segurança fazendo chamadas reais de ferramentas contra servidores MCP. LLMs são necessários para executar o pentest. Execute isso antes da implantação real em produção.
# Executar pentest com plano de teste gerado automaticamente (requer modelo LLM)
./mcpxray pentest /path/to/mcp/config.json --llm-model claude-sonnet-4-5
# Usar um arquivo YAML de plano de teste personalizado
./mcpxray pentest /path/to/mcp/config.json --test-plan /path/to/test-plan.yaml --llm-model claude-sonnet-4-5
Capacidades de Detecção: Execução de código, SSRF, path traversal, bypass de autorização, injeção de entrada, divulgação de informações e vulnerabilidades DoS
Varra a base de código em busca de vulnerabilidades; use quando você possui ou pode alterar o código.
# Varrer o diretório atual
./mcpxray repo-scan
# Varrer um repositório específico
./mcpxray repo-scan /path/to/repository
# Especificar arquivo de saída personalizado
./mcpxray repo-scan --output custom-report.sarif.json
Capacidades de Detecção:
O MCP X-Ray gera relatórios no formato SARIF (Static Analysis Results Interchange Format), que é amplamente suportado por ferramentas de segurança e plataformas CI/CD.
Envie os resultados da varredura para o Traceforce Atlas para gerenciamento centralizado de segurança, relatórios e rastreamento ao longo do tempo. Adicione a flag --upload a qualquer comando de varredura. Use --clean-up para remover arquivos gerados após o envio bem-sucedido.
Variáveis de ambiente necessárias:
TRACEFORCE_CLIENT_IDTRACEFORCE_CLIENT_SECRETEssas credenciais podem ser baixadas da página de configurações na interface do Atlas.
# Enviar resultados da varredura de configuração
./mcpxray config-scan /path/to/mcp/config.json --upload
# Enviar com limpeza
./mcpxray config-scan /path/xia-add-registry-imageto/mcp/config.json --upload --clean-up
# Enviar resultados do pentest
./mcpxray pentest /path/to/mcp/config.json --llm-model claude-sonnet-4-5 --upload
Exemplos de saídas de varredura estão disponíveis em examples/findings/.
Arquivos de configuração MCP de exemplo estão disponíveis no diretório examples/mcp_configs/.
Um servidor MCP de exemplo está disponível no diretório examples/mcp_server/:
mcp_server.py: Servidor FastMCP usando transporte streamable-httpmcp.json: Arquivo de configuração para conectar ao servidorREADME.md: Instruções para configurar e varrer o servidorO MCP X-Ray fornece dois métodos para analisar a segurança das ferramentas:
O analisador de tokens usa correspondência de padrões baseada em regras para detectar rapidamente problemas de segurança em descrições de ferramentas. É rápido, não requer chaves de API e funciona offline. O analisador de tokens usa dois tipos de regras:
internal/configscan/tokenanalyzer/token_rules.yaml. Cada regra especifica:
internal/yararules/unsafe_patterns.yar. Essas regras detectam padrões inseguros de comandos do sistema.Uso:
mcpxray config-scan --analyzer-type token
O analisador LLM usa modelos de linguagem grandes para análise semântica profunda de descrições de ferramentas, fornecendo insights de segurança mais abrangentes.
Uso:
mcpxray config-scan --analyzer-type llm --llm-model <model-name>
Por padrão, a ferramenta de pentest usa um LLM para gerar automaticamente planos de teste com base nas ferramentas disponíveis nos servidores MCP. Os planos de teste também podem ser personalizados e fornecidos como arquivos YAML. Planos de teste são arquivos YAML contendo casos de teste com argumentos de entrada e saídas esperadas.
Comportamento padrão (plano de teste gerado por LLM):
./mcpxray pentest /path/to/mcp/config.json --llm-model claude-sonnet-4-5
Plano de teste personalizado:
./mcpxray pentest /path/to/mcp/config.json --test-plan /path/to/test-plan.yaml --llm-model claude-sonnet-4-5
O MCP X-Ray suporta os seguintes provedores de LLM para análise de ferramentas:
claude-sonnet-4-5ANTHROPIC_API_KEYgpt-5OPENAI_API_KEYarn:aws:bedrock: e contendo llamaarn:aws:bedrock:<region>:<account-id>:inference-profile/us.meta.llama3-2-1b-instruct-v1:0Para análise de ferramentas baseada em LLM, configure suas credenciais de API do LLM:
export ANTHROPIC_API_KEY=your-api-key
export OPENAI_API_KEY=your-api-key
Cada provedor requer sua própria variável de ambiente específica. A ferramenta detecta automaticamente qual provedor usar com base no nome do modelo.
Para modelos AWS Bedrock, configure as credenciais AWS usando um dos métodos padrão do AWS SDK:
# Opção 1: Variáveis de ambiente
export AWS_ACCESS_KEY_ID=your-access-key
export AWS_SECRET_ACCESS_KEY=your-secret-key
export AWS_REGION=us-east-1
# Opção 2: Arquivo de credenciais AWS (~/.aws/credentials)
# Opção 3: Função IAM (ao executar em EC2/ECS/Lambda)
O MCP X-Ray usa o AWS SDK que carregará automaticamente as credenciais do ambiente, arquivo de credenciais ou função IAM.
Contribuições são bem-vindas! Por favor, certifique-se de que: