____         ____                       ____  _
    / __ \  ___  / __/___   ___   ___  ___  / ___|| | __ _ __      __
   / / / / / _ \/ /_// _ \ / _ \ / __|/ _ \| |    | |/ _` |\ \ /\ / /
  / /_/ / /  __/ __//  __/| | | |\__ \  __/| |___ | | (_| | \ V  V /
 /_____/  \___/_/   \___/ |_| |_||___/\___| \____||_|\__,_|  \_/\_/

يجمع DefenseClaw بين سطر أوامر مشغل Python، وسايدكار بوابة Go، وإضافة OpenClaw TypeScript. ويعملون معًا لفرض قاعدة تشغيل بسيطة: يتم فحص قدرات الوكيل غير الموثوقة وحوكمتها وتسجيلها ومنعها عندما تقول السياسة إنها غير آمنة.

أبرز الميزات

• التحكم في القبول - افحص المهارات، خوادم MCP، الإضافات، والكود قبل تشغيلها.
• الحواجز الوقائية في وقت التشغيل - افحص الاستفسارات، الإنجازات، واستدعاءات الأدوات مع قواعد regex، السياسة، قاضي LLM اختياري، وفحص Cisco AI Defense.
• CodeGuard - فحوصات ثابتة مدمجة للأسرار، التنفيذ الخطير، إلغاء التسلسل غير الآمن، التشفير الضعيف، أنماط الحقن، والوصول الخطير للملفات.
• دعم صندوق OpenShell الرملي - إعداد صندوق رملي لنظام Linux مع ضوابط الشبكة، نظام الملفات، استدعاءات النظام، والسياسات.
• السجلات - استيعاب كتالوجات المهارات / MCP الخارجية (YAML HTTPS مؤسسي، smithery.ai، skills.sh، git، ClawHub) مع حراس SSRF، أحكام مدفوعة بالماسح، وترقية تلقائية إلى سياسة الأصول. انظر docs/REGISTRIES.md.
• التدقيق والمراقبة - رسم بياني config-v8 واحد لجمع الدلاء، سجل SQLite إلزامي، تنقيح مركزي، ووجهات JSONL، OTLP، Prometheus، Splunk HEC، Galileo، HTTP، وحدة التحكم، و Grafana/Splunk المحلية مستقلة.
• تجربة المستخدم للمشغل - CLI و TUI للإعداد، فحوصات الصحة، التنبيهات، قوائم الحظر/السماح، نتائج الماسح، وسير عمل السياسات.

النطاق والقيود

DefenseClaw هو طبقة إنفاذ وأدلة لنشر الذكاء الاصطناعي العام بالوكلاء. يحسن السلامة من خلال الجمع بين نتائج الماسح، الفحص في وقت التشغيل، قرارات السياسة، ضوابط الصندوق الرملي، ومسارات التدقيق، لكنه لا يثبت أن الوكيل أو المهارة أو الإضافة أو التفاعل النموذجي خالٍ من المخاطر.

يجب دمج DefenseClaw في عمليات النشر عالية المخاطر مع مراجعة بشرية، بيانات اعتماد ذات صلاحية دنيا، صناديق رملية، بوابات CI، ومراقبة الإنتاج. في وضع المراقبة، يتم تسجيل النتائج دون منع. في وضع العمل، يمكن لنتائج HIGH و CRITICAL المكونة منع الاستفسارات، استدعاءات الأدوات، أو قبول المكونات.

التوثيق

توثيق المشروع Markdown مركزي تحت docs/. تبقى ملفات README المحلية للحزم بجانب الحزم أو الأمثلة التي تحتاج سياقًا محليًا.

التثبيت

المتطلبات الأساسية

البناء من المصدر (للمطورين فقط)

اختر الأمر حسب الهدف:

