هيكلية المستودع
تمنحك هذه الصفحة خريطة كاملة لمستودع AuroraSOC (monorepo). يتم شرح كل مجلد وملف رئيسي بحيث تعرف بالضبط أين تبحث عند قراءة المشروع أو تعديله.
نظرة عامة عالية المستوى (Top-Level Overview)
AuroraSOC/
├── aurorasoc/ # Python backend — agents, API, tools, events, memory
├── rust_core/ # Rust edge engine — MQTT consumer, alert normaliser, attestation
├── dashboard/ # Next.js 15 web UI
├── firmware/ # Embedded device firmware (STM32, nRF52840, ESP32-S3)
├── training/ # Granite LLM fine-tuning pipeline
├── docs/ # This Docusaurus documentation site
├── tests/ # Python test suite (pytest)
├── infrastructure/ # Canonical infra configs (Docker, Mosquitto, NATS, Vault, etc.)
├── scripts/ # Setup and helper scripts
├── alembic/ # Database migration scripts
├── .env.example # Required environment variables (copy to .env)
│
├── Makefile # 70+ build/dev/test/deploy targets (start here)
├── pyproject.toml # Python project metadata and dependencies
├── pytest.ini # Pytest configuration
├── alembic.ini # Alembic migration configuration
├── docker-compose.yml # Production Docker stack
├── docker-compose.dev.yml # Development Docker stack
├── docker-compose.training.yml # GPU training Docker stack
├── Dockerfile.python # Python backend image
├── Dockerfile.rust # Rust core engine image
├── Dockerfile.dashboard # Next.js dashboard image
├── Dockerfile.training # Training environment image
└── README.md # Project README
aurorasoc/ — الواجهة الخلفية بلغة بايثون (Python Backend)
هذا هو قلب المشروع. جميع وكلاء الذكاء الاصطناعي، وواجهة برمجة التطبيقات (REST API)، ومعالجة الأحداث، والأدوات، والذاكرة، ومنطق الأعمال (business logic) تتواجد هنا.
aurorasoc/
├── __init__.py
├── config/
│ ├── __init__.py
│ └── settings.py # Pydantic BaseSettings — all env-var configuration
│
├── core/
│ ├── __init__.py
│ ├── auth.py # JWT token creation, verification, RBAC permission checks
│ ├── database.py # Async SQLAlchemy engine, session factory, get_db()
│ ├── logging.py # structlog config with OpenTelemetry trace correlation
│ ├── models.py # 13 SQLAlchemy ORM models (Alert, Case, Agent, etc.)
│ ├── rate_limit.py # Redis-backed sliding-window rate limiter
│ └── tracing.py # OpenTelemetry tracer/meter/provider setup
│
├── api/
│ ├── __init__.py
│ └── main.py # FastAPI app — lifespan, routes, WebSocket managers, auth
│
├── agents/
│ ├── __init__.py
│ ├── factory.py # AuroraAgentFactory + AGENT_SPECS dict (16 specialists)
│ ├── generic_server.py # Generic A2AServer bootstrapper for any agent
│ ├── mcp_agent_loader.py # AGENT_MCP_BINDINGS + load_agent_tools() for MCP tools
│ ├── prompts.py # System prompts for all 17 agents
│ ├── server_builder.py # Helpers for building A2A agent servers
│ │
│ ├── orchestrator/ # The Orchestrator agent
│ │ ├── __init__.py
│ │ ├── server.py # deploy_orchestrator(), HandoffTool creation
│ │ └── dispatch.py # CircuitBreaker (CLOSED→OPEN→HALF_OPEN)
│ │
│ ├── security_analyst/ # Per-specialist agent directories
│ ├── threat_hunter/ # Each contains __init__.py and server.py
│ ├── malware_analyst/ # that deploys the specialist on its port
│ ├── incident_responder/
│ ├── network_security/
│ ├── web_security/
│ ├── cloud_security/
│ ├── cps_security/
│ ├── threat_intel/
│ ├── endpoint_security/
│ ├── ueba_analyst/
│ ├── forensic_analyst/
│ ├── compliance_analyst/
│ ├── vulnerability_manager/
│ ├── report_generator/
│ └── network_analyzer/
│
├── tools/
│ ├── __init__.py
│ ├── base.py # Base tool class and shared tool utilities
│ ├── mcp_domain_registry.py # Registry mapping MCP domain names to ports
│ ├── mcp_launcher.py # Launches MCP tool servers
│ │
│ ├── siem/ # SIEM tools (port 8101)
│ ├── soar/ # SOAR playbook tools (port 8102)
│ ├── edr/ # Endpoint detection tools (port 8103)
│ ├── network/ # Network analysis tools (port 8104)
│ ├── malware/ # Malware sandbox tools (port 8105)
│ ├── threat_intel/ # Threat intelligence tools (port 8106)
│ ├── cps/ # CPS/IoT device tools (port 8107)
│ ├── ueba/ # User behavior analytics tools (port 8108)
│ ├── forensics/ # Forensic analysis tools (port 8109)
│ ├── osint/ # Open-source intelligence tools (port 8110)
│ ├── network_capture/ # Packet capture tools (port 8111)
│ ├── document/ # Document generation tools (port 8112)
│ ├── malware_intel/ # Malware intelligence tools (port 8113)
│ ├── cloud_provider/ # Cloud security tools (port 8114)
│ ├── vuln_intel/ # Vulnerability intelligence tools (port 8115)
│ └── registry/ # Tool registry server
│
├── events/
│ ├── __init__.py
│ ├── redis_streams.py # RedisStreamPublisher — 5 internal streams
│ ├── nats_jetstream.py # NATS JetStream — cross-site federation
│ └── mqtt_consumer.py # MQTT v5 consumer — IoT edge integration
│
├── engine/
│ ├── __init__.py
│ └── playbook.py # SOAR playbook execution engine
│
├── memory/
│ ├── __init__.py
│ ├── tiered.py # TieredAgentMemory — 3-tier memory with 6 presets
│ └── stores.py # Backend stores (Redis cache, Qdrant vector, PostgreSQL)
│
├── models/
│ ├── __init__.py
│ └── domain.py # Pydantic domain models (DTOs, request/response schemas)
│
├── services/
│ ├── __init__.py
│ └── scheduler.py # APScheduler background tasks (stale cases, metrics, etc.)
│
├── granite/
│ ├── __init__.py
│ └── registry.py # Model registry — maps agents to Granite model variants
│
└── workflows/
├── __init__.py
└── investigation.py # End-to-end investigation workflow orchestration
العلاقات الرئيسية (Key Relationships)
| ما ترغب بالقيام به (You want to…) | ابحث في (Look in) |
|---|---|
| تغيير شخصية وتوجيه وكيل | agents/prompts.py |
| إضافة وكيل متخصص جديد | agents/factory.py + مجلد agents/<name>/ جديد |
| منح وكيل صلاحية وصول لأدوات جديدة | agents/mcp_agent_loader.py |
| إضافة نطاق أدوات جديد لـ MCP | tools/<domain>/ + tools/mcp_domain_registry.py |
| تعديل واجهة برمجة التطبيقات (REST API) | api/main.py |
| تغيير مخطط قاعدة البيانات (database schema) | core/models.py + إنشاء ترحيل (migration) |
| تعديل معالجة الأحداث | events/redis_streams.py أو events/nats_jetstream.py |
| ضبط وتوليف ذاكرة الوكلاء | memory/tiered.py |
| تغيير الإعدادات الافتراضية للتهيئة | config/settings.py |
rust_core/ — محرك لغة رست للاتصال الطرفي (Rust Edge Engine)
محرك عالي الأداء لاستقبال الإنذارات وتسويتها (normalisation)، مكتوب بلغة Rust مع وقت تشغيل غير متزامن (async runtime) من Tokio.
rust_core/
├── Cargo.toml # Rust dependencies (tokio, axum, rumqttc, redis, etc.)
├── build.rs # Proto/build script
├── Dockerfile # Standalone Rust image
├── proto/ # Protobuf definitions (if used for gRPC)
│
└── src/
├── main.rs # Entry point — starts Axum HTTP server + MQTT consumer
├── config.rs # Configuration (env vars, MQTT/Redis connection strings)
├── mqtt.rs # MQTT v5 client — connects to Mosquitto, subscribes to topics
├── normalizer.rs # Alert normaliser — parses CEF, Syslog, JSON into unified format
├── publisher.rs # Publishes normalised alerts to Redis Streams
├── events.rs # Event type definitions
├── health.rs # Health check endpoint (/health)
└── attestation.rs # ECDSA P-256 firmware attestation signature verification
تدفق البيانات عبر Rust Core (Data Flow Through Rust Core)
dashboard/ — واجهة عرض ومستخدم Next.js للويب (Next.js Web UI)
لوحة التحكم والمعلومات والقياس الموجهة والمصممة خصيصًا للمحللين، تم بناؤها وتطويرها باستخدام Next.js 15، و React 19، و shadcn/ui.
dashboard/
├── package.json # Dependencies (next, react, shadcn, zustand, recharts)
├── next.config.ts # Next.js configuration
├── tailwind.config.ts # Tailwind CSS theme
├── tsconfig.json # TypeScript configuration
├── postcss.config.js # PostCSS plugin config
│
└── src/
├── app/ # Next.js App Router pages
│ ├── layout.tsx # Root layout (sidebar, auth provider)
│ ├── page.tsx # Dashboard home page
│ ├── globals.css # Global styles
│ ├── login/ # Login page
│ ├── alerts/ # Alert management page
│ ├── cases/ # Case management page
│ ├── agents/ # Agent fleet monitoring page
│ ├── chat/ # Interactive agent chat page
│ ├── cps/ # CPS/IoT device monitoring page
│ ├── edr/ # EDR endpoint page
│ ├── firmware/ # Firmware status page
│ ├── network-analyzer/ # Network analysis page
│ ├── siem/ # SIEM integration page
│ ├── soar/ # SOAR playbook page
│ ├── threat-intel/ # Threat intelligence page
│ └── settings/ # System settings page
│
├── components/
│ ├── sidebar.tsx # Navigation sidebar
│ ├── client-layout.tsx # Client-side layout wrapper
│ ├── auth-guard.tsx # Authentication guard component
│ ├── dashboard/ # Dashboard-specific components
│ └── ui/ # shadcn/ui reusable components
│
└── lib/
├── api.ts # HTTP client for FastAPI backend
├── auth.tsx # Auth context and hooks
├── store.ts # Zustand global state store
└── utils.ts # Utility functions
firmware/ — البرامج الثابتة للأجهزة المدمجة (Embedded Device Firmware)
ثلاثة خيارات تشغيل للبرامج الثابتة كأهداف لتحقيق وضمان أمن وتوثيق أجهزة ومعدات CPS/IoT الراسخة على العتاد الصلب (hardware-rooted):
firmware/
├── stm32/ # STM32 microcontroller — Ada SPARK (formal verification)
├── nrf52840/ # Nordic nRF52840 BLE — Rust Embassy (async embedded Rust)
└── esp32s3/ # Espressif ESP32-S3 WiFi — Zephyr RTOS (C)
كل برنامج وبرمجية ثابتة (firmware) تؤدي وتنجز المهام التالية:
- جمع بيانات الاستشعار (Sensor data collection) من العمليات المادية والحقيقية الفيزيائية
- صناعة وتوليد توقيعات ECDSA P-256 كتقارير تصديقية وتوثيقية (attestation reports)
- تطبيق إصدار والنشر من مستوى MQTT QoS 2 publish لرفعه إلى المحرك الأساسي (Rust core engine) عبر شبكة واتصال مؤمنة ومشفرة بصيغة mTLS.
training/ — مسارات وتدفق ضبط وتحسين وتدريب النماذج اللغوية (LLM Fine-Tuning Pipeline)
كل ما يلزم ويتطلب لضبط وتحسين وتطوير (fine-tune) أداء نماذج IBM Granite 4 للقيام بإنجاز مهام وعمليات مخصصة وحصرية وموجهه لعمل واهتمامات مراكز الأمان (SOC-specific tasks).
training/
├── configs/
│ ├── granite_soc_finetune.yaml # Training hyperparameters and agent configs
│ └── Modelfile.granite-soc # Ollama Modelfile template
│
├── scripts/
│ ├── __init__.py
│ ├── prepare_datasets.py # Downloads MITRE ATT&CK, Sigma, NVD, creates datasets
│ ├── finetune_granite.py # Unsloth + LoRA fine-tuning (r=64, alpha=64)
│ ├── evaluate_model.py # Evaluation against SOC benchmarks
│ ├── serve_model.py # Export to Ollama GGUF or vLLM
│ └── train_all_agents.py # Batch fine-tuning for all 16 specialists
│
├── data/ # Generated/downloaded training datasets
└── notebooks/ # Jupyter notebooks for experiments
tests/ — حزمة اختبارات لغة بايثون (Python Test Suite)
جميع اختبارات ووحدات وتراكيب بايثون تستخدم منصات وتوجهات pytest وتقيم وتكمن حلتها ضمن مجلد وأرشيف واحد مسطح.
tests/
├── conftest.py # Shared fixtures (async DB sessions, mock Redis, etc.)
├── test_auth.py # JWT creation/verification, RBAC permission tests
├── test_dispatch.py # CircuitBreaker state machine tests
├── test_models.py # ORM model creation and relationship tests
├── test_normalizer.py # Alert normalisation (CEF, Syslog, JSON) tests
├── test_rate_limit.py # Sliding-window rate limiter tests
├── test_scheduler.py # APScheduler task tests
├── test_settings.py # Settings loading and validation tests
└── test_tiered_memory.py # 3-tier memory system tests
بتنفيذ أمر تشغيل كامل ولجميع الاختبارات والسيناريوهات:
make test # تشغيل وفحص سريع (Quick run)
make test-cov # فحص مشمول مرفق بتقرير ولائحة فحص تغطية شامل (With coverage report)
alembic/ — ترحيل وتسويات قواعد البيانات (Database Migrations)
عمليات ترحيلات وإنشاء مخطط قواعد بيانات (schema migrations) لخادم PostgreSQL المُدارة بوساطة وبموجب Alembic.
alembic/
├── env.py # Migration environment (async SQLAlchemy setup)
├── script.py.mako # Template for new migration files
└── versions/
└── 001_initial_schema.py # Initial schema — creates all 13 tables
الأوامر وطرق الاستخدام:
make migrate # الموافقة والتطبيق والشروع بجميع طلبات الترحيل والتسويات المعلقة
make migrate-new MSG="add new column" # اختلاق وإنشاء خطوة وموجة وعملية ترحيل جديدة (Generate a new migration)
make migrate-down # استرجاع وإلغاء أخر عملية وموجة ترحيل والتراجع خطوة للوراء
infrastructure/ — الخدمات الداعمة للعمليات والبنية التحتية (Supporting Services)
تشكيلات وتكوينات Docker، المراقبة، وعناصر البنية التحتية لجميع الخدمات الداعمة.
infrastructure/
├── docker/ # Shared Docker utilities and scripts
├── postgres/ # PostgreSQL init scripts and config
├── grafana/ # Grafana dashboard JSON definitions
├── prometheus/ # prometheus.yml scrape config
├── otel/ # OpenTelemetry Collector config (otel-collector-config.yaml)
├── mosquitto/ # Mosquitto MQTT broker config (mosquitto.conf, ACLs, TLS certs)
├── nats/ # NATS JetStream server config (nats-server.conf)
├── vault/ # HashiCorp Vault config (secrets management)
└── vllm/ # vLLM serving config (FP16 model serving)
docs/ — موقع مستندات وأدلة التوثيق (Documentation Site)
هو موقع أدلة وتوثيق Docusaurus الموقع الذي تقرأه وتتصفحه وتتواجد به أنت الآن.
docs/
├── docusaurus.config.ts # Site config (Mermaid, i18n, themes)
├── sidebars.ts # Sidebar navigation definitions
├── package.json # Docusaurus dependencies
├── tsconfig.json # TypeScript config
│
├── docs/ # Markdown documentation pages
│ ├── user/ # User-facing guide (dashboard, concepts, security)
│ ├── developer/ # Developer guide (architecture, agents, API, tools)
│ └── contributor/ # Contributor guide (this section — you are here)
│
├── src/
│ ├── pages/index.tsx # Custom homepage
│ └── css/custom.css # Theme customisation
│
├── static/ # Static assets (images, favicon)
└── i18n/ # Translations (Arabic)
scripts/ — سكربتات مساعدة ومراسيل (Helper Scripts)
scripts/
└── setup_local.sh # One-command local setup — installs Ollama, pulls Granite models,
# configures .env, verifies dependencies
ملفات التهيئة للجذور الرئيسية (Root Configuration Files)
| الملف (File) | الغاية ومناط الغرض (Purpose) |
|---|---|
Makefile | نقطة الانطلاق (Start here) — أكثر من 70 هدف وتوجيه لإدارة المهام ومراحل التطوير. اطبع ونفذ make help لاستعراض اللائحة بأكملها. |
pyproject.toml | تفصيلات ومعلومات وبيانات المشروع الأم لدليل بايثون، و توابع وملحقات الارتباطات المعتمدة، وضبوط وإعدادات الأدوات (مثل ruff، و mypy، و pytest). |
pytest.ini | ضوابط وإعدادات Pytest (نمط ومسار وحزمة asyncio، ووجهات حزم الاختبارات ومساراتها test paths، والمقيدات والأسس markers). |
alembic.ini | منظومات الترحيل وقواعد البيانات الخاصة بـ Alembic (مسار وسلاسل وسلك الاتصالات، وبوصلة مواقع وتخزين scripts). |
docker-compose.yml | كتل وركام عمليات التشغيل والإنتاج الفعلي (Production stack) — لكافة الأنظمة والخدمات وواجهات (كتل وطلبات API، والمحرك الأساسي لـ Rust، ومحاريب الوكلاء، والـ Redis، و قواعد PostgreSQL، وما نحو ذلك). |
docker-compose.dev.yml | متجاوزات واستثناءات العمليات وبيئات التطوير (إعادات التشغيل والتعريف الساخنة والسريعة، وتفريغ منافذ استكشاف ومراجعة الأخطاء). |
docker-compose.training.yml | منصة وعمليات وتكوينات التدريب والتلقين المعزز على رقاقات GPU (تصدير وتضمين Unsloth، و vLLM، وواردات استقطاب حواضن Ollama). |
Dockerfile.python | صور وأوجه حاويات الواجهة الخلفية لبايثون وصناديقها (شاملة وكافلة لإطارات الـ FastAPI + وخلايا الوكلاء). |
Dockerfile.rust | صورة ومكائن الحاوية الأم وأسطوانة التشغيل المركزية لكبسولات Rust core. |
Dockerfile.dashboard | صورة واجهات لوحة القيادة وحاويات Next.js التشبيهية. |
Dockerfile.training | بيئاب وحواضن وغرف عمليات التدريبات المتوافقة والمصحوبة بدعم ومؤازرة (CUDA support). |
دليل التصفح والانتقال والمعابر السريعة للمهام (Quick Navigation by Task)
| أودُ أن أقوم بـ... (I want to…) | اذهب ومُد مسارك لشطر إلى... (Go to) |
|---|---|
| استيعاب النظم والاستيضاح من طبيعته الشاملة الكاملة | aurorasoc/ (اتخذ إكليل وبداية مع api/main.py) |
| الإطلاع ومعاينة ومراجعة القراءة والتعديل على تصرف وبنية وكيل (agent's behaviour) | aurorasoc/agents/prompts.py |
| الاستحداث ورسم محامل ومعابر إيصال وتبادل بيانات لواجهات API إضافية وجديدة (endpoint) | aurorasoc/api/main.py |
| الالتفات والانشغال والعمل للوحة وتفرعات وأسطح الويب والمستعرض (dashboard) | dashboard/src/ |
| تدارك ومعكوس ومداواة الخلل والأعطاب (bug) الكامنة بإخفاق تحليل وتمثيل الإنذارات | rust_core/src/normalizer.rs |
| استحداث واقتناء ملاحق وأدوات بروتوكولات وممرات (MCP) جديدة وإضافية | aurorasoc/tools/<domain>/ |
| إقراء وبدء التعديلات وإحداث تعديلات على بنية قواعد البيانات (database schema) | aurorasoc/core/models.py → make migrate-new |
| تسطير وكتابة وابتكار أو تنفيـذ ورصد الفحوصات والتجارب التشخصية والاختبارات الروتينية لعمل البرنامج | tests/ |
| تأهيل وتنصيب وربط أسس وركائز البنية التحتية والمخدمة | infrastructure/ + docker-compose.yml |
| الانضباط والتسويات الرفيعة لتطوير حواضن ومستقطبات وملقمات (LLM) | training/ |
| الانهماك وشغل الانتباه ومجالات والصلة بالبرمجيات الثابتة (firmware) | firmware/<target>/ |
| تجديد وتطوير وترسيخ وصيغ وحرفية توثيق ومحافل المستندات (documentation) | docs/docs/ |