انتقل إلى المحتوى الرئيسي

دليل المطور لـ AuroraSOC

هذا هو المرجع الأساسي والرسمي للمطورين الخاص بمنصة AuroraSOC. فهو يدمج، يستوعب ويحل محل التوثيقات والمراجع والإرشادات السابقة والخاصة بالمساهمين والمطورين. وقد تم تصحيح جميع وتصويب ومراجعة أي معلومات أو أرقام، وحقائق غير دقيقة كانت واردة في التوثيقات السابقة والإصدارات القديمة بناءً على ما جاء وصدر واعتمده ومحُص في تقرير التدقيق والفحص (audit report).

1. نظرة عامة على البنية الهيكلية (Architecture Overview)​

تُعتبر AuroraSOC منصة لمركز عمليات أمنية (Security Operations Center) مفتوحة المصدر، وتعمل وتُدار وتُعزز وتُขับ بقوة وتقنيات الذكاء الاصطناعي، حيث توظف وتدير وتنشر 14 وكيلاً متخصصاً ومستقلاً من وكلاء الذكاء الاصطناعي (بالإضافة إلى وكيل منسق واحد (orchestrator)) لأتمتة، جدولة ومساندة وتكليف وتوجيه عمليات الفرز الأمني، التحقيق المعمق، واطلاق وضبط وتوجيه الاستجابة. يتم تشغيل وتعزيز وتطوير عقول كل وكيل باستخدام ومقدرات نموذج لغوي ضخم ومُحسن (Fine-tuned IBM Granite LLM)، ويتم ويوصل وتوثيقه وربطه بأدوات وبرمجيات وبروتوكولات متخصصة حسب مجاله الدقيق، وخبراته ومساقه عبر ومقاس بروتوكول وبرمجية سياق ومحتوى النموذج (Model Context Protocol - MCP).

الغرض من المنصة (Platform Purpose)​

تحل منصة AuroraSOC محل وتُغني عن عمليات الفرز، التقييم، الترحيل والتتبع ومقايسات التقويم والتوجيه اليدوية لمركز العمليات الأمنية (SOC) من خلال التوجه نحو توظيف واستخدام وتكليف وممارسه التحقيق المستقل والمُوجه والمُحلل والقائم على كوكبه وعصائر وحزم وعقود واسعة ووفرة وتضامن وكلاء وأفراد متعددين:

  1. وصول، تدفق وتوارد الأحداث من أنظمة إدارة الأحداث والمعلومات الأمنية (SIEMs) الخارجية، أجهزة وبرمجيات ونظم إنترنت الأشياء والأنظمة السيبرانية المادية (IoT/CPS)، أو من خلال الاستيعاب والاستجلاب المباشر والجلب والمكاشفة عبر واجهة تطبيقات مأتمته (API).
  2. محرك الصميم والجوهر المركزي المبني بلغة (Rust Core Engine) يقوم بتطويع، توحيد وتسوية وقولبة الأحداث وتحويلها إلى بنية ومخطط ومسار وقالب موحد وتأكيد ومصادقة وإثبات شهادات واعتماد التجهيزات.
  3. الوكيل المنسق (Orchestrator agent) يفرز ويحلل ويواجه الإنذارات ويقوم بتفويضها وتوليتها وتوجيهها وصرفها وتقسيمها وإرسال وتكليفها للوكلاء المتخصصين عبر بروتوكول التخاطب بين الوكلاء A2A (Agent-to-Agent).
  4. الوكلاء المتخصصون (Specialist agents) يجرون ويقومون ويشرعون بالتحقيقات المعمقة باستخدام واعتماد أدوات MCP، ويسترجعون ويسألون ويستخلصون الأحداث والسوابق ويختزنون ويتفكرون ويعودون بذاكرتهم وتاريخهم للبحث وسبر أغوار ودلائل القضايا المماثلة والشبيهة والسابقة المحفوظة والمستنتجه من الذاكرة العرضية.
  5. النتائج، الخلاصات والبراهين يتم تجميعها، توليفها وتركيبها وتأليفها وتكثيفها وصياغتها وتخزينها، ثم تُعرض وتُنشر وتُبرز وتُقدم وتترجم للمستفيدين والمختصين والمحللين من خلال لوحة البيانات والقيادة المبنيه بتقنيات (Next.js).

هكيلة بيئة واتِصال شبكة ودارات دوكر (Docker Network Topology)​

تعمل منصة AuroraSOC عبر أربع شبكات Docker معزولة:

┌─────────────────────────────────────────────────────────────┐
│                    agent-mesh (A2A)                          │
│  Orchestrator ← → 14 Specialists ← → 15 MCP Tool Servers  │
│  Ollama (LLM) ← → OTel Collector ← → Vault                │
└────────────┬─────────────────────────────────────┬──────────┘
             │                                     │