الأهداف المصدرية و `scripts/install-dev.sh` هي أدوات تطويرية، وليست مسار ترقية. أهداف التثبيت المباشر ترفض الكتابة فوق تثبيت مُدار بإصدار أو تثبيت مملوك لنسخة عمل أخرى. `make all` هو سير العمل الصريح لإعادة التثبيت على جهاز المطور: عندما يشير CLI المُثبت بالضبط إلى نسخة العمل الحالية، قد يستعيد حالة المصدر الخالية من العلامات أو من الإصدار السابق، ويسجل علامة ملكية صارمة بعد إعادة البناء. يمكن لهذا تشغيل الترحيلات الحالية لنسخة العمل ضد حالة المطور، ويجب عدم استخدامه كترقية إصدار. يجب على التثبيتات المُدارة بالإصدار استخدام المُحلِّل `scripts/upgrade.sh` أو `scripts/upgrade.ps1` المملوك للإصدار. `make install` و `make dev-install` و `scripts/install-dev.sh` هي أدوات سباكة صارمة منخفضة المستوى لبيئة تطوير جديدة أو معزولة؛ فهي ليست الأمر العادي للتطوير المتكرر.

### التثبيت باستخدام سكريبت الإصدار```bash
VERSION=0.8.6
INSTALL_URL="https://raw.githubusercontent.com/cisco-ai-defense/defenseclaw/${VERSION}/scripts/install.sh"
curl -LsSf "$INSTALL_URL" | VERSION="$VERSION" bash
defenseclaw init --enable-guardrail

للحصول على خطوات خاصة بالمنصة، انظر docs/INSTALL.md.

على Windows x64 الأصلي، استخدم مسار Setup EXE الأصلي وموصل hook-only في دليل Native Windows guide. WSL غير مدعوم. Codex CLI وClaude Code هما الموصلان المعتمدان الوحيدان لنظام Windows.

بداية سريعة```bash

Check the local install and dependencies

defenseclaw doctor

Initialize config, scanner defaults, and guardrail plumbing

defenseclaw init --enable-guardrail

Scan installed agent capabilities

defenseclaw skill scan all defenseclaw mcp list defenseclaw plugin scan extensions/defenseclaw

Start the Go gateway sidecar

defenseclaw-gateway start

Open the operator dashboard

defenseclaw tui

تشغيل الحاجز في وضع المراقبة أثناء الضبط:```bash
defenseclaw setup guardrail --mode observe --restart

التبديل إلى وضع الإجراء عندما تكون السياسة جاهزة للحظر:```bash defenseclaw setup guardrail --mode action --restart

راجع [docs/QUICKSTART.md](https://github.com/cisco-ai-defense/defenseclaw/blob/HEAD/docs/QUICKSTART.md) للاطلاع على الشرح الكامل.

---

## الهندسة المعمارية

| المكون | بيئة التشغيل | الدور |
|--------|------------|-------|
| واجهة سطر أوامر Python | Python | أوامر المشغل، تنسيق الماسح، إعداد التهيئة، الحزم المحلية |
| سايدكار البوابة | Go | واجهة برمجة تطبيقات REST، جسر WebSocket، محرك السياسات، وكيل الحواجز الحماية، مخزن التدقيق، القياس عن بعد |
| إضافة OpenClaw | TypeScript | اعتراض الجلب، خطافات فحص استدعاء الأدوات، أوامر الشرطة المائلة، تكامل السايدكار |
| السياسات | YAML/Rego | قرارات القبول، إجراءات الحواجز الحماية، سلوك الحماية/جدار الحماية، ملفات تعريف الماسح |
| التوثيق | Markdown/JSON | توثيق مركزي، ملفات README محلية للحزم، وتهيئة DeepWiki |

تعرض البوابة واجهات برمجة تطبيقات REST محلية لواجهة سطر الأوامر والإضافة، وتتصل بـ OpenClaw عبر WebSocket، وتفحص حركة مرور LLM عبر وكيل محلي، وتسجل القرارات في مخزن تدقيق دائم.```text
Agent runtime -> OpenClaw plugin -> DefenseClaw gateway -> policy + scanners + audit
                                    |
                                    +-> guardrail proxy -> LLM provider
                                    +-> OTLP / Splunk / webhooks / JSONL

للاطلاع على الرسوم البيانية والتدفقات التفصيلية، اقرأ docs/ARCHITECTURE.md.

المسح والحواجز الوقائية

تغلف DefenseClaw ماسحات Cisco AI Defense والسياسات المحلية في تدفق قبول واحد:

توجد سياسات الماسح في policies/scanners/. توجد حزم قواعد الحواجز الوقائية في policies/guardrail/.

قابلية المراقبة

تسجل DefenseClaw أدلة التنفيذ والتشغيل عبر عدة قنوات:

يحافظ Config v8 على المصدر موجزًا مع تجميع الإغفالات في خطة فعالة كاملة:```yaml config_version: 8 observability: {}

يقوم هذا الإعداد الافتراضي بجمع كل سجل وتتبع ومقياس مسجل، ويحتفظ بكل سجل تم جمعه دون تنقيح في قاعدة SQLite المحلية الإلزامية. لا يحدث أي تصدير عن بُعد حتى تتم إضافة وجهة. تتلقى الوجهة الممكّنة التي لا تحتوي على `send` أو `routes` كل مجموعة وكل إشارة يدعمها نوعها، دون تنقيح: يتلقى OTLP العام السجلات/التتبعات/المقاييس، ويتلقى Splunk HEC السجلات، ويتلقى Prometheus المقاييس، ويتلقى إعداد Galileo المسبق التتبعات. تتلقى الوجهات المتعددة نسخًا مستقلة.

راجع السياسة الموسعة والأجزاء غير المنقحة باستخدام:```bash
defenseclaw config show --effective --section observability
defenseclaw observability plan

استخدم ملفات تعريف التنقيح المركزية none، sensitive، content، strict، أو المخصصة المدركة للحقول لكل bucket أو وجهة. يمكن أن تتضمن الإعدادات الافتراضية كاملة الدقة المطالبات، والمخرجات، ووسيطات/نتائج الأدوات، والأدلة، والمسارات، والمعرفات، لذا قم بتكوين ملف تعريف تنقيح قبل التصدير عبر حدود الثقة التي يجب ألا تتلقى ذلك المحتوى.

قم بتحرير سياسة bucket والتنقيح في الملف المصدر، وتحقق من صحتها قبل أن يراها gateway، وافحص النتيجة المجمعة بدلاً من نسخ المرجع المُنشأ بالكامل:```bash umask 077 cp "$HOME/.defenseclaw/config.yaml"
"$HOME/.defenseclaw/config.yaml.before-observability-edit" ${EDITOR:-vi} "$HOME/.defenseclaw/config.yaml"

defenseclaw config validate &&
defenseclaw config show --effective --section observability &&
defenseclaw observability plan &&
defenseclaw-gateway restart &&
defenseclaw doctor

لا تقم بإعادة التشغيل بعد فشل التحقق. استعادة النسخة الاحتياطية الخاصة، قم بتصحيح المصدر، وتحقق مرة أخرى. كما ينطبق ملف تعريف التنقيح العام أو الخاص بالـ bucket على الإسقاط المحلي لـ SQLite الناتج. للحفاظ على تاريخ محلي كامل الدقة أثناء تنقيح حد الثقة عن بعد فقط، اترك ملف تعريف العام/الـ bucket عند `none` وقم بتعيين `send.redaction_profile` أو ملف تعريف مسار على ذلك الوجهة البعيدة.

ابدأ المراقبة المحلية باستخدام:```bash
defenseclaw setup local-observability up
defenseclaw-gateway start
defenseclaw setup local-observability status

فراغ لوحة القيادة ليس حالة واحدة: 0 يعني أن الإشارة المُقاسة لم تحتوي على أي أحداث متطابقة، No data يعني عدم وجود سلسلة/سجل/تتبع مطابق للنطاق والمرشحات المحددة، و Not reported يعني أن الموصّل/المزوّد لم يقدم قيمة اختيارية مثل الرموز أو التكلفة. اللوحات الشرطية مثل HITL، طرق عرض الفشل فقط، وشلال التتبع قبل تحديد معرف التتبع من المتوقع أن تظهر No data. اختبار الوجهة يتحقق من الاتصال فقط ولا ينشئ حركة مرور عادية للوحة القيادة؛ قم بإنشاء دورة وكيل حقيقية جديدة، استدعاء أداة، فحص، أو موافقة للتحقق من اللوحات المقابلة.

