scopeblind-gateway v0.13.1
Ed25519 서명된 영수증 + AI 에이전트를 위한 Cedar 정책. 금융 위임 게이트(Legate), 증명 팩, 3개의 IETF 인터넷 초안. npx protect-mcp
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://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
This is an accountable, position-blind attestation, not full zero-knowledge: it
reveals the shape, not the content.
## Try it in 60 seconds (no agent required)
[](https://scopeblind.com/film)
Watch the two-minute film at [scopeblind.com/film](https://scopeblind.com/film), then replay it against your own copy:```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