دليل المساهمة
تغطي هذه الصفحة كل ما تحتاج إلى معرفته لتقديم مساهمات عالية الجودة في منصة AuroraSOC — بدءًا من اصطلاحات البرمجة ووصولاً إلى سير عمل طلبات السحب (pull request)، بالإضافة إلى أدلة تفصيلية خطوة بخطوة لأكثر مهام التطوير والإضافة شيوعًا.
استراتيجية التفريع
يستخدم نظام AuroraSOC سير عمل بسيط يعتمد على تفريع الميزات (feature-branch):
- أنشئ فرعًا من
main:git checkout -b feature/your-feature-name - أضف تغييراتك من خلال إيداعات (commits) واضحة ومستقلة (atomic).
- ادفع (Push) التغييرات وافتح طلب سحب (Pull Request) وتوجيهه نحو فرع
main. - تفاعل مع الملاحظات التعقيبية (review feedback) حتى تتم الموافقة عليه.
- اجمعه وادمج (Squash-merge) التغييرات المعتمدة في فرع
main.
تسمية الفروع
| السابقة (Prefix) | حالة الاستخدام (Use Case) | مثال |
|---|---|---|
feature/ | وظيفة جديدة | feature/add-dns-tools |
fix/ | إصلاحات أخطاء برمجية | fix/circuit-breaker-timeout |
docs/ | تحديثات توثيقية فقط | docs/update-agent-reference |
refactor/ | إعادة هيكلة وتطوير البرامج | refactor/memory-stores |
test/ | إضافة أو إصلاح اختبارات | test/add-playbook-tests |
معايير البرمجة (Coding Standards)
بايثون (الخلفية - Backend)
تستخدم منصة AuroraSOC كلاً من ruff للتحليل الأكاديمي للبرمجة (linting) والتنسيق، و mypy للتحقق من أنواع البيانات المكتوبة. توجد جميع إعدادات التكوين في pyproject.toml.
القواعد الأساسية:
| القاعدة | التفصيل |
|---|---|
| الهدف المعماري | بايثون 3.12 فما أحدث |
| طول السطر | 100 حرفًا كحد أقصى |
| المنسّق | ruff format |
| قواعد المدقق (Linter) | E، F، W، I (استيراد)، N (التسمية)، UP (تحديث بايثون)، ANN (التعليقات التوضيحية)، B (الأخطاء الشائعة bugbear)، A (دوال داخلية builtins)، SIM (تبسيط) |
| التحقق من النوع | mypy مع إعداد تخطي عدم الاستيراد --ignore-missing-imports |
| التزامن (Async) | يجب أن تكون جميع عمليات الإدخال والإخراج غير متزامنة (async def, await) |
| الواردات (Imports) | مفروزة باستخدام ruff (متعافق مع isort) |
قبل الإيداع (committing):
make format # تنسيق الشيفرة تلقائيا
make lint # فحص المشكلات البرمجية
make type-check # التحقق من التوضيحات للأنواع (type annotations)
أمثلة للنمط البرمجي (Style examples):
# ✅ جيّد — يحمل توضيحا للأنواع، غير متزامن، ووصفي
async def get_alert_by_id(session: AsyncSession, alert_id: str) -> Alert | None:
result = await session.execute(select(Alert).where(Alert.id == alert_id))
return result.scalar_one_or_none()
# ❌ سيّئ — لا يوجد توضيح للأنواع، متزامن، وغير واضح
def get_alert(s, id):
return s.query(Alert).filter_by(id=id).first()
رست (المحرك الأساسي - Rust Core Engine)
make rust-clippy # استخدام clippy كأداة Linting (التحذيرات تُعامل كأخطاء)
make rust-test # تشغيل الاختبارات
يجب أن تمرر جميع الأكواد الخاصة بـ Rust من أداة clippy -- -D warnings بصفر أخطاء وتحذيرات.
تايب سكريبت (لوحة التحكم - TypeScript Dashboard)
make dashboard-lint # استخدام ESLint و TypeScript checks
يُرجى اتّباع النماذج الحالية المعتمدة في مجلد dashboard/src/ — المكونات المتعلقة بخشادم (React Server Components) تتخذ كحالات نموذجية بشكل افتراضي، بينما يتم استعمال مكونات الموكلين الخارجيين فقط في الحالات التي تسدعي ذلك (client components).
متطلبات الاختبار (Testing Requirements)
يجب أن يتضمن كل طلب سحب (PR) اختبارات للوظائف والميزات الجديدة أو المُعدلة.
اختبارات بايثون (Python Tests)
- توجد الاختبارات في مجلد
tests/(بهيكلة مسطحة، ملف واحد لكل وحدة برمجية). - استخدم pytest مع pytest-asyncio للاختبارات غير المتزامنة.
- سمّ الملفات بالصيغة
test_<module>.pyوالدوال بالصيغةtest_<behavior>().
كتابة اختبار:
# tests/test_my_feature.py
import pytest
from aurorasoc.my_module import my_function
@pytest.mark.asyncio
async def test_my_function_returns_expected_value():
result = await my_function(input_data)
assert result == expected_output
@pytest.mark.asyncio
async def test_my_function_raises_on_invalid_input():
with pytest.raises(ValueError, match="invalid"):
await my_function(bad_data)
التجهيزات والموارد المشتركة (Shared fixtures) توضع في ملف tests/conftest.py (مثل جلسات قواعد البيانات غير المتزامنة، وواجهات Redis الوهمية mock clients، وغيرها).
تشغيل الاختبارات:
make test # جميع الاختبارات
make test-cov # الاختبارات مع قياس تغطية الكود
python -m pytest tests/test_my_feature.py -v # تشغيل ملف واحد فقط
python -m pytest tests/test_my_feature.py::test_specific -v # تشغيل اختبار محدد
اختبارات رست (Rust Tests)
make rust-test
توجد اختبارات Rust بجوار الشيفرة المصدرية في وحدات مقيدة كالتالي: #[cfg(test)].
الحد الأدنى للتغطية (Minimum Coverage)
احرص دائمًا على كتابة اختبارات ذات معنى تغطي المسار الناجح (happy path)، ومسارات الخطأ، والحالات الحديّة (edge cases). يتم قياس نسبة تغطية الكود المصدري باستخدام الأمر make test-cov — احرص على عدم تقليل نسبة التغطية العامة في المستودع.
سير عمل طلبات السحب (Pull Request Workflow)
قبل فتح طلب سحب (PR)
شغّل مجموعة الفحوصات الكاملة:
make check
هذا الأمر سيقوم بتشغيل التسلسل التالي: lint → type-check → test → rust-clippy → rust-test → dashboard-lint.
يجب أن تنجح جميع هذه الفحوصات واجتيازها بسلام قبل المبادرة بفتح وإنشاء طلب السحب التعديلي.
قالب ووصف طلب السحب
عند فتح طلب السحب (PR)، قم بتضمين ما يلي:
## What
وصف موجز للتعديل أو التغيير المدخل.
## Why
اربط ووفر رابط المشكلة أو اشرح الدافع وراء هذا التغيير.
## How
أهم القرارات الفنية والتقنية التي اتخذت لمعالجة الخلل وما تم فعله.
## Testing
كيف تم اختبار التغييرات؟ ما هي الاختبارات التي أضيفت؟
## Checklist
- [ ] أمر `make check` اجتاز بنجاح
- [ ] تمت إضافة اختبارات للوظائف الجديدة المنشأة
- [ ] تم تحديث التوثيقات (إن كان التغيير يتطلب ذلك)
- [ ] لم تظهر أي تحذيرات جديدة إثر التغييرات
إجراءات المراجعة
- يُشترط الحصول على مراجعة واحدة على الأقل من أحد المشرفين (Maintainer).
- يجب اجتياز جميع فحوصات وإجراءات التكامل المستمر (CI checks) بنجاح.
- قد يطلب المراجعون بعض التعديلات — تفاعل وأشبع كل تعليق بالاهتمام المطلوب والرد.
- بمجرد الموافقة، سيتم دمج الطلب وإدماج جميع الإيداعات في إيداع واحد (squash-merged).
مهام المساهمة الشائعة (Common Contribution Tasks)
إضافة وكيل ذكاء اصطناعي جديد (Adding a New AI Agent)
هذه هي المهمة الأكثر شيوعًا عند توسيع وتطوير المنصة. اتبع هذه الخطوات الثمانية:
1. حدد مواصفات الوكيل (agent spec) في ملف aurorasoc/agents/factory.py:
# أضف إلى قاموس AGENT_SPECS
"my_new_agent": AgentSpec(
role="My New Agent",
instructions=MY_NEW_AGENT_PROMPT,
memory_template="ANALYST", # اختر من بين: ANALYST, HUNTER, RESPONDER, INTEL, ORCHESTRATOR, LIGHTWEIGHT
exclude_tools=[], # الأدوات المراد حظرها (مثلا، ["block_ip"] للوكلاء المخصصين للقراءة فقط)
),
2. اكتب موجه النظام (system prompt) في ملف aurorasoc/agents/prompts.py:
MY_NEW_AGENT_PROMPT = """You are the My New Agent for AuroraSOC.
## Primary Mission
[صف هنا ما هو دور هذا الوكيل]
## Capabilities
- [القدرة أو الوظيفة 1]
- [القدرة أو الوظيفة 2]
## Investigation Methodology
1. [الخطوة 1]
2. [الخطوة 2]
## Output Requirements
Always structure your findings as:
- **Finding**: What was discovered
- **Severity**: Critical/High/Medium/Low
- **Evidence**: Supporting data
- **Recommendation**: Suggested action
"""
3. قم بتعيين روابط ومجالات أدوات MCP (MCP tool bindings) في ملف aurorasoc/agents/mcp_agent_loader.py:
# أضف إلى قاموس AGENT_MCP_BINDINGS
"my_new_agent": ["siem", "threat_intel"], # أدرج نطاقات MCP التي يحتاجها هذا الوكيل
4. أنشئ مجلد الوكيل (agent directory):
mkdir -p aurorasoc/agents/my_new_agent
touch aurorasoc/agents/my_new_agent/__init__.py
5. أنشئ ملف الخادم (server file) في aurorasoc/agents/my_new_agent/server.py:
from aurorasoc.agents.generic_server import deploy_agent
if __name__ == "__main__":
deploy_agent("my_new_agent", port=9017) # المنفذ التالي المتاح (Next available port)
6. سجل الوكيل الجديد لدى وكيل التنظيم (Orchestrator) — أضف اسم الوكيل إلى القائمة SPECIALIST_NAMES في الملف aurorasoc/agents/orchestrator/server.py.
7. أضف الاختبارات في tests/test_my_new_agent.py.
8. تحديث التوثيق — أضف الوكيل إلى docs/docs/contributor/ai-agents.md و docs/docs/developer/agents/.
إضافة نطاق أدوات جديد (Adding a New MCP Tool Domain)
1. أنشئ مجلد الأداة:
mkdir -p aurorasoc/tools/my_domain
touch aurorasoc/tools/my_domain/__init__.py
2. قم بتنفيذ وبناء الأدوات باتباع نمط الصنف الأساسي (base class pattern) المتاح في aurorasoc/tools/base.py.
3. سجّل النطاق (Register the domain) في aurorasoc/tools/mcp_domain_registry.py باستخدام المنفذ التالي المتاح (8116+ وما فوق).
4. اربط الوكلاء بالنطاق الجديد في ملف aurorasoc/agents/mcp_agent_loader.py — أضف اسم النطاق إلى إدخالات الوكلاء ذوي الصلة في قسم AGENT_MCP_BINDINGS.
5. أضف الاختبارات للأدوات الجديدة المُضافة.
إضافة نقطة نهاية واجهة برمجة تطبيقات جديدة (Adding a New API Endpoint)
1. أضف المسار (route) في ملف aurorasoc/api/main.py:
@app.get("/api/v1/my-endpoint", tags=["my-feature"])
async def my_endpoint(
current_user: dict = Depends(require_permissions("my_feature:read")),
session: AsyncSession = Depends(get_db),
):
# التنفيذ والبرمجة (Implementation)
return {"data": result}
2. أضف نماذج الطلب/الاستجابة (request/response models) في aurorasoc/models/domain.py إذا لزم الأمر.
3. أضف الصلاحيات المطلوبة (required permission) إلى الأدوار المناسبة في aurorasoc/core/auth.py.
4. اكتب الاختبارات لتغطية حالات المصادقة، والترخيص، والنجاح، والأخطاء المحتملة.
إضافة نموذج قاعدة بيانات (Adding a Database Model)
1. حدد النموذج (Define the model) في aurorasoc/core/models.py:
class MyModel(Base):
__tablename__ = "my_models"
id = Column(String, primary_key=True, default=lambda: str(uuid4()))
name = Column(String, nullable=False)
created_at = Column(DateTime(timezone=True), server_default=func.now())
2. أنشئ ملف تهجير جديد (Generate a migration):
make migrate-new MSG="add my_models table"
3. راجع ملف التهجير المُولد تلقائيًا في المجلد alembic/versions/.
4. قم بتطبيق وتفعيل التهجير (Apply the migration):
make migrate
مساهمات التوثيق (Documentation Contributions)
يستخدم موقع التوثيق (Documentation site) إطار عمل Docusaurus مع توافر دعم للمخططات باستخدام مكتبة Mermaid.
تشغيل التوثيقات محليًا (Running Docs Locally)
cd docs
npm install # للمرة الأولى فقط
npm run start # سيبدأ التشغيل محليًا على الرابط http://localhost:3000
كتابة ونتابة وثائق الشرح (Writing Docs)
- جميع الوثائق عبارة عن ملفات Markdown موجودة في مجلد
docs/docs/. - استخدم كتل رموز وأكواد Mermaid البرمجية لإنشاء المخططات والرسوم البيانية (يتم معالجتها وتقديمها تلقائيًا).
- تحتاج كل صفحة إلى وصف تعريفي للبيانات (YAML frontmatter) يوضع في بداية الملف:
---
id: my-page
title: عنوان صفحتي (My Page Title)
sidebar_label: عنوان قصير للشريط الجانبي (Short Label)
sidebar_position: 1
description: وصف من سطر واحد يخدم محسينات محركات البحث (SEO).
---
- بعد إضافة صفحة جديدة، قم بتسجيل الصفحات المضافة في ملف
docs/sidebars.ts.
التدويل وتعدد اللغات (Internationalisation)
تدعم توثيقات AuroraSOC اللغتين الإنجليزية والعربية. الإنجليزية هي اللغة الأساسية للمشروع — توجد الترجمات العربية في مجلد docs/i18n/ar/.
اتفاقيات وتعليمات كتابة رسائل الإيداع (Commit Message Convention)
استخدم رسائل إيداع واضحة مصاغة بصيغة الأمر:
feat: add DNS resolution tools to network domain
fix: prevent circuit breaker from opening on timeout
docs: update agent reference with new CPS agent
test: add regression test for playbook rollback
refactor: extract memory store interface
| السابقة (Prefix) | متى تُستخدم (When) |
|---|---|
feat: | إضافة وظيفة أو ميزة جديدة |
fix: | إصلاح أخطاء وعلل برمجية |
docs: | مساهمات تتعلق بالتوثيق |
test: | إضافة أو تعديل اختبارات |
refactor: | إعادة هيكلة أو إعادة كتابة الشفرة (بدون تغيير في الوظائف) |
chore: | تعديلات في البناء أو مسارات التكامل المستمر CI، أو التهيئة |
الحصول على المساعدة (Getting Help)
- قضايا ومشاكل GitHub (GitHub Issues): تستخدم للإبلاغ عن مشكلة برمجية أو طلب إضافة ميزة.
- الاستفسارات البرمجية: يُرجى أولاً قراءة صفحة هيكلية النظام (System Architecture) وصفحة وكلاء الذكاء الاصطناعي (AI Agents) — فهما تشرحان أنماط التصميم المعماري بشكل تفصيلي.
- في حالة مواجهة مشكلة خلال التهيئة (Stuck on Setup): راجع دليل البدء المبدئي للاطلاع على خطوات استكشاف الأخطاء وإصلاحها.
خلاصة (Summary)
| الخطوة (Step) | الأمر والتنفيذ (Command) |
|---|---|
| تنسيق الكود | make format |
| التحليل والفحص المبدئي (Lint) | make lint |
| فحص وتدقيق الأنواع | make type-check |
| تشغيل الاختبارات | make test |
| تشغيل كافة الخطوات | make check |
| بناء رست (Rust) | make rust-build |
| بناء لوحة التحكم | make dashboard-build |
| تطبيق تغييرات قواعد البيانات | make migrate |
شكرًا لك على مساهمتك في AuroraSOC. كل مساهمة تقوم بها — سواء كانت تصحيحًا لخطأ إملائي بسيط، أو إضافة وكيل جديد، أو تحسينًا في التوثيقات — من شأنها تحسين المشروع وجعله أفضل.