**هيكل المستودع:**```
home_SOC_suite/
├── Analysts/           — PowerShell analyst scripts
├── Collectors/         — PowerShell collector scripts
├── Dashboard/          — Flask single-page SOC dashboard (Phase 8)
│   ├── app.py              — Flask server, all routes, process detection, DB reads
│   ├── Launch_Dashboard.ps1 — Launcher: checks if Flask running, starts it, opens browser
│   ├── templates/
│   │   └── index.html      — Single-page dashboard layout
│   └── static/
│       ├── style.css       — Dark terminal aesthetic, severity colours, bar graph tiers
│       └── dashboard.js    — All polling, Start Day / End Day sequence, session alert counter
├── Engine/             — Python correlation engine
│   ├── engine.py           — Main loop and orchestration
│   ├── log_parser.py       — Collector log ingestion
│   ├── normalizer.py       — Event normalisation to canonical schema
│   ├── correlator.py       — Correlation rules engine
│   ├── alert_manager.py    — Alert deduplication, flood detection, log writing
│   ├── db.py               — SQLite operations (batch ingest, query, retention)
│   ├── health_db.py        — Heartbeat SQLite store (collector_status, heartbeats tables)
│   ├── config.py           — All thresholds and time windows in one place
│   ├── test_parser.py      — Log parser test suite (7 tests)
│   ├── test_normalizer.py  — Normaliser test suite (32 tests)
│   └── test_correlator.py  — Correlator test suite (135 tests)
└── Documentation/      — Research documents, red team analysis, and dashboard screenshots

---

## لغات نظام التشغيل المدعومة

يكتشف Steward تلقائياً مسار عداد أداء وحدة المعالجة المركزية الصحيح للغات نظام التشغيل التالية:

| اللغة | مسار العداد |
|---|---|
| الإنجليزية | \Process(*)\% Processor Time |
| الألمانية | \Prozess(*)\Prozessorzeit (%) |
| الفرنسية | \Processus(*)\% temps processeur |
| الإسبانية | \Proceso(*)\% de tiempo de procesador |
| الإيطالية | \Processo(*)\% Tempo processore |
| البرتغالية | \Processo(*)\% de Tempo do Processador |
| الروسية | \Процесс(*)\% загруженности процессора |
| الصينية (المبسطة) | \Process(*)\% Processor Time (عادةً الإنجليزية) |

لإضافة دعم للغة أخرى، أضف مسار العداد المترجم إلى مصفوفة `$PathsToTry` في دالة `Get-WorkingCounterPath` في `Steward.ps1`.

---

## التوثيق والبحث

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

| المستند | الغرض |
|---|---|
| `home_soc_pre_coding_architecture_guide.pdf` | إطار القرار قبل البناء. نموذج البيانات الأساسي، نموذج الثقة، دورة حياة الخط الأساسي، استراتيجية الاختبار، وفرص التحقق عبر المجمعات. كُتب قبل كتابة سطر واحد من الكود. |
| `Home_Soc_Architecture_And_Engine_Design.pdf` | مواصفات البنية المستهدفة. تصميم محرك بايثون ثلاثي البرامج، مخطط SQLite، نموذج الكشف الهجين (قواعد حتمية + تسجيل المخاطر)، منطق ترقية التنبيهات. |
| `HomSOC_Implementation_Guide.pdf` | خطة البناء على مراحل. أكواد هيكلية لجميع المجمعات، جدول عمل أسبوعي، أنماط مرجعية سريعة لـ PowerShell. دليل البناء لطبقة PowerShell. |
| `RedTeam_Analysis_HomSOC_Final.pdf` | المرجع الأساسي للفريق الأحمر. 11 جولة عدائية (Claude + Gemini + محاكاة هجمات مباشرة)، جميع قواعد الربط الـ 26 مع منطق الكشف الكامل، نتائج الالتفاف، والتدابير التخفيفية المطبقة على البناء. |
| `Home_SOC_Red_Team_Analysis_Pro.pdf` | الفريق الأحمر المعماري. 11 سيناريو هجوم يستهدف نقاط الضعف الهيكلية: تسميم الخط الأساسي، تجاوز الربط، غمر الضوضاء، قمع المجمع، التلاعب بالأرشيف، حقن السجلات، هجمات إعادة التشغيل، وإساءة استخدام الهوية. |
| `Home_SOC_Red_Team_Whitepaper.pdf` | ملخص تنفيذي. جدول كامل لسيناريوهات الهجوم، مقارنة النظام (الخط الأساسي مقابل المحصن)، التحسينات المعمارية الرئيسية، ونظرة عامة على تصميم نموذج الكشف. |

---

## الميزات الرئيسية

- **تصميم عدائي** — تم تحديد 48 قاعدة ربط من خلال تحليل الفريق الأحمر متعدد الجولات قبل بناء محرك بايثون. منطق الكشف يستند إلى هجمات حقيقية، وليس سيناريوهات افتراضية
- **جمع خط الأساس السلوكي** — جميع المجمعات تبني خطوطاً أساسية بمرور الوقت، مما يتيح كشف الحالات الشاذة بالنسبة إلى الوضع الطبيعي الملاحظ بدلاً من القواعد الثابتة
- **مراقبة الموقع الجغرافي** — الاتصالات الصادرة، الاتصالات الواردة، عناوين IP لمصدر المصادقة، واتصالات DoH يتم تتبعها حسب البلد مع تنبيهات TELEMETRY_GAP عند فشل الموقع الجغرافي
- **بصمات العمليات** — كل حدث شبكة، منفذ، عملية، ومصادقة يتم تسجيله مع مسار العملية الكامل، مما يكشف هجمات التمويه واستخدام LOLBin
- **الحماية الذاتية للمجموعة** — يراقب Warden جميع البرامج النصية والإعدادات عبر SHA256 FIM مع سلسلة حماية ثلاثية الطبقات: سلامة البيان، مهمة مجدولة خارجية، ومراقبة مهمة CityGuard
- **القائمة البيضاء ذات الثقة الصفرية** — جميع القوائم البيضاء تبدأ فارغة. جمع خط الأساس لمدة 30 يوماً يسبق أي استثناءات
- **تسجيل مُوسم بالخطورة** — إدخالات سجل منظمة مصممة للتوافق مع محلل بايثون والتكامل المستقبلي مع SIEM
- **تدوير السجل لمدة 7 أيام** — أرشفة تلقائية مع التحقق من SHA256 وسلسلة سلامة هاش الأرشيف في حدود الصباح/المساء عبر Auditor.ps1
- **توافق مع أنظمة Windows متعددة اللغات** — يتم اكتشاف مسارات عداد الأداء تلقائياً عبر 8 لغات نظام تشغيل عند بدء التشغيل
- **لوحة معلومات SOC بصفحة واحدة** — لوحة Flask للرؤية المباشرة تحل محل جميع نوافذ PowerShell الفردية. تتضمن مُشغل المجموعة (بدء اليوم / إنهاء اليوم)، مراقب موارد Steward المباشر، موجز اتصال Sentinel، نقاط نبض ثلاثية الحالة (أخضر نشط / كهرماني لم يبدأ / أحمر متوقف — تُقرأ مباشرة من ملفات JSON الصحية للمجمع، مستقلة عن حالة المحرك)، بطاقات أحداث SUSPICIOUS/CRITICAL، موجز تنبيهات المحرك القابل للتمرير، عداد التنبيهات للجلسة، وإنشاء تقرير أسبوعي بنقرة واحدة. إنهاء اليوم يوقف جميع المجمعات ويشغل مراجعة Auditor المسائية — ثم يظهر زر إيقاف لوحة المعلومات لإنهاء عملية Flask بشكل نظيف. يجب إغلاق علامة تبويب المتصفح يدوياً (المتصفحات لا تعرض واجهة برمجة تطبيقات إغلاق للعمليات الخارجية)

---

## الحالة الحالية — اكتمال المرحلة 8

محرك الربط بلغة بايثون مبني ويعمل مباشرةً على جميع المجمعات الـ 12، بما في ذلك SysmonWatcher (أحداث مستوى النواة من Sysmon).

**خط أنابيب المحرك:**

`log_parser.py` → `normalizer.py` → `correlator.py` → `alert_manager.py`

جميع خطوات الإدخال والتطبيع والربط تستخدم معاملات SQLite الدفعية. 174 اختباراً عبر ثلاث مجموعات اختبار — جميعها ناجحة.

**القواعد المنفذة:** 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 13, 16, 17, 18, 21, 22, 41, 42,
43, 44, 45, 46, 47, 48 (الطبقة 1 حدث واحد والطبقة 2 ربط زمني) والقواعد 28–39
(أحداث نواة Sysmon عبر SysmonWatcher). القواعد 12, 14, 15, 20 مؤجلة إلى الطبقة 4 (تتطلب
بيانات خط أساس لمدة 30 يوماً). القواعد 23, 24, 25 معلقة بانتظار مجمعات متخصصة.

**نموذج الكشف:** هجين — قواعد حتمية لسلاسل الهجوم الواضحة،
تسجيل المخاطر التراكمي للإشارات الضعيفة، تنبيهات الرؤية لصمت المجمع
وتدهور جودة الإدخال.

**المراحل التالية:**

| المرحلة | البرنامج | الحالة |
|---|---|---|
| 8 | لوحة معلومات SOC — Flask صفحة واحدة رؤية مباشرة | مكتملة |
| 9 | المحرك الجنائي — التحقيق بعد الحدث، بنك أدلة قابل للإضافة فقط | مخطط |
| 9 | لوحة المعلومات الجنائية — ملخص النتائج، إنشاء التقارير، تصفح الأدلة | مخطط |

راجع [`roadmap.md`](https://github.com/nate-ryan-7690/home_soc_suite/blob/main/roadmap.md) للجدول الزمني الكامل للتطوير.

---

## تنبيهات مزعجة معروفة — قبل التحصين

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

| المجمع | التنبيه | السبب |
|---|---|---|
| Sentinel | انتهاك بيئي حاسم (CRITICAL environmental violation) | أي برنامج طرف ثالث مثبت خارج مسارات المنطقة الموثوقة الافتراضية (Windows, Program Files) — عملاء المزامنة السحابية، تطبيقات الاتصالات، والأدوات المساعدة للبائعين التي تثبت في AppData هي مصادر شائعة |
| Sentinel | ثغرة قياس عن بعد مشبوهة (SUSPICIOUS TELEMETRY_GAP) | عناوين IPv6 الحلقية والمحلية الرابط تفشل في بحث الموقع الجغرافي — تم إصلاحه في البناء الحالي |
| SysmonWatcher | مشبوه/حاسم (SUSPICIOUS/CRITICAL) في القواعد 31, 33, 34 | برامج مكافحة الفيروسات وأمن نقطة النهاية تجري بانتظام قراءات LSASS، قراءات القرص الخام، وتحميل DLLs من مسارات قابلة للكتابة من قبل المستخدم كجزء من التشغيل الطبيعي |
| SysmonWatcher | مشبوه (SUSPICIOUS) في القاعدة 28 | أدوات التطوير التي تعلق بعمليات المتصفح لأغراض التصحيح ستؤدي إلى تشغيل قاعدة تصحيح المتصفح المرفق |
| Bulwark | فشل GeoIP مشبوه (SUSPICIOUS GeoIP failures) | الاتصالات على نطاقات IP الخاصة والمحجوزة لا يمكن تحديد موقعها جغرافياً — ينتج TELEMETRY_GAP حتى يتم إدراجها في القائمة البيضاء |
| Bloodhound | اكتشاف DGA مشبوه (SUSPICIOUS DGA detection) | استعلامات DNS قصيرة العمر أو ذات عينة منخفضة تؤدي إلى فحوصات العشوائية قبل استقرار خط الأساس المتداول |
| Warden | مفقود البيان مشبوه (SUSPICIOUS MANIFEST_MISSING) | لا يوجد بيان FIM عند التشغيل الأول — قم بالبناء باستخدام `.\Warden.ps1 -BuildManifest` بعد الإعداد الأولي |
| Warden | مجمع معطل مشبوه (SUSPICIOUS COLLECTOR_DOWN) | المجمعات التي لم يتم نشرها بعد ليس لديها ملف نبض — متوقع حتى تشغيل المجموعة الكاملة |
| DoH_Detector | حاسم (CRITICAL) لـ DoH المتصفح | المتصفحات المهيأة لاستخدام DNS عبر HTTPS ستطلق التنبيه حتى تُضاف إلى قائمة العمليات المسموح بها |

التحصين الخاص بالجهاز (قوائم العمليات الموثوقة، القوائم البيضاء للمسارات، الإدخالات الآمنة المعروفة)
يتم تطبيقه محلياً ولا يتم تضمينه في هذا المستودع.

---

## ملاحظات

- قم بتعيين `$RootPath` في كل برنامج نصي إلى المجلد الذي قمت بتثبيت مجموعة SOC فيه.
  الافتراضي هو `Desktop\SOC`
- تتطلب البرامج النصية تعيين سياسة تنفيذ PowerShell إلى Bypass
- تتطلب البرامج النصية للمجمع صلاحيات Administrator للحصول على رؤية كاملة للنظام
- تعمل البرامج النصية للمحلل كـ user عادي
- الموقع الجغرافي يتم توفيره بواسطة ip-api.com المستوى المجاني
- يجب تمكين سجل أحداث DNS Client قبل تشغيل Bloodhound.ps1:
  `wevtutil sl "Microsoft-Windows-DNS-Client/Operational" /e:true`

---

## سياق التعلم

بني أثناء إعادة التدريب في Fachinformatiker Anwendungsentwicklung، ألمانيا 2026.
استهداف مهنة في مجال الدفاع السيبراني واستخبارات التهديدات.
بني بمساعدة الذكاء الاصطناعي كأداة تعليمية. كل قرار تصميمي،
جلسة تصحيح أخطاء واختيار معماري كان مدفوعاً من قبل المطور
مع الفهم الكامل للمفاهيم الأساسية.