protect-mcp

AI 에이전트 도구 호출을 위한 fail-closed Cedar 정책 게이트와 서명된 영수증.

protect-mcp는 AI 에이전트의 도구 호출 앞에 위치하는 게이트입니다. 각 호출을 Cedar 정책(AWS가 IAM에 사용하는 것과 동일한 언어)에 대조하여 평가하고, 규칙을 위반하는 호출이 실행되기 전에 차단하며, 모든 결정에 대해 오프라인에서 검증 가능한 Ed25519 영수증에 서명합니다. 로컬에서 실행되고, 결정에 대한 텔레메트리를 어디에도 전송하지 않으며, MIT 라이선스입니다.

차별점

• 기본적으로 fail-closed. 정책 오류, 엔진 누락, 평가 실패 등 어떤 상황에서도 결정은 DENY입니다. 게이트는 결코 조용히 허용하지 않습니다. 섀도 롤아웃을 위한 관찰 모드가 존재하지만, 그곳에서도 차단되었을 호출은 would_deny: true로 표시되므로 실패가 조용히 넘어가는 일은 없습니다.
• 스스로의 절제를 증명합니다. serve --enforce와 doctor는 시작 시 자체 테스트를 실행하며, 알려진 금지 동작이 실제로 거부되는 것을 보여주지 못하면 게이트를 무장시키기를 거부합니다. 거부를 증명할 수 없는 게이트는 시작하지 않습니다.
• 모든 결정은 누구나 검증할 수 있는 영수증입니다. 결정은 Ed25519로 서명되며 @veritasacta/verify로 오프라인에서 검증할 수 있습니다. 벤더 신뢰가 필요하지 않습니다. 수학은 누가 실행하는지 신경 쓰지 않습니다.

빠른 시작: 설치부터 첫 번째 유용한 증명까지```bash

1. Generate an Ed25519 keypair, config template, and sample policy.

npx protect-mcp init

2. Wrap any MCP server in shadow mode. Nothing is blocked yet; calls are logged.

npx protect-mcp wrap -- node your-mcp-server.js

3. Inspect the local-only dashboard: tool inventory, risk, approvals, receipts.

npx protect-mcp dashboard --open

4. Draft a reviewable policy from observed calls.

npx protect-mcp recommend --write

5. When reviewed, restart the wrapper in enforce mode with that policy.

npx protect-mcp --policy protect-mcp.recommended.json --enforce -- node your-mcp-server.js

Claude Desktop의 경우, 먼저 드라이런(dry-run) 구성 패치를 실행한 다음 적용하세요:```bash
npx protect-mcp wrap --claude-desktop
npx protect-mcp wrap --claude-desktop --write
npx protect-mcp dashboard --open

대시보드는 127.0.0.1에 바인딩되며, 로컬 로그/영수증 파일만 읽고, 아무것도 업로드하지 않습니다. 호스팅된 ScopeBlind 대시보드를 명시적으로 원하는 경우에만 npx protect-mcp connect를 사용하세요.

MCP 서버로서의 게이트

Claude Code 훅을 연결하는 대신 게이트를 도구로 호출하고 싶다면, MCP 서버로 실행하세요:```bash npx protect-mcp mcp

MCP를 stdio를 통해 사용하며, 전체 루프를 구성하는 네 가지 읽기 전용 도구를 노출합니다:

- **`evaluate_action`**: 제안된 도구 호출을 인라인 Cedar 정책에 따라 판단하며, fail-closed 방식입니다(모든 정책 오류는 DENY). `{ allowed, decision, reason, policy_digest }`를 반환합니다.
- **`sign_decision`**: 결정을 Ed25519 서명된 영수증으로 변환합니다(거부는 `gateway_restraint`에 서명하고, 허용은 `decision_receipt`에 서명합니다). 영수증과 해당 공개 키를 반환하며, 키를 제공하지 않으면 임시 키를 생성합니다.
- **`verify_receipt`**: 서명된 영수증을 공개 키에 대해 오프라인으로 검증합니다. `{ valid, error, type, kid, issuer }`를 반환합니다.
- **`self_test`**: 입력 없이 스스로를 증명합니다. 알려진 금지된 작업이 거부된 다음, 서명된 영수증이 왕복 검증되고 변조된 복사본은 실패합니다.

MCP 호스트를 여기에 연결하세요, 예를 들어 Claude Desktop:```json
{
  "mcpServers": {
    "protect-mcp": { "command": "npx", "args": ["-y", "protect-mcp", "mcp"] }
  }
}

