muad-dib

Installation | Verwendung | Funktionen | VS Code | CI/CD

Version française

Warum MUAD'DIB?

Supply-Chain-Angriffe auf npm und PyPI explodieren. Shai-Hulud hat 2025 über 25.000 Repositories kompromittiert. Bestehende Tools erkennen Bedrohungen, helfen aber nicht bei der Reaktion.

MUAD'DIB kombiniert 22 parallele Scanner (277 Erkennungsregeln), eine Deobfuskierungs-Engine, modulübergreifende Datenflussanalyse, zusammengesetzte Bewertung (21 zusammengesetzte Regeln) und eine gVisor/Docker-Sandbox, um bekannte Bedrohungen und verdächtige Verhaltensmuster in npm- und PyPI-Paketen zu erkennen. Ein XGBoost-Klassifikator ist im Code vorhanden, aber derzeit inaktiv (siehe Evaluierung).

Positionierung

MUAD'DIB ist ein kostenloser, offener und vollständig prüfbarer Supply-Chain-Scanner für npm und PyPI. Er erkennt bekannte Bedrohungen (225.000+ IOCs), Installationszeit-RCE, Credential-Exfiltration-Abläufe, obfuskierte Payloads und andere verdächtige Verhaltensmuster – lokal, ohne Telemetrie.

Er ist unter der AGPL-3.0 lizenziert; eine kommerzielle Lizenz ist für Organisationen erhältlich, die ihn in ein proprietäres Produkt einbetten oder als geschlossenen Hosted-Dienst betreiben müssen (siehe Lizenz).

Er versucht bewusst nicht, alles zu können – siehe Umfang für eine genaue Auflistung, was er erfasst und was nicht.

Umfang

Erkennt (npm & PyPI): bekanntermaßen bösartige Pakete (Name + SHA256 IOC-Übereinstimmung), Typosquats, Installationszeit-RCE (Lifecycle preinstall/postinstall, curl | sh, Python-Import-Zeitpunkt, binding.gyp), Credential-Lesen und anschließende Netzwerk-Exfiltration (innerhalb und zwischen Dateien), obfuskierte / hochentropische / Stub-Loader-Payloads, binäre Dropper (chmod +x + exec/spawn) und Anti-Analyse-Ausweichmerkmale.

Nicht im Fokus: reine Browser-Angriffe (DOM/window, keine Node.js-API), die Inhalte nativer Binärdateien / WASM (keine Binäranalyse), Zero-Day-unbekannte Pakete (der IOC-Feed ist reaktiv) und nicht-npm/PyPI-Ökosysteme (RubyGems, Maven, Go). Gezieltes Anti-Sandbox-Fingerprinting und mehrstufige Remote-Payloads sind bekannte Risiken für falsch-negative Ergebnisse. Vollständige Details: Bedrohungsmodell.

Keine Telemetrie. Ihr Code und Ihre Scan-Ergebnisse verlassen niemals Ihren Rechner – MUAD'DIB lädt nur Bedrohungsinformationen herunter (muaddib update) und liest für die Bewertung öffentliche npm-Registry-Metadaten. Webhook-Benachrichtigungen sind optional.

Installation

npm (empfohlen)

npm install -g muaddib-scanner

Aus dem Quellcode

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

Verwendung

Grundlegender Scan

muaddib scan .
muaddib scan /path/to/project

Scannt sowohl npm- (package.json, node_modules) als auch Python-Abhängigkeiten (requirements.txt, setup.py, pyproject.toml).

Interaktiver Modus

muaddib

Sichere Installation

muaddib install <package>
muaddib install lodash axios --save-dev
muaddib install suspicious-pkg --force    # Installation trotz Bedrohungen erzwingen

Scannt Pakete auf Bedrohungen VOR der Installation. Blockiert bekannte bösartige Pakete.

Risikobewertung

Jeder Scan zeigt eine Risikobewertung von 0-100 an:

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

Erklärungsmodus

muaddib scan . --explain

Zeigt Regel-ID, MITRE ATT&CK-Technik, Referenzen und Reaktions-Playbook für jede Erkennung an.

Export

muaddib scan . --json > results.json     # JSON
muaddib scan . --html report.html        # HTML
muaddib scan . --sarif results.sarif     # SARIF (GitHub Security)

Schweregrad-Schwellenwert

muaddib scan . --fail-on critical  # Nur bei KRITISCH fehlschlagen
muaddib scan . --fail-on high      # Bei HOCH und KRITISCH fehlschlagen (Standard)

Paranoid-Modus

muaddib scan . --paranoid

Ultra-strenge Erkennung mit niedrigerer Toleranz. Erkennt jeglichen Netzwerkzugriff, Subprozessausführung, dynamische Codeauswertung und Zugriff auf sensible Dateien.

Webhook-Benachrichtigungen

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

Strenge Filterung (v2.1.2): Benachrichtigungen nur bei IOC-Übereinstimmungen, sandboxbestätigten Bedrohungen oder Canary-Token-Exfiltration. Priorisierte Triage (v2.10.21): P1 (rot, IOC/Sandbox/Canary), P2 (orange, hohe Bewertung/zusammengesetzte), P3 (gelb, Rest).

Erkennung von Verhaltensanomalien (v2.0)

muaddib scan . --temporal-full     # Alle 4 zeitlichen Merkmale
muaddib scan . --temporal          # Erkennung plötzlicher Lifecycle-Skripte
muaddib scan . --temporal-ast      # AST-Differenz zwischen Versionen
muaddib scan . --temporal-publish  # Anomalie der Veröffentlichungshäufigkeit
muaddib scan . --temporal-maintainer # Erkennung von Maintainer-Wechseln

