muad-dib — Echtzeit-Bedrohungserkennung für npm/PyPI-Lieferketten. Verhaltenskettenanalyse, AST-Scanning, IOC-Feeds und kombinierte Bewertungs-Engine. | Kitploit
<p align="center">
  <img src="https://assets.kitploit.com/production/public/readmes/10373/84132538a800a2879cff088259fe9e98e975a3fe37f8462fe731d6a06f82314a.png" alt="MUAD'DIB Logo" width="700">
</p>

<p align="center">
  <a href="https://www.npmjs.com/package/muaddib-scanner"><img src="https://img.shields.io/npm/v/muaddib-scanner" alt="npm version"></a>
  <a href="https://github.com/DNSZLSK/muad-dib/actions/workflows/scan.yml"><img src="https://github.com/DNSZLSK/muad-dib/actions/workflows/scan.yml/badge.svg" alt="CI"></a>
  <a href="https://codecov.io/gh/DNSZLSK/muad-dib"><img src="https://codecov.io/gh/DNSZLSK/muad-dib/branch/master/graph/badge.svg" alt="Coverage"></a>
  <a href="https://scorecard.dev/viewer/?uri=github.com/DNSZLSK/muad-dib"><img src="https://api.scorecard.dev/projects/github.com/DNSZLSK/muad-dib/badge" alt="OpenSSF Scorecard"></a>
  <img src="https://img.shields.io/badge/license-AGPL--3.0--only-blue" alt="License">
  <img src="https://img.shields.io/badge/node-%3E=18-brightgreen" alt="Node">
  <img src="https://img.shields.io/badge/IOCs-225,000+-red" alt="IOCs">
</p>

<p align="center">
  <a href="#installation">Installation</a> |
  <a href="#usage">Verwendung</a> |
  <a href="#features">Funktionen</a> |
  <a href="#vs-code">VS Code</a> |
  <a href="#cicd">CI/CD</a>
</p>

<p align="center">
  <a href="https://github.com/dnszlsk/muad-dib/blob/master/docs/README.fr.md">Version francaise</a>
</p>

---

## 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 **<!--stat:scanners-->22<!--/stat:scanners--> parallele Scanner** (<!--stat:rulesTotal-->278<!--/stat:rulesTotal--> Erkennungsregeln), eine **Deobfuskierungs-Engine**, **modulübergreifende Datenflussanalyse**, **zusammengesetzte Bewertung** (<!--stat:compound-->21<!--/stat:compound--> 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](#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](#lizenz)).

Er versucht bewusst nicht, alles zu tun — siehe [Umfang](#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](https://github.com/dnszlsk/muad-dib/blob/master/docs/threat-model.md).

**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)

```bash
npm install -g muaddib-scanner
```

### Aus dem Quellcode

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

---

## Verwendung

### Grundlegender Scan

```bash
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

```bash
muaddib
```

### Sichere Installation

```bash
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

```bash
muaddib scan . --explain
```

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

### Export

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

### Schweregrad-Schwelle

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

### Paranoider Modus

```bash
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

```bash
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)

```bash
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](https://github.com/dnszlsk/muad-dib/blob/master/docs/EVALUATION_METHODOLOGY.md).

### Docker-Sandbox

```bash
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

