protect-mcp

بوابة سياسة Cedar المغلقة عند الفشل مع إيصالات موقّعة لاستدعاءات أدوات وكيل الذكاء الاصطناعي.

protect-mcp هي بوابة تقف أمام استدعاءات أدوات وكيل الذكاء الاصطناعي. تقيّم كل استدعاء مقابل سياسة Cedar (نفس اللغة التي تستخدمها AWS لـ IAM)، وتحجب ما يخالف القواعد قبل تنفيذه، وتوقّع إيصال Ed25519 قابلاً للتحقق دون اتصال لكل قرار. تعمل محلياً، ولا ترسل أي بيانات قياس عن قراراتك إلى أي مكان، وهي مرخّصة بموجب MIT.

لماذا هي مختلفة

• مغلقة عند الفشل افتراضياً. عند أي خطأ في السياسة، أو غياب المحرّك، أو فشل في التقييم، يكون القرار 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، قم بتشغيل تصحيح تكوين تجريبي أولاً، ثم طبّقه:```bash
npx protect-mcp wrap --claude-desktop
npx protect-mcp wrap --claude-desktop --write
npx protect-mcp dashboard --open

تستمع لوحة المعلومات إلى 127.0.0.1، وتقرأ فقط ملفات السجلات/الإيصالات المحلية، ولا ترفع أي شيء. استخدم npx protect-mcp connect فقط إذا كنت تريد صراحةً لوحة معلومات ScopeBlind المستضافة.

البوابة كخادم MCP

إذا كنت تفضّل استدعاء البوابة كأدوات بدلاً من ربط خطافات Claude Code، فشغّلها كخادم MCP:```bash npx protect-mcp mcp

يتحدث MCP عبر stdio ويكشف عن أربع أدوات للقراءة فقط، الحلقة الكاملة:

- **`evaluate_action`**: يقرر استدعاء أداة مقترحًا مقابل سياسة Cedar مضمّنة، بفشل مغلق (أي خطأ في السياسة هو 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"] }
  }
}

الإيصالات متوافقة بايت-ببايت مع تلك التي توقّعها البوابة في وقت التشغيل، لذا فإن الإيصال الصادر هنا يُتحقق منه باستخدام @veritasacta/verify ومُتحقِّق المتصفح بنفس الطريقة.

لوحة تحكم الإجراءات المحلية

protect-mcp dashboard هي واجهة المشغّل للانتقال من الرؤية إلى التنفيذ:

• جرد الأدوات: كل أداة مرصودة، وعدد الاستدعاءات، ومستوى الخطورة مرتفع/متوسط/منخفض، وما إذا كانت السياسة النشطة تحتوي على قاعدة دقيقة، أو بديل بنمط شامل، أو لا قاعدة.
• تغطية السياسة: تعديلات السياسة المحلية بنقرة واحدة لـ Require approval، أو Block، أو Observe. أعد تشغيل الغلاف بعد مراجعة التغييرات.
• قائمة انتظار الموافقة على الإجراء الدقيق: الأداة الدقيقة، والإجراء، والوجهة، ومعاينة الحمولة المنقّحة، وتجزئة الحمولة، وأساس السياسة، والتقاط السبب قبل أن يوافق إنسان أو يرفض أو يعدّل أو يتولى.
• سلسلة الإيصالات: معرّفات الطلبات مرتبطة بتجزئات الإيصالات الموقّعة، حتى يتمكن مراجع التدقيق من رؤية القرارات التي لديها إثبات تشفيري.
• تصدير التدقيق: يُنزّل حزمة التدقيق القابلة للتحقق دون اتصال عندما توجد إيصالات موقّعة. إذا وُجدت سجلات محلية غير موقّعة فقط، توضح اللوحة أنه يجب تمكين التوقيع أولاً.

للموافقات الاحتياطية الحية على سطح المكتب، ابدأ اللوحة بنقطة نهاية الموافقة على البوابة المحلية والـ 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. الوضع المستضاف يثبّت فقط تجزئات الإيصالات، ومعرّفات الطلبات، والمفاتيح العامة للمؤسسة، وبيانات الفوترة الوصفية. ولا يرفع الإيصالات الخام أو السياق الحساس.

العرض التوضيحي القاتل: من الظل إلى السياسة إلى الإثبات

protect-mcp killer-demo يولّد حزمة عرض/بيع كاملة مدتها ثلاث دقائق:```bash npx protect-mcp killer-demo --dir ./scopeblind-demo

ينشئ نظام ملفات وهميًا ونشاطًا وهميًا لـ GitHub والبريد الإلكتروني ونظام إدارة الأداء (PMS)؛ ويعرض الاستدعاءات عالية المخاطر في
وضع الظل (shadow mode)؛ ويطبّق حزمة سياسات؛ ويطلب موافقة على حجز حساس في نظام إدارة الأداء (PMS)؛
وينفّذ عبر البوابة (gateway)؛ ويكتب إيصالًا موقّعًا؛ ويثبت أن الإيصال الأصلي
قابل للتحقق؛ ويثبت أن إيصالًا مُعدَّلًا يفشل في التحقق؛ وينشئ حزمة
إفصاح انتقائي تُخفي السياق الحساس مع إظهار الحد الأدنى من الإثبات.

افتح ملف `DEMO-RUNBOOK.md` المُنشأ أولًا. ثم شغّل أمر لوحة المعلومات المطبوع
لإرشاد العميل عبر التسلسل الدقيق.

### الإفصاح الانتقائي v0

يمكن أن تحمل إيصالات وضع الالتزام (Commitment-mode) قيمة `committed_fields_root` بدلًا من كشف
كل حقل بنص صريح. لاحقًا، يمكن للحائز أن يفصح عن حقول محددة فقط:```bash
npx protect-mcp verify-disclosure \
  --receipt ./receipts/selective-disclosure.receipt.json \
  --disclosure ./receipts/selective-disclosure.tool-only.json