Erkennt Supply-Chain-Angriffe bevor sie in IOC-Datenbanken auftauchen, durch Analyse von Änderungen zwischen Paketversionen. Siehe Evaluierungsmethodik für Details.

Docker-Sandbox

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

Dynamische Analyse in einem isolierten Docker-Container: strace, tcpdump, Dateisystem-Diff, Canary-Token, CI-bewusste Umgebung und Monkey-Patching-Preload für Zeitbombenerkennung (mehrere Läufe zu [0h, 72h, 7d] Offsets).

Weitere Befehle

muaddib watch .                    # Echtzeit-Überwachung
muaddib daemon                     # Daemon-Modus (automatischer Scan bei npm install)
muaddib update                     # IOCs aktualisieren (schnell, ~5s)
muaddib scrape                     # Vollständige IOC-Aktualisierung (~5min)
muaddib diff HEAD~1                # Bedrohungen mit vorherigem Commit vergleichen
muaddib init-hooks                 # Pre-Commit-Hooks (husky/pre-commit/git)
muaddib scan . --breakdown         # Erklärbare Bewertungszerlegung
muaddib replay                     # Ground-Truth-Validierung (90/94 TPR@3, v2.11.48)

Funktionen

22 parallele Scanner

277 Erkennungsregeln

Alle Regeln (272 REGELN + 5 PARANOID) sind MITRE ATT&CK-Techniken zugeordnet. Siehe SECURITY.md für die vollständige Referenz der Regeln.

Erkannte Kampagnen

VS Code

Die VS Code-Erweiterung scannt automatisch Ihre npm-Projekte.

code --install-extension dnszlsk.muaddib-vscode

• MUAD'DIB: Scan Project – Gesamtes Projekt scannen
• MUAD'DIB: Scan Current File – Aktuelle Datei scannen
• Einstellungen: muaddib.autoScan, muaddib.webhookUrl, muaddib.failLevel

Siehe vscode-extension/README.md für die vollständige Dokumentation.

CI/CD

GitHub Actions (Marketplace)

name: Security Scan

on: [push, pull_request]

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

Pre-Commit-Hooks

muaddib init-hooks                        # Auto-Erkennung (husky/pre-commit/git)
muaddib init-hooks --type husky           # Husky erzwingen
muaddib init-hooks --mode diff            # Nur NEUE Bedrohungen blockieren

Mit pre-commit-Framework:

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

Evaluierung

Zuletzt gemessen v2.11.48 (2026-05-26), nur Regeln (der ML-Klassifikator ist inaktiv – siehe unten). Ground Truth: 94 reale Angriffe im Umfang + 200 zufällige npm + 124 PyPI + 107 adversarial/holdout.

ML-Klassifikator: inaktiv. Ein XGBoost-Modell befindet sich in src/ml/, ist aber nie in muaddib scan eingebunden und läuft seit 2026-04-08 im LOG-ONLY-Modus des Monitors (das trainierte Modell ist kollabiert, steht vor einem Retraining). Alle Zahlen oben sind nur Regeln.

Vollständiges Protokoll, Verlauf pro Track, die PyPI-Cap-35-Einschränkung, operative (GHSA-denominierte) Abdeckung und die ML-Retrain-Methodik: Evaluierungsmethodik.

Mitwirken

IOCs hinzufügen

Bearbeiten Sie YAML-Dateien in iocs/:

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

Entwicklung

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

Tests

• 4545 Tests über 152 modulare Testdateien
• 56 Fuzz-Tests – Fehlerhafte Eingaben, ReDoS, Unicode, Binär
• Datadog-17K-Benchmark – 14.587 bestätigte Malware-Beispiele (im Umfang)
• Ground-Truth-Validierung – 96 reale Angriffe (95,74 % TPR@3, 88,30 % TPR@20 – v2.11.48 vollständige Messung an 94 im Umfang)
• False-Positive-Validierung (v2.11.48-Messung) – 1,10 % FPR-Regeln (6/545 gescannt), 2,50 % bei 200 zufälligen, 9,68 % bei 124/132 PyPI (erste ehrliche Messung nach Track-D-Download-Fix). ML-Klassifikator derzeit inaktiv – siehe Evaluierungsmetriken → ML-Klassifikator.

Community

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

Dokumentation

• Blog – Technische Artikel zur Supply-Chain-Bedrohungserkennung
• Carnet de bord – Entwicklungstagebuch (auf Französisch)
• Dokumentationsindex – Alle Dokumentation an einem Ort
• Evaluierungsmethodik – Experimentelles Protokoll, Holdout-Ergebnisse
• Bedrohungsmodell – Was MUAD'DIB erkennt und nicht erkennt
• Sicherheitsrichtlinie – Referenz der Erkennungsregeln (277 Regeln)
• Sicherheitsaudit – Bypass-Validierungsbericht
• FP-Analyse – Historische False-Positive-Analyse

Lizenz

MUAD'DIB ist lizenziert unter der GNU Affero General Public License v3.0 only (AGPL-3.0-only) – siehe LICENSE und NOTICE.

Sie dürfen es frei nutzen, studieren, modifizieren und weiterverbreiten – auch über ein Netzwerk – vorausgesetzt, dass abgeleitete Werke und netzwerkbereitgestellte Modifikationen unter derselben Lizenz veröffentlicht werden.

Kommerzielle Lizenzierung: zur Einbettung von MUAD'DIB in ein proprietäres / quellgeschlossenes Produkt oder um es als Hosted-Dienst ohne die Quelloffenlegungspflichten der AGPL anzubieten, ist eine separate kommerzielle Lizenz erhältlich. Eröffnen Sie ein Issue oder kontaktieren Sie den Autor (DNSZLSK).

Copyright (C) 2026 DNSZLSK.

Das Gewürz muss fließen. Die Würmer müssen sterben.