القواعد
لغة المطابقة — أنماط globs للأدوات، وعبارات الوسائط، وقوائم egress،
والمُطهّرات، والتسلسلات.
خوادم MCP
سجّل واحكم خوادم Model Context Protocol خلف بوابة واحدة مدقَّقة.
المهارات
افحص وقيّم مخاطر القدرات التي يثبّتها وكلاؤك قبل أن تتمكن من العمل.
1. ما هو جدار الحماية
وكيل الذكاء الاصطناعي لا يولّد نصاً فحسب — بل يتصرّف. يستدعيshell.exec، ويستعلم db.query، ويجلب URL، ويحمّل مهارة مجتمعية، أو
يوجّه استدعاء أداة عبر خادم MCP تابع لطرف ثالث. كل واحد من هذه إجراء له
عواقب في العالم الحقيقي، وحواجز الحماية على مستوى المطالبة لا يمكنها رؤيتها.
جدار الحماية هو سياسة مسمّاة ضمن نطاق مساحة العمل تقيّمها البوابة
على كل استدعاء أداة. تحرّر سياسة مرة واحدة، وتربط مفتاح API بها (أو تضبط
واحدة كافتراضي لمساحة العمل)، ومن ثم يُفحص كل استدعاء أداة يصدره ذلك
المفتاح مقابل السياسة — قبل أن يصل إلى الأداة.
كل سياسة هي قائمة مرتبة من القواعد. تقرر القاعدة شيئاً واحداً — على
أي استدعاءات أدوات تنطبق (نمط glob لاسم الأداة، يمكن قصره اختيارياً على
مهارة وعلى سطح فرض) وماذا تفعل حيالها (حكم: allow أو audit أو deny
أو sanitize أو تعليق للموافقة أو وضع سقف للتكلفة). يجتاز المحرك القواعد
بترتيب الأولوية، أول مطابقة تفوز، ويتراجع إلى الحكم الافتراضي للسياسة
إذا لم يطابق شيء.
تعديل سياسة يحدث أثره على كل مفتاح مرتبط بها في الاستدعاء التالي. بدون
إعادة نشر. بدون تغيير في كود الوكيل. تُفرض السياسة في البوابة — يبقى وكيلك
يصدر استدعاءات الأدوات تماماً كما كان.
الكشف يحدث في البوابة، عند أول استخدام. يجلس جدار الحماية على مسار
ترحيل LLM، وليس داخل مدير حزم وكيلك أو نظام ملفاته. الأداة أو خادم MCP أو
المهارة التي يثبّتها الوكيل ذاتياً تُلتقَط أول مرة يعبر فيها استدعاؤها
البوابة — وليس وقت التثبيت. هذا متعمّد: إنها نقطة الاختناق الوحيدة التي
ترى كل مزود، وكل وكيل، وكل استدعاء أداة بغض النظر عن كيفية وصول القدرة
إلى هناك.
2. أسطح الفرض الأربعة
يُقيَّم كل استدعاء أداة مقابل سطح واحد بالضبط — النقطة في دورة حياة الطلب التي يراه فيها جدار الحماية:| السطح | ماذا يرى |
|---|---|
inbound | الأدوات التي يعلن عنها الوكيل للنموذج على الطلب (تعريفات الأدوات). يتيح لك حجب أداة خطرة قبل أن يتمكن النموذج حتى من اختيارها. |
response | استدعاءات tool_calls التي يصدرها النموذج في رده. |
mcp | استدعاء tools/call مُرسَل عبر بوابة Firewall MCP أو مُقيَّم عبر خطّاف SDK. |
egress | وجهة شبكية صادرة (host / IP / CIDR) أبلغت عنها أداة — سطح SSRF وتسريب البيانات. |
3. المفاهيم الأساسية
| المفهوم | التعريف |
|---|---|
| Policy | مجموعة قواعد مسمّاة ضمن نطاق مساحة العمل. لها enabled وis_default وdefault_verdict وعلامة shadow_mode. |
| Rule | فحص واحد داخل سياسة: أولوية، ومطابقة أداة/مهارة، وسطح اختياري، ومُسنِد وسائط اختياري، وحكم. انظر القواعد. |
| Verdict | الإجراء الذي تنتجه قاعدة (أو الافتراضي) — انظر §4. |
| Default verdict | يُطبَّق عندما لا تطابق أي قاعدة. إحدى القيم allow أو audit (الافتراضي) أو deny. |
| Shadow mode | تقيّم السياسة وتسجّل لكنها لا تحجب أبداً — يُخفَّض كل حكم فارض إلى audit ويُسبَق السبب بـ [shadow] would …. مفتاح الطرح الآمن لديك. |
| Observe mode | إعداد على مستوى مساحة العمل. عندما لا يُحَل أي سياسة لطلب ووضع observe مفعّل، يُسمح بالاستدعاء لكنه يُسجَّل كـثغرة تغطية — وهذا ما يملأ عرض الأدوات المكتشفة. |
النطاق والحل
تُحَل السياسات تماماً مثل حواجز الحماية ومفاتيح API — مشتركة على مستوى مساحة العمل عندما يكون لديك مساحة عمل نشطة. لأي استدعاء أداة، تحل البوابة السياسة بهذا الترتيب:- ربط المفتاح — إذا كان للمفتاح المستدعي
firewall_policy_id، فإن تلك السياسة تنطبق (عندما تكون موجودة ومفعّلة). - افتراضي مساحة العمل — وإلا تنطبق سياسة
is_defaultالمفعّلة لمساحة العمل. - لا هذا ولا ذاك — لا فرض. مع وضع observe مفعّلاً، يُسمح بالاستدعاء ويُسجَّل كثغرة؛ ومع إطفائه، يُسمح بالاستدعاء صامتاً (متطابق بايت ببايت مع مساحة عمل لم تفعّل الميزة أبداً).
Fail-open على المجهول، fail-closed على الغامض. إذا اصطدم حل السياسة
بخطأ عابر، تتدهور البوابة إلى observe/allow بدلاً من إسقاط حركة المرور.
لكن حيث يكون عدم الفرض هزيمةً للقاعدة — تقرير egress بلا وجهة قابلة
للاستخدام، أو متجر موافقات غير قابل للوصول، أو مهارة لا يمكن حل ملكيتها —
يفشل المحرك مغلقاً (deny أو hold). يُحفظ التوفّر؛ ولا تُتخطّى السلامة
صامتةً في الحالات التي تهمّ.
4. الأحكام
تنتج القاعدة (أو الحكم الافتراضي) إحدى القيم:| الحكم | ماذا يفعل |
|---|---|
allow | يمرّر الاستدعاء. يُسجَّل. |
audit | يسمح، لكن يسجّله للمراجعة. الـ default_verdict الافتراضي — راقب كل شيء، لا تحجب شيئاً، حتى تكون مستعداً. |
deny | يحجب الاستدعاء. يرى الوكيل خطأ أداة (أو HTTP 400 على سطح inbound). |
sanitize | ينقّح السلاسل الفرعية المطابقة من وسائط الأداة (الأسرار، PII) ويعيد توجيه الاستدعاء المنظَّف. انظر المُطهّرات. على سطح inbound — حيث لا توجد وسائط وقت الاستدعاء بعد — يتصاعد sanitize إلى حجب. |
pending_approval | يعلّق الاستدعاء لإنسان. يحصل الوكيل على استجابة “مُعلَّقة”؛ يوافق مراجِع أو يرفض خارج النطاق؛ يعيد الوكيل التقديم برمز موافقة أحادي الاستخدام. انظر §7. |
cap_cost | يحجب بمجرد أن يتجاوز الإنفاق المتراكم لتشغيل الوكيل سقف السنتات لكل قاعدة. قاطع دائرة لحلقات الانفلات. |
deny / sanitize / pending_approval جميعها إلى
audit حتى تتمكن من قياس أثر السياسة قبل أن تغيّر حركة المرور.
5. كيف يُقيَّم استدعاء أداة
- يصل استدعاء أداة إلى البوابة (مُعلَن عنه inbound، أو مُصدَر في response، أو مُرسَل عبر بوابة MCP، أو مُبلَّغ عنه كـ egress).
- يحل المحرك السياسة النشطة (§3).
- يجتاز قواعد السياسة بترتيب الأولوية (الأولوية الأدنى أولاً؛ تُحسم التعادلات بمعرّف القاعدة). تطابق القاعدة عندما تطابق كل من: سطحها، ونمط glob لاسم الأداة، ونمط glob الاختياري لاسم المهارة، وعبارات الوسائط الاختيارية، ونطاق egress الاختياري.
- أول مطابقة تفوز ← يُطبَّق حكم القاعدة. إذا لم تطابق أي قاعدة ←
default_verdictللسياسة. - إذا كان الاستدعاء مملوكاً لـمهارة
محكومة، يُطبَّق وضع فرض المهارة فوق ذلك — مهارة في وضع
blockتفرض deny؛ ومهارة في وضعquarantineتصعّد أي شيء دون deny إلىpending_approval. - يُسجَّل القرار كحدث جدار حماية (ما لم يكن تشغيلاً تجريبياً)، مرتبطاً بتشغيل الوكيل والجلسة.
6. كيف يبدو الحجب
استدعاء مرفوض على سطح inbound يعيد HTTP 400 بجسم خطأ على هيئة OpenAI، ورمز خطأfirewall_blocked، ورسالة تسمّي الأداة والسبب — مثل
tool "shell.exec" blocked by firewall: destructive shell command. يحمل
الخطأ metadata مهيكلة (رمز السبب، عوامل المخاطرة، الدرجة) ويُعلَّم
بـ skip-retry (إعادة تشغيل نفس الاستدعاء ستحجب مجدداً فحسب).
استدعاء مُرسَل عبر بوابة MCP يُحجب كـخطأ أداة
(firewall deny: <reason>) بدلاً من فشل نقل، فيرى النموذج الرفض ويمكنه
التفاعل — اختيار أداة أخرى، أو سؤال المستخدم، أو التوقف — بدلاً من الانهيار.
استدعاء مُعلَّق (pending_approval) يعيد HTTP 400 برمز
firewall_approval_pending ومعرّف موافقة يستطلعه العميل.
7. الموافقة البشرية (HITL)
حكمpending_approval يحوّل استدعاء أداة إلى مراجعة خارج النطاق:
- يضع المحرك سجل موافقة في الطابور ويعيد استجابة “مُعلَّقة” تحمل معرّفه؛ الاستدعاء لا يصل إلى الأداة.
- يحلّها مراجِع — من وحدة التحكم (Developer+)، أو عبر استدعاء webhook مُوقَّع بـ HMAC إلى نظام الموافقات الخاص بك.
- يستطلع وكيلك (أو MCP SDK) معرّف الموافقة؛ بمجرد الموافقة، يعيد تقديم
الاستدعاء الأصلي بترويسة
X-OrcaRouter-Firewall-Approvalأحادية الاستخدام، وتمرّره البوابة تلك المرة الواحدة.
rule_changed حتى يعرف المراجِعون أن
السياق تغيّر.
8. مستويات الاستقلالية — مفتاح واحد لكامل موقفك
ضبط السياسات قاعدةً بقاعدة هو المسار الدقيق؛ أما مستويات الاستقلالية فهي السريع. يستبدل تحكّم واحد ذرّياً موقف جدار الحماية وحواجز الحماية لمساحة عملك في معاملة واحدة، مع تراجع بنقرة واحدة:| المستوى | الموقف |
|---|---|
tight | حجب shell المدمّر، والأسرار في الوسائط، وegress الخاص بـ SSRF (الافتراضي deny)؛ حواجز PII Shield + Secrets Blocker مفعّلة؛ وضع observe مطفأ. |
balanced | تدقيق shell المدمّر، تعليم PII؛ وضع observe مطفأ. الموقف المبدئي الموصى به. |
permissive | لا سياسة فارضة، لا حواجز حماية؛ وضع observe مفعّل حتى ترى كل شيء رغم ذلك. |
9. كشف الشذوذ
إلى جانب القواعد الساكنة، يتعلّم جدار الحماية الشكل الطبيعي لاستخدام الأدوات في كل مساحة عمل ويعلّم الانحرافات على تغذية قابلة للقراءة:- ارتفاعات المعدل / التكلفة — تُسجَّل نقاط النشاط لكل أداة مقابل
خط أساس لساعة الأسبوع (متوسط متحرك على 14 يوماً)، بحيث تبرز
“100 استدعاء
db.queryعند الساعة 3 صباح الأحد” حتى لو كان كل استدعاء مسموحاً به على حِدة. retry_loop— وكيل يطرق نفس الأداة الفاشلة باستمرار.novel_path— انتقال من أداة إلى أداة لم تقم به مساحة العمل هذه من قبل.
10. القابلية للملاحظة
يترك جدار الحماية أثراً يمكنك التصرف بناءً عليه، كله ضمن نطاق مساحة العمل:| السطح | ماذا يمنحك |
|---|---|
| Events | كل تقييم، قابل للتصفية حسب الحكم، السطح، الأداة، التشغيل، والجلسة. السجل الخام وراء كل شيء آخر. |
| Runs & sessions | الأحداث مجمّعة حسب تشغيل الوكيل أو المحادثة — تفصيل الأحكام، الأدوات والنماذج المتمايزة، أول/آخر ظهور. عرض “ماذا فعل هذا الوكيل فعلاً”. |
| Discovered tools | كل أداة رأتها مساحة العمل، مُعلَّمة covered (تنطبق قاعدة) أو gap (لا شيء ينطبق). يقود تأليف السياسات من حركة المرور الحقيقية. |
| Simulate | معاينة ما سيغيّره مستوى استقلالية قبل أن تطبّقه. |
| Test | تشغيل تجريبي لسياسة مقابل استدعاء أداة عينة ورؤية الحكم، والقاعدة المطابقة، والسبب — لا يُحفظ شيء، ولا يُرسَل شيء. |
| Audit | كل تغيير في سياسة أو قاعدة أو إعدادات يكتب صف تدقيق (مساحة العمل + المركزي) بعد أن يُثبَّت التغيير. لا تُسجَّل الأسرار وكتل القواعد أبداً. |
11. العلاقة مع بقية البوابة
| السطح | كيف يتكامل مع جدار الحماية؟ |
|---|---|
| حواجز الحماية | مستويان متكاملان. تفحص حواجز الحماية نص المطالبة/الاستجابة؛ ويحكم جدار الحماية إجراءات الأدوات. يمكن أن ينطبق كلاهما على طلب واحد. تضبط مستويات الاستقلالية كليهما دفعةً واحدة. |
| التوجيه | مستقل. يختار التوجيه النموذج/القناة؛ بينما يحكم جدار الحماية استدعاءات الأدوات بغض النظر عن أي نموذج خدمها. |
| مفاتيح API | يرتبط المفتاح بسياسة عبر firewall_policy_id؛ يعيش الربط على المفتاح في البوابة. عدم وجود ربط يتراجع إلى افتراضي مساحة العمل. |
| بوابة MCP | جدار الحماية هو بوابة MCP — كل خادم تسجّله يرسل tools/call خاصته عبر المحرك. |
| المهارات | وضع فرض المهارة المحكومة يركب فوق حكم القاعدة، فمهارة محجوزة في الحجر الصحي تُعلَّق حتى لو لم تسمِّ أي قاعدة أدواتها. |
12. توصيل وكيل ببوابة جدار الحماية
هناك طريقتان يصل بهما استدعاء أداة إلى المحرك:- بوابة MCP — وجّه عميل MCP الخاص بك (Claude Desktop، Cursor، إطار عمل
وكيل) إلى
https://api.orcarouter.ai/api/v1/firewall/mcp. تكشف البوابة أدوات كل خادم مسجّل قابل للوصول، بمساحة أسماء<server>.<tool>، وتقيّم كلtools/callمضمّناً. انظر خوادم MCP. - خطّاف Evaluate — استدعِ
POST /api/v1/firewall/evaluateمن حلقة وكيلك قبل إرسال استدعاء أداة، وتصرّف بناءً على الحكم.
403 على هذه المسارات.
13. مرجع API
جميع مسارات وحدة التحكم ضمن نطاق مساحة العمل عبر سياق مساحة العمل وتفرض RBAC باستمرار: القراءات وصناديق الرمل للاختبار/المحاكاة مفتوحة لكل عضو؛ الكتابات تتطلب Developer+.السياسات والإعدادات
| الطريقة والمسار | الدور | الغرض |
|---|---|---|
GET /api/workspace/firewall/settings | Member | قراءة إعدادات جدار حماية مساحة العمل (وضع observe، الافتراضيات). |
PUT /api/workspace/firewall/settings | Developer+ | تحديث الإعدادات. |
GET /api/workspace/firewall/policies | Member | قائمة السياسات (مع عدد القواعد + المفاتيح المرتبطة). |
GET /api/workspace/firewall/policies/:id | Member | تفاصيل سياسة واحدة. |
POST /api/workspace/firewall/policies | Developer+ | إنشاء سياسة. |
PUT /api/workspace/firewall/policies | Developer+ | تحديث سياسة. |
DELETE /api/workspace/firewall/policies/:id | Developer+ | حذف سياسة (409 إذا كانت المفاتيح لا تزال مرتبطة). |
الموقف والإعدادات المسبقة وصناديق الرمل
| الطريقة والمسار | الدور | الغرض |
|---|---|---|
GET /api/workspace/firewall/presets | Member | الإعدادات المسبقة المدمجة للقواعد. |
POST /api/workspace/firewall/autonomy | Developer+ | تطبيق مستوى استقلالية. |
POST /api/workspace/firewall/autonomy/undo/:audit_id | Developer+ | التراجع عن تغيير استقلالية. |
GET /api/workspace/firewall/simulate | Member | معاينة مستوى استقلالية (?level=). |
POST /api/workspace/firewall/test | Developer+ | تشغيل تجريبي لسياسة مقابل استدعاء أداة عينة. |
القابلية للملاحظة
| الطريقة والمسار | الدور | الغرض |
|---|---|---|
GET /api/workspace/firewall/discovered-tools | Member | الأدوات المرئية، مُعلَّمة covered / gap. |
GET /api/workspace/firewall/events | Developer+ | قائمة أحداث جدار الحماية (قابلة للتصفية). |
GET /api/workspace/firewall/events/by-request/:request_id | Developer+ | أحداث طلب واحد. |
GET /api/workspace/firewall/events/aggregate | Developer+ | تجميع التشغيلات / الجلسات. |
GET /api/workspace/firewall/trace/by-run | Developer+ | عقد التتبّع لتشغيل (?run_id=). |
GET /api/workspace/firewall/anomalies | Member | تغذية الشذوذ (?window=). |
POST /api/workspace/firewall/anomalies/snooze | Developer+ | تأجيل تغذية الشذوذ. |
البوابة (من آلة إلى آلة)
تعمل هذه على رمز ضمن نطاق بوابة جدار الحماية، وليس جلسة وحدة التحكم:| الطريقة والمسار | الغرض |
|---|---|
POST /api/v1/firewall/evaluate | حكم ما قبل الإرسال لاستدعاء أداة واحد. |
POST /api/v1/firewall/evaluate_plan | فحص ما قبل التنفيذ لخطة متعددة الخطوات. |
ANY /api/v1/firewall/mcp | نقطة نهاية بوابة MCP الموحَّدة. |
GET /api/v1/firewall/approvals/:id | استطلاع حالة موافقة استدعاء مُعلَّق. |
POST /api/v1/firewall/approvals/:id/callback | استدعاء موافقة مُوقَّع بـ HMAC. |
14. الأسئلة الشائعة
ماذا لو لم تُحَل أي سياسة على استدعاء أداة؟
ماذا لو لم تُحَل أي سياسة على استدعاء أداة؟
مع وضع observe مطفأً، يكون السلوك متطابقاً بايت ببايت مع مساحة عمل
لم تفعّل الميزة أبداً — لا يُحجب ولا يُسجَّل شيء. ومع وضع observe
مفعّلاً، يُسمح بالاستدعاء لكنه يُسجَّل كثغرة تغطية بحيث يظهر في
الأدوات المكتشفة.
كيف أطرح سياسة بأمان؟
كيف أطرح سياسة بأمان؟
فعّل وضع الظل. تقيّم السياسة وتسجّل تماماً كما ستفعل في الإنتاج،
لكن يُخفَّض كل حكم فارض إلى
audit ويُسبَق السبب بـ [shadow] would ….
راقب عرضي الأحداث والتشغيلات، تأكّد أنها تُطلق على ما تتوقعه ولا شيء لا
تتوقعه، ثم أطفئ وضع الظل لتبدأ الفرض.هل يكلّف استدعاء أداة محجوب حصة؟
هل يكلّف استدعاء أداة محجوب حصة؟
حجب inbound يُطلق قبل استدعاء النموذج الأعلى، فلا يكلّف أي رموز نموذج.
أحكام audit / allow لا تغيّر الفوترة. قاعدة
cap_cost هي نفسها تحكّم
فوترة — تحجب بمجرد أن يتجاوز إنفاق التشغيل سقف السنتات لديك.جدار الحماية أم حواجز الحماية — أيّهما أستخدم؟
جدار الحماية أم حواجز الحماية — أيّهما أستخدم؟
كلاهما، لطبقات مختلفة. تفحص حواجز الحماية النص في المطالبات
والاستجابات (PII، الأسرار، jailbreaks). ويحكم جدار الحماية
الإجراءات التي يتخذها الوكيل (أي أدوات، أي خوادم MCP، أي مضيفين). يمكن
أن يمر طلب عبر كليهما. يضبط مستوى الاستقلالية
tight كليهما معاً.هل الفرض مضمون لكل أداة يشغّلها الوكيل؟
هل الفرض مضمون لكل أداة يشغّلها الوكيل؟
يفرض جدار الحماية على استدعاءات الأدوات التي تعبر البوابة — مسار
الترحيل، وبوابة MCP، وخطّاف evaluate. الأداة التي ينفّذها وكيلك بالكامل
داخل عمليته الخاصة، دون لمس البوابة أبداً، خارج رؤية جدار الحماية. هدف
التصميم هو جعل البوابة المسار المدقَّق الوحيد للاستدعاءات التي تهمّ
(الأدوات بوساطة النموذج، إرسال MCP، egress الشبكي)؛ وجّهها عبرها وتصبح
محكومة.
انظر أيضاً
تتعمّق أكثر في أمان الوكلاء؟ تضع أدلة أمّن وكلاءك - الثقة الصفرية هذه الميزة ضمن سير عمل قائم على الثقة الصفرية.أمّن وكلاءك (الثقة الصفرية)
دليل جدار حماية الوكلاء القائم على الثقة الصفرية — قوائم سماح الأدوات، وفحوص الوسائط، والتحكم في egress.
الأساس المرجعي لأمان الوكلاء
مفتاح واحد يضبط موقف جدار الحماية وحواجز الحماية لديك معاً.