## حول 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 Compose واحد. تمنحك مشغل فحص، وتغذية وحدة تحكم مباشرة، وسجلاً قابلاً للتصفح للتقارير السابقة، دون الحاجة إلى بيئة Python محلية.

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

### تشغيل واجهة الويب

وضع المقدمة (تتدفق السجلات إلى الطرفية):```bash
docker compose up --build

ثم افتح [http://localhost:8080](http://localhost:8080).

لاستخدام منفذ مختلف:```bash
DAKSH_PORT=9090 docker compose up

### تسجيل الدخول

تتطلب واجهة الويب حسابًا. عند أول تشغيل، يتم إنشاء حساب مسؤول أولي من `DAKSH_ADMIN_USERNAME` / `DAKSH_ADMIN_PASSWORD` (قم بتعيينهما في `.env`)؛ إذا تُرك `DAKSH_ADMIN_PASSWORD` غير معيّن، يتم إنشاء كلمة مرور عشوائية وطباعتها مرة واحدة في سجل بدء تشغيل API - احفظها، حيث لا يمكن استعادتها لاحقًا.

سيُطلب منك تعيين كلمة المرور الخاصة بك (واختياريًا اسم المستخدم) في أول مرة تسجل فيها الدخول. يمكن لحساب المسؤول إنشاء حسابات إضافية عبر نقطة نهاية API `POST /api/v1/auth/users` (لا توجد واجهة مخصصة لهذا بعد). راجع `.env.example` للحصول على القائمة الكاملة لإعدادات المصادقة (مدة الجلسة، أمان ملفات تعريف الارتباط، CORS).

### ما ستحصل عليه

- منشئ أوامر متجاوب لأوضاع الفحص، والاستطلاع، والتقدير، والاستطلاع+التقدير، والقائمة، وPDF من JSON
- بث وحدة التحكم في الوقت الفعلي وتقدم مباشر لكل مرحلة أثناء التنفيذ
- لقطات مصنّفة لكل مهمة لمخرجات HTML / PDF / JSON
- تنقل سريع داخل المتصفح عبر نموذج التشغيل، والبث المباشر، والملفات المصنّفة، والمهام الأخيرة
- متصفح أدلة مدمج لاختيار مسارات الهدف (مراعٍ لنظام التشغيل: Windows، macOS، Linux / Docker)

تحت الغطاء، يظل CLI هو مصدر الحقيقة - فهو يقوم بكل الفحص ويولّد كل مخرجات HTML / PDF / JSON. تشغّل واجهة الويب مهمة نشطة واحدة في كل مرة وتلتقط لقطات لمخرجات كل مهمة مكتملة في `runtime/webui/jobs/<job-id>/artifacts/` بحيث تبقى التقارير السابقة قابلة للوصول.

### تشغيل CLI في Docker

لا تحتاج إلى بيئة Python محلية لاستخدام CLI أيضًا - فهو متاح كخدمة Compose خاصة به، مبنية من نفس الصورة:```bash
docker compose run --rm cli -h
docker compose run --rm cli -r auto -t /scan-targets/path/to/source

أو قم بتنزيل أحدث ملف مضغوط من [https://github.com/coffeeandsecurity/DakshSCRA](https://github.com/coffeeandsecurity/DakshSCRA) وفك ضغطه.

### 2. إعداد بيئة افتراضية

> 💡 يمكن إنشاء البيئة الافتراضية في أي مجلد - لا يلزم أن تكون داخل مجلد DakshSCRA.

**الخيار أ: الإعداد بخطوة واحدة (موصى به)**```bash
python setup_env.py

macOS / Linux:```bash
python3 -m venv daksh-env
source daksh-env/bin/activate

---

## استخدام سطر الأوامر

استخدم `python` داخل بيئة افتراضية، أو `python3` خارجها.

### خيارات سطر الأوامر```
usage: dakshscra.py [-h] [-r RULES] [-f FILE_TYPES] [-v] [-t TARGET_DIR]
                    [-l {R,RF}] [--recon] [--rs] [--estimate]
                    [-rpt FORMATS] [--pdf-from-json]
                    [--json-input-dir PATH] [--pdf-output PATH]
                    [--pdf-multi-dir PATH] [--pdf-single-only]
                    [--skip-analysis] [--loc]
                    [--baseline-file PATH] [--baseline-generate] [--no-baseline]
                    [--review-config PATH]
                    [--resume-scan] [--state-file PATH] [--no-state] [--state]

### قواعد وأُطر المنصات المدعومة```bash
python dakshscra.py -l R    # List platform rules and framework mappings
python dakshscra.py -l RF   # List platform rules, framework mappings, and filetypes

---

## مرجع الإعدادات

### `config/tool.yaml`

