traceforce/mcp-xrayMCP 서버를 위한 통합 보안 스캐너로, config, pentest, repo-scan 모드를 제공합니다. CI/CD 통합을 위한 SARIF 보고서를 생성하며, 토큰 및 LLM 분석기를 통해 비밀, 취약점, 잘못된 구성을 탐지합니다.
[!NOTE] AI 에이전트 스킬을 보호하려고 하십니까? 설치 전에 스킬 패키지를 실행하지 않고 악의적이거나 위험한 동작을 분석하는 오픈소스 정적 보안 스캐너인 Skill X-Ray를 확인해 보세요.
MCP X-Ray는 Model Context Protocol(MCP) 서버를 위한 통합 오픈소스 보안 스캐닝 및 침투 테스트 솔루션입니다. 보안 도구 및 CI/CD 파이프라인과의 원활한 통합을 위해 프로덕션 환경에서 바로 사용할 수 있는 SARIF 보고서를 생성합니다. 스캔 결과는 중앙화된 보안 관리 및 추적을 위해 선택적으로 Traceforce Atlas에 업로드할 수 있습니다. Atlas는 레지스트리에 600개 이상의 MCP를 보유하고 있어 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
보안 문제가 있는지 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
탐지 기능:
MCP 서버를 대상으로 실제 도구 호출을 수행하여 보안 테스트 계획을 실행합니다. Pentest를 실행하려면 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
탐지 기능:
테인트 SAST는 OpenGrep 엔진을 사용합니다. make install-opengrep(Linux x86_64/arm64, macOS arm64/x86_64)으로 고정되고 SHA로 검증된 바이너리를 설치하십시오. 다른 플랫폼에서는 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은 언어별로 데이터베이스를 빌드하므로, 번들이 설치된 후에는 스캔에 눈에 띄게 더 오래 걸립니다. 이 비용은 파일 간 분석의 대가입니다. 빠른 파일 내 패스로 되돌리려면 엔진을 설치했던 방식대로 제거하십시오. make install-codeql에서 번들을 제거하거나(바이너리 옆에 위치함), 특정 경로를 지정했다면 MCPXRAY_CODEQL_BIN을 해제하십시오. Python과 TypeScript 추출은 빌드 없이 동작합니다(대상은 절대 실행되지 않음). Go는 빌드 없는 모드가 없으므로 CodeQL이 대상을 컴파일합니다. 이 단계는 --codeql-allow-build가 있을 때만 실행되며, 그렇지 않으면 경고와 함께 건너뜁니다. 스캔은 프롬프트에서 절대 차단되지 않습니다.
각 언어에는 database create와 analyze를 합친 시간 예산이 주어지며, 기본값은 600초입니다. 이를 초과하는 대상은 아무것도 기여하지 않으므로, 대규모 저장소의 경우 --codeql-timeout <seconds>(또는 MCPXRAY_CODEQL_TIMEOUT)로 예산을 늘리십시오. 둘 다 설정된 경우 플래그가 우선합니다. 예산 초과는 timed out after Ns로 보고되며, 결코 깨끗한 0으로 보고되지 않습니다.
MCP X-Ray는 보안 도구와 CI/CD 플랫폼에서 널리 지원되는 SARIF (Static Analysis Results Interchange Format) 형식으로 보고서를 생성합니다.
중앙화된 보안 관리, 보고 및 시간 경과 추적을 위해 스캔 결과를 Traceforce Atlas에 업로드하십시오. 모든 스캔 명령에 --upload 플래그를 추가하십시오. 성공적으로 업로드한 후 생성된 파일을 제거하려면 --clean-up을 사용하십시오.
필요한 환경 변수:
TRACEFORCE_CLIENT_IDTRACEFORCE_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는 도구 보안을 분석하기 위한 두 가지 방법을 제공합니다:
토큰 분석기는 규칙 기반 패턴 매칭을 사용하여 도구 설명에서 보안 문제를 빠르게 탐지합니다. 빠르고 API 키가 필요하지 않으며 오프라인에서 작동합니다. 토큰 분석기는 두 가지 유형의 규칙을 사용합니다:
internal/configscan/tokenanalyzer/token_rules.yaml에 정의되어 있습니다. 각 규칙은 다음을 지정합니다:
internal/yararules/unsafe_patterns.yar에 정의되어 있습니다. 이 규칙들은 안전하지 않은 시스템 명령 패턴을 탐지합니다.사용법:
mcpxray config-scan --analyzer-type token
LLM 분석기는 대규모 언어 모델을 사용하여 도구 설명에 대한 심층적인 의미 분석을 수행하며, 보다 포괄적인 보안 인사이트를 제공합니다.
사용법:
mcpxray config-scan --analyzer-type llm --llm-model <model-name>
기본적으로 pentest 도구는 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 제공자를 지원합니다:
claude-sonnet-4-5ANTHROPIC_API_KEY 환경 변수gpt-5OPENAI_API_KEY 환경 변수arn:aws:bedrock:로 시작하고 llama를 포함하는 Meta Llama 추론 프로필 ARNarn:aws:bedrock:<region>:<account-id>:inference-profile/us.meta.llama3-2-1b-instruct-v1:0LLM 기반 도구 분석을 위해서는 LLM API 자격 증명을 구성하세요:
export ANTHROPIC_API_KEY=your-api-key
export OPENAI_API_KEY=your-api-key
각 제공자는 자체적인 특정 환경 변수를 필요로 합니다. 이 도구는 모델 이름을 기반으로 사용할 제공자를 자동으로 감지합니다.
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는 환경, 자격 증명 파일 또는 IAM 역할에서 자격 증명을 자동으로 로드하는 AWS SDK를 사용합니다.
기여를 환영합니다! 다음 사항을 확인해 주세요: