이 가이드에서는 MCP-Scan의 설치부터 고급 활용법까지 단계별로 안내합니다. MCP-Scan은 MCP(Model Context Protocol) 환경의 보안 취약점을 진단하고 대응하기 위한 오픈소스 도구로, Invariant Labs에서 개발했습니다. 이 도구를 통해 Tool Poisoning, Prompt Injection, Cross-Origin Escalation 등 다양한 보안 위협에 효과적으로 대응할 수 있습니다.
설치 방법
1. 사전 요구 사항
MCP-Scan을 사용하기 위해 필요한 환경:
- Python 3.8 이상
- uv 패키지 매니저 (또는 pip)
- 인터넷 연결 (클라우드 기반 분석 기능 사용 시)
2. uv 패키지 매니저 설치
MCP-Scan은 uv 패키지 매니저를 통해 간편하게 설치할 수 있습니다. 아직 uv가 설치되어 있지 않다면 다음 명령어로 설치하세요:
또는 pip를 사용할 수도 있습니다:
3. MCP-Scan 설치
uv 패키지 매니저를 사용하여 MCP-Scan을 설치합니다:
또는 최신 버전을 직접 실행하려면:
pip를 사용한 설치:
설치 팁
- 가상 환경(venv, conda 등)을 사용하여 의존성 충돌을 방지하는 것이 좋습니다.
- 최신 보안 패턴을 적용하기 위해 주기적으로 업데이트하세요:
uv pip install -U mcp-scan - Git 저장소에서 직접 개발 버전을 설치할 수도 있습니다:
pip install git+https://github.com/invariantlabs-ai/mcp-scan.git
기본 사용법
1. 기본 스캔 실행
가장 기본적인 MCP-Scan 실행 방법은 다음과 같습니다:
이 명령은 기본적으로 시스템에서 MCP 서버를 자동으로 감지하고, 등록된 모든 도구를 스캔합니다. 로컬에서 기본적인 보안 검사를 수행하고, 필요한 경우 클라우드 분석 서비스에 연결하여 추가 분석을 수행합니다.
2. 특정 서버 스캔
특정 MCP 서버를 지정하여 스캔할 수 있습니다:
이 옵션은 자동 감지 대신 지정된 서버에 연결하여 스캔을 수행합니다. 원격 서버나 비표준 포트를 사용하는 경우에 유용합니다.
3. 도구 상세 검사
등록된 도구의 상세 정보를 검사하려면 inspect 명령을 사용합니다:
특정 도구만 검사하려면 이름을 지정할 수 있습니다:
4. 보고서 저장
스캔 결과를 파일로 저장하려면 다음과 같이 사용합니다:
다양한 형식으로 출력할 수 있습니다:
고급 기능 활용
1. Tool Pinning (도구 고정)
Tool Pinning은 도구 설명의 해시값을 저장하여 나중에 변경되었는지 감지하는 기능입니다. 이를 통해 MCP Rug Pull 공격을 방지할 수 있습니다.
모든 도구를 한 번에 고정하려면:
저장된 해시값으로 도구 변경 여부를 확인하려면:
2. 설명 필터링 및 검증
도구 설명에서 잠재적인 악성 지시를 필터링하거나 검증하려면 filter 명령을 사용합니다:
3. 오프라인 모드
클라우드 분석 서비스 없이 로컬에서만 분석을 수행하려면 오프라인 모드를 사용할 수 있습니다:
오프라인 모드에서는 로컬 위협 데이터베이스만 사용하므로, 최신 위협 패턴이 적용되지 않을 수 있습니다. 주기적으로 데이터베이스를 업데이트하는 것이 좋습니다:
4. 사용자 정의 규칙
사용자 정의 규칙 파일을 사용하여 스캔 기준을 맞춤화할 수 있습니다:
custom_rules.yaml 예시:
# 사용자 정의 규칙 예시
rules:
- name: "회사 도메인 위장 감지"
pattern: "mycompany\\.com"
context: "다른 도메인에서 등록된 도구 설명"
severity: "HIGH"
- name: "민감한 경로 접근 시도"
pattern: "/(etc|var|home)/"
context: "파일 경로 파라미터"
severity: "MEDIUM"
자동화 및 통합
1. CI/CD 파이프라인 통합
MCP-Scan을 CI/CD 파이프라인에 통합하여 자동화된 보안 검사를 구현할 수 있습니다:
GitHub Actions 워크플로우 예시:
name: MCP Security Scan
on:
push:
branches: [ main ]
pull_request:
branches: [ main ]
schedule:
- cron: '0 0 * * *' # 매일 자정에 실행
jobs:
security-scan:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v3
- name: Set up Python
uses: actions/setup-python@v4
with:
python-version: '3.10'
- name: Install dependencies
run: |
python -m pip install --upgrade pip
pip install mcp-scan
- name: Run MCP-Scan
run: |
mcp-scan --format json --output scan-results.json
- name: Check for security issues
run: |
python -c "import json; f=open('scan-results.json'); data=json.load(f); f.close(); exit(1 if any(i['severity'] == 'HIGH' for i in data['issues']) else 0)"
2. API 활용
MCP-Scan은 Python API를 제공하여 자체 도구나 스크립트에 통합할 수 있습니다:
Python API 사용 예시:
from mcp_scan import MCPScanner, ScanConfig
# 스캐너 초기화
config = ScanConfig(
server_url="http://localhost:8000",
offline=False,
verbose=True
)
scanner = MCPScanner(config)
# 스캔 실행
results = scanner.scan()
# 결과 처리
for issue in results.issues:
if issue.severity == "HIGH":
print(f"Critical issue found: {issue.description}")
print(f"Affected tool: {issue.tool_name}")
print(f"Recommended action: {issue.recommendation}")
# 특정 도구 검사
tool_details = scanner.inspect_tool("file_manager")
print(f"Tool description: {tool_details.description}")
print(f"Security score: {tool_details.security_score}/10")
3. 정기적인 스캔 자동화
cron 작업으로 MCP-Scan을 설정하여 정기적인 보안 검사를 자동화할 수 있습니다:
crontab 설정 예시:
# 매일 자정에 MCP-Scan 실행 및 결과 이메일 전송
0 0 * * * /usr/local/bin/mcp-scan --format html --output /tmp/mcp_scan_report.html && mail -s "Daily MCP Security Report" admin@example.com < /tmp/mcp_scan_report.html
문제 해결 및 자주 묻는 질문
일반적인 문제
Q: MCP 서버를 찾을 수 없다는 오류가 발생합니다.
A: MCP 서버가 실행 중인지 확인하고, --server 옵션으로 서버 URL을 직접 지정해보세요. 기본적으로 MCP-Scan은 localhost의 표준 포트에서 서버를 찾습니다.
Q: 클라우드 분석 서비스 연결 오류가 발생합니다.
A: 인터넷 연결을 확인하고, 필요한 경우 프록시 설정을 확인하세요. 일시적인 서비스 중단일 수도 있으니 나중에 다시 시도하거나, --offline 모드를 사용해보세요.
Q: 오탐(False Positive) 문제가 있습니다.
A: 사용자 정의 규칙 파일을 사용하여 특정 패턴을 제외하거나, --threshold 옵션으로 경고 기준을 조정할 수 있습니다. 또한 버그 리포트를 제출하여 개선에 기여할 수 있습니다.
성능 최적화
- 대규모 환경에서는
--parallel옵션을 사용하여 병렬 처리를 활성화하세요. - 자주 사용하지 않는 검사는
--skip-checks옵션으로 건너뛸 수 있습니다. - 정기적으로 로컬 위협 데이터베이스를 업데이트하여 오프라인 모드의 효율성을 높이세요.
- 메모리 사용량이 많은 환경에서는
--low-memory옵션을 고려하세요.
보안 모범 사례
MCP-Scan을 효과적으로 활용하기 위한 보안 모범 사례는 다음과 같습니다:
- 정기적인 스캔 수행: 최소 주 1회 또는 새로운 도구 등록 시마다 스캔을 실행하세요.
- 새 도구 승인 전 스캔: 새로운 도구를 등록하기 전에 반드시 MCP-Scan으로 안전성을 검증하세요.
- 모든 도구에 Tool Pinning 적용: 중요한 도구에는 반드시 pinning을 적용하여 변조를 탐지하세요.
- 보안 로그 모니터링: MCP-Scan 로그를 중앙 로깅 시스템에 통합하여 모니터링하세요.
- 정기적인 업데이트: MCP-Scan과 위협 데이터베이스를 최신 버전으로 유지하세요.
- 경고 대응 프로세스 수립: 보안 경고 발생 시 따를 명확한 대응 절차를 마련하세요.
- CI/CD 파이프라인 통합: 자동화된 보안 검사를 개발 및 배포 과정에 통합하세요.
참고 자료
'AI' 카테고리의 다른 글
| 커서 AI 사용 후기 – 코드 생성은 뛰어나지만, 디버깅과 디자인은 한계 (2) | 2025.03.28 |
|---|---|
| 📱 커서 AI로 3일 만에 플러터 앱 개발부터 배포까지 – 레벨업코딩 MVP (0) | 2025.03.25 |
| 파이썬으로 시작하는 데이터 분석 (0) | 2025.03.18 |
| Manus AI 초대코드 받는 방법 – 빠르고 간편하게 가입 (0) | 2025.03.18 |
| 인공지능 에이전트, Manus AI 소개 (0) | 2025.03.18 |