يتم التحكم في الإعدادات الافتراضية لوقت تشغيل Daksh SCRA من خلال `config/tool.yaml`.```yaml
state_management:
  enabled: false
  resume_mode: manual
  persist_after_seconds: 300
  persist_interval_seconds: 30
  default_state_file: runtime/scan_state.json
  cleanup_on_success: false

analysis:
  run_by_default: true
  include_frameworks: true
  report_theme: hacker_mode

#### تسلسل الفحص

بالنسبة لقاعدة المصدر، يقوم DakshSCRA بتقييم المنطق بهذا الترتيب:

1. يقوم Recon باختيار المنصات والأطر المطابقة.
2. يتم تحميل قاعدة XML من `rules/scanning/platform/...`.
3. يقوم `regex` بالعثور على الأسطر المرشحة أو مطابقات الملف الكامل عند وجودها.
4. يقوم `exclude` بإزالة الضوضاء الواضحة لتلك القاعدة، إذا كانت موجودة.
5. يتم تقييم ملف `.rdl` الخارجي من `rdl_ref` مقابل نص الملف الحالي، ومسار الملف الحالي، وجذر المشروع.
6. إذا نجح سكربت RDL، يحتفظ DakshSCRA بالنتيجة ويدمج بيانات تعريف المنطق المُصدَّرة في مخرجات التقرير.
7. إذا فشل سكربت RDL، يتم كتم المطابقة مع سبب فشل RDL وبيانات تعريف تتبع القرار.

بالنسبة لقواعد مسارات الملفات في `filepaths.xml`، ينطبق نفس نموذج `rdl_ref`، لكن موضوع المطابقة هو
المسار النسبي المُطبَّع بدلاً من نص الكود المصدري. في هذا الوضع، يستقبل RDL سلسلة المسار النسبي
كنص الملف الحالي وسياق المسار.

#### هيكل القاعدة الحالي```xml
<rule>
  <name>Rule Name</name>
  <regex><![CDATA[regex_to_match]]></regex>
  <rdl_ref>logic/common/core/insecure_sql_query_unsafe_string_concatenation.rdl</rdl_ref>
  <exclude><![CDATA[pattern_to_exclude_lines]]></exclude>  <!-- optional -->
  <scan_config>...</scan_config>                           <!-- optional -->
  <rule_desc>Short description of what the rule detects.</rule_desc>
  <vuln_desc>Why the pattern matters.</vuln_desc>
  <developer>Fix guidance for developers.</developer>
  <reviewer>Manual confirmation guidance for reviewers.</reviewer>
</rule>

#### التخطيط الحالي```text
rules/
└── scanning/
    ├── platform/
    │   ├── php/php.xml
    │   ├── java/java.xml
    │   └── ...
    └── logic/
        ├── common/core/
        ├── php/core/
        ├── php/framework/laravel/
        ├── mobile/android/core/
        ├── filepaths/core/
        └── ...

ترجمة:

RDL الخارجي:```text
VERSION 1
WHEN PRESENT /\b(?:mysql_query|mysqli_query|->query)\s*\(/i
WHEN EXPR PRESENT:\$_(GET|POST|REQUEST|COOKIE) && MISSING:\b(?:prepare|bindParam|bindValue|PDO::prepare)\b
REPORT AS area_of_interest
REASON Query execution appears to rely on direct input without parameterisation.
FAIL_REASON Query API matched, but parameterised query indicators were also found in the file.

External RDL:```text
VERSION 1
WHEN FILE_NAME_IS AndroidManifest.xml
WHEN CURRENT_FILE_MATCHES /android:exported\s*=\s*"true"/i
WHEN MISSING /android:permission\s*=\s*"/i
REPORT AS area_of_interest
REASON Exported component appears reachable without a permission guard.

ترجمة المحتوى:

RDL الخارجي:```text
VERSION 1
WHEN CURRENT_FILE_MATCHES /(^|\/)(admin|administrator|root)(\/|$)/i
UNLESS CURRENT_FILE_MATCHES /(^|\/)(tests?|docs?|samples?|examples?)(\/|$)/i
REPORT AS area_of_interest
REASON File path suggests privileged application functionality.
FAIL_REASON Path matched an excluded documentation or sample location.

تُكتب ملفات التشغيل (حالة الفحص، السجلات، المخزون) تحت `runtime/`.

عند التشغيل عبر واجهة الويب، يتم أيضًا التقاط لقطات من مخرجات كل وظيفة تحت `runtime/webui/jobs/<job-id>/artifacts/` (انظر [واجهة الويب (Docker)](#web-ui-docker)).

---

## المؤلف

| | |
|---|---|
| الموقع الإلكتروني | [coffeeandsecurity.com](https://www.coffeeandsecurity.com) |
| البريد الإلكتروني | [email protected] |
| تويتر / X | [@coffeensecurity](https://x.com/coffeensecurity) |
| المصدر | [github.com/coffeeandsecurity/DakshSCRA](https://github.com/coffeeandsecurity/DakshSCRA) |
| الترخيص | رخصة جنو العمومية العامة الإصدار 3.0 (GPL-3.0) |

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

وجدت خطأ أو تريد المساهمة؟ افتح مشكلة (issue) أو طلب سحب (pull request) على GitHub.