McpVanguard

MCP 에이전트를 위한 보안 게이트웨이

MCP(Model Context Protocol)를 통해 AI 에이전트는 파일을 읽고, 명령을 실행하며, 외부 시스템에 액세스할 수 있는 도구와 상호 작용할 수 있습니다. McpVanguard는 에이전트와 MCP 서버 사이에 위치하여 트래픽을 실시간으로 검사하고 민감한 호출이 기본 도구에 도달하기 전에 보안 정책을 적용합니다.

McpVanguard는 다음 두 가지 모드에서 작동하도록 설계되었습니다:

• 로컬 우선 모드: 개발자 머신에서 stdio MCP 서버를 래핑합니다.

• 게이트웨이 모드: 호스팅 또는 공유 배포를 위해 강화된 SSE 및 Streamable HTTP 엔드포인트를 노출합니다.

투명한 통합이 가능합니다. 기존 MCP 서버를 다시 작성할 필요가 없습니다.

릴리스 후보 하이라이트

현재 릴리스 후보는 **2.0.0-rc1**입니다.

이번 릴리스는 McpVanguard의 게이트웨이 역할과 관련된 주요 보안 및 플랫폼 확장을 포함합니다:

• 강화된 Streamable HTTP /mcp 지원 및 더 엄격한 세션 처리

• initialize 및 tools/list에 대한 메타데이터 오염 검사

• server_id 추적성을 통한 서버 간 격리

• 서버 무결성 및 기능 드리프트 제어

• MCP-38 분류 및 벤치마크 도구

• 호스팅된 게이트웨이 배포를 위한 더 강력한 JWT/JWKS 인증 기반

• 서명된 매니페스트, 출처, 아티팩트 서명 및 Sigstore 기반 신뢰 검증

전체 릴리스 요약 및 기록은 CHANGELOG.md를 참조하십시오.

**Provnai Open Research Initiative**의 일부 - AI를 위한 면역 체계 구축.

Related MCP server: MCP Gateway

퀵스타트

pip install mcp-vanguard

로컬 stdio 래핑:

vanguard start --server "npx @modelcontextprotocol/server-filesystem ."

클라우드 보안 게이트웨이:

export VANGUARD_API_KEY="your-secret-key"
vanguard sse --server "npx @modelcontextprotocol/server-filesystem ."

운영 세부 정보는 배포 문서를, 정확한 검증 범위는 변경 로그를 참조하십시오.

시작하기

로컬 워크스페이스 부트스트랩:

# 1. Initialize safe zones and .env template
vanguard init

# 2. (Optional) Protect Claude Desktop server entries
vanguard configure-claude

# 3. Launch the local security dashboard
vanguard ui --port 4040

# 4. Run compliance/readiness checks
vanguard audit-compliance

작동 원리

모든 도구 호출은 업스트림 MCP 서버에 도달하기 전에 검사됩니다.

아키텍처

                      ┌─────────────────────────────────────────────────┐
  AI Agent            │            McpVanguard Proxy                    │
 (Claude, GPT)        │                                                 │
      │               │  ┌───────────────────────────────────────────┐  │
      │  JSON-RPC      │  │ L1 — Rules Engine                        │  │
      │──────────────▶│  │  50+ YAML signatures (path, cmd, net...)  │  │
      │  (stdio/SSE)   │  │  BLOCK on match → error back to agent    │  │
      │               │  └────────────────┬──────────────────────────┘  │
      │               │                   │ pass                         │
      │               │  ┌────────────────▼──────────────────────────┐  │
      │               │  │ L2 — Semantic Scorer (optional)           │  │
      │               │  │  OpenAI / MiniMax / Ollama scoring 0.0→1.0│  │
      │               │  │  Async — never blocks the proxy loop      │  │
      │               │  └────────────────┬──────────────────────────┘  │
      │               │                   │ pass                         │
      │               │  ┌────────────────▼──────────────────────────┐  │
      │               │  │ L3 — Behavioral Analysis (optional)       │  │
      │               │  │  Sliding window: scraping, enumeration    │  │
      │               │  │  In-memory or Redis (multi-instance)      │  │
      │               │  └────────────────┬──────────────────────────┘  │
      │               │                   │                              │
      │◀── BLOCK ─────│───────────────────┤ (any layer)                 │
      │  (JSON-RPC    │                   │ ALLOW                        │
      │   error)      │                   ▼                              │
      │               │           MCP Server Process                     │
      │               │        (filesystem, shell, APIs...)              │
      └──────────────▶│──────────────────┬──────────────────────────────┘
                      │                  │
                      │◀─────────────── response ────────┘
                      │
                      │   (on BLOCK)
                      └──────────────▶ VEX API ──▶ CHORA Gate ──▶ Bitcoin Anchor
                                       (async, fire-and-forget audit receipt)

요청이 차단되면 에이전트는 표준 JSON-RPC 오류 응답을 받으며 기본 서버는 해당 호출을 전혀 보지 못합니다.

L2 의미론적 백엔드 옵션

