vuln_mcp_App

의도적으로 취약하게 설계된, 로컬에서 실행 가능한 Model Context Protocol(MCP) 보안 실습 환경 — 별도의 FYP 보안 스캐너를 평가하기 위한 통제된 타깃(개념적으로 "MCP용 DVWA")입니다. 이 앱은 스캐너가 아니라 타깃입니다. 소규모의 문서화된 MCP 취약점 집합을 호스팅하며 증거를 생성합니다. 취약 여부를 보고하지 않습니다(오라클 없음, SEC-006).

⚠️ 교육/연구용으로만 사용하세요. 모든 것은 로컬에서 합성 데이터와 더미 시크릿(DEMO_SECRET_*)으로 실행됩니다. 실제 자격 증명 없음, 외부 타깃 없음, 인터넷 스캔 없음, 호스트 접근 없음.

범위(정확히 3개의 랩)

추가 취약점 랩은 범위에 없습니다. 각 구현된 랩은 취약(VULNERABLE) 모드와 진정으로 수정된 안전(SECURE) 모드를 제공합니다.

Related MCP server: vuln-mcp-server

실행 방법(Docker 없음 — 명령 하나 + 브라우저)

전체 앱은 단일 uvicorn 프로세스로 실행됩니다: FastAPI가 빌드된 UI를 /에서 제공하고 API를 /api에서 제공합니다.

처음 실행 시

# 1) Build the UI once (Node 18+). Produces frontend/dist.
cd frontend && npm install && npm run build && cd ..

# 2) Run the app (uv resolves Python deps automatically; Python 3.12+).
uv run uvicorn backend.app.main:app --reload --host 127.0.0.1 --port 8000

그런 다음 **http://127.0.0.1:8000**을 여세요 — 랩 UI가 표시됩니다. 대화형 API 문서는 **http://127.0.0.1:8000/docs**에 있습니다.

uv 대신 일반 venv를 선호하시나요?

python -m venv .venv && source .venv/Scripts/activate   # Windows Git Bash
pip install -r backend/requirements.txt
uvicorn backend.app.main:app --reload --host 127.0.0.1 --port 8000

첫 빌드 이후

uvicorn 명령을 실행하고 브라우저를 여세요. 프론트엔드 코드를 변경한 경우에만 UI를 다시 빌드하세요(npm run build).

프론트엔드 핫 리로드(선택 사항, UI 개발용)

API를 :8000에서 실행하고 Vite 개발 서버를 :5173에서 실행하세요(/api를 프록시합니다):

# terminal 1
uv run uvicorn backend.app.main:app --reload --host 127.0.0.1 --port 8000
# terminal 2
cd frontend && npm run dev      # open http://127.0.0.1:5173

테스트

# Backend (pytest)
uv run pytest                    # or: .venv/Scripts/python -m pytest

# Frontend (Vitest + tsc)
cd frontend && npm test && npx tsc --noEmit

아키텍처

Browser (React SPA, served by FastAPI at :8000)
        │  HTTP/JSON  (/api)
        ▼
  FastAPI control plane (ordinarily secure)  ── MCP client ──►  MCP tool registry
        │                                                        (vulnerable | secure)
        ▼                                                              │
   SQLite (labs, tools, telemetry, evidence)  ◄── telemetry/evidence ─┘

컨트롤 플레인은 일반적으로 안전한 인프라입니다(SEC-004). 명확하게 표시된 MCP 플레인 도구만 취약해질 수 있으며, vulnerable 모드에서만 그렇습니다. 의도적으로 취약한 파일에는 배너가 포함됩니다: # INTENTIONALLY VULNERABLE — <VULN-ID> — see docs/GROUND-TRUTH.md.

MCP 전송: 1단계에서는 인프로세스 레지스트리 전송을 사용하므로 전체 앱이 단일 프로세스로 실행됩니다. 공식 SDK의 streamable-HTTP MCP 전송은 동일한 클라이언트 API 뒤에서 향후 업그레이드 항목입니다.

MCP05 샌드박스(구축 시): Docker를 제거한 상태에서 MCP05 랩의 명령 실행은 제한된 인프로세스 서브프로세스 러너에서 실행됩니다 — 임시 작업 디렉터리, 프로젝트 제공 가짜 convert 셸, 하드 타임아웃, 그리고 secure 모드에서는 셸이 없습니다. 폭발 반경은 로컬 및 합성 범위로 제한됩니다(SEC-001/003); Docker가 제공하던 OS 수준 격리(네트워크 차단, 캡 비활성화)는 이 제한된 러너로 대체됩니다. sandbox/README.md를 참조하세요.

기술 스택

React + TypeScript + Vite + Tailwind · Python 3.12 + FastAPI + Pydantic v2 · 공식 Python MCP SDK · SQLite + SQLModel · pytest + httpx · Vitest + Testing Library. uv/uvicorn으로 실행합니다(Docker 없음).

API 표면(FYP가 분석 가능)

GET /api/health · GET /api/labs · GET /api/labs/{id} · POST /api/labs/{id}/mode|reset|attack|start · GET /api/labs/{id}/telemetry · GET /api/mcp/servers|tools · GET /api/mcp/tools/{id} · POST /api/mcp/tools/{id}/call · GET /api/vulnerabilities(카탈로그 메타데이터만) · GET /api/evidence.

어떤 엔드포인트도 취약점 판정을 공개하지 않습니다(SEC-006).

FYP에 대한 사용 방법(평가 루프)

1. 타깃을 시작합니다(MCP03은 기본적으로 vulnerable입니다). 2. docs/GROUND-TRUTH.md의 수동 검증을 통해 랩이 활성 상태인지 확인합니다. 3. HTTP + MCP 표면에 대해 FYP를 실행합니다. 4. 결과를 docs/GROUND-TRUTH.md와 비교합니다.

2. Secure 모드로 전환하고 재실행하여 오탐(false positive)을 측정합니다. 6. 재설정하고 반복합니다.

프로젝트 문서

• docs/GROUND-TRUTH.md — 정답 키(취약점별 + 매트릭스).

• docs/OWASP-MCP-MAPPING.md — OWASP MCP Top 10 매핑.

• docs/TEST-SCENARIOS.md — FYP 검증 시나리오.

• CLAUDE.md — 구현 메모 / 현재 단계 상태.

• docs/PRD.md, docs/TDD.md — 설계 계약서, 로컬 전용(git 제외)으로 유지. 2026-08-21에 Docker 없는 실행 모델로 업데이트됨.

현재 상태

MCP03 및 MCP05 완료(모든 단계). uvicorn을 통해 Docker 없이 실행됩니다. MCP10은 카탈로그에 골격만 잡혀 있으며 아직 구축되지 않았습니다. CLAUDE.md를 참조하세요.