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.
[!NOTE] Procurando proteger as habilidades de agentes de IA? Confira o Skill X-Ray, um scanner de segurança estático de código aberto que analisa pacotes de habilidades em busca de comportamentos maliciosos ou de risco antes da instalação, sem executá-los.
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, para integração perfeita com ferramentas de segurança e pipelines de CI/CD. Os resultados da varredura podem, opcionalmente, ser enviados ao Traceforce Atlas para gerenciamento e acompanhamento centralizados de segurança. O Atlas possui mais de 600 MCPs em seu registro, oferecendo um banco de dados abrangente de avaliação de segurança para o ecossistema 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
Verifique as configurações do MCP em busca de problemas de segurança; execute antes do pentest para estabelecer uma linha de base da sua configuração.
# 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 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 isto antes da implantação real em produção.
# 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 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 de DoS
Escaneie a base de código em busca de vulnerabilidades; use quando você é proprietário do código ou pode alterá-lo.
# 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 Detecção:
O SAST de taint usa o motor OpenGrep. Instale
o binário fixado e verificado por SHA com make install-opengrep (Linux x86_64/arm64, macOS
arm64/x86_64). Noutras plataformas, instale o opengrep manualmente e defina
MCPXRAY_OPENGREP_BIN. A análise de taint ativa-se por instalação: o repo-scan executa-a
sempre que o motor fixado for resolvível, e quando o motor está ausente ignora o taint
e continua a executar SCA, segredos e as regras de comandos inseguros.
Para taint interprocedimental e entre ficheiros em Go e TypeScript (e Python), instale o motor CodeQL. Também se ativa por instalação, e os seus resultados são combinados com os do OpenGrep:
make install-codeql # pinned CodeQL bundle (Linux x86_64, macOS, Windows)
./mcpxray repo-scan <repo> # every installed engine runs; results merged
O CodeQL cria um banco de dados por linguagem, portanto um scan leva consideravelmente mais tempo depois que o bundle é instalado; esse custo é o preço da análise entre arquivos. Para voltar à passagem rápida intra-arquivo, desinstale o motor da mesma forma que o instalou: remova o bundle do make install-codeql (ele fica ao lado do binário), ou desdefina MCPXRAY_CODEQL_BIN se você o apontou para um. Python e TypeScript extraem sem build (o alvo nunca é executado). Go não tem modo sem build, então o CodeQL compila o alvo; essa etapa só é executada com --codeql-allow-build e, caso contrário, é ignorada com um aviso; o scan nunca bloqueia em um prompt.
Cada linguagem recebe um orçamento de tempo que cobre database create mais analyze — 600s por padrão. Um alvo que o exceda não contribui com nada, então aumente-o para repositórios grandes com --codeql-timeout <seconds> (ou MCPXRAY_CODEQL_TIMEOUT); a flag prevalece quando ambos estão definidos. Exceder o orçamento é reportado como timed out after Ns, nunca como um zero limpo.
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 de CI/CD.
Envie os resultados do scan para o Traceforce Atlas para gerenciamento centralizado de segurança, relatórios e acompanhamento ao longo do tempo. Adicione a flag --upload a qualquer comando de scan. Use --clean-up para remover os arquivos gerados após um upload bem-sucedido.
Variáveis de ambiente necessárias:
TRACEFORCE_CLIENT_IDTRACEFORCE_CLIENT_SECRETEssas credenciais podem ser baixadas na página de configurações da interface do 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
Exemplos de resultados de verificação estão disponíveis em examples/findings/.
Arquivos de configuração MCP de exemplo estão disponíveis no diretório examples/mcp_configs/.