Receipt는 런타임에 게이트가 서명하는 것과 바이트 호환되므로, 여기서 발급된 receipt는 @veritasacta/verify와 브라우저 검증기에서 동일하게 검증됩니다.

로컬 액션 대시보드

protect-mcp dashboard는 가시성에서 시행으로 나아가기 위한 운영자 뷰입니다:

• 도구 인벤토리: 관찰된 모든 도구, 호출 횟수, 높음/중간/낮음 위험도, 그리고 활성 정책에 정확한 규칙이 있는지, 와일드카드 폴백이 있는지, 규칙이 없는지를 보여줍니다.
• 정책 커버리지: Require approval, Block, Observe에 대한 원클릭 로컬 정책 편집. 변경 사항을 검토한 후 래퍼를 재시작하세요.
• 정확한 액션 승인 큐: 사람이 승인, 거부, 편집 또는 인수하기 전에 정확한 도구, 액션, 목적지, 마스킹된 페이로드 미리보기, 페이로드 해시, 정책 근거, 그리고 사유를 캡처합니다.
• Receipt 체인: 요청 id를 서명된 receipt 해시와 연관시켜, 감사 검토자가 어떤 결정에 암호학적 증명이 있는지 확인할 수 있습니다.
• 감사 내보내기: 서명된 receipt가 존재할 때 오프라인 검증 가능한 감사 번들을 다운로드합니다. 서명되지 않은 로컬 로그만 존재하는 경우, 대시보드는 먼저 서명을 활성화해야 한다고 설명합니다.

실시간 데스크톱 폴백 승인의 경우, 래퍼가 출력한 로컬 게이트웨이 승인 엔드포인트와 nonce로 대시보드를 시작하세요:```bash npx protect-mcp dashboard --open
--approval-endpoint http://127.0.0.1:9876
--approval-nonce "$PROTECT_MCP_APPROVAL_NONCE"

`Approve`는 해당 플래그가 있을 때 라이브 로컬 게이트웨이로 전달합니다.
`Deny`, `Edit`, `Take over`는 승인 해결 기록으로 로컬에 기록됩니다.
운영자 지시로 사용하고 필요할 때 도구를 다시 실행하세요.

### 유료 경계 MVP: 데이터 업로드가 아닌 다이제스트 앵커링

로컬 자체 서명 영수증은 무료로 유지되며 오프라인에서 검증 가능합니다. 유료 경계는
ScopeBlind가 원시 프롬프트, 도구 페이로드, 출력, 개인 키 또는
원시 영수증을 받지 않고 조직 신원 아래 특정 시점에 영수증 다이제스트를 보았다는
독립적인 증거입니다.```bash
# Create or refresh a local org identity and public-key directory.
npx protect-mcp registry init --org "Meridian Global Macro" --billing-account acct_meridian

# Local preview: writes a digest registry and shareable static verifier page.
npx protect-mcp registry anchor

# Hosted mode: uploads receipt digests only for independent anchoring.
SCOPEBLIND_TOKEN=... npx protect-mcp registry anchor \
  --hosted \
  --endpoint https://api.scopeblind.com \
  --verifier-base https://legate.scopeblind.com

로컬 미리보기는 의도적으로 local-preview-not-independent로 표시됩니다. 호스팅 모드는 영수증 해시, 요청 ID, 조직 공개 키, 청구 메타데이터만 앵커링합니다. 원시 영수증이나 민감한 컨텍스트는 업로드하지 않습니다.

킬러 데모: 섀도우에서 정책으로, 그리고 증명으로

protect-mcp killer-demo는 완전한 3분 분량의 세일즈/데모 팩을 생성합니다:```bash npx protect-mcp killer-demo --dir ./scopeblind-demo

모의 파일시스템, GitHub, 이메일, PMS 활동을 생성하고, 섀도 모드에서 위험한 호출을 보여주며, 정책 팩을 적용하고, 민감한 PMS 예약에 대한 승인을 요구하며, 게이트웨이를 통해 실행하고, 서명된 영수증을 작성하며, 원본 영수증이 검증됨을 증명하고, 변조된 영수증이 실패함을 증명하며, 민감한 컨텍스트를 숨기면서 최소 증명을 보여주는 선택적 공개 패키지를 생성합니다.

생성된 `DEMO-RUNBOOK.md`를 먼저 여십시오. 그런 다음 출력된 대시보드 명령을 실행하여 고객에게 정확한 순서를 안내하십시오.

### 선택적 공개 v0

커밋먼트 모드 영수증은 모든 필드를 평문으로 노출하는 대신 `committed_fields_root`를 포함할 수 있습니다. 나중에 보유자는 선택된 필드만 공개할 수 있습니다:```bash
npx protect-mcp verify-disclosure \
  --receipt ./receipts/selective-disclosure.receipt.json \
  --disclosure ./receipts/selective-disclosure.tool-only.json

