MCPGuard-Lab

실제 mcp==2.0.0 SDK 기반의 MCP 도구 호출 보안 실험 프로젝트입니다. 외부 대규모 언어 모델이나 API Key에 의존하지 않으며, 결정론적 정책을 통해 도구 화이트리스트, 매개변수 검증, 파일 경계, SSRF 보호, 민감 작업 확인, 출력 비식별화, 도구 설명 오염 탐지 및 JSONL 감사를 수행하고, 회귀 테스트를 통해 보호 기능이 이후 변경 사항에 의해 손상되지 않음을 검증합니다.

사용 범위: 이 프로젝트는 로컬 실험, 승인된 테스트 및 방어 연구에만 사용되며, 승인되지 않은 대상을 대상으로 하는 공격 기능을 포함하지 않습니다.

구현된 기능

• MCP 2.0 stdio 서버와 실제 클라이언트 간 왕복 테스트.

• 6가지 데모 도구: 안전 계산, 루트 디렉터리 내 파일 읽기, 메모 조회, 공개 URL 요청, 도구 메타데이터 확인, 확인 후 메모 작성.

• 도구 화이트리스트 및 JSON Schema 엄격한 검증, 추가 매개변수 거부.

• 파일 경로 정규화, 절대 경로, 디렉터리 트래버설 및 루트 디렉터리 이탈 거부.

• URL 프로토콜, 사용자 정보, 포트, DNS 확인 결과 검사, 루프백, 사설 네트워크, 링크-로컬 등 비공개 주소 거부.

• 쓰기 작업 confirmed=true 게이트.

• 신뢰할 수 없는 도구 출력 명시적 라벨링; 비밀번호, 토큰, API Key 및 Bearer 자격 증명 재귀적 비식별화.

• 도구 이름/설명 내 고위험 프롬프트 인젝션 신호 탐지.

• 각 결정을 JSONL에 기록: 요청 ID, 시간, 도구, 매개변수, 허용/거부, 이유 및 결과.

• pytest 단위/통합 테스트 및 반복 가능한 공격 회귀 보고서.

Related MCP server: meok-mcp-injection-scan-mcp

아키텍처

MCP Client
   │ stdio / MCP 2.0
   ▼
MCP Server ──► GuardedGateway ──► PolicyEngine
                      │                 ├─ allowlist + schema
                      │                 ├─ path boundary
                      │                 ├─ URL / SSRF
                      │                 └─ confirmation
                      ├─ Tool handler
                      ├─ untrusted labeling + redaction
                      └─ JSONL audit

핵심 원칙은 "먼저 결정, 그다음 실행, 그다음 출력 정화, 전체 과정 기록"입니다. 프롬프트 텍스트는 직접 추가 권한을 얻지 않으며, 권한은 코드 내 화이트리스트 및 정책을 기준으로 합니다.

빠른 실행 (Windows)

py -3.10 -m venv .venv
.\.venv\Scripts\python.exe -m pip install -e ".[dev]"
.\.venv\Scripts\python.exe -m pytest
.\.venv\Scripts\python.exe -m mcpguard.regression

또는 직접 실행할 수도 있습니다:

powershell -ExecutionPolicy Bypass -File .\scripts\verify.ps1

보고서는 다음 위치에 생성됩니다:

• reports/regression-report.md

• reports/regression-report.json

• reports/regression-audit.jsonl

MCP 클라이언트 설정 예시

먼저 pip install -e .를 실행한 후, 다음 구조를 현재 저장소의 절대 경로로 교체하십시오:

{
  "mcpServers": {
    "mcpguard-lab": {
      "command": "D:/path/to/mcpguard-lab/.venv/Scripts/python.exe",
      "args": ["-m", "mcpguard.server"],
      "env": {
        "MCPGUARD_WORKSPACE": "D:/path/to/mcpguard-lab/fixtures/workspace",
        "MCPGUARD_NOTES": "D:/path/to/mcpguard-lab/fixtures/workspace/notes",
        "MCPGUARD_AUDIT": "D:/path/to/mcpguard-lab/reports/audit.jsonl"
      }
    }
  }
}

실제 한계

• 도구 설명 오염 탐지는 높은 신호 규칙 레이어로, 수동 검토 및 고정 화이트리스트를 대체할 수 없습니다.

• confirmed=true는 로컬 실험에서의 명시적 확인 게이트입니다; 프로덕션 환경에서는 호스트 UI/아이덴티티 시스템에서 발급되고 모델이 임의로 위조할 수 없는 확인 자격 증명을 사용해야 합니다.

• URL 도구는 현재 리디렉션을 비활성화하여 첫 번째 점프에서 검사를 통과한 후 내부 네트워크로 이동하는 것을 방지합니다; 프로덕션 버전에서는 응답 크기, 콘텐츠 유형 및 아웃바운드 네트워크도 제한해야 합니다.

• 신뢰할 수 없는 콘텐츠 라벨링은 "데이터가 명령으로 사용되는" 위험을 줄일 수 있지만, 최종 호스트 Agent는 여전히 신뢰 경계를 따라야 합니다.

• 회귀 데이터는 저장소 내 고정된 테스트 케이스만을 나타내며, 모든 프롬프트 인젝션 또는 모든 MCP 위험을 차단할 수 있음을 의미하지는 않습니다.

목차

src/mcpguard/       核心实现
tests/              单元测试与真实 MCP stdio 集成测试
fixtures/           可公开的本地测试数据
reports/            自动生成的测试和审计证据
scripts/verify.ps1  一键验证入口

참고

• Model Context Protocol Python SDK

• AgentDojo