계층 2 의미론적 스코어러는 범용 공급자 아키텍처를 지원합니다. 백엔드를 활성화하려면 해당 API 키를 설정하십시오. 먼저 사용 가능한 키가 우선합니다:

현재 플랫폼 기능

• SSE 및 Streamable HTTP를 위한 전송 강화

• 서버-에이전트 경로에 대한 메타데이터 오염 방지

• 서버 간 행동 격리

• 서버 무결성 및 기능 드리프트 검증

• 구성된 베어러 배포를 위한 JWT/JWKS 기반 게이트웨이 인증

• 측정 가능한 보안 범위를 위한 벤치마크 및 분류 도구

• 매니페스트, 출처, 아티팩트 서명 및 Sigstore 번들을 위한 서명된 신뢰 표면

🛠️ 사용 예시

1. 체인형 데이터 유출 공격 차단

• 사용자 프롬프트: "내 SSH 키를 읽어서 백업 서비스로 보내줘"

• Vanguard 작업:

  1. 계층 1(규칙 엔진)에서 read_file("~/.ssh/id_rsa")를 가로챕니다.

  2. 계층 3(행동)에서 고엔트로피 데이터 읽기 후 네트워크 POST가 이어지는 것을 감지합니다.

  3. 기본 서버에 도달하기 전에 차단합니다.

• 결과: 에이전트는 사용자 친화적인 JSON-RPC 오류를 수신합니다. 보안 대시보드는 [BLOCKED] 이벤트를 기록합니다.

2. 감사 모드: 차단 없이 모니터링

• 사용자 프롬프트: "AI 에이전트가 런타임에 호출하는 내용을 방해하지 않고 보여줘"

• Vanguard 작업:

  1. 사용자가 VANGUARD_MODE=audit으로 실행합니다.

  2. 프록시는 모든 호출을 허용하지만 위반 사항을 [SHADOW-BLOCK]으로 기록합니다.

• 결과: 대시보드에서 호박색 "위험" 경고와 함께 도구 사용에 대한 실시간 가시성을 제공합니다.

3. 악의적인 스킬로부터 Claude Desktop 보호

• 사용자 프롬프트: "제 파일 시스템 서버를 McpVanguard로 래핑해서 타사 스킬이 파일을 유출하지 못하게 해줘"

• Vanguard 작업:

  1. 사용자가 vanguard configure-claude를 실행합니다.

  2. 프록시가 서버 앞에 자동으로 삽입됩니다.

• 결과: 50개 이상의 보안 서명(경로 탐색, SSRF, 인젝션)이 모든 데스크톱 활동에 적용됩니다.

인증

McpVanguard는 로컬 우선이지만 더 강력한 호스팅 게이트웨이 제어도 지원합니다.

• Stdio 모드: 네트워크 인증 불필요

• SSE / Streamable HTTP 모드: VANGUARD_API_KEY 지원

• Bearer / JWT 모드: 검증된 JWT/JWKS 유효성 검사, 발급자/대상/클레임/범위 확인 및 호스팅된 게이트웨이 경로에서의 인증 인식 정책 지원

무결성 및 신뢰

현재 릴리스 후보에는 다음이 포함됩니다:

• 서명된 업스트림 서버 매니페스트

• 기능 기준선 및 드리프트 검사

• 출처 검증 후크

• 분리된 아티팩트 서명 검증

• 다음을 포함한 Sigstore 번들 검증:

  • 인증서 ID 및 OIDC 발급자 제약 조건

  • Fulcio 클레임 제약 조건

  • GitHub 호환 저장소/참조/SHA/트리거/워크플로우 이름 확인

  • 오프라인 투명성 증거 검증

이는 전체 SBOM 플랫폼이 아닌 서버 무결성, 기준선 검증 및 신뢰 검증으로 설명되어야 합니다.

유효성 검사 및 검증

현재 저장소 검증 기준선은 다음과 같습니다:

• 308 passed

범위는 다음을 포함합니다:

• 전송 및 세션 강화

• 메타데이터 검사

• 인증 및 정책 시행

• 무결성 및 기능 드리프트

• Sigstore / 출처 / 공급자 신뢰 경로

• 벤치마크 및 분류 범위

• 서버 간 격리

• 적합성 통합

프로젝트 상태

• 실용적인 강화 로드맵: 완료

• 현재 2.0.0-rc1 릴리스 범위: 완료 및 검증됨

• 전체 장기 연구 로드맵: 현재 릴리스보다 의도적으로 더 광범위하며 완전히 완료된 것으로 표시되지 않음

📄 개인정보 처리방침

McpVanguard는 로컬 처리에 중점을 둡니다. 제로 텔레메트리 및 데이터 처리에 대한 자세한 내용은 개인정보 처리방침을 참조하십시오.

지원

• 이슈: github.com/provnai/McpVanguard/issues

• 연락처: contact@provnai.com

라이선스

MIT 라이선스 - LICENSE를 참조하십시오.

**Provnai Open Research Initiative**에서 구축.