MCP X-Ray

[!NOTE] 想要保护 AI agent 技能的安全吗？ 请查看 Skill X-Ray，这是一个开源静态安全扫描器，可在安装前分析技能包是否存在恶意或高风险行为，而无需执行它们。

概述

MCP X-Ray 是一个面向模型上下文协议（MCP）服务器的统一开源安全扫描与渗透测试解决方案。它可生成生产就绪的 SARIF 报告，以便与安全工具和 CI/CD 流水线无缝集成。扫描结果可选择上传至 Traceforce Atlas，用于集中化安全管理和跟踪。Atlas 的注册表中收录了 600 多个 MCP，为 MCP 生态系统提供了全面的安全评估数据库。

安装

前置条件

• Go 1.25.4 或更高版本

从源码构建

# 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

用法

配置扫描

扫描 MCP 配置以发现安全问题；在渗透测试前运行，为你的环境建立基线。

# 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

检测能力：

• 连接安全：验证 TLS 证书，检测不安全的 localhost/loopback 暴露，并验证 OAuth 2.0 配置（PRM/ASMD）
• 密钥检测：扫描暴露的凭据、API 密钥和敏感信息
• 工具分析：使用 Token Analyzer（默认）或 LLM Analyzer 分析工具描述，以识别包括任意执行、注入漏洞、授权绕过和信息泄露在内的风险

渗透测试

通过对 MCP 服务器发起实际工具调用来执行安全测试计划。运行渗透测试需要 LLM。请在生产环境实际部署之前运行此步骤。

# 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

检测能力： 代码执行、SSRF、路径遍历、授权绕过、输入注入、信息泄露和 DoS 漏洞

仓库扫描

扫描代码库以查找漏洞；当你拥有代码或可以修改代码时使用。

# 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

检测能力：

• SCA：使用 OSV API 检测存在漏洞的依赖项
• SAST：污点分析，追踪 MCP 工具/处理程序的输入（源）到危险 汇聚点——命令注入、代码注入、路径遍历、SSRF 和 SQL 注入—— 以及现有的不安全命令模式规则
• 密钥检测：扫描硬编码的密钥和凭据

污点 SAST 使用 OpenGrep 引擎。使用 make install-opengrep 安装固定版本、经 SHA 校验的二进制文件（Linux x86_64/arm64、macOS arm64/x86_64）。在其他平台上，请自行安装 opengrep 并设置 MCPXRAY_OPENGREP_BIN。污点分析通过安装激活：只要固定版本的引擎可解析，repo-scan 就会运行它；当引擎缺失时，它会跳过污点分析， 但仍会运行 SCA、密钥检测和不安全命令规则。

对于 Go 和 TypeScript（以及 Python）的跨文件、过程间污点分析，请安装 CodeQL 引擎。它同样通过安装激活，其发现结果会与 OpenGrep 的合并：

make install-codeql                        # pinned CodeQL bundle (Linux x86_64, macOS, Windows)
./mcpxray repo-scan <repo>                 # every installed engine runs; results merged

CodeQL 会为每种语言构建一个数据库，因此一旦安装了该 bundle，扫描耗时会明显变长；这就是跨文件分析所需付出的代价。若要回退到快速的单文件内分析流程，请按照安装引擎时的方式卸载它：从 make install-codeql 中移除该 bundle（它位于二进制文件旁边），或者如果你曾将 MCPXRAY_CODEQL_BIN 指向某个引擎，则取消设置该变量。Python 和 TypeScript 的提取无需构建（目标永远不会被执行）。Go 没有免构建模式，因此 CodeQL 会编译目标；该步骤仅在指定 --codeql-allow-build 时运行，否则会被跳过并给出警告；扫描过程绝不会因等待提示而阻塞。

每种语言都有一个时间预算，涵盖 database create 加上 analyze——默认 600 秒。超出该预算的目标不会贡献任何结果，因此对于大型仓库，请使用 --codeql-timeout <seconds>（或 MCPXRAY_CODEQL_TIMEOUT）提高该值；当两者都设置时，以该标志为准。超出预算会被报告为 timed out after Ns，绝不会被报告为干净的零结果。