검증자는 상위 영수증 해시, Ed25519 서명, 커밋먼트 루트, 그리고 공개된 각 필드의 머클 증명을 확인합니다. 그런 다음 어떤 필드가 공개되었고 어떤 커밋된 필드가 숨겨진 채로 남아 있는지 설명합니다. 이는 솔트 처리된 커밋먼트 공개이며, 완전한 영지식은 아니지만 프라이버시 주장을 구체적으로 만듭니다: 감사자는 전체 도구 페이로드나 민감한 데스크 컨텍스트를 받지 않고도 선택된 사실을 검증할 수 있습니다.

레코드에 대한 주장 증명 (위치 블라인드 증명)

레코드를 공개하지 않고도 레코드에 대한 CLAIM을 증명할 수 있습니다. 전체 레코드에 대해 서명된 위치 블라인드 증명을 발행하여 결정별 범주(영수증 다이제스트, 판정, 기능 태그)만 공개하고, 도구 입력, 출력, 데이터는 절대 공개하지 않습니다:```bash

"No action reached the network across the record":

npx protect-mcp claim --no net.egress

other predicates:

--only fs.read,fs.write all actions were confined to these capabilities

--no-verdict blocked no action was blocked

--count blocked how many were blocked

누구나 오프라인에서 검증할 수 있으며, 카테고리만 볼 수 있고 내용은 절대 볼 수 없습니다:```bash
npx protect-mcp verify-claim claim-<id>.json

검증자는 공개된 집합에 대해 Merkle 루트를 다시 계산하고 술어를 독립적으로 다시 계산하므로, 발급자는 공개된 내용을 고려할 때 주장에 대해 거짓말을 할 수 없다. --anchor를 추가하면 주장의 다이제스트를 공개적이고 추가 전용인 ScopeBlind 투명성 로그에 기록하므로, 당신을 신뢰하지 않는 상대방도 공개된 집합이 완전하며 몰래 재구성되지 않았음을 확인할 수 있다(해시만 전송되며 기록은 로컬에 남는다):```bash npx protect-mcp claim --no net.egress --anchor

이것은 책임성이 있고 위치를 알지 못하는 증명이며, 완전한 영지식은 아니다: 내용이 아니라 형태를 드러낸다.

## 60초 만에 사용해 보기 (에이전트 필요 없음)

[![2분 데모 영상 보기](https://assets.kitploit.com/production/public/readmes/13151/01d856d6ca762bf76992ad56ab4c05824f272e9d98d62516a8f53bb90bce0db5.jpg)](https://legate.scopeblind.com/record)

[legate.scopeblind.com/record](https://legate.scopeblind.com/record)에서 2분 영상을 시청한 다음, 자신의 복사본에 대해 다시 재생해 보세요:```bash
npx protect-mcp sample     # seed a labeled sample record (8 decisions: 1 blocked, 2 payments)
npx protect-mcp record     # open it: signatures verified in your browser

npx protect-mcp claim --payment-under 100 --anchor --output payments-under-100.json
npx protect-mcp verify-claim payments-under-100.json
npx protect-mcp anchor-record

생성된 demo-tampered.jsonl을 레코드 페이지에 드롭하면 서명 후 편집이 적발되는 것을 확인할 수 있습니다. sample은 기존 레코드를 건드리지 않으므로 빈 폴더에서 실행하세요. 실제 작업을 할 준비가 되면 아래의 게이트를 연결하면 동일한 명령이 에이전트 자체 레코드에 대해 실행됩니다.

Claude Code 훅 빠른 시작```bash

Generate hook config and a sample Cedar policy.

npx protect-mcp init-hooks

Serve the Claude Code hook gate in enforce mode. It runs a restraint self-test

first and refuses to start if it cannot prove it denies a forbidden vector.

npx protect-mcp serve --enforce --cedar ./cedar

단일 실행 평가로, PreToolUse 훅이 호출하는 방식이다. 종료 코드 2는 거부를 의미하며(도구가 차단됨), 종료 코드 0은 허용을 의미한다:```bash
npx protect-mcp evaluate --cedar ./cedar --tool Bash --input '{"command":"rm"}'
echo $?   # 2  -> denied, fail-closed

npx protect-mcp evaluate --cedar ./cedar --tool Read --input '{"path":"README.md"}'
echo $?   # 0  -> allowed