الرسم البياني للعقد لـ Agent360 هو DAG مدعوم بـ Loki: إنشاء الجلسة هو نقطة ارتساء منفصلة، عقدة Prompt inputs لكل جذر تحسب حقائق model.request المميزة ذات العمق صفر في النطاق، والتسلسل من الأب إلى الابن يغذي ملخصات لكل وكيل من نموذج، أداة، موافقة، تحديث، نتيجة دورة، وملخصات نهائية. تتم إزالة تكرار Prompt inputs حسب الدورة، طلب النموذج، الطلب، العملية، ثم معرف الحدوث؛ الاحتفاظ بالسجلات الأولية واللاحقة في العروض المرتبة/الخام. يمكن استرداد نقاط الارتساء للجلسة والإنتاج من الـ 24 ساعة السابقة بحيث تظل النوافذ الحدودية قابلة للعرض؛ يتم الاحتفاظ بنقطة إنتاج مستردة فقط عندما يكون لذلك الطفل نشاط مؤهل للرسم البياني في النطاق المحدد. يتم تجميع استدعاءات النموذج المتكررة حسب الوكيل المالك، المزود، والنموذج. يتم تجميع استدعاءات الأدوات المتكررة حسب الوكيل المالك إلى Bash، MCP، Skills، Collaboration، File edits، Web/browser، Visual، أو Task control؛ الأداة غير المعروفة تحتفظ باسمها المُبلغ عنه. يتم استبعاد طلبات collaboration.send_message الدقيقة من عائلة Collaboration العامة بحيث تظهر فقط كمجموعات رسائل؛ تبقى أدوات التعاون الأخرى في تلك العائلة. يتم تضمين سجلات الطلبات حتى عندما لا يصل مقابل نهائي. مجموعهم المُجمّع هو عدد الطلبات، وليس ادعاءً بأن كل طلب لا يزال معلقًا؛ تظل الحالة النهائية متاحة في السجلات الخام المرتبطة. العمق 0 هو الجذر وقد يتم الإبلاغ عن الأطفال المتكررين حتى العمق 64؛ تحديد التفاصيل بالنقر يحدد ما إذا كانت كل حافة نسب قد تم الإبلاغ عنها بواسطة الموصّل أو استنتاجها بواسطة DefenseClaw. يكشف النقر على العقدة عن الأعداد الدقيقة وهوية الوكيل/الجذر/الأب المستقرة، مع روابط مُرشحة لأحداث OTEL الخام وراء كل مجموعة. تبقى حقول الجلسة الاختيارية الحالية/الجذر/الأب على الأسطح دورة الحياة، الجلسة، المرتبة، والخام؛ ليست مفاتيح تجميع عقدة الوكيل، لذا لا يمكن لبيانات الجلسة المفقودة أو المتأخرة تقسيم مجموع وكيل واحد.