┌────────────▼──────────────────┐   ┌──────────────▼──────────┐
│        data-plane             │   │       frontend          │
│  PostgreSQL │ Redis │ Qdrant  │   │  Next.js :3000          │
│  NATS │ Prometheus │ Grafana  │   │  FastAPI :8000          │
│  OTel Collector               │   │  Grafana :3001          │
└────────────┬──────────────────┘   └─────────────────────────┘
             │
┌────────────▼──────────────────┐
│        iot-plane              │
│  Mosquitto (MQTT mTLS :8883) │
│  Rust Core ← → CPS Agent     │
└───────────────────────────────┘

بنية ومسارات وتوزيع الوكلاء (Agent Topology)​

                         ┌──────────────────┐
                         │   Orchestrator   │
                         │     :9000        │
                         └────────┬─────────┘
                                  │ A2A HandoffTool
           ┌──────────────────────┼──────────────────────┐
           │         │         │         │         │     │
     ┌─────▼───┐ ┌───▼───┐ ┌──▼──┐ ┌───▼───┐ ┌───▼──┐  │
     │Security │ │Threat │ │Mal- │ │Incid- │ │Net-  │ ...
     │Analyst  │ │Hunter │ │ware │ │ent    │ │work  │
     │:9001    │ │:9002  │ │:9003│ │Resp.  │ │Sec.  │
     └─────────┘ └───────┘ └─────┘ │:9004  │ │:9005 │
                                   └───────┘ └──────┘
     + CPS :9008  ThreatIntel :9009  UEBA :9011
     + Forensic :9012  WebSec :9006  CloudSec :9007
     + Endpoint :9010  Compliance :9013  VulnMgr :9014
      + ReportGen :9015  NetworkAnalyzer :9016

2. مجموعة التكنولوجيا والتقنيات (Technology Stack)​

اللغات وبيئات التشغيل (Languages & Runtimes)​

اللغة (Language)الإصدار (Version)الاستخدام (Usage)
بايثون (Python)CPython 3.12+إطار عمل الوكلاء، واجهة برمجة التطبيقات API، تدريب نماذج تعلم الآلة، الأدوات
رست (Rust)1.83 (edition 2021)محرك تسوية وتقنين وتوحيد الأحداث عالي الأداء
تايب سكريبت (TypeScript)5.7 (strict)الواجهة الأمامية للوحة البيانات والقيادة لمنافذ ومزيايا المدار لـ Next.js
أدا سبارك (Ada SPARK)GNAT/GNATproveبرامج الأجهزة الثابتة (firmware) الحساسة جداً للسلامة والأمن التابعة لوحدات ونظم STM32
سي (C)C17/Zephyrالبرامج الثابتة (firmware) لبوابة إنترنت الأشياء لـ ESP32-S3
رست للأنظمة المدمجة (Rust embedded)nightly + Embassyالبرامج الثابتة الحارسه (sentinel firmware) لمتحكم ومعالج ووحدات ومآخذ ومعايير وحياد شرائح وحلق ومساق nRF52840

أطر العمل والمكتبات (Frameworks & Libraries)​

المكون (Component)إطار العمل (Framework)الإصدار (Version)الغرض (Purpose)
نواة ومركز الوكيل (Agent Core)IBM BeeAI Framework≥0.1.0 (a2a,mcp)تنسيق وتوجيه نظام الوكلاء المتعدد، بروتوكول A2A، أدوات ومقايس MCP
بوابة واجهة التطبيقات (API Gateway)FastAPI0.115+نقاط نهاية للـ REST + اتصال ومرامي ومنافذ وربط مُرسال وأواصر ومحاكاة مأخذ الـ WebSocket
تخطيط وتوصيف وارتباط قاعدة البيانات (ORM)SQLAlchemy2.0+ (async)أداة تخطيط قاعدة البيانات لـ PostgreSQL غير المتزامنه
لوحة القيادة التفاعلية (Dashboard)Next.js15.1.0إطار تصيير وبناء واجهات ريآكت (React SSR/SSG)
مكونات الواجهة (UI Components)Radix UI + shadcn/uiv1.1.xأساسيات وحزم وعناصر وقطع وقوالب مسطحه وسهلة التطويع (headless primitives) يمكن الوصول إليها بحريّة وثقة
الرسوم البيانية (Charts)Recharts2.15.0تصورات ومرئيات وعروض رسومية للوحة القيادة
خادم ومضيف HTTP الخاص ونواة لغة مبني بـ (Rust)Axum0.8توجيه طلبات استعلام مسار HTTP (لا يوجد دعم وواجهة لـ gRPC — راجع المشكلات والطوارئ المعروفة)
الضبط الدقيق والتدريب العالي (Fine-tuning)Unslothأحدث إصدارمضاعفة وتقليل مقاس وسرعه ونسب كفاءة وسرعة واستعراض بضعفي (2×) السرعة وسلاسه ومخازن واستحقاق ومكاسب وتقنين واستقصاء وتقطير تقنيه ومخرج وقدره LoRA بنسبة ورافد توفير وتخفيض وسحب لحجم استخدام 70% من ذاكرة الوصول العشوائي للفيديو (VRAM)
التقديم والاستضافة (Serving)Ollama / vLLMأحدث إصدارتشغيل واستدلال ونشر وتقييم وموجه ومستضيف للنموذج اللغوي الكبير (LLM) محلياً
التوثيق والمراجع والصياغه (Documentation)Docusaurus3.9.2موقع ومحفل ومساحات ومورد لتخزين وعرض وتوليد صفحات التوثيقات الثابتة