```bash
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

### <!--stat:scanners-->22<!--/stat:scanners--> parallele Scanner

| Scanner | Erkennung |
|---------|-----------|
| AST-Parse (acorn) | eval, Function, Credential-Diebstahl, binäre Dropper, Prototype-Hooks |
| Musterabgleich | Shell-Befehle, Reverse Shells, Dead Man's Switch |
| Datenflussanalyse | Credential-Lesen + Netzwerk-Senden (innerhalb und zwischen Dateien) |
| Obfuskations-Erkennung | JS-Obfuskationsmuster (.min.js überspringen) |
| Deobfuskierungs-Vorverarbeitung | String-Konkatenation, Charcode, base64, Hex-Array, Konstante-Propagation |
| Modulübergreifender Datenfluss | Dateiübergreifende Taint-Propagation (3-Hop-Ketten, Klassenmethoden) |
| Intent-Kohärenz | Quell-Senke-Paarung innerhalb einer Datei (Credential + eval/Netzwerk) |
| Typosquatting | npm + PyPI (Levenshtein-Distanz) |
| Python-Scanner | requirements.txt, setup.py, pyproject.toml, 14K+ PyPI-IOCs |
| Shannon-Entropie | High-Entropy-Strings (5,5 Bits + mind. 50 Zeichen) |
| KI-Konfigurations-Scanner | .cursorrules, CLAUDE.md, copilot-instructions.md-Injektion |
| Paket/Abhängigkeiten | Lifecycle-Skripte, IOC-Abgleich (225K+ Pakete) |
| GitHub Actions | Shai-Hulud-Backdoor-Erkennung |
| Hash-Scanner | Bekannte bösartige Datei-Hashes |
| IOC-Strings (intel-triage P1.1) | YARA-artiger String-Abgleich (Axios 2026, TeamPCP, GlassWorm, CanisterSprawl) |
| Anti-Forensik-AST (intel-triage P1.2) | XOR-Schleife + Selbstlöschung + Köder-Schreibvorgang zusammengesetzt (csec autodelete) |
| Stub-Paket (intel-triage P1.3) | Winzige Hauptdatei + externe Dep-URL + Lifecycle-Hook (ltidi-Kette) |
| Monorepo-Scanner | Lerna/pnpm-workspace/turbo-Erkennung (Sprint-1-Audit MR-C2-Fix) |
| Trusted-Dep-Diff (optional) | Diff gegen vertrauenswürdige Dep-Tarballs aus der Registry (v2.10.x) |
| Python-Quellcode (PYSRC) | Import-/Installationszeit-RCE-Muster in `__init__.py` / `setup.py` (v2.11.41 — schließt TrapDoor-PyPI-Lücke) |
| Python-AST (PYAST) | Tree-sitter-Python-AST mit Taint-bewussten Detektoren (v2.11.42+) |
| Anti-Scanner-Injektion (ASI) | Prompt-Injektionstext in Kommentaren/Zeichenketten, der einen LLM-Code-Reviewer zu einem sauberen Urteil oder zum Überspringen einer obfuskierten Payload zwingt (ASI-001..004, Hades-Kampagne 2026-06) |

### <!--stat:rulesTotal-->278<!--/stat:rulesTotal--> Erkennungsregeln

Alle Regeln (<!--stat:rulesCore-->273<!--/stat:rulesCore--> REGELN + <!--stat:rulesParanoid-->5<!--/stat:rulesParanoid--> PARANOID) sind MITRE-ATT&CK-Techniken zugeordnet. Die vollständige Regeln-Referenz finden Sie in [SECURITY.md](https://github.com/dnszlsk/muad-dib/blob/master/SECURITY.md#detection-rules).

### Erkannte Kampagnen

| Kampagne | Status |
|----------|--------|
| GlassWorm (2026, 433+ Pakete) | Erkannt |
| Shai-Hulud v1/v2/v3 (2025) | Erkannt |
| event-stream (2018) | Erkannt |
| eslint-scope (2018) | Erkannt |
| Protestware (node-ipc, colors, faker) | Erkannt |
| Typosquats (crossenv, mongose, babelcli) | Erkannt |

---

## VS Code

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

```bash
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](https://github.com/dnszlsk/muad-dib/blob/master/vscode-extension/README.md).

---

## CI/CD

### GitHub Actions (Marketplace)

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

```yaml
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):

```yaml
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**

| Eingabe | Beschreibung | Standard |
|-------|-------------|---------|
| `path` | Zu scannender Pfad | `.` |
| `fail-on` | Minimale Schwere für Fehlschlag (`critical`/`high`/`medium`/`low`/`none`) | `high` |
| `sarif` | SARIF-Ausgabedateipfad — setzen, um auch auf den Security-Tab hochzuladen | |
| `paranoid` | Ultra-strikte Erkennung (höhere FPR) | `false` |
| `version` | Zu installierende `muaddib-scanner`-npm-Version | `latest` |

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

| Ausgabe | Beschreibung |
|--------|-------------|
| `risk-score` | Risikobewertung 0–100 |
| `risk-level` | `SAFE` / `LOW` / `MEDIUM` / `HIGH` / `CRITICAL` |
| `threats-count` | Gesamtzahl erkannter Bedrohungen |
| `critical-count` / `high-count` | Bedrohungen nach Schweregrad |
| `exit-code` | `0` = `fail-on`-Schwelle bestanden, sonst ungleich Null |
| `sarif-file` | Pfad zur SARIF-Datei (leer, wenn `sarif` nicht gesetzt) |

### Pre-Commit-Hooks

```bash
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:
```yaml
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.

| Metrik | Ergebnis |
|--------|--------|
| Erkennungsrate (TPR@3) | **95,74%** (90/94) |
| Alarmrate (TPR@20) | **88,30%** (83/94) |
| FPR — kuratierte npm (548) | **1,10%** (6/545) |
| FPR — zufällige npm (200) | **2,50%** (5/200) |
| FPR — PyPI (132) | **9,68%** (12/124) |
| ADR — adversarial + Holdout | **96,26%** (103/107) |
| Wild-TPR (Datadog 17K) | **92,8%** (13.538/14.587) |

**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](https://github.com/dnszlsk/muad-dib/blob/master/docs/EVALUATION_METHODOLOGY.md).

---

## Mitwirken

### IOCs hinzufügen

YAML-Dateien in `iocs/` bearbeiten:

```yaml
- 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

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

### Testen

- **<!--stat:tests-->4545<!--/stat:tests--> Tests** über <!--stat:testFiles-->155<!--/stat:testFiles--> 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](https://dnszlsk.github.io/muad-dib/blog/) - Technische Artikel zur Lieferketten-Bedrohungserkennung
- [Carnet de bord](https://github.com/dnszlsk/muad-dib/blob/master/docs/CARNET_DE_BORD_MUADDIB.md) - Entwicklungstagebuch (auf Französisch)
- [Dokumentationsindex](https://github.com/dnszlsk/muad-dib/blob/master/docs/INDEX.md) - Alle Dokumentation an einem Ort
- [Evaluierungsmethodik](https://github.com/dnszlsk/muad-dib/blob/master/docs/EVALUATION_METHODOLOGY.md) - Experimentelles Protokoll, Holdout-Ergebnisse
- [Bedrohungsmodell](https://github.com/dnszlsk/muad-dib/blob/master/docs/threat-model.md) - Was MUAD'DIB erkennt und nicht erkennt
- [Sicherheitsrichtlinie](https://github.com/dnszlsk/muad-dib/blob/master/SECURITY.md) - Referenz der Erkennungsregeln (<!--stat:rulesTotal-->278<!--/stat:rulesTotal--> Regeln)
- [Sicherheitsaudit](https://github.com/dnszlsk/muad-dib/blob/master/docs/SECURITY_AUDIT.md) - Bypass-Validierungsbericht
- [FP-Analyse](https://github.com/dnszlsk/muad-dib/blob/master/docs/EVALUATION.md) - 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](https://github.com/dnszlsk/muad-dib/blob/master/LICENSE) und [NOTICE](https://github.com/dnszlsk/muad-dib/blob/master/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](https://github.com/DNSZLSK)).

Copyright (C) 2026 DNSZLSK.

---

<p align="center">
  <strong>The spice must flow. The worms must die.</strong>
</p>
Beliebteste

muad-dib
