⚠️ 이 저장소는 이전되었습니다. 활성 개발은 ScopeBlind/scopeblind-gateway 에서 계속됩니다.

이 개인 포크는 공식 저장소보다 뒤쳐질 수 있습니다. 이슈, 풀 리퀘스트 및 최신 코드는 조직 저장소를 사용해 주세요.

protect-mcp

MCP 서버를 위한 보안 게이트웨이. 기본적으로 섀도우 모드 로그, 도구별 정책, 선택적 로컬 Ed25519 영수증, 검증 친화적인 감사 출력.

현재 CLI 경로: 모든 stdio MCP 서버를 투명 프록시로 래핑합니다. 섀도우 모드에서는 모든 tools/call 요청을 기록하고 모든 것을 통과시킵니다. 정책 파일을 추가하여 도구별 규칙을 적용합니다. protect-mcp init을 실행하여 로컬 서명 키와 구성을 생성하면 게이트웨이가 서명된 영수증도 발행할 수 있습니다.

Quick Start

# Wrap an existing OpenClaw / MCP config into a usable pack
npx @scopeblind/passport wrap --runtime openclaw --config ./openclaw.json --policy email-safe

# Shadow mode — log every tool call, enforce nothing
npx protect-mcp -- node my-server.js

# Generate keys + config template for local signing
npx protect-mcp init

# Shadow mode with local signing enabled
npx protect-mcp --policy protect-mcp.json -- node my-server.js

# Enforce mode
npx protect-mcp --policy protect-mcp.json --enforce -- node my-server.js

# Export an offline-verifiable audit bundle
npx protect-mcp bundle --output audit.json

기능

protect-mcp는 MCP 클라이언트와 서버 사이에 stdio 프록시로 위치합니다:

MCP 클라이언트 ←stdin/stdout→ protect-mcp ←stdin/stdout→ 당신의 MCP 서버

tools/call JSON-RPC 요청을 가로채서 다음을 수행합니다:

섀도우 모드 (기본값): 모든 도구 호출을 기록하고 모든 것을 통과시킵니다.
강제 모드: block, rate_limit, min_tier와 같은 도구별 정책 규칙을 적용합니다.
선택적 로컬 서명: 서명이 구성된 경우 구조화된 로그와 함께 Ed25519 서명 영수증을 발행합니다.

다른 모든 MCP 메시지(initialize, tools/list, 알림)는 투명하게 통과합니다.

현재 제공되는 기능

도구별 정책 — 파괴적인 도구 차단, 비용이 많이 드는 도구 속도 제한, 최소 티어 요구 사항 첨부
구조화된 결정 로그 — 모든 결정이 [PROTECT_MCP]와 함께 stderr로 출력됩니다.
선택적 로컬 서명 영수증 — signing.key_path가 포함된 정책과 함께 실행할 때 생성되며, .protect-mcp-receipts.jsonl에 저장되고 http://127.0.0.1:9876/receipts에서 노출됩니다.
오프라인 검증 — npx @veritasacta/verify로 영수증 또는 번들을 검증합니다.
계정 불필요 — 로컬 키, 로컬 정책, 로컬 프로세스

현재 기능 한계

이것들은 배포하거나 사용자에게 설명하기 전에 중요합니다:

서명은 기본 npx protect-mcp -- ... 경로에서 자동으로 이루어지지 않습니다. 해당 경로는 섀도우 모드에서 결정을 기록합니다. 로컬 서명을 위해서는 npx protect-mcp init을 실행한 후 생성된 정책 파일로 게이트웨이를 시작하십시오.
티어 인식 정책 검사는 활성화되어 있지만, 매니페스트 승인은 기본 CLI/stdio 경로에 연결되지 않았습니다. CLI는 호스트 통합이 프로그래밍 방식으로 승인 API를 호출하지 않는 한 세션을 unknown으로 기본 설정합니다.
자격 증명 구성은 현재 env 기반 자격 증명 참조를 검증하고 로그/영수증에 자격 증명 레이블을 기록합니다. 일반적인 stdio 도구에 대한 일반적인 호출별 주입은 어댑터에 따라 다르며 기본 프록시 경로에서 수행되지 않습니다.
외부 PDP 어댑터 및 감사 번들 도우미는 내보낸 유틸리티로 존재합니다. 아직 기본 CLI 경로에 완전히 연결되지 않았습니다.

정책 파일

{
  "default_tier": "unknown",
  "tools": {
    "dangerous_tool": { "block": true },
    "admin_tool": { "min_tier": "signed-known", "rate_limit": "5/hour" },
    "read_tool": { "require": "any", "rate_limit": "100/hour" },
    "*": { "rate_limit": "500/hour" }
  },
  "signing": {
    "key_path": "./keys/gateway.json",
    "issuer": "protect-mcp",
    "enabled": true
  },
  "credentials": {
    "internal_api": {
      "inject": "env",
      "name": "INTERNAL_API_KEY",
      "value_env": "INTERNAL_API_KEY"
    }
  }
}

정책 규칙

도구 이름은 정확히 일치하며, "*"는 와일드카드 폴백으로 사용됩니다.

MCP 클라이언트 설정

Claude Desktop

claude_desktop_config.json에 추가:

{
  "mcpServers": {
    "my-protected-server": {
      "command": "npx",
      "args": [
        "-y", "protect-mcp",
        "--policy", "/path/to/protect-mcp.json",
        "--enforce",
        "--", "node", "my-server.js"
      ]
    }
  }
}

Cursor / VS Code