مخازن وقواعد البيانات​

مسلك التخزينالإصدارالغرض
PostgreSQL16بيانات القضايا، الإنذارات، أجهزة CPS، كراسات التشغيل (playbooks)، سجلات التدقيق
Redis7ناقل الأحداث (Event Streams)، ذاكرة التخزين المؤقت، الذاكرة العاملة (working memory)، تحديد معدل الطلبات
Qdrantأحدث إصدارقاعدة بيانات المتجهات للذاكرة العرضية (episodic memory) + تضمينات استخبارات التهديدات
NATS JetStream2.10+نظام مراسلات دائم للاتحاد عبر المواقع (cross-site federation)

3. بنية المستودع (Repository Structure)​

بعد التنظيف والتوحيد (المرحلة 2):

AuroraSOC/
├── aurorasoc/              # الجزء الخلفي (الخادم) المبني ومطور ببايثون — الوكلاء، الواجهة API، الأدوات، الذاكرة، الأحداث
│   ├── agents/             # 15 تعريفاً وبرامج ومقر ومساحات استقطاب وعمل لوكيل متخصص + المنسق (orchestrator)
│   ├── api/                # بوابة FastAPI المرجعية (مسارات REST + WebSocket)
│   ├── config/             # إعدادات ونظم مسار وبيئات وبرمجيات Pydantic (تُدار وتُستثمر حقول واعدادات وبيئة بشكل كلي وحصري عبر متغيرات البيئة)
│   ├── core/               # المصادقه والموثوقيه، التوزيع والارسال، أداة قطع ومحاكاة ومرآب قاطع وايقاف الدائرة ومهيمن الأعطال (circuit breaker)
│   ├── engine/             # محرك مسار تنفيذ وممارسه، تولي وإدلال وحصاد، تدبير وحوكم وتجسيد، إدارة كراسات ودساتير نظم الاستجابه والتشغيل المُعده (Playbook execution engine)
│   ├── events/             # مستهلكون ومقرات لتلقي واعتناق رسائل ومحاور ومقررات Redis Streams، NATS JetStream، MQTT
│   ├── memory/             # نظام الذاكرة ثلاثي الطبقات والأبعاد والمساق والشرائح (عاملة/عرضية/تهديدات)
│   ├── models/             # نماذج ومقر ومضابط وسنخ ومجسات، جداول وقوالب وحمائل وكراسي وقواعد وبرمجه وتأصيل وتوثيق، شواهد وسطور ربط وعنوان وتخطيط بيانات ومشارب، كبسولات واروقه ونواتج SQLAlchemy ORM
│   ├── tools/              # 15 خادم متخصص لتلقين ودعم وبث مساق خوادم وأدوات للـ MCP (المقسمه على 15 مجال وتخصص مستقل)
│   └── workflows/          # تعريفات مسارات العمل واجراءاته
├── rust_core/              # النواة الأساسية والمحرك القوي المبني كإمتداد ومنتظم وقاصد ومساق ومجند ونسج بالـ Rust الموحد للأحداث + وحدة ومفتش، مدقق وجابي وتوثيق والتحقق من مصادقه الاعتماد والتأصيل
├── dashboard/              # لوحة القيادة، المنصه ومقاصد الاستعلام ولوحات ومحطات الـ Next.js 15 (وتشمل 13 صفحة مرئيه، 47 دالة ومقاس ورسم وبيان وتشكيل ومسارات اتصالات، مخرجات وبوابات وتوليد API)
├── docs/                   # موقع ونموذج ومرتقى وحوائط وملفات وثاق التوثيق وسيرة ومُقالات المخطوطة المبنية بدوكوسورس (Docusaurus)
├── firmware/               # مشارب وبرامج الأجهزة الثابتة والموائمه (3 مكدسات للمنصات العتاديه)
│   ├── stm32/              # لغة ومسار وبيانات Ada SPARK — بيئة ومكان وحكم للتحكم المحكم في وحدات الإحالة الحسّاسة والمبرمجه للسلامه والتوثق
│   ├── nrf52840/           # نظم ومسار Rust Embassy — واجهة ومقصد، مناوح وترتيب لـ حارس نقط منافذ فخاخ ومنافذ USB وحامية، مكاشفات ومجند وحرس ومغارة، واجهة واستدرار ونقاط الاختراق USB honeypot sentinel
│   └── esp32s3/            # نظام تشغيل وتكليف ومزاملة وبرمجيات Zephyr RTOS — بوابة ومِراس ودقر وبرج ومعين ووحدة بلوتوث منخفض ومنصة وبطاقه وخادم واجهة وحائط BLE gateway + واجهة وحاضنه استدلال وبروتوكول، مستكشف ومعمق لبرامج TFLite
├── infrastructure/         # إعدادات البنية التحتية الرئيسية والتوثيقية الدقيقه (Mosquitto، NATS، Vault، وغيرها)
├── training/               # خط وحزم سير تدقيق، توليف وتنجيز الضبط الدقيق وتعلم الآلة (ML fine-tuning)
│   ├── configs/            # إعدادات ووصف، لوائح ونواتج تدريب YAML
│   ├── data/               # نصوص متسلسله لتحضير وتنقيح، مقايسه وتجهيز، صف وصناعة وإعداد ونفث وبناء وإقامة ونداء مجموعه وبينات وبيانه وتوثيقات البيانات
│   ├── notebooks/          # كراسات، مآخذ ودلائل وبيئات ودفاتر جوبيتر (Jupyter notebooks)
│   │   └── scratch/        # دفاتر ودلائل تجريبية وتأشيرات واستحصال للمكاتب والكراسات غير منسقه وعشوائية (نُقلت من المجلد العشوائي المتنوع المؤقت /Temporary Miscellaneous/)
│   └── scripts/            # نقاط وقوائم وتشكيل وعمود ومقاصد واللإرساء ومداخل وأسس وتسيير ولوج وأمر وأعمال ونص التدريب والمناورة
├── tests/                  # 40 اختبار وتجريب وتشخيص وحدة ومقاس، معايير وتأصيل وإيراد وتأسيس وقياس واستكمال ومعيار وبيئه وأسس للقياس وتحصين وبرج ومقر وبناء وثغور واسناد وحياد وتوثق وفحص وحدة دقيق وقانون وحدة لأساليب وتجارب ومقارنات مرافقه ومتخمه بالمبررات (باي تيست pytest)
├── alembic/                # بنية ومشارب لترحيلات وقوالب وهجرة واستحداث ومقر لقاعدة البيانات
├── scripts/                # نصوص أداة ووظائف وتيسير ومكرمات ورصد ونقاط وأعمال ومهام خدمية وتشغيليه
├── .github/                # مسارات وصلاحيات وموارد وأسرار وحلقات تدفق وعمل، أعمال وتسلسل وخط وتواصل وعون، واصدار التكامل/النشر المستمر (CI/CD workflows)
├── docker-compose.yml      # مكدس الإنتاج الكامل والمتكامل والشمولي للبيئة التشغيلية
├── docker-compose.dev.yml  # بنية تحتية خفيفة الوزن للمطور
├── .env.example            # متغيرات وبيئه ومدونات واسرار ومأخذ وقاموس وسجل للبيئة المطلوبة (انسخ، عَدل ووجه وضع النواتج وخصص وبدل وحدد وارسل وميّل واسنده واللصق إلى ملف منفرد واسمه وصيغته ومأخذه وخطه وكينونته .env)
├── pyproject.toml          # ملف تكوين، ضبط وتنظيم وتسلسل وبنية مقاسات وإعدادات مشروع بايثون
└── Makefile                # أوامر ومِقاسات ودلائل واستخلاص ونظم ومعادن وأصول التطوير والتشغيل وأمر التطويع والانشاء

