muad-dib

التثبيت | الاستخدام | الميزات | VS Code | CI/CD

النسخة الفرنسية

لماذا MUAD'DIB؟

هجمات سلسلة التوريد على npm و PyPI في انفجار مستمر. اخترق Shai-Hulud أكثر من 25 ألف مستودع في 2025. الأدوات الحالية تكتشف التهديدات لكنها لا تساعدك على الاستجابة.

يجمع MUAD'DIB بين 22 ماسحًا متوازيًا (278 قاعدة كشف)، ومحرك إزالة التعتيم، وتحليل تدفق البيانات بين الوحدات، وتسجيل مركّب (21 قاعدة مركّبة)، وبيئة رملية gVisor/Docker لكشف التهديدات المعروفة والأنماط السلوكية المشبوهة في حزم npm و PyPI. يوجد مصنّف XGBoost في قاعدة الكود لكنه غير مفعّل حاليًا (انظر التقييم).

التموضع

MUAD'DIB هو ماسح مجاني ومفتوح وقابل للتدقيق بالكامل لسلسلة التوريد لـ npm و PyPI. يكتشف التهديدات المعروفة (أكثر من 225,000 مؤشر IOC)، و RCE وقت التثبيت، وتدفقات سرقة الاعتمادات ثم تسريبها، والحمولات المعتّمة، وأنماط سلوكية مشبوهة أخرى — محليًا، دون أي قياس عن بُعد.

مرخّص بموجب AGPL-3.0؛ يتوفر ترخيص تجاري للمنظمات التي تحتاج إلى دمجه في منتج مملوك أو تشغيله كخدمة مستضافة مغلقة (انظر الترخيص).

لا يحاول عمدًا فعل كل شيء — انظر النطاق لمعرفة بالضبط ما يلتقطه وما لا يلتقطه.

النطاق

يكتشف (npm و PyPI): الحزم الخبيثة المعروفة (تطابق الاسم + SHA256 مع IOC)، و typosquats، و RCE وقت التثبيت (سكربتات دورة الحياة preinstall/postinstall، و curl | sh، ووقت استيراد Python، و binding.gyp)، وقراءة الاعتمادات ثم التسريب الشبكي (داخل الملف وعبر الملفات)، والحمولات المعتّمة / عالية الإنتروبيا / محمّلات الواجهة، ومسقِطات الملفات الثنائية (chmod +x + exec/spawn)، وعلامات التهرب من التحليل.

خارج النطاق: الهجمات التي تقتصر على المتصفح (DOM/window، بدون واجهة Node.js)، ومحتويات الملفات الثنائية الأصلية / WASM (بدون تحليل ثنائي)، والحزم غير المعروفة صفرية اليوم (تغذية IOC تفاعلية)، وأنظمة بيئية غير npm/PyPI (RubyGems و Maven و Go). يُعرف التحديد المتعمد لبصمات مكافحة البيئة الرملية والحمولات البعيدة متعددة المراحل كمخاطر نتائج سلبية كاذبة معروفة. التفاصيل الكاملة: نموذج التهديد.

بدون قياس عن بُعد. لا يغادر كودك ونتائج الفحص جهازك أبدًا — MUAD'DIB فقط ينزّل خلاصات استخبارات التهديدات (muaddib update) ولأغراض التسجيل يقرأ بيانات وصفية عامة من سجل npm. تنبيهات Webhook اختيارية.

التثبيت

npm (موصى به)

npm install -g muaddib-scanner

من المصدر

git clone https://github.com/DNSZLSK/muad-dib
cd muad-dib
npm install
npm link

الاستخدام

فحص أساسي

muaddib scan .
muaddib scan /path/to/project

يفحص تبعيات npm (package.json، node_modules) و Python (requirements.txt، setup.py، pyproject.toml).

الوضع التفاعلي

muaddib

تثبيت آمن

muaddib install <package>
muaddib install lodash axios --save-dev
muaddib install suspicious-pkg --force    # فرض التثبيت رغم التهديدات

يفحص الحزم بحثًا عن التهديدات قبل التثبيت. يمنع الحزم الخبيثة المعروفة.

درجة المخاطر

يعرض كل فحص درجة مخاطر من 0-100:

[SCORE] 58/100 [***********---------] HIGH

وضع الشرح

muaddib scan . --explain

يعرض معرف القاعدة، وتقنية MITRE ATT&CK، والمراجع، ودليل الاستجابة لكل كشف.

التصدير

muaddib scan . --json > results.json     # JSON
muaddib scan . --html report.html        # HTML
muaddib scan . --sarif results.sarif     # SARIF (أمان GitHub)

عتبة الخطورة

muaddib scan . --fail-on critical  # الفشل فقط على CRITICAL
muaddib scan . --fail-on high      # الفشل على HIGH و CRITICAL (الافتراضي)

وضع المراقبة الشديدة

muaddib scan . --paranoid

كشف فائق الصرامة بتسامح أقل. يكتشف أي وصول شبكي، وتنفيذ عمليات فرعية، وتقييم كود ديناميكي، والوصول إلى ملفات حساسة.

تنبيهات Webhook

muaddib scan . --webhook "https://discord.com/api/webhooks/..."

تصفية صارمة (v2.1.2): تنبيهات فقط لتطابقات IOC، أو تهديدات مؤكدة بالبيئة الرملية، أو تسريب رموز canary. فرز بالأولوية (v2.10.21): P1 (أحمر، IOC/بيئة رملية/canary)، P2 (برتقالي، درجات عالية/مركّبات)، P3 (أصفر، الباقي).

كشف الشذوذ السلوكي (v2.0)

muaddib scan . --temporal-full     # جميع الميزات الزمنية الأربع
muaddib scan . --temporal          # كشف سكربتات دورة الحياة المفاجئة
muaddib scan . --temporal-ast      # فرق AST بين الإصدارات
muaddib scan . --temporal-publish  # شذوذ تواتر النشر
muaddib scan . --temporal-maintainer # كشف تغيير المشرف

يكتشف هجمات سلسلة التوريد قبل ظهورها في قواعد بيانات IOC من خلال تحليل التغييرات بين إصدارات الحزم. انظر منهجية التقييم للتفاصيل.

البيئة الرملية Docker

muaddib sandbox <package-name>
muaddib sandbox <package-name> --strict

تحليل ديناميكي في حاوية Docker معزولة: strace، tcpdump، فرق نظام الملفات، رموز canary، بيئة مدركة لـ CI، وتحميل مسبق بتصحيح القرد لكشف القنابل الزمنية (تشغيل متعدد عند إزاحات [0h، 72h، 7d]).

أوامر أخرى

muaddib watch .                    # مراقبة في الوقت الفعلي
muaddib daemon                     # وضع الخفي (فحص تلقائي عند npm install)
muaddib update                     # تحديث IOCs (سريع، ~5 ثوانٍ)
muaddib scrape                     # تحديث IOC كامل (~5 دقائق)
muaddib diff HEAD~1                # مقارنة التهديدات مع الالتزام السابق
muaddib init-hooks                 # خطافات ما قبل الالتزام (husky/pre-commit/git)
muaddib scan . --breakdown         # تحليل درجة قابل للشرح
muaddib replay                     # تحقق من الحقيقة الأرضية (90/94 TPR@3، v2.11.48)

الميزات

22 ماسحًا متوازيًا

278 قاعدة كشف

جميع القواعد (273 قاعدة + 5 قاعدة PARANOID) مرتبطة بتقنيات MITRE ATT&CK. انظر SECURITY.md للمرجع الكامل للقواعد.

الحملات المكتشفة

VS Code

إضافة VS Code تفحص مشاريع npm تلقائيًا.

code --install-extension dnszlsk.muaddib-vscode

• MUAD'DIB: Scan Project - فحص المشروع بأكمله
• MUAD'DIB: Scan Current File - فحص الملف الحالي
• الإعدادات: muaddib.autoScan، muaddib.webhookUrl، muaddib.failLevel

انظر vscode-extension/README.md للتوثيق الكامل.

CI/CD

GitHub Actions (Marketplace)

الحد الأدنى (فشل البناء على تهديدات HIGH+، فحص واحد):

name: Security Scan

on: [push, pull_request]

jobs:
  scan:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: DNSZLSK/[email protected]   # pin to a released tag
        with:
          fail-on: 'high'

مع رفع SARIF إلى علامة التبويب الأمان (يتطلب security-events: write؛ يشغّل تمريرة ثانية لإصدار SARIF):

jobs:
  scan:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      security-events: write
    steps:
      - uses: actions/checkout@v4
      - uses: DNSZLSK/[email protected]
        with:
          path: '.'
          fail-on: 'high'
          sarif: 'results.sarif'

المدخلات