동일한 패턴 — 서버 명령을 protect-mcp로 감싸서 교체합니다.

CLI 옵션

protect-mcp [options] -- <command> [args...]
protect-mcp init

Commands:
  init              Ed25519 키쌍 + 구성 템플릿 생성
  status            결정 통계 및 로컬 패스포트 아이덴티티 표시
  digest            로컬 사람이 읽을 수 있는 요약 생성
  receipts          최근 저장된 서명 영수증 표시
  bundle            오프라인 검증 가능한 감사 번들 내보내기

Options:
  --policy <path>   정책/구성 JSON 파일
  --slug <slug>     로그/영수증용 서비스 식별자
  --enforce         강제 모드 활성화 (기본값: shadow)
  --verbose         디버그 로깅 활성화
  --help            도움말 표시

프로그래밍 방식 훅

라이브러리는 기본 CLI 경로에 아직 연결되지 않은 기본 요소도 노출합니다:

import {
  ProtectGateway,
  loadPolicy,
  evaluateTier,
  meetsMinTier,
  resolveCredential,
  initSigning,
  signDecision,
  queryExternalPDP,
  buildDecisionContext,
  createAuditBundle,
} from 'protect-mcp';

다음과 같은 기능을 추가하려면 사용하세요:

세션 시작 전 매니페스트 승인
외부 PDP (OPA, Cerbos 또는 일반 HTTP 웹훅)
사용자 정의 자격 증명 브로커 통합
자체 영수증 저장소 주변의 감사 번들 내보내기

결정 로그 및 영수증

모든 도구 호출은 구조화된 JSON을 stderr로 출력합니다:

[PROTECT_MCP] {"v":2,"tool":"read_file","decision":"allow","reason_code":"observe_mode","policy_digest":"none","mode":"shadow","timestamp":1710000000}

서명이 구성되면 서명된 영수증이 이어집니다:

[PROTECT_MCP_RECEIPT] {"v":2,"type":"decision_receipt","algorithm":"ed25519","kid":"...","issuer":"protect-mcp","issued_at":"2026-03-22T00:00:00Z","payload":{"tool":"read_file","decision":"allow","policy_digest":"...","mode":"shadow","request_id":"..."},"signature":"..."}

CLI로 검증: npx @veritasacta/verify receipt.json 브라우저에서 검증: scopeblind.com/verify

감사 번들

패키지는 자체 포함된 감사 번들을 위한 도우미를 제공합니다:

{
  "format": "scopeblind:audit-bundle",
  "version": 1,
  "tenant": "my-service",
  "receipts": ["..."],
  "verification": {
    "algorithm": "ed25519",
    "signing_keys": ["..."]
  }
}

수집된 서명 영수증 주변에 createAuditBundle()을 사용하세요.

철학

섀도우 우선. 강제하기 전에 에이전트가 무엇을 하는지 확인하세요.
대시보드 전용 로그보다 영수증. 서명된 아티팩트는 독립적으로 검증 가능해야 합니다.
클레임을 좁게 유지하세요. 기본 CLI 경로는 아직 장기 아키텍처가 지원할 모든 것을 수행하지 않습니다.
기존 인증 위에 계층화하세요. 제어와 증거를 추가하기 위해 스택을 제거하지 마세요.

사건 기반 정책 팩

protect-mcp와 함께 제공 — 각각 실제 공격을 방지합니다:

npx protect-mcp --policy node_modules/protect-mcp/policies/clinejection.json -- node server.js

전체 OWASP Agentic Top 10 매핑: scopeblind.com/docs/owasp

BYOPE: 외부 정책 엔진

OPA, Cerbos, Cedar (AWS AgentCore) 및 일반 HTTP 엔드포인트 지원:

{
  "policy_engine": "hybrid",
  "external": {
    "endpoint": "http://localhost:8181/v1/data/mcp/allow",
    "format": "cedar",
    "timeout_ms": 200,
    "fallback": "deny"
  }
}

표준 및 IP

IETF 인터넷 초안: draft-farley-acta-signed-receipts-00 — M2M 접근 제어를 위한 서명된 결정 영수증
특허 상태: 4건의 호주 가특허 출원 중 (2025-2026) — 구성 가능한 공개, 도구 호출 게이트웨이, 에이전트 매니페스트, 휴대용 아이덴티티를 포함한 결정 영수증
검증: MIT 라이선스 — npx @veritasacta/verify --self-test

라이선스

MIT — 제한 없이 자유롭게 사용, 수정, 배포 및 개발할 수 있습니다.

scopeblind.com · npm · GitHub · IETF 초안

`block`	`true`	이 도구를 명시적으로 차단
`require`	`"any"`, `"none"`	기본 접근 요구 사항
`min_tier`	`"unknown"`, `"signed-known"`, `"evidenced"`, `"privileged"`	호스트가 승인 상태를 설정하는 경우 필요한 최소 티어
`rate_limit`	`"N/unit"`	속도 제한 (예: `"5/hour"`, `"100/day"`)

`clinejection.json`	CVE-2025-6514: MCP OAuth 프록시 하이재킹 (437K 환경)	A01, A03
`terraform-destroy.json`	자율 Terraform 에이전트가 프로덕션 파괴	A05, A06
`github-mcp-hijack.json`	조작된 GitHub 이슈를 통한 프롬프트 인젝션	A01, A02, A03
`data-exfiltration.json`	아웃바운드 도구 남용을 통한 에이전트 데이터 도난	A02, A04
`financial-safe.json`	승인되지 않은 금융 거래	A05, A06

scopeblind-gateway

인기