4. المتطلبات المسبقة (Prerequisites)​

الأداة (Tool)الإصدار (Version)الغرض (Purpose)
دوكر وتأليف دوكر (Docker + Docker Compose)أحدث إصدارتنسيق وإنشاء الحاويات (Container orchestration)
رست (Rust)1.83+بناء rust_core/
بايثون (Python)3.14 (CPython)إطار عمل الوكلاء وواجهة برمجة التطبيقات
نود جي إس (Node.js)18+بناء لوحة القيادة
أولاما (Ollama)أحدث إصداراستدلال وتشغيل النموذج اللغوي محلياً
فلوت (Vault CLI)1.18+إدارة الأسرار (Secrets management)
أدا (Ada GNAT / GNATprove)أحدث إصدارالبرامج الثابتة لـ STM32 (firmware/stm32/)
ألاير (Alire)أحدث إصدارمدير حزم أدا (Ada)
سلسلة وأدوات (arm-zephyr-eabi toolchain)أحدث إصدارالبرامج الثابتة لـ ESP32-S3 (firmware/esp32s3/)
رست الليلي (Rust nightly + probe-rs)أحدث إصدارالبرامج الثابتة لـ nRF52840 (firmware/nrf52840/)

5. الإعداد المحلي (Local Setup)​

خطوة بخطوة (Step-by-step)​