정책이 없거나 로드할 수 없으면 명시적으로 --fail-on-missing-policy false를 전달하지 않는 한 거부(종료 2)합니다.

Claude Code 훅

protect-mcp init-hooks가 .claude/settings.json을 대신 작성해 줍니다. 게이트를 수동으로 연결하려면 필요한 두 가지 동사는 evaluate(PreToolUse, 종료 2에서 차단)와 sign(PostToolUse, 영수증 기록)입니다. Claude Code 세션이 항상 테스트한 게이트를 실행하도록 버전을 고정하세요:```json { "hooks": { "PreToolUse": [ { "matcher": "", "hooks": [ { "type": "command", "command": "npx [email protected] evaluate --cedar ./cedar --tool "$TOOL_NAME" --input "$TOOL_INPUT"" } ] } ], "PostToolUse": [ { "matcher": "", "hooks": [ { "type": "command", "command": "npx [email protected] sign --tool "$TOOL_NAME" --receipts ./receipts --key ./keys/gateway.json" } ] } ] } }

### 정책 결정 자체에 서명하기

0.13.0부터 `sign`은 정책을 평가하고 무조건적 허용 대신 실제 결정을 영수증에 기록할 수 있습니다. 훅이 `evaluate`에 전달할 것과 동일한 정책 디렉터리, 입력, 컨텍스트를 전달하세요:```bash
npx [email protected] sign --cedar ./cedar --tool Bash \
  --input '{"command":"rm -rf /"}' --context '{"command_pattern":"rm -rf"}' \
  --receipts ./receipts --key ./keys/gateway.json

receipt payload는 그런 다음 decision(allow 또는 deny), reason (cedar_allow 또는 cedar_deny), policy_digest(정책 집합의 acta-policy-digest-v1 digest)를 담고, draft-farley-acta-signed-receipts-03을 인용합니다. 이 명령은 decision과 digest를 stdout에 출력합니다. deny도 여전히 서명됩니다: receipt는 결정의 기록이지, 진행에 대한 허가가 아닙니다.

두 가지 Cedar action 모델이 지원됩니다. 런타임 gate는 Action::"MCP::Tool::call"을 tool을 resource로 하여 평가하는데, 이는 cedar/의 정책들이 기대하는 것이고 sign --cedar가 기본적으로 사용하는 것입니다. tool을 action으로 지정하는 정책(action == Action::"Bash"), 예를 들어 agent-governance-testvectors에 공개된 conformance policy는 --action-model tool이 필요합니다. evaluate도 같은 플래그를 받습니다.

evaluate는 deny 시 종료 코드 2로 종료하여 Claude Code가 tool 호출을 차단하고, allow 시 0으로 종료합니다. sign은 best-effort입니다: 키가 구성되어 있으면 Ed25519 서명된 receipt를 추가하고, signer를 사용할 수 없으면 tool을 실패시키는 대신 정직한 unsigned 줄 ("signed": false)을 기록합니다.

다른 에이전트에서 사용하기 (Codex, Cursor, Gemini, Hermes)

동일한 fail-closed gate는 이를 지원하는 모든 에이전트에서 tool hook으로 실행됩니다. --format <host>를 추가하면 해당 verb가 그 host의 hook payload를 stdin에서 읽고 그 계약에 따라 deny합니다:```bash

the PreToolUse / before-tool command for each host

npx -y protect-mcp@latest evaluate --format codex --cedar ./cedar # OpenAI Codex npx -y protect-mcp@latest evaluate --format gemini --cedar ./cedar # Gemini CLI BeforeTool npx -y protect-mcp@latest evaluate --format cursor --cedar ./cedar # Cursor beforeShellExecution npx -y protect-mcp@latest evaluate --format hermes --cedar ./cedar # Hermes pre_tool_call

각각을 post-tool 이벤트에서 `sign --format <host>`와 짝지어 영수증을 남기세요. 중요한 경우는 **Hermes**로, 이는 훅 종료 코드를 무시하고 stdout에서 판정을 읽으므로, `--format hermes`는 exit 2가 아니라 `{"decision":"block"}`을 통해 거부합니다 (여기서 raw exit-2는 조용히 fail open이 됩니다). `--format`이 없으면, 동사들은 위의 Claude Code 섹션에서와 정확히 동일하게 `--tool`/`--input` 플래그를 읽습니다.

## 정책 작성하기

Cedar 정책은 `--cedar`로 지정하는 디렉터리에 위치합니다. `forbid` 규칙은 거부하고, `permit` 규칙은 허용합니다. 도구 입력의 값과 일치시키려면 `.contains()` 관용구를 사용하세요:```cedar
// Allow read-only tools.
permit(
  principal,
  action == Action::"MCP::Tool::call",
  resource == Tool::"Read"
);