يتحقق المدقق من تجزئة الإيصال الأصلي، وتوقيع Ed25519، وجذر الالتزام، وإثبات Merkle لكل حقل مُفصح عنه. ثم يوضح الحقول التي تم الإفصاح عنها والحقول الملتزم بها التي تظل مخفية. هذا إفصاح عن التزام مملح، وليس معرفة صفرية كاملة، لكنه يجعل ادعاء الخصوصية ملموسًا: يمكن للمدققين التحقق من حقائق مختارة دون تلقي حمولة الأداة الكاملة أو سياق المكتب الحساس.

إثبات ادعاء على السجل (شهادات عمياء الموقع)

يمكنك إثبات ادعاء على سجلك دون الكشف عنه. اصك شهادة موقعة وعمياء الموقع على السجل بأكمله لا تفصح إلا عن فئات كل قرار (ملخص إيصال، الحكم، وسوم القدرات)، ولا تكشف أبدًا عن مدخلات أداتك أو مخرجاتها أو بياناتك:```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 ثانية (لا حاجة إلى وكيل)

[![شاهد الفيلم التجريبي الذي مدته دقيقتان](https://assets.kitploit.com/production/public/readmes/13151/01d856d6ca762bf76992ad56ab4c05824f272e9d98d62516a8f53bb90bce0db5.jpg)](https://legate.scopeblind.com/record)

شاهد الفيلم الذي مدته دقيقتان على [legate.scopeblind.com/record](https://legate.scopeblind.com/record)، ثم أعد تشغيله مقابل نسختك الخاصة:```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

سياسة مفقودة أو غير قابلة للتحميل ترفض (exit 2) ما لم تمرر صراحةً --fail-on-missing-policy false.

خطافات Claude Code

يكتب protect-mcp init-hooks ملف .claude/settings.json نيابةً عنك. لتوصيل البوابة يدويًا، الفعلان اللذان تحتاجهما هما evaluate (PreToolUse، يحجب عند exit 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` تقييم السياسة وتسجيل القرار الفعلي في
الإيصال بدلاً من السماح غير المشروط. مرّر دليل السياسة ونفس المدخلات والسياق
التي سيمررها الـ hook إلى `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

تحمل حمولة الإيصال بعد ذلك decision (allow أو deny)، وreason (cedar_allow أو cedar_deny)، وpolicy_digest (ملخص acta-policy-digest-v1 لمجموعة السياسات)، وتستشهد بـ draft-farley-acta-signed-receipts-03. يطبع الأمر القرار والملخص على stdout. الرفض لا يزال موقّعًا: الإيصال هو سجل القرار، وليس إذنًا بالمتابعة.

يُدعم نموذجا إجراء Cedar. تقيّم البوابة وقت التشغيل Action::"MCP::Tool::call" مع الأداة كالمورد، وهو ما تتوقعه السياسات في cedar/ وما يستخدمه sign --cedar افتراضيًا. السياسات التي تسمّي الأداة كالإجراء (action == Action::"Bash")، مثل سياسة المطابقة المنشورة في agent-governance-testvectors، تحتاج --action-model tool. ويقبل evaluate العلامة نفسها.

يخرج evaluate بالرمز 2 عند الرفض حتى يحجب Claude Code استدعاء الأداة، و0 عند السماح. أما sign فهو بذل أفضل جهد: يضيف إيصالًا موقّعًا بـ Ed25519 عند تهيئة مفتاح، وإذا لم يتوفر موقّع فإنه يسجّل سطرًا غير موقّع صادقًا ("signed": false) بدلًا من إفشال الأداة.

استخدمه في وكلاء آخرين (Codex، Cursor، Gemini، Hermes)

تعمل البوابة نفسها القائمة على الفشل المغلق كخطاف أداة في أي وكيل يدعمها. أضف --format <host> ليقرأ الفعل حمولة خطاف ذلك المضيف من stdin ويرفض وفق عقدها:```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

اربط كل واحد منها بـ `sign --format <host>` على حدث ما بعد الأداة للحصول على الإيصالات. الحالة المهمة هي **Hermes**، التي تتجاهل رموز خروج الخطاف وتقرأ الحكم من stdout، لذا فإن `--format hermes` يرفض عبر `{"decision":"block"}` بدلاً من exit 2 (فإن exit-2 الخام سيفشل بصمت مفتوحاً هناك). بدون `--format`، تقرأ الأفعال أعلام `--tool`/`--input` تماماً كما في قسم Claude Code أعلاه.

## كتابة سياسة

توجد سياسات 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 ترفض البوابة عند هذا الخطأ بدلاً من السماح، ويفشل اختبار tripwire في 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`: وضعية قاعدة بيانات موجّهة للقراءة، وحظر كتابة/إدارة SQL.
- `cloud-spend-safe`: الإنشاء الواضح لإنفاق السحابة وتدمير البنية التحتية.
- `secrets-safe`: تسريب الأسرار الشائع من الملفات وenv وshell والسحابة.
- `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 مغلقًا بحكم التصميم. عند أي خطأ في تقييم السياسة، أو غياب المحرك، أو سياسة أخطأت عند التقييم، يكون القرار DENY وليس allow. يشغّل serve --enforce وdoctor اختبارًا ذاتيًا عند الإقلاع يثبت أن البوابة ترفض متجهًا محظورًا معروفًا قبل الوثوق بها، وترفض التسليح إن لم تستطع ذلك.

الإصدارات المتأثرة: 0.5.x و0.6.x. تلك السلالات تفشل مفتوحة (تُرجع 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.