muad-dib v2.12.0

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

Version francaise

Warum MUAD'DIB?

Angriffe auf die Lieferkette von npm und PyPI explodieren. Shai-Hulud kompromittierte 2025 über 25.000+ Repositories. Bestehende Tools erkennen Bedrohungen, helfen aber nicht bei der Reaktion.

MUAD'DIB kombiniert 22 parallele Scanner (278 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 existiert im Code, ist aber derzeit inaktiv (siehe Evaluierung).

Positionierung

MUAD'DIB ist ein kostenloser, offener und vollständig prüfbarer Lieferketten-Scanner für npm und PyPI. Er erkennt bekannte Bedrohungen (225.000+ IOCs), RCE bei der Installation, Credential-Diebstahl mit anschließender Exfiltration, 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 verfügbar, die ihn in ein proprietäres Produkt einbetten oder als geschlossenen gehosteten Dienst betreiben müssen (siehe Lizenz).

Er versucht bewusst nicht, alles zu tun — siehe Umfang für genau das, was er erkennt und was nicht.

Umfang

Erkennt (npm & PyPI): bekannte bösartige Pakete (Name + SHA256-IOC-Abgleich), Typosquats, RCE bei der Installation (Lifecycle preinstall/postinstall, curl | sh, Python-Import-Zeit, binding.gyp), Credential-Lesen mit anschließender Netzwerk-Exfiltration (innerhalb und zwischen Dateien), obfuskierte / High-Entropy- / Stub-Loader-Payloads, binäre Dropper (chmod +x + exec/spawn) und Anti-Analyse-Evasion-Marker.

Außerhalb des Umfangs: Browser-only-Angriffe (DOM/window, keine Node.js-API), der Inhalt nativer Binärdateien / WASM (keine Binäranalyse), Zero-Day-unbekannte Pakete (der IOC-Feed ist reaktiv) und Nicht-npm/PyPI-Ökosysteme (RubyGems, Maven, Go). Entschlossenes Anti-Sandbox-Fingerprinting und mehrstufige Remote-Payloads sind bekannte False-Negative-Risiken. Vollständige Details: Bedrohungsmodell.

Keine Telemetrie. Ihr Code und Ihre Scan-Ergebnisse verlassen niemals Ihren Rechner — MUAD'DIB lädt nur Threat-Intel-Feeds 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:

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

Erklärungsmodus

muaddib scan . --explain

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

Export

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

Schweregrad-Schwelle

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

Paranoider Modus

muaddib scan . --paranoid

Ultra-strikte Erkennung mit geringerer Toleranz. Erkennt jeden Netzwerkzugriff, jede Subprozess-Ausführung, jede dynamische Code-Auswertung und jeden Zugriff auf sensible Dateien.

Webhook-Benachrichtigungen

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

Strikte Filterung (v2.1.2): Benachrichtigungen nur bei IOC-Treffern, sandbox-bestätigten Bedrohungen oder Canary-Token-Exfiltration. Priorisierte Triage (v2.10.21): P1 (rot, IOC/Sandbox/Canary), P2 (orange, hohe Bewertung/zusammengesetzt), 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-Diff zwischen Versionen
muaddib scan . --temporal-publish  # Anomalie der Veröffentlichungshäufigkeit
muaddib scan . --temporal-maintainer # Erkennung von Maintainer-Wechseln

Erkennt Lieferketten-Angriffe bevor sie in IOC-Datenbanken erscheinen, durch Analyse von Änderungen zwischen Paketversionen. Details siehe Evaluierungsmethodik.

Docker-Sandbox

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

Dynamische Analyse in einem isolierten Docker-Container: strace, tcpdump, Dateisystem-Diff, Canary-Tokens, CI-bewusste Umgebung und Monkey-Patching-Preload für Zeitbomben-Erkennung (mehrfache Ausführung bei [0h, 72h, 7d] Offsets).

Andere 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 Bewertungs-Zerlegung
muaddib replay                     # Ground-Truth-Validierung (90/94 TPR@3, v2.11.48)

Funktionen

22 parallele Scanner

278 Erkennungsregeln

Alle Regeln (273 REGELN + 5 PARANOID) sind MITRE-ATT&CK-Techniken zugeordnet. Die vollständige Regeln-Referenz finden Sie in SECURITY.md.

Erkannte Kampagnen

VS Code

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

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

Vollständige Dokumentation finden Sie in vscode-extension/README.md.

CI/CD

GitHub Actions (Marketplace)

Minimal (Build bei HOCH+-Bedrohungen fehlschlagen lassen, einzelner Scan):

name: Security Scan

on: [push, pull_request]

jobs:
  scan:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: DNSZLSK/[email protected]   # auf ein veröffentlichtes Tag pinnen
        with:
          fail-on: 'high'

Mit SARIF-Upload auf den Security-Tab (benötigt security-events: write; führt einen zweiten Durchlauf zur SARIF-Erzeugung aus):

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'

Eingaben

Ausgaben (in späteren Schritten über steps.<id>.outputs.* konsumierbar)

Pre-Commit-Hooks

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

Mit dem 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 im Umfang liegende reale Angriffe + 200 zufällige npm + 124 PyPI + 107 adversariale/Holdout.

ML-Klassifikator: inaktiv. Ein XGBoost-Modell liegt in src/ml/ vor, ist aber nie in muaddib scan eingebunden und läuft seit 2026-04-08 nur im LOG-ONLY-Modus im Monitor (das trainierte Modell kollabierte, Neuschulung ausstehend). Alle obigen Zahlen sind nur Regeln.

Vollständiges Protokoll, Verlauf pro Track, der PyPI-Cap-35-Vorbehalt, operative (GHSA-denominierte) Abdeckung und die ML-Neuschulungsmethodik: Evaluierungsmethodik.

Mitwirken

IOCs hinzufügen

YAML-Dateien in iocs/ bearbeiten:

- 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

Entwicklung

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

Testen

• 4545 Tests über 155 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 auf 94 im Umfang)
• False-Positive-Validierung (v2.11.48-Messung) - 1,10% FPR-Regeln (6/545 gescannt), 2,50% auf 200 zufällige, 9,68% auf 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 Lieferketten-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 (278 Regeln)
• Sicherheitsaudit - Bypass-Validierungsbericht
• FP-Analyse - Historische False-Positive-Analyse

Lizenz

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

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

Kommerzielle Lizenzierung: Zur Einbettung von MUAD'DIB in ein proprietäres / Closed-Source-Produkt oder zur Bereitstellung als gehosteter Dienst ohne die Quelloffenlegungspflichten der AGPL ist eine separate kommerzielle Lizenz erhältlich. Öffnen Sie ein Issue oder kontaktieren Sie den Autor (DNSZLSK).

Copyright (C) 2026 DNSZLSK.

The spice must flow. The worms must die.