MCP 서버를 위한 통합 보안 스캐너로, config, pentest, repo-scan 모드를 제공합니다. CI/CD 통합을 위한 SARIF 보고서를 생성하며, 토큰 및 LLM 분석기를 통해 비밀, 취약점, 잘못된 구성을 탐지합니다.
MCP X-Ray는 Model Context Protocol (MCP) 서버를 위한 통합 오픈소스 보안 스캐닝 및 침투 테스트 솔루션입니다. 보안 도구 및 CI/CD 파이프라인과의 원활한 통합을 위해 프로덕션에 바로 사용 가능한 SARIF 보고서를 생성합니다. 스캔 결과는 선택적으로 Traceforce Atlas에 업로드하여 중앙 집중식 보안 관리 및 추적이 가능합니다. Atlas는 레지스트리에 600개 이상의 MCP를 보유하여 MCP 생태계를 위한 포괄적인 보안 평가 데이터베이스를 제공합니다.
# 리포지토리 복제
git clone https://github.com/traceforce/mcp-xray
cd mcp-xray
# 필수 종속성 설치 (buf 등)
make install-dependencies
# 전체 빌드 (protobuf 코드 생성 및 바이너리 빌드)
# 바이너리는 현재 디렉토리에 `mcpxray`로 생성됩니다.
make all
보안 문제에 대해 MCP 구성을 스캔합니다. 침투 테스트 전에 실행하여 설정을 기준선화하세요.
# 특정 MCP 구성 파일 스캔 (기본적으로 토큰 분석기 사용)
./mcpxray config-scan /path/to/mcp/config.json
# Cursor, Claude 및 Windsurf의 알려진 MCP 구성 경로를 자동으로 스캔
# 알려진 구성 위치 (홈 디렉토리 기준):
# ~/.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
# 더 광범위하고 깊이 있는 분석을 위해 LLM 분석기 사용
./mcpxray config-scan /path/to/mcp/config.json --analyzer-type llm --llm-model claude-3-5-sonnet-20241022
# 사용자 정의 출력 파일 지정
./mcpxray config-scan /path/to/mcp/config.json --output custom-report.sarif.json
탐지 기능:
MCP 서버에 실제 도구 호출을 수행하여 보안 테스트 계획을 실행합니다. 침투 테스트를 실행하려면 LLM이 필요합니다. 프로덕션에 실제 배포하기 전에 이것을 실행하세요.
# 자동 생성된 테스트 계획으로 침투 테스트 실행 (LLM 모델 필요)
./mcpxray pentest /path/to/mcp/config.json --llm-model claude-sonnet-4-5
# 사용자 정의 테스트 계획 YAML 파일 사용
./mcpxray pentest /path/to/mcp/config.json --test-plan /path/to/test-plan.yaml --llm-model claude-sonnet-4-5
탐지 기능: 코드 실행, SSRF, 경로 순회, 권한 우회, 입력 주입, 정보 노출, DoS 취약점
코드베이스에서 취약점을 스캔합니다. 코드를 소유하거나 변경할 수 있을 때 사용하세요.
# 현재 디렉토리 스캔
./mcpxray repo-scan
# 특정 저장소 스캔
./mcpxray repo-scan /path/to/repository
# 사용자 정의 출력 파일 지정
./mcpxray repo-scan --output custom-report.sarif.json
탐지 기능:
MCP X-Ray는 보안 도구 및 CI/CD 플랫폼에서 널리 지원되는 SARIF(Static Analysis Results Interchange Format) 형식으로 보고서를 생성합니다.
스캔 결과를 Traceforce Atlas에 업로드하여 중앙 집중식 보안 관리, 보고 및 시간 경과에 따른 추적을 수행합니다. 모든 스캔 명령에 --upload 플래그를 추가하세요. 업로드 성공 후 생성된 파일을 제거하려면 --clean-up을 사용하세요.
필요한 환경 변수:
TRACEFORCE_CLIENT_IDTRACEFORCE_CLIENT_SECRET이 자격 증명은 Atlas UI의 설정 페이지에서 다운로드할 수 있습니다.
# 구성 스캔 결과 업로드
./mcpxray config-scan /path/to/mcp/config.json --upload
# 정리와 함께 업로드
./mcpxray config-scan /path/xia-add-registry-imageto/mcp/config.json --upload --clean-up
# 침투 테스트 결과 업로드
./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>
기본적으로 침투 테스트 도구는 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 자격 증명을 구성하세요:
# 옵션 1: 환경 변수
export AWS_ACCESS_KEY_ID=your-access-key
export AWS_SECRET_ACCESS_KEY=your-secret-key
export AWS_REGION=us-east-1
# 옵션 2: AWS 자격 증명 파일 (~/.aws/credentials)
# 옵션 3: IAM 역할 (EC2/ECS/Lambda에서 실행 시)
MCP X-Ray는 환경, 자격 증명 파일 또는 IAM 역할에서 자격 증명을 자동으로 로드하는 AWS SDK를 사용합니다.
기여를 환영합니다! 다음 사항을 확인해 주세요: