muad-dib v2.11.179 — Real-time npm/PyPI supply-chain threat detection. Behavioral chain analysis, AST scanning, IOC feeds, and compound scoring engine.

MUAD

Installation | Utilisation | Fonctionnalités | VS Code | CI/CD

Pourquoi MUAD'DIB ?

Les attaques supply-chain npm et PyPI explosent. Shai-Hulud a compromis 25K+ repos en 2025. Les outils existants détectent, mais n'aident pas à répondre.

MUAD'DIB combine 22 scanners paralleles (277 regles de detection), un moteur de desobfuscation, une analyse dataflow inter-module, du scoring compose (21 regles compound), et un sandbox gVisor/Docker pour detecter les menaces connues et les patterns comportementaux suspects dans les packages npm et PyPI. Un classifier XGBoost existe dans le code mais est actuellement inactif (modele effondre, en attente de re-entrainement — voir section ML Classifier ci-dessous).

Positionnement

MUAD'DIB est un scanner supply-chain npm et PyPI libre, ouvert et entièrement auditable. Il détecte les menaces connues (225 000+ IOCs), le RCE à l'installation, les flux credential-puis-exfiltration, les payloads obfusqués et d'autres patterns comportementaux suspects — en local, sans télémétrie.

Il est distribué sous licence AGPL-3.0 ; une licence commerciale est disponible pour les organisations qui doivent l'intégrer dans un produit propriétaire ou l'exécuter en service hébergé fermé (voir Licence).

Il ne cherche volontairement pas à tout couvrir — voir le Threat Model pour ce qu'il détecte et ce qu'il ne détecte pas.

Installation

npm (recommandé)

npm install -g muaddib-scanner

Depuis les sources

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

Utilisation

Scan basique

muaddib scan .
muaddib scan /chemin/vers/projet

Scanne les dépendances npm (package.json, node_modules) et Python (requirements.txt, setup.py, pyproject.toml).

Mode interactif

muaddib

Lance un menu interactif pour vous guider à travers toutes les fonctionnalités.

Installation sécurisée

muaddib install <package>
muaddib install lodash axios --save-dev
muaddib i express -g
muaddib install suspicious-pkg --force    # Forcer l'installation malgré les menaces

Scanne les packages AVANT installation. Bloque les packages malveillants connus.

Score de risque

Chaque scan affiche un score de risque 0-100 :

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

Mode explain (détails complets)

muaddib scan . --explain

Affiche pour chaque détection :

Rule ID
Technique MITRE ATT&CK
Références (articles, CVEs)
Playbook de réponse

Export

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

Seuil de sévérité

muaddib scan . --fail-on critical  # Fail seulement sur CRITICAL
muaddib scan . --fail-on high      # Fail sur HIGH et CRITICAL (défaut)
muaddib scan . --fail-on medium    # Fail sur MEDIUM, HIGH, CRITICAL

Mode paranoid

muaddib scan . --paranoid

Détection ultra-stricte avec moins de tolérance. Utile pour les projets critiques. Détecte tout accès réseau, exécution de sous-processus, évaluation de code dynamique et accès aux fichiers sensibles.

Webhook Discord/Slack

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

Envoie une alerte avec le score et les menaces sur Discord ou Slack. Filtrage strict (v2.1.2) : les alertes ne sont envoyées que pour les correspondances IOC, les menaces confirmées par sandbox, ou l'exfiltration de canary tokens — réduisant le bruit des détections heuristiques seules.

Surveillance temps réel

muaddib watch .

Mode daemon

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

Surveille automatiquement tous les npm install et scanne les nouveaux packages.

Mise à jour IOCs (rapide, ~5 secondes)

muaddib update

Charge les 225 000+ IOCs inclus dans le package, fusionne les IOCs YAML et les sources GitHub additionnelles (GenSecAI, DataDog). Lancez cette commande après npm install pour un rafraîchissement instantané des IOCs.

Scrape IOCs (complet, ~5 minutes)

muaddib scrape

Rafraîchissement complet depuis toutes les sources primaires. Télécharge les dumps OSV pour npm et PyPI (~100-200 Mo), OSSF, et toutes les autres sources. Lancez cette commande quand vous voulez les données les plus récentes.

Sources :

OSV.dev npm dump - Téléchargement en masse de toutes les entrées MAL-*
OSV.dev PyPI dump - Téléchargement en masse de toutes les entrées PyPI MAL-*
GenSecAI Shai-Hulud 2.0 Detector - Liste consolidée de 700+ packages Shai-Hulud
DataDog Security Labs - IOCs consolidés de plusieurs vendors
OSSF Malicious Packages - Base OpenSSF (8000+ rapports via OSV.dev)
Snyk Known Malware - Packages malveillants historiques
IOCs Statiques - Socket.dev, Phylum, packages supprimés de npm

Sandbox Docker

muaddib sandbox <nom-package>
muaddib sandbox <nom-package> --strict

Analyse dynamique : installe le package dans un container Docker isolé et surveille le comportement à l'exécution via strace, tcpdump et diff filesystem.