输出格式

MCP X-Ray 以 SARIF（静态分析结果交换格式） 格式生成报告，该格式被安全工具和 CI/CD 平台广泛支持。

将结果上传到 Traceforce

将扫描结果上传到 Traceforce Atlas，以实现集中化的安全管理、报告和长期跟踪。在任何扫描命令中添加 --upload 标志。使用 --clean-up 在成功上传后删除生成的文件。

所需环境变量：

• TRACEFORCE_CLIENT_ID
• TRACEFORCE_CLIENT_SECRET

这些凭据可以从 Atlas UI 的设置页面下载。

# 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

示例

示例扫描输出可在 examples/findings/ 中获取。

示例 MCP 配置文件位于 examples/mcp_configs/ 目录中。

示例 MCP 服务器位于 examples/mcp_server/ 目录中：

• mcp_server.py：使用 streamable-http 传输的 FastMCP 服务器
• mcp.json：用于连接服务器的配置文件
• README.md：设置和扫描服务器的说明

配置

工具分析方法

MCP X-Ray 提供两种分析工具安全性的方法：

Token 分析器（默认）

Token 分析器使用基于规则的模式匹配来快速检测工具描述中的安全问题。它速度快、无需 API 密钥，并且可以离线工作。Token 分析器使用两种类型的规则：

1. Token 规则定义在 internal/configscan/tokenanalyzer/token_rules.yaml 中。每条规则指定：
   • 模式匹配条件（token 和短语）
   • 严重性级别（低、中、高、严重）
   • 安全类别和原因
2. YARA 规则定义在 internal/yararules/unsafe_patterns.yar 中。这些规则检测不安全的系统命令模式。

用法：

mcpxray config-scan --analyzer-type token

LLM 分析器

LLM 分析器使用大型语言模型对工具描述进行深度语义分析，提供更全面的安全洞察。

用法：

mcpxray config-scan --analyzer-type llm --llm-model <model-name>

渗透测试配置

默认情况下，渗透测试工具使用 LLM 根据 MCP 服务器中可用的工具自动生成测试计划。测试计划也可以自定义并以 YAML 文件形式提供。测试计划是包含测试用例（含输入参数和预期输出）的 YAML 文件。

默认行为（LLM 生成的测试计划）：

./mcpxray pentest /path/to/mcp/config.json --llm-model claude-sonnet-4-5

自定义测试计划：

./mcpxray pentest /path/to/mcp/config.json --test-plan /path/to/test-plan.yaml --llm-model claude-sonnet-4-5

支持的模型

MCP X-Ray 支持以下 LLM 提供商进行工具分析：

Anthropic (Claude)

• 示例：claude-sonnet-4-5
• 需要：ANTHROPIC_API_KEY 环境变量

OpenAI (GPT)

• 示例：gpt-5
• 需要：OPENAI_API_KEY 环境变量

AWS Bedrock（Meta Llama）

• 以 arn:aws:bedrock: 开头且包含 llama 的 Meta Llama 推理配置文件 ARN
• 示例：arn:aws:bedrock:<region>:<account-id>:inference-profile/us.meta.llama3-2-1b-instruct-v1:0
• 要求：通过 AWS SDK 配置 AWS 凭证（环境变量、IAM 角色或凭证文件）

环境变量

对于基于 LLM 的工具分析，请配置您的 LLM API 凭证：

Anthropic

export ANTHROPIC_API_KEY=your-api-key

OpenAI

export OPENAI_API_KEY=your-api-key

每个提供商都需要自己的特定环境变量。该工具会根据模型名称自动检测要使用哪个提供商。

AWS Bedrock

对于 AWS Bedrock 模型，请使用标准 AWS SDK 方法之一配置 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 使用 AWS SDK，它会自动从环境变量、凭证文件或 IAM 角色加载凭证。

贡献

欢迎贡献！请确保：

1. 代码遵循 Go 最佳实践
2. 为新功能包含测试和示例
3. 更新文档

参考资料

• 模型上下文协议 (MCP)
• SARIF 规范
• OSV Scanner
• Gitleaks