// Deny dangerous shell commands by matching the command against a list.
forbid(
  principal,
  action == Action::"MCP::Tool::call",
  resource == Tool::"Bash"
) when {
  ["rm", "dd", "mkfs"].contains(context.command)
};

// Block destructive tools outright.
forbid(
  principal,
  action == Action::"MCP::Tool::call",
  resource == Tool::"delete_file"
);

위험: 문자열을 리스트와 일치시키기 위해 context.command in ["rm", "dd"]를 작성하지 마십시오. in은 엔터티 계층 구조를 위한 것이지 문자열 멤버십을 위한 것이 아닙니다. Cedar는 해당 표현식을 타입 오류로 처리하고 전체 forbid 규칙을 조용히 폐기하며, 이는 (fail-open 게이트 하에서) 잔여 permit이 남게 만듭니다. 이것이 아래 권고의 정확한 결함입니다. 대신 [...].contains(context.command)를 사용하십시오. 0.7.0부터 게이트는 해당 오류에 대해 허용하는 대신 거부하며, CI 트립와이어 테스트는 해당 패턴이 배포된 정책에 다시 도입되면 빌드를 실패시킵니다. GHSA-hm46-7j72-rpv9를 참조하십시오.

스타터 정책 팩

대부분의 팀은 첫날부터 Cedar를 처음부터 작성해서는 안 됩니다. 스타터 팩을 설치하고, 섀도 모드로 실행하고, 영수증을 검사한 다음, 강화하거나 시행하십시오:```bash npx protect-mcp policy-packs list npx protect-mcp policy-packs show secrets-safe npx protect-mcp policy-packs install filesystem-safe --dir ./cedar npx protect-mcp policy-packs install all --dir ./cedar npx protect-mcp serve --cedar ./cedar

내장 팩:

- `filesystem-safe`: 파괴적인 파일 작업 및 비밀 정보로 의심되는 경로 읽기.
- `git-safe`: 강제 푸시, 하드 리셋, 파괴적 정리, 저장소 삭제.
- `email-safe`: 초안 작성 허용, 무인 전송 차단.
- `database-safe`: 읽기 중심 DB 태세, 쓰기/관리 SQL 차단.
- `cloud-spend-safe`: 명백한 클라우드 지출 생성 및 인프라 파괴.
- `secrets-safe`: 일반적인 파일, 환경 변수, 셸, 클라우드 비밀 정보 유출.
- `finance-mandate-safe`: 예약 흐름에서 제한 목록 및 집중 위반.

## 영수증 검증

영수증은 서명되어 있으며 공개 키를 가진 누구나 오프라인에서 검증할 수 있습니다. 네트워크도, 벤더도, ScopeBlind에 대한 신뢰도 필요하지 않습니다:```bash
npx @veritasacta/verify ./receipts/receipts.jsonl --format jsonl
# Exit 0 = valid, non-zero = tampered or malformed

npx protect-mcp bundle --output audit.json는 영수증과 공개 서명 키를 포함한 자체 포함형, 오프라인 검증 가능 감사 번들을 내보냅니다.

보안

protect-mcp 0.7.0은 설계상 실패 시 차단(fail closed)합니다. 정책 평가 오류, 엔진 누락, 또는 평가 중 오류가 발생한 정책이 있을 경우 결정은 허용이 아니라 DENY입니다. serve --enforce와 doctor는 게이트가 신뢰되기 전에 알려진 금지 벡터를 거부하는지 증명하는 부팅 자체 테스트를 실행하며, 이를 증명할 수 없으면 무장을 거부합니다.

영향받는 버전: 0.5.x 및 0.6.x. 해당 버전 계열은 실패 시 허용(fail open)하며(평가 오류 시 ALLOW 반환) 고정된 엔진에 대해 Cedar를 올바르게 평가하지 않으므로 forbid 규칙이 차단에 실패할 수 있습니다. >= 0.7.0으로 업그레이드하세요.

세부 정보 및 해결 방법: GHSA-hm46-7j72-rpv9. 취약점을 신고하려면 SECURITY.md를 참조하세요.

명령어

전체 플래그 참조는 npx protect-mcp --help를 실행하세요.

링크

• 프로토콜(IETF): draft-farley-acta-signed-receipts
• CHANGELOG
• npm
• scopeblind.com

MIT 라이선스. ScopeBlind가 제작했습니다.