أداة تحليل كود ثابتة مدركة للإطار لمراجعة تلقائية للكود المصدري مع قواعد خاصة بالمنصة، وتحليل التلوث، وتقدير الجهد، وخطوط أساس للكبت.
Author:
## حول Daksh SCRA
تم بناء Daksh SCRA (مساعد مراجعة الكود المصدري) لتعزيز كفاءة عملية مراجعة الكود المصدري، مما يوفر نهجًا منظمًا ومنسقًا لمراجعي الكود.
بدلاً من وضع علامة على كل شيء بشكل عشوائي كمشكلة محتملة، يشجع Daksh SCRA التحليل المدروس، ويحث على التحقيق في المشكلات المحتملة وتأكيدها. يخفف هذا النهج من التسرع في تصنيف كل مخاوف محتملة كخطأ برمجي، مما يقلل من الارتباك والوقت الضائع في النتائج الإيجابية الكاذبة.
### الظهور الأول
تم تقديم Daksh SCRA لأول مرة خلال جلسة تدريبية حول مراجعة الكود المصدري في Black Hat USA 2022 (6-9 أغسطس)، حيث تم عرضه بشكل غير ملحوظ لجمهور محدد. وحدث ظهوره العام الرسمي الأول في Black Hat USA 2023 في لاس فيغاس.
## الميزات والوظائف
- **تحديد مجالات الاهتمام في الكود المصدري:** يشجع على التحقيق والتحقق المركز بدلاً من تصنيف كل شيء بشكل عشوائي كخطأ برمجي.
- **تحديد مجالات الاهتمام في مسارات الملفات (الأول من نوعه عالميًا):** يتعرف على الأنماط في مسارات الملفات لتحديد الأقسام ذات الصلة للمراجعة.
- **الاستطلاع على مستوى البرمجيات لتحديد التقنيات المستخدمة:** يحدد تقنيات المشروع، مما يمكّن مراجعي الكود من إجراء فحوصات دقيقة بقواعد مناسبة.
- **تقدير الجهد العلمي الآلي لمراجعة الكود (الأول من نوعه عالميًا):** يوفر نهجًا قابلًا للقياس لتقدير الجهد المطلوب لمراجعة الكود.
- **الفحص المدرك للإطار:** يطبق تلقائيًا قواعد خاصة بالإطار عند اكتشاف إطار المشروع.
- **تقارير تحليل التلوث:** تقارير تدفق التلوث بصيغة HTML لكل منصة مع سمات وضع الهاكر والوضع الاحترافي.
- **RDL (لغة وصف القواعد):** منطق قواعد خارجي يُشار إليه بـ `rdl_ref` ويُنفذ بواسطة خط أنابيب `core/rdl_engine.py` - يدعم البوابات المدركة للملفات، والتعبيرات المنطقية، وملاحظات المشروع، وبيانات المنطق الوصفية المُصدَّرة في التقارير.
- **حالة الفحص / الاستئناف:** حفظ نقاط التفتيش للفحوصات الطويلة والاستئناف بعد الانقطاع.
- **خط أساس الكبت:** إنشاء وتطبيق خط أساس للنتائج الإيجابية الكاذبة المعروفة لكبتها من التقارير المستقبلية.
- **واجهة الويب:** مشغّل فحص قائم على المتصفح مع تغذية وحدة التحكم في الوقت الفعلي ومتصفح مخرجات المهام.
> التحسينات النشطة مستمرة. هناك العديد من الميزات والتحسينات الجديدة المخطط لها للإصدارات القادمة.
لا تتردد في المساهمة نحو تحديث أو إضافة قواعد جديدة والتطوير المستقبلي.
إذا وجدت أي أخطاء، أبلغ عنها إلى [[email protected]](mailto:[email protected]).
التوثيق المفصل: [https://dakshlabs.com/#docs](https://dakshlabs.com/#docs)
---
## البدء
هناك طريقتان لتشغيل Daksh SCRA - اختر ما يناسب سير عملك:
| | الأفضل لـ | الانتقال إلى |
|---|---|---|
| 🌐 **واجهة الويب (Docker)** | أسهل طريقة للبدء - أمر واحد، لوحة تحكم في المتصفح، تقدم الفحص المباشر، ومتصفح التقارير/المخرجات. موصى به لمعظم المستخدمين. | [واجهة الويب (Docker)](#web-ui-docker) |
| 💻 **واجهة سطر الأوامر (Python)** | البرمجة النصية، خطوط أنابيب CI، أو تشغيل الفحوصات بدون Docker. | [إعداد واجهة سطر الأوامر](#cli-setup) |
كلا المسارين يشغّلان نفس محرك الفحص بالضبط - واجهة الويب هي واجهة أمامية للمتصفح فوق نفس واجهة سطر الأوامر، لذا النتائج متطابقة في كلتا الحالتين.
---
## واجهة الويب (Docker)
أسرع طريقة لتشغيل Daksh SCRA هي من خلال واجهة الويب القائمة على المتصفح، التي تُشغَّل بمساعدة بدء Docker المدركة للمضيف. تمنحك مشغّل فحص، وتغذية وحدة تحكم مباشرة، وسجلًا قابلًا للتصفح للتقارير السابقة. تحتاج مساعدة البدء إلى Python 3 (المكتبة القياسية فقط)؛ التطبيق وتبعياته يعملان في Docker.
إعداد Docker يشغّل واجهة الويب وواجهة سطر الأوامر كخدمات مستقلة مبنية من نفس الصورة، لذا يمكنك استخدام أي منهما (أو كليهما) من نفس الحاوية.
### تشغيل واجهة الويب
بعد تنزيل Daksh SCRA من GitHub، **استخرج أرشيف ZIP أولاً**.
افتح طرفية (PowerShell أو Command Prompt على Windows) داخل مجلد
المشروع المستخرج الذي يحتوي على `docker-compose.yml` و `dakshscra.py`.
**شغّل جميع أوامر البدء و Docker Compose أدناه من ذلك المجلد.**
إذا فُتحت طرفيتك في مكان آخر، انتقل إلى المجلد المستخرج أولاً:```text
cd "path/to/extracted/DakshSCRA-folder"
استبدل مسار المثال بموقع التنزيل الفعلي واسم المجلد.
إذا قمت باستنساخ المستودع بدلاً من ذلك، فشغّل cd DakshSCRA من المجلد الأصلي.
يتعرف مساعد بدء التشغيل على Windows وWSL وLinux وmacOS، ثم يقوم بتركيب جذر المضيف وأقراص Windows المتاحة والمجلدات الشائعة للقراءة فقط قبل بدء الحاويات. شغّله على الكمبيوتر الذي يعمل عليه Docker.
Linux أو macOS أو WSL (في المقدمة):```bash python3 tools/start_webui.py
Windows PowerShell أو موجه الأوامر (في المقدمة):```powershell
py tools/start_webui.py
أضف --detach للوضع في الخلفية، أو --dry-run لفحص المسارات المكتشفة.
يتم احترام تجاوزات مسار .env الموجودة. يتم الحفاظ على الحسابات والفحوصات
وحجم وقت التشغيل عند إعادة إنشاء الحاويات.
قد يتطلب Docker Desktop إذنًا لمشاركة مسارات المضيف المحددة. إذا رفض نقطة تركيب، اسمح بذلك الموقع في Docker Desktop وأعد تشغيل المساعد. يرى المتصفح البعيد مجلدات مضيف Docker، وليس محركات حاسوبه الخاص. يتطلب الاكتشاف التلقائي محرك Docker محليًا؛ شغّل المساعد على مضيف المحرك عند استخدام سياق Docker بعيد.
بالنسبة لنقاط التركيب المُهيأة يدويًا، يظل docker compose up --build -d api web متاحًا. يقوم إعداده الأساسي بتركيب المستودع على /scan-targets و
${DAKSH_HOST_MOUNT:-/} على /host/root. استخدم المساعد لاكتشاف محركات أقراص Windows
واختصارات المجلدات الشائعة؛ لا يمكن لـ Compose العادي اكتشاف نظام تشغيل العميل.
ثم افتح http://localhost:8080.
لاستخدام منفذ مختلف:```bash DAKSH_PORT=9090 python3 tools/start_webui.py
أوقف الحزمة باستخدام:```bash
docker compose down
تتطلب واجهة الويب حسابًا. عند أول تشغيل، يتم إنشاء حساب مسؤول أولي من DAKSH_ADMIN_USERNAME / DAKSH_ADMIN_PASSWORD (قم بتعيينهما في .env)؛ إذا تُرك DAKSH_ADMIN_PASSWORD بدون تعيين، يتم إنشاء كلمة مرور عشوائية وطباعتها مرة واحدة في سجل بدء تشغيل API - احفظها، لأنه لا يمكن استعادتها بعد ذلك.
سيُطلب منك تعيين كلمة المرور الخاصة بك (واختياريًا، اسم المستخدم) في أول مرة تسجل فيها الدخول. يمكن لحساب المسؤول إنشاء حسابات إضافية عبر نقطة نهاية API POST /api/v1/auth/users (لا توجد واجهة مستخدم مخصصة لهذا بعد). راجع .env.example للحصول على القائمة الكاملة للإعدادات المتعلقة بالمصادقة (مدة الجلسة، أمان ملفات تعريف الارتباط، CORS).
تحت الغطاء، يظل CLI مصدر الحقيقة - فهو يقوم بكل عمليات الفحص وينشئ كل مخرجات HTML / PDF / JSON. تشغّل واجهة الويب مهمة نشطة واحدة في كل مرة وتلتقط مخرجات كل مهمة مكتملة في runtime/webui/jobs/<job-id>/artifacts/ لتبقى التقارير السابقة قابلة للوصول.
لا تحتاج إلى بيئة Python محلية لاستخدام CLI أيضًا - فهو متاح كخدمة Compose خاصة به، مبنية من نفس الصورة:```bash docker compose run --rm cli -h docker compose run --rm cli -r auto -t /scan-targets/path/to/source
### ما الموجود في الصورة
- خادم FastAPI الخلفي + واجهة الويب الأمامية
- واجهة Daksh SCRA CLI الكاملة، كخدمة منفصلة
- Playwright Chromium، لتوليد ملفات PDF
- وحدات تخزين دائمة `reports/` و `runtime/`
- نقاط تحميل مسارات المضيف حتى تتمكن الفحوصات من الوصول إلى أشجار المصدر من داخل الحاوية
**نقاط التحميل الرئيسية:**
| نقطة التحميل | المسار داخل الحاوية |
|---|---|
| مصدر المشروع | `/app` |
| جذر الفحص الافتراضي (المستودع، أو `DAKSH_SCAN_ROOT`) | `/scan-targets` |
| نظام ملفات المضيف (قرص النظام على Windows) | `/host/root` |
| أقراص Windows/WSL الإضافية | `/host/drives/<letter>` |
| المجلد الرئيسي للمستخدم الحالي | `/host/user` |
| مجلدات المضيف الشائعة | `/host/locations/<name>` |
| `DAKSH_HOST_SOURCE` الاختياري | `/host/source` |