# 1. استنساخ المستودع وتهيئة البيئة
git clone <repo-url> && cd AuroraSOC
cp .env.example .env
# قم بتحرير ملف .env — واملأ: JWT_SECRET_KEY, API_SERVICE_KEY, VAULT_TOKEN, PG_PASSWORD

# 2. تهيئة Vault (وضع الإنتاج الأساسي، وليس وضع التطوير)
# توليد مفاتيح فك الختم والـ root token:
vault operator init -key-shares=5 -key-threshold=3
# فك الختم باستخدام 3 من أصل 5 مفاتيح:
vault operator unseal <key1>
vault operator unseal <key2>
vault operator unseal <key3>
# تشغيل نص إعدادات الـ PKI:
bash infrastructure/vault/init-vault.sh

# 3. سحب نموذج Ollama
ollama pull granite4:8b

# 4. بدء تشغيل البنية التحتية بترتيب التبعيات
docker compose up -d postgres redis nats qdrant mosquitto vault
# انتظر حتى تنجح وجميع فحص وتأكيدات السلامة، ثم:
docker compose up -d ollama prometheus grafana otel-collector
# ثم ابدأ الوكلاء وواجهة برمجة التطبيقات:
docker compose up -d

# 5. تشغيل ترحيلات Alembic
alembic upgrade head

# 6. تحقق من سلامة وحالة جميع الوكلاء الـ 14
# تحقق من حالة الوكيل عبر واجهة برمجة التطبيقات:
curl http://localhost:8000/api/v1/agents/health
# أو تحقق من مكونات دوكر (docker compose):
docker compose ps | grep agent

ملاحظة: يتم الآن تشغيل NetworkAnalyzer (المنفذ 9016) عبر المسار المشترك generic_server.py، ولم يعد يتطلب ملف server.py مخصصًا.

أنماط الاكتشاف A2A وفحوصات بدء التشغيل​

يقوم AuroraSOC بحل جميع عناوين Agent-to-Agent عبر دوال A2ASettings:

  • A2A_DISCOVERY_MODE=compose يستخدم نمط المضيف agent-<name>
  • A2A_DISCOVERY_MODE=k8s يستخدم نمط المضيف agent-<name>-svc
  • A2A_CLIENT_HOST يتجاوز جميع المضيفين على مستوى عام
  • A2A_<AGENT_NAME>_HOST يتجاوز مضيف وكيل محدد (مثال: A2A_SECURITY_ANALYST_HOST)

عند بدء تشغيل API، يقوم AuroraSOC بفحص كل نقطة نهاية A2A GET /health:

  • الاستجابات السليمة وغير 5xx يتم تسجيلها كاتصال ناجح
  • الخدمات غير المتاحة أو استجابات 5xx يتم تسجيلها كتحذيرات
  • يستمر بدء تشغيل API في وضع degraded (تحذيرات فقط) لدعم نشر جزئي لأسطول الوكلاء

إعداد مزودي MCP الخارجيين​

يمكن لنطاقات MCP في AuroraSOC استدعاء مزودي استخبارات خارجيين عند ضبط بيانات الاعتماد:

  • OSINT: OSINT_SEARCH_API_URL, OSINT_SEARCH_API_KEY, OSINT_SHODAN_API_KEY, OSINT_ABUSEIPDB_API_KEY, OSINT_OTX_API_KEY
  • Malware Intel: MALWARE_INTEL_VT_API_KEY
  • Vulnerability Intel: VULN_INTEL_NVD_API_KEY

إذا لم يتم ضبط هذه المتغيرات، تُعيد الأدوات استجابات منظمة من نوع integration_required/degraded بدلاً من إيقاف مسار الوكلاء بشكل قاسٍ.

6. التشغيل والاختبار (Running & Testing)​

مكدس كامل عبر (Docker Compose)​

docker compose up -d          # ابدأ تشغيل كل شيء
docker compose logs -f api    # تابع سجلات وتحديثات الواجهة API
docker compose ps             # تحقق من حالة الخدمات

وكلاء بايثون الفرديون (Individual Python Agents)​

# تشغيل وكيل مستواه واحد محلياً (خارج Docker):
python -m aurorasoc.agents.orchestrator.server
# أو استخدم وبرمجه الخادم والمزود العام:
AGENT_NAME=SecurityAnalyst AGENT_PORT=9001 python -m aurorasoc.agents.generic_server