لوحات القيادة لا تقوم بإخفاء أو طمس أو إخفاء الحقول مرة أخرى. يطبق DefenseClaw إخفاء مركزي v8 قبل التصدير الكنسي لـ OTEL؛ يعرض Grafana أو يربط كل حقل موجود فعليًا في ذلك الإسقاط، بما في ذلك المحتوى عندما قام المنتج بتصديره. لا يمكن استرداد حقل تمت إزالته أو تحويله قبل التصدير بواسطة المجموعة المحلية. تأتي حواف التحديث فقط من سجلات أداة collaboration.send_message الفعلية. لكل مرسل، تنهار أهداف /root و /root/* في عقدة واحدة Messages to root يتم حل معرف الوكيل الهدف إلى الجذر المُصدّر. تبقى مسارات واستدعاءات المهام الجذرية الدقيقة في عمليات التنقل التفصيلية المرتبة/الخام. تبقى الأهداف غير الجذرية مجمعة بشكل صريح حسب مسار المهمة الدقيق ولا يتم اختراعها كوصلات معرف وكيل غير شفافة عندما لا يبلغ الموصّل عن هذا التعيين. لا يتم إعادة تسمية أحداث التوافق العامة أبدًا كتحديثات.

الوجهات الاختيارية تمتلك طوابير محدودة مستقلة. الافتراضيات هي 2,048 سجل و 64 MiB لكل طابور؛ الدُفعات الافتراضية للدفع هي 512 سجل، 8 MiB، و 5 ثوانٍ (ثانية واحدة لتأخير Galileo المحدد مسبقًا المحذوف). يؤدي تجاوز سعة الطابور إلى إسقاط أحدث محاولة إدراج دون إخلاء عمل FIFO الأقدم أو التأثير على SQLite الإلزامي والوجهات الشقيقة. الحقول الدقيقة، الحدود، واختلافات المحولات موجودة في docs/OBSERVABILITY.md.

أضف Galileo Cloud أو Galileo المُستضاف ذاتيًا دون استبدال المسار المحلي:```bash export GALILEO_API_KEY='...' defenseclaw setup galileo --project defenseclaw --logstream production defenseclaw setup galileo test

انظر [docs/OBSERVABILITY.md](https://github.com/cisco-ai-defense/defenseclaw/blob/HEAD/docs/OBSERVABILITY.md)، [دليل Galileo](https://github.com/cisco-ai-defense/defenseclaw/blob/HEAD/docs-site/content/docs/observability/galileo.mdx)، و[خريطة ملكية المخطط](https://github.com/cisco-ai-defense/defenseclaw/blob/HEAD/schemas/README.md). الإعداد الخاص بـ Splunk موجود في [docs/SPLUNK_APP.md](https://github.com/cisco-ai-defense/defenseclaw/blob/HEAD/docs/SPLUNK_APP.md).

كل تثبيت POSIX موجود مدعوم، بما في ذلك التثبيت الموجود بالفعل على `0.8.4`، يعبر القطع الصارم `0.8.5` مع أصل الإصدار الهدف المصادق عليه `defenseclaw-upgrade.sh` في الوضع الأحدث، دون تجاوز الإصدار. لا يمكن لمحلل `0.8.4` المدمج غير القابل للتغيير قبول بيان الهدف الصادق الذي تكون مصفوفة جسر Windows فيه فارغة. لا تنفذ أي تلميح شبكة خام قديم مطبوع بواسطة واجهة سطر أوامر مدمجة مجمدة. يقوم المحلل المملوك للإصدار بتنفيذ `source → 0.8.4 bridge → fresh 0.8.4 controller → 0.8.5 hard cut` كمعاملة واحدة. يقوم الترحيل بعمل نسخ احتياطي وتحويل التكوين بشكل ذري، ويحافظ على سلوك التوجيه/التحرير الأضيق وتوافق Agent360 الجذر/الفرعي، ويقوم بتحديث لوحات المعلومات المحلية المملوكة دون إعادة تعيين الأحجام، ولا يتطلب أبدًا أمر تطبيق منفصل. انظر [مرجع CLI — ترقية](https://github.com/cisco-ai-defense/defenseclaw/blob/HEAD/docs/CLI.md#upgrade) للحصول على تمهيد المحلل المصادق عليه.

بالنسبة لـ Splunk Observability Cloud، استخدم حزمة لوحات المعلومات في [bundles/splunk_o11y_dashboards/README.md](https://github.com/cisco-ai-defense/defenseclaw/blob/HEAD/bundles/splunk_o11y_dashboards/README.md):```bash
defenseclaw setup splunk dashboards apply \
  --api-url <api-endpoint> \
  --o11y-api-token <api-access-token> \
  --with-detectors \
  --enable-detectors \
  --yes

التطوير```bash

Build all components

make build

Run primary test suites

make test

Run lint checks

make lint

توجد إرشادات مركزة للاختبار والتطوير في [docs/TESTING.md](https://github.com/cisco-ai-defense/defenseclaw/blob/HEAD/docs/TESTING.md) و [docs/CONTRIBUTING.md](https://github.com/cisco-ai-defense/defenseclaw/blob/HEAD/docs/CONTRIBUTING.md).

---

## المساهمة

المساهمات مرحب بها. ابدأ بـ [CONTRIBUTING.md](https://github.com/cisco-ai-defense/defenseclaw/blob/HEAD/CONTRIBUTING.md) و [docs/CONTRIBUTING.md](https://github.com/cisco-ai-defense/defenseclaw/blob/HEAD/docs/CONTRIBUTING.md) والوثائق المركزة للمجال الذي تقوم بتغييره.

## الأمان

يرجى الإبلاغ عن الثغرات الأمنية من خلال العملية الموضحة في [SECURITY.md](https://github.com/cisco-ai-defense/defenseclaw/blob/HEAD/SECURITY.md).

## الترخيص

Apache 2.0 - انظر [LICENSE](https://github.com/cisco-ai-defense/defenseclaw/blob/HEAD/LICENSE).

حقوق النشر 2026 لشركة Cisco Systems, Inc. والشركات التابعة لها.