الانتقال إلى المحتوى الرئيسي
يُضبط جدار حماية الوكيل بطريقتين: عبر وحدة التحكم (جلستك، نفس تسجيل الدخول الذي تستخدمه للوحة التحكّم) وعبر البوابة (مفتاح API مخصّص ضمن نطاق جدار الحماية يقدّمه وكيلك وقت التشغيل). تعيش العائلتان عند بادئات مسار مختلفة، وتأخذان مصادقة مختلفة، وتجيبان أسئلة مختلفة — “حرّر السياسة” مقابل “قيّم استدعاء الأداة هذا”. هذه الصفحة هي خريطة كلتيهما مساراً بمسار. لمعرفة ما تعنيه السياسة — الأحكام، والأسطح، والقواعد، والحل — ابدأ من جدار الحماية وقواعد جدار الحماية. هذه الصفحة هي سطح API فقط.

​
1. عائلتا المسارات

وحدة التحكم — اضبط

/api/workspace/firewall/*. مُصادَق بـرمز جلستك / وصولك (UserAuth)، ضمن نطاق مساحة عملك النشطة. ألّف سياسات، اقرأ أحداثاً، سجّل خوادم MCP، حُلّ موافقات. كل إجراء مُقيَّد بالدور.

البوابة — افرِض

/api/v1/firewall/*. مُصادَق بـمفتاح ضمن نطاق بوابة جدار الحماية (مفتاح بـ is_firewall_gateway مضبوط). السطح من آلة إلى آلة الذي يستدعيه وكيلك أو عميل MCP وقت التشغيل. مفتاح ترحيل عادي يحصل على 403 هنا.
مسارات وحدة التحكم لا تأخذ أبداً مفتاح ترحيل sk-orca-…، ومسارات البوابة لا تأخذ أبداً رمز جلسة. خلطهما هو أشيع 401/403 عند توصيل جدار الحماية أول مرة. مفتاح sk-orca-… الوحيد الذي ينتمي إلى استدعاء /v1/firewall/* هو مفتاح مسكوك بـ is_firewall_gateway مفعّلاً — انظر النطاق والمفاتيح والسياسات.

​
2. الأدوار في لمحة

تحلّ مسارات وحدة التحكم دور مساحة عملك وتقيّد تبعاً لذلك. القراءات التي لا تحمل أصل استدعاء أداة مفتوحة لأي عضو؛ والكتابات وأي شيء يكشف وسائط استدعاء الأداة تتطلب Developer+.
الدوريمكنه فعل
Viewer / memberقراءة الإعدادات، والسياسات، والإعدادات المسبقة، والأدوات المكتشفة، والمحاكاة، والشذوذ.
Developer+كل ما سبق، بالإضافة إلى كل كتابة، وسطح events/runs/trace، وتشغيل test التجريبي.
Admin+إضافةً، ضبط علامة is_firewall_gateway على مفتاح وقراءة النص الصريح لمفتاح بوابة.
الفصل متعمّد: يستطيع viewer أن يرى أن سياسة موجودة وما الذي ستحجبه، لكن ليس وسائط استدعاء الأداة الخام وراء حدث. إذا كنت تبني لوحات تحكّم لغير المطوّرين، فمسارات القراءة المفتوحة هي المجموعة الآمنة.

​
3. اضبط سياسة من وحدة التحكم

مسارات وحدة التحكم هي كيف تؤلّف وتفحص السياسة. تضبط كل شيء في واجهة لوحة التحكّم — هذه هي نفس نقاط النهاية التي تستدعيها.

​
السياسات والإعدادات

الطريقة والمسارالدورالغرض
GET /api/workspace/firewall/settingsMemberوضع observe + الأعداد.
PUT /api/workspace/firewall/settingsDeveloper+تحديث إعدادات جدار حماية مساحة العمل.
GET /api/workspace/firewall/policiesMemberسرد السياسات.
GET /api/workspace/firewall/policies/:idMemberتفاصيل سياسة واحدة.
POST /api/workspace/firewall/policiesDeveloper+إنشاء سياسة.
PUT /api/workspace/firewall/policiesDeveloper+تحديث سياسة.
DELETE /api/workspace/firewall/policies/:idDeveloper+حذف سياسة.
POST /api/workspace/firewall/rulesDeveloper+إضافة قاعدة.
PUT /api/workspace/firewall/rulesDeveloper+تحديث قاعدة.
DELETE /api/workspace/firewall/rules/:idDeveloper+حذف قاعدة.

​
الموقف والإعدادات المسبقة وصناديق الرمل

الطريقة والمسارالدورالغرض
GET /api/workspace/firewall/presetsMemberالإعدادات المسبقة المدمجة للقواعد.
GET /api/workspace/firewall/templatesMemberمعرض قوالب حالات الاستخدام.
POST /api/workspace/firewall/templates/applyDeveloper+تطبيق قالب ← سياسة واحدة + قواعدها.
POST /api/workspace/firewall/autonomyDeveloper+تطبيق مستوى استقلالية (tight / balanced / permissive).
POST /api/workspace/firewall/autonomy/undo/:audit_idDeveloper+تراجع بنقرة واحدة من لقطة التدقيق.
GET /api/workspace/firewall/simulateMemberما الذي سيحجبه مستوى (?level=).
POST /api/workspace/firewall/testDeveloper+تشغيل تجريبي لسياسة مقابل استدعاء عينة.

​
القابلية للملاحظة

الطريقة والمسارالدورالغرض
GET /api/workspace/firewall/discovered-toolsMemberالأدوات المرئية، مُعلَّمة covered / gap.
GET /api/workspace/firewall/eventsDeveloper+سرد أحداث جدار الحماية (قابلة للتصفية).
GET /api/workspace/firewall/events/by-request/:request_idDeveloper+أحداث طلب واحد.
GET /api/workspace/firewall/events/aggregateDeveloper+تجميع التشغيلات / الجلسات.
GET /api/workspace/firewall/trace/by-runDeveloper+عقد التتبّع لتشغيل (?run_id=).
GET /api/workspace/firewall/anomaliesMemberتغذية الشذوذ.
POST /api/workspace/firewall/anomalies/snoozeDeveloper+تأجيل التغذية (≤ 7 أيام).

​
خوادم MCP

سجّل خوادم Model Context Protocol التي يصل إليها وكلاؤك، خلف بوابة واحدة مدقَّقة. تُخزَّن بيانات الاعتماد مشفّرة وتُخفى عند القراءة.
الطريقة والمسارالدورالغرض
GET /api/workspace/firewall/mcp_serversMemberسرد الخوادم المسجّلة.
GET /api/workspace/firewall/mcp_servers/:idMemberتفاصيل خادم.
POST /api/workspace/firewall/mcp_serversDeveloper+تسجيل خادم (409 على name مكرّر).
PUT /api/workspace/firewall/mcp_serversDeveloper+تحديث خادم.
DELETE /api/workspace/firewall/mcp_servers/:idDeveloper+إزالة خادم.
POST /api/workspace/firewall/mcp_servers/:id/probeDeveloper+قابلية الوصول + مصافحة tools/list.
يحمل الخادم name فريداً، وendpoint، وauth_mode (none / bearer / oauth / basic)، وحالة صحة status (ok / degraded / down). انظر Firewall MCP لدورة الحياة الكاملة وحجر المهارة الصحي.

​
4. افرِض عند البوابة

هذه تعمل على مفتاح ضمن نطاق بوابة جدار الحماية، لا جلستك. إنها ما تستدعيه حلقة وكيلك أو عميل MCP وقت التشغيل.
الطريقة والمسارالغرض
POST /api/v1/firewall/evaluateحكم ما قبل الإرسال لاستدعاء أداة واحد.
POST /api/v1/firewall/evaluate_planفحص ما قبل التنفيذ لخطة متعددة الخطوات.
ANY /api/v1/firewall/mcpنقطة نهاية بوابة MCP الموحَّدة.
GET /api/v1/firewall/mcp_serversتعداد خوادم مساحة العمل المسجّلة.
GET /api/v1/firewall/approvals/:idاستطلاع حالة موافقة استدعاء مُعلَّق.
POST /api/v1/firewall/approvals/:id/callbackاستدعاء موافقة مُوقَّع بـ HMAC.

​
مثال واحد ملموس: قيّم استدعاء أداة

قبل أن يرسل وكيلك أداة، اطلب من البوابة حكماً. مرّر المفتاح ضمن نطاق بوابة جدار الحماية — لا مفتاح الترحيل sk-orca-… لديك: 
curl https://api.orcarouter.ai/api/v1/firewall/evaluate \
  -H "Authorization: Bearer <firewall-gateway-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "tool_name": "shell.exec",
    "arguments": { "command": "rm -rf /" }
  }'
تحمل الاستجابة الحكم — allow أو audit أو deny أو sanitize أو pending_approval. على deny تتخطّى الاستدعاء وتُظهر السبب للنموذج؛ وعلى sanitize تمرّر الوسائط المنظَّفة التي تعيدها البوابة (sanitize ينقّح وسائط استدعاء الأداة فقط — لا المحتوى الذي تعيده أداة)؛ وعلى pending_approval تدخل حلقة الموافقة أدناه.
تقيّم البوابة الاستدعاءات التي تعبرها — خطّاف evaluate، وبوابة MCP، ومسار الترحيل. الأداة التي يشغّلها وكيلك بالكامل داخل عمليته، دون لمس OrcaRouter أبداً، خارج رؤيتها. وجّه الاستدعاءات التي تهمّ (الأدوات بوساطة النموذج، إرسال MCP، egress الشبكي) عبر البوابة وتصبح محكومة.

​
5. مصافحة الموافقة (HITL)

حكم pending_approval يعلّق الاستدعاء لإنسان. خطأ HTTP أثناء التعليق هو firewall_approval_pending. تجاوزه حلقة من ثلاث خطوات مقسومة عبر عائلتي المسارات:
1

يحلّ مراجِع التعليق

من وحدة التحكم (PATCH /api/workspace/firewall/approvals/:id، Developer+)، أو ينشر نظامك الخاص استدعاءً راجعاً مُوقَّعاً بـ HMAC إلى POST /api/v1/firewall/approvals/:id/callback. يتحقّق الاستدعاء الراجع من HMAC مضمّناً — لا تُقبل مصادقة أخرى.
2

يستطلع وكيلك الموافقة

GET /api/v1/firewall/approvals/:id بمفتاح البوابة، حتى تنقلب الحالة إلى approved أو rejected.
3

أعد التقديم بالرمز أحادي الاستخدام

بمجرد الموافقة، أعد إصدار الاستدعاء الأصلي حاملاً ترويسة X-OrcaRouter-Firewall-Approval بمعرّف الموافقة. تتعرّف عليه البوابة وتمرّر ذلك الاستدعاء الواحد. الترويسة أحادية الاستخدام.
القرارات بمبدأ أول كاتب يفوز وعديمة الأثر التكراري — حلّ ثانٍ لنفس التعليق عديم الأثر. انظر جدار الحماية — الموافقة البشرية للمسار من البداية إلى النهاية ولماذا حُجب هذا؟ لقراءة حكم.

​
6. كيف يبدو الحجب

النتيجةHTTPالرمز
استدعاء أداة مرفوض (سطح inbound)400firewall_blocked
مرفوض عبر بوابة MCPخطأ أداةfirewall deny: <reason>
مُعلَّق للموافقة400firewall_approval_pending
firewall_blocked معلَّم skip-retry — إعادة تشغيل الاستدعاء المطابق تماماً ستحجب مجدداً فحسب، فيتراجع العميل المعيد للمحاولة بدلاً من القرع. قائمة الرموز الكاملة تعيش في رموز الأخطاء.

​
7. مراجع ذات صلة

Guardrail API

نظير سياسة المحتوى — مسارات /api/guardrail/* لمستوى النص.

مسرد الأحكام

كل حكم وماذا يفعل باستدعاء.

Glob وJSONPath

قواعد المطابقة خلف tool_name_glob وargs_match.

Compliance API

الحزم، والتقارير المُوقَّعة، والإقامة، والمحو.

​
8. الأسئلة الشائعة

تتطلب مسارات البوابة مفتاحاً ضمن نطاق بوابة جدار الحماية — مفتاحاً مسكوكاً بـ is_firewall_gateway مضبوطاً (إجراء Admin+). مفتاح ترحيل عادي، حتى الصالح، يحصل على 403. اسكُك مفتاح بوابة مخصّصاً لوقت تشغيل وكيلك.
لا. مسارات events وevents/aggregate وtrace هي Developer+ لأن السجلات تحمل أصل وسائط استدعاء الأداة. يستطيع المشاهدون قراءة الإعدادات، والسياسات، والإعدادات المسبقة، والأدوات المكتشفة، والمحاكاة، وتغذية الشذوذ.
أيّهما. يحلّها إنسان في وحدة التحكم عبر PATCH /api/workspace/firewall/approvals/:id (Developer+)، أو ينشر نظامك الخاص قراراً مُوقَّعاً بـ HMAC إلى POST /api/v1/firewall/approvals/:id/callback. يستطلع الوكيل GET /api/v1/firewall/approvals/:id بغض النظر عن أي مسار حلّها.
لا. حكم sanitize ينقّح وسائط استدعاء الأداة فقط — لا المحتوى الذي تعيده أداة أبداً. على سطح inbound، حيث لا توجد بعد وسائط وقت الاستدعاء، يتصاعد sanitize إلى حجب. انظر قواعد جدار الحماية.
لكيفية تركيب هذه التحكّمات مع حواجز الحماية وبقية البوابة، انظر تأمين وكلاء الذكاء الاصطناعي و حواجز الحماية مقابل جدار الحماية.