جوهر وأساسيات لغة (Rust Core)​

cd rust_core
cargo run                     # بدء وتشغيل نظام مُوحد الأحداث
cargo test                    # تشغيل اختبارات Rust
cargo clippy                  # التمحيص والتدقيق وتتبع وفُحص (Lint)

مسار التدريب (Training Pipeline)​

# تحضير وتجهيز مجموعات البيانات:
python training/scripts/prepare_datasets.py --output-dir training/data
# تشغيل وتنفيذ وإحداث الضبط والبرمجه والتدقيق والمقارنه (fine-tuning):
python training/scripts/finetune_granite.py --config training/configs/granite_soc_finetune.yaml --data-dir training/data
# تصدير وإعداد ورفد ومراجعة وتجميع المخرجات إلى GGUF لـ Ollama:
python training/scripts/serve_model.py ollama --gguf training/checkpoints/granite_soc_gguf/unsloth.Q8_0.gguf --name granite-soc:latest

حزمة الاختبار (Test Suite)​

pytest                        # تشغيل جميع اختبارات الواجهة الخلفية
pytest tests/ -v              # إخراج ومطابقة ورصد لفظي واسهاب ومخرج ومخرجات واسعة تفصيليه (Verbose output)
pytest --tb=short             # تتبع وتقادم واستدعاء وبحث وخطأ مختصر ومقلص وملخص ومقتضب وقصير (Short tracebacks)

تغطية الاختبارات تتحسن: تمت إضافة اختبارات تكاملية لسلوك العامل واختبارات انحدار للإعدادات/التوجيه، لكن اختبارات E2E للوحة وRust الأوسع واختبارات firmware ما زالت فجوات قائمة.

7. مرجع وتوصيف أسطول الوكلاء (Agent Fleet Reference)​

الوكيل (Agent)الدليل (Directory)منفذ A2Aالدور (Role)إعداد الذاكرة المسبق (Memory Preset)الحالة (Status)
المنسق (Orchestrator)agents/orchestrator/9000منسق — يفرز الإنذارات ويفوض ويعمم الشروع للمتخصصينORCHESTRATOR (60 رسالة، عرضية)✅ تم النشر (نسختان)
محلل أمني (SecurityAnalyst)agents/security_analyst/9001تحليل الـ SIEM، إرتباط ونسج الإنذارات، استخراج مؤشرات IOCANALYST (30 رسالة، عرضية)✅ تم النشر (3 نسخ)
صائد التهديدات (ThreatHunter)agents/threat_hunter/9002صيد وسبق التهديدات، مسايرة LOLBins، وجلب انحراف الأساسHUNTER (40 رسالة، عرضية+تهديد)✅ تم النشر (نسختان)
محلل البرمجيات الخبيثة (MalwareAnalyst)agents/malware_analyst/9003مسح YARA، تحليل وفحص الـ sandbox، استخراج IOCANALYST✅ تم النشر
مستجيب الحوادث (IncidentResponder)agents/incident_responder/9004تنفيذ محتوى وخبرات الـ playbook، عزل واسر نقطة وتكوين النهاية، إدارة وصد القضيةRESPONDER (50 رسالة، عرضية)✅ تم النشر
NetworkSecurityagents/network_security/9005تحليل التدفق، اكتشاف أنفاق DNS، حظر IPANALYST✅ تم النشر
WebSecurityagents/web_security/9006أمن تطبيقات الويب، تحليل WAFLIGHTWEIGHT✅ تم النشر
CloudSecurityagents/cloud_security/9007إدارة الوضع السحابي، تحليل سجل التدقيقLIGHTWEIGHT✅ تم النشر
CPSSecurityagents/cps_security/9008مراقبة أجهزة IoT/OT، التحقق من المصادقةANALYST✅ تم النشر
ThreatIntelagents/threat_intel/9009البحث عن IOC، الإثراء، المشاركة عبر المواقعINTEL✅ تم النشر
EndpointSecurityagents/endpoint_security/9010قدرات EDR، مسح نقاط النهايةLIGHTWEIGHT✅ تم النشر
UEBAAnalystagents/ueba_analyst/9011تحليلات سلوك المستخدم، تقييم المخاطرANALYST✅ تم النشر
ForensicAnalystagents/forensic_analyst/9012جمع الأدلة، إعادة بناء الإطار الزمنيANALYST✅ تم النشر
ComplianceAnalystagents/compliance_analyst/9013تدقيق الامتثال، إنشاء التقاريرLIGHTWEIGHT✅ تم النشر
VulnerabilityManageragents/vulnerability_manager/9014مسح الثغرات، تنسيق التحديثاتLIGHTWEIGHT✅ تم النشر
ReportGeneratoragents/report_generator/9015إنشاء التقارير، البحث في السجلاتLIGHTWEIGHT✅ تم النشر
NetworkAnalyzeragents/network_analyzer/9016تحليل الشبكة السلبي (التدفقات، DNS)ANALYST✅ مُنشَر عبر generic_server.py