المخرجات (استهلكها في خطوات لاحقة عبر steps.<id>.outputs.*)

خطافات ما قبل الالتزام

muaddib init-hooks                        # كشف تلقائي (husky/pre-commit/git)
muaddib init-hooks --type husky           # فرض husky
muaddib init-hooks --mode diff            # حظر التهديدات الجديدة فقط

مع إطار pre-commit:

repos:
  - repo: https://github.com/DNSZLSK/muad-dib
    rev: v2.11.139
    hooks:
      - id: muaddib-scan

التقييم

آخر قياس v2.11.48 (2026-05-26)، قواعد فقط (مصنّف التعلم الآلي غير مفعّل — انظر أدناه). الحقيقة الأرضية: 94 هجومًا حقيقيًا داخل النطاق + 200 npm عشوائي + 124 PyPI + 107 عدائي/احتياطي.

مصنّف التعلم الآلي: غير مفعّل. يوجد نموذج XGBoost في src/ml/ لكنه غير موصول أبدًا بـ muaddib scan، ويعمل في وضع LOG-ONLY في المراقب منذ 2026-04-08 (النموذج المدرب انهار، بانتظار إعادة التدريب). جميع الأرقام أعلاه قواعد فقط.

البروتوكول الكامل، وتاريخ كل مسار، وملاحظة سقف PyPI البالغ 35، والتغطية التشغيلية (المعتمدة على GHSA)، ومنهجية إعادة تدريب التعلم الآلي: منهجية التقييم.

المساهمة

إضافة IOCs

حرّر ملفات YAML في iocs/:

- id: NEW-MALWARE-001
  name: "malicious-package"
  version: "*"
  severity: critical
  confidence: high
  source: community
  description: "Threat description"
  references:
    - https://example.com/article
  mitre: T1195.002

التطوير

git clone https://github.com/DNSZLSK/muad-dib
cd muad-dib
npm install
npm test

الاختبار

• 4545 اختبارًا عبر 155 ملف اختبار معياري
• 56 اختبار تشويش - مدخلات مشوهة، ReDoS، يونيكود، ثنائي
• معيار Datadog 17K - 14,587 عينة برمجيات خبيثة مؤكدة (داخل النطاق)
• تحقق الحقيقة الأرضية - 96 هجومًا حقيقيًا (95.74% TPR@3، 88.30% TPR@20 — قياس v2.11.48 الكامل على 94 داخل النطاق)
• تحقق الإيجابيات الكاذبة (قياس v2.11.48) - 1.10% FPR للقواعد (6/545 مفحوصة)، 2.50% على 200 عشوائي، 9.68% على 124/132 PyPI (أول قياس صادق بعد إصلاح تنزيل Track-D). مصنّف التعلم الآلي غير مفعّل حاليًا — انظر مقاييس التقييم ← مصنّف التعلم الآلي.

المجتمع

• Discord: https://discord.gg/y8zxSmue

التوثيق

• المدونة - مقالات تقنية حول كشف تهديدات سلسلة التوريد
• Carnet de bord - دفتر التطوير (بالفرنسية)
• فهرس التوثيق - جميع التوثيق في مكان واحد
• منهجية التقييم - البروتوكول التجريبي، درجات الاحتياطي
• نموذج التهديد - ما يكتشفه MUAD'DIB وما لا يكتشفه
• سياسة الأمان - مرجع قواعد الكشف (278 قاعدة)
• تدقيق الأمان - تقرير تحقق الالتفاف
• تحليل FP - تحليل الإيجابيات الكاذبة التاريخي

الترخيص

MUAD'DIB مرخّص بموجب GNU Affero General Public License v3.0 فقط (AGPL-3.0-only) — انظر LICENSE و NOTICE.

أنت حر في استخدامه ودراسته وتعديله وإعادة توزيعه — بما في ذلك عبر الشبكة — بشرط إصدار الأعمال المشتقة والتعديلات المنشورة عبر الشبكة بموجب نفس الترخيص.

الترخيص التجاري: لدمج MUAD'DIB في منتج مملوك / مغلق المصدر، أو لتقديمه كخدمة مستضافة دون التزامات الكشف عن المصدر في AGPL، يتوفر ترخيص تجاري منفصل. افتح مشكلة أو تواصل مع المؤلف (DNSZLSK).

حقوق النشر (C) 2026 DNSZLSK.

يجب أن تتدفق التوابل. يجب أن تموت الديدان.