8. مرجع أدوات MCP (MCP Tools Reference)​

يتم تسجيل جميع الأدوات عبر خوادم MCP معزولة النطاق. يعمل كل نطاق بشكل مستقل على منفذه الخاص.

أدوات النطاق الداخلي (Internal Domain Tools)​

النطاقالمنفذالأدواتالحالة
SIEM8101SearchLogs, CorrelateEvents, ExtractIOC, MitreMap✅ وظيفي
SOAR8102ExecutePlaybook, RequestApproval, CreateCase, UpdateCase, GenerateReport✅ وظيفي
EDR8103IsolateEndpoint, ScanEndpoint✅ وظيفي (قائم على النشر)
الشبكة8104AnalyzeFlows, DetectDNSTunneling, BlockIP✅ وظيفي
البرمجيات الخبيثة8105RunYARAScan, SandboxAnalysis⚠️ SandboxAnalysis عبارة عن عنصر نائب
استخبارات التهديدات8106LookupIOC, EnrichIOC, ShareIOC✅ وظيفي (قاعدة بيانات محلية فقط)
CPS/IoT8107QuerySensor, VerifyAttestation, RevokeCert, CorrelatePhysicalCyber, QueryOTProtocol, IsolateSegment⚠️ QueryOTProtocol عبارة عن عنصر نائب
UEBA8108HuntLOLBins, BaselineDeviation, UserRiskScore✅ وظيفي
الأدلة الجنائية8109CollectEvidence, TimelineReconstruction✅ وظيفي

أدوات النطاق الخارجي (External Domain Tools)​

النطاقالمنفذالأدواتالحالة
OSINT8110WebSearch, DomainRecon, WHOISLookup, ShodanSearch✅ وظيفي
التقاط الشبكة8111CaptureTraffic, AnalyzePCAP, ExtractStreams, ProtocolDecode✅ وظيفي
المستندات8112ParseDocument, GeneratePDF, ExtractText, RenderReport✅ وظيفي
استخبارات البرمجيات الخبيثة8113أدوات استخبارات البرمجيات الخبيثة✅ وظيفي
مزود السحابة8114AWSCloudTrailQuery, AzureActivityQuery, GCPAuditQuery, IAMAudit✅ وظيفي
استخبارات الثغرات8115NVDLookup, CVESearch, EPSSScore, ExploitDBSearch✅ وظيفي

9. المشكلات المعروفة وقائمة مراجعة ما قبل الإنتاج (Known Issues & Pre-Production Checklist)​

ملاحظة الحالة (2026-04-03): العناصر المعلَّمة بـ [x] تم علاجها خلال دورة التحسين الحالية.

أولوية حرجة (يجب إصلاحها قبل أي نشر حقيقي)​

  • #1 فرض سرية JWT — أصبح بدء التشغيل يفرض متطلبات قوية على JWT_SECRET_KEY ويرفض القيم الضعيفة أو الافتراضية.
  • #2 التحقق من كلمة المرور / bcrypt — استبدال مخزن المستخدمين في الذاكرة بمصادقة مدعومة بـ PostgreSQL باستخدام passlib bcrypt. حاليًا تُقبل أي كلمة مرور. (1-2 أيام)
  • #3 تعطيل وضع التطوير لـ Vault — التبديل إلى تهيئة الإنتاج مع فك الختم التلقائي، و TLS، وإدارة الرموز الحقيقية. (يوم واحد)
  • #4 ملء سجل مفاتيح الأجهزة — تهيئة Vault PKI الأساسية موجودة، لكن دورة إدارة المفاتيح الديناميكية الصارمة للإنتاج ما زالت مطلوبة. (2-3 أيام)
  • #5 إصلاح عمليات تسليم الذاكرة لـ A2A — يقوم المنسق بتفويض المتخصصين ولكن لا يتم حفظ السياق مرة أخرى. تفقد استمرارية التحقيق عبر مهام الوكلاء المتعددين. (1-2 أيام)
  • #6 إصلاح وصول المنسق للأدوات — أداة RequestHumanApprovalTool موجودة ولكنها غير متصلة بمجموعة أدوات المنسق. نظام تدخل الإنسان في الحلقة غير فعال. (30 دقيقة)
  • #7 تعطيل مستمع MQTT العادي — قم بإزالة/تعليق مستمع المنفذ 1883 في mosquitto.conf الخاص بالإنتاج. (30 دقيقة)

أولوية عالية (قبل الإنتاج المحدود)​

  • #8 نقل JWT إلى httpOnly cookies — مُخزنة حاليًا في localStorage (يمكن الوصول إليها عبر XSS). يتطلب هذا تغيير وضع جلب بيانات اعتماد لوحة البيانات وتعيين ملف تعريف الارتباط في الواجهة الخلفية. (يوم واحد)
  • #9 إصلاح مقارنة مفاتيح API — تم استخدام hmac.compare_digest()، لكن ما زال يُنصح بتقسية مقارنة القيم المُجزّأة المخزنة. (ساعتان)
  • #10 إضافة قيود معدل نقطة نهاية المصادقة — تم تفعيل قيود المعدل لمسارات المصادقة والعمليات الحساسة.
  • #11 إصلاح تعبيرات ReDoS النمطية — استبدال أنماط IOC المكتوبة يدويًا بتعابير نمطية محدودة مجمعة مسبقًا أو بمكتبة iocextract. (4 ساعات)
  • #12 نشر وكيل NetworkAnalyzer — أصبح الوكيل يعمل عبر الخادم العام للوكلاء ويمكن توجيهه ضمن A2A.
  • #13 إزالة بيانات اعتماد التطوير الثابتة — تمت إزالة القيم الثابتة وفرض الاعتماد على متغيرات البيئة.
  • #14 إصلاح اتحاد ShareIOC NATS — مشاركة IOC عبر المواقع تعمل الآن عبر NATS JetStream.
  • #15 إضافة مستخدم غير جذري (non-root) إلى agent.Dockerfile — حاويات الوكلاء وواجهة API تعمل الآن كمستخدم غير جذري.
  • #16 تنفيذ أو إزالة gRPC — يُعرف aurora.proto خدمات gRPC لكن جوهر Rust يعتمد على HTTP فقط (Axum). ملف Proto هو كود ميت. إما تنفيذ الخدمات أو إزالة الملف وتصحيح تعيين منفذ docker-compose. (1-3 أيام)

10. المساهمة (Contributing)​

استراتيجية التفرع (Branching Strategy)​

  • main — فرع رئيسي، مستقر ومحمي.
  • develop — فرع التكامل للميزات الجديدة.
  • feature/<name> — فروع الميزات (تتفرع من develop).
  • fix/<name> — فروع إصلاح الأخطاء.

عملية طلب السحب (PR Process)​

  1. إنشاء فرع ميزة من develop.
  2. إجراء التغييرات وضمان نجاح الاختبارات (pytest, cargo test, npm run lint).
  3. إرسال طلب سحب (PR) إلى develop.
  4. مطلوب موافقة واحدة على الأقل من المراجعين.
  5. دمج السحق (Squash merge) في develop.

كيفية إضافة وكيل جديد (How to Add a New Agent)​

استخدم أي وكيل متخصص منشور بالفعل (مثل SecurityAnalyst) كمرجع للتنفيذ:

  1. إنشاء دليل الوكيل: aurorasoc/agents/<agent_name>/
  2. إنشاء __init__.py — لتحديد اسم الوكيل، والوصف، والأدوات، والإعداد المسبق للذاكرة.
  3. إنشاء server.py — نقطة الدخول لخادم A2A (راجع أي وثيقة server.py الخاصة بوكيل يعمل لمعرفة النمط).
  4. التسجيل في agents/factory.py — إضافة الوكيل إلى خريطة المصنع.
  5. الإضافة إلى docker-compose.yml — تحديد الخدمة بالمنفذ المناسب، ومتغيرات البيئة، والشبكة.
  6. تعيين مجالات أدوات MCP — توصيل الوكيل بخوادم أدوات MCP ذات الصلة الخاصة به عبر depends_on.

كيفية إضافة خادم أدوات MCP جديد (How to Add a New MCP Tool Server)​

  1. إنشاء دليل الأداة: aurorasoc/tools/<domain>/
  2. إنشاء server.py — لتحديد فئات AuroraTool الفرعية باستخدام أساليب _execute().
  3. إنشاء __init__.py — لتصدير فئات الأدوات.
  4. الإضافة إلى docker-compose.yml كخدمة mcp-<domain> جديدة.
  5. تكوين المنفذ في aurorasoc/config/settings.py MCPSettings.
  6. توصيل الوكلاء — إضافة depends_on: mcp-<domain> إلى خدمات الوكلاء المستهلكة.

اصطلاحات رسالة الإيداع (Commit Message Conventions)​

<type>(<scope>): <description>

الأنواع (Types): feat, fix, docs, refactor, test, chore, ci
المجال (Scope): agents, api, tools, rust, dashboard, infra, training, firmware

أمثلة (Examples):

  • feat(agents): add FraudDetection specialist wiring
  • fix(api): enforce JWT secret at startup
  • docs(readme): add architecture diagram