dnszlsk/muad-dibDétection en temps réel des menaces sur la chaîne d'approvisionnement npm/PyPI. Analyse des chaînes comportementales, analyse AST, flux IOC et moteur de notation composite.
<p align="center">
MUAD
</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="#utilisation">Utilisation</a> |
<a href="#fonctionnalités">Fonctionnalités</a> |
<a href="#vs-code">VS Code</a> |
<a href="#ci-cd">CI/CD</a>
</p>
<p align="center">
<a href="https://github.com/dnszlsk/muad-dib/blob/master/docs/README.md">English version</a>
</p>
---
## 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 **<!--stat:scanners-->22<!--/stat:scanners--> scanners paralleles** (<!--stat:rulesTotal-->277<!--/stat:rulesTotal--> regles de detection), un **moteur de desobfuscation**, une **analyse dataflow inter-module**, du **scoring compose** (<!--stat:compound-->21<!--/stat:compound--> 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](#licence)).
Il ne cherche volontairement pas à tout couvrir — voir le [Threat Model](https://github.com/dnszlsk/muad-dib/blob/master/docs/threat-model.md) pour ce qu'il détecte et ce qu'il ne détecte pas.
---
## Installation
### npm (recommandé)
```bash
npm install -g muaddib-scanner
```
### Depuis les sources
```bash
git clone https://github.com/DNSZLSK/muad-dib
cd muad-dib
npm install
npm link
```
---
## Utilisation
### Scan basique
```bash
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
```bash
muaddib
```
Lance un menu interactif pour vous guider à travers toutes les fonctionnalités.
### Installation sécurisée
```bash
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)
```bash
muaddib scan . --explain
```
Affiche pour chaque détection :
- Rule ID
- Technique MITRE ATT&CK
- Références (articles, CVEs)
- Playbook de réponse
### Export
```bash
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é
```bash
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
```bash
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
```bash
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
```bash
muaddib watch .
```
### Mode daemon
```bash
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)
```bash
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)
```bash
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
```bash
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.
Monitoring multi-couches :
- **Traçage système** (strace) : accès fichiers, spawn de processus, monitoring syscalls
- **Capture réseau** (tcpdump) : résolutions DNS avec IPs résolues, requêtes HTTP (méthode, host, path, body), détection TLS SNI
- **Diff filesystem** : snapshot avant/après install, détecte les fichiers créés dans des emplacements suspects
- **Détection exfiltration de données** : 16 patterns sensibles (tokens, credentials, clés SSH, clés privées, .env)
- **Environnement CI simulé** (v2.1.2) : simule un environnement CI (GITHUB_ACTIONS, GITLAB_CI, TRAVIS, CIRCLECI, JENKINS) pour déclencher les malwares CI-aware qui resteraient autrement dormants
- **Canary tokens enrichis** (v2.1.2) : 6 honeypots injectés comme variables d'environnement (GITHUB_TOKEN, NPM_TOKEN, AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, SLACK_WEBHOOK_URL, DISCORD_WEBHOOK_URL). Si exfiltrés via réseau, DNS ou filesystem, déclenche une alerte CRITICAL avec score +50
- **Monkey-patching preload** (v2.4.9) : Instrumentation runtime via `NODE_OPTIONS=--require /opt/preload.js`. Patche les APIs de temps (Date.now, setTimeout→0, setInterval→immédiat), intercepte les appels réseau/fichiers/processus/env. Mode multi-run à [0h, 72h, 7j] pour détecter les malwares time-bomb (MITRE T1497.003)
- **Moteur de scoring** : score de risque 0-100 basé sur la sévérité des comportements
Utilisez `--strict` pour bloquer tout trafic réseau sortant non essentiel via iptables.
Nécessite Docker Desktop installé.
```bash
muaddib sandbox lodash # Package safe
muaddib sandbox suspicious-pkg # Analyser un package inconnu
```
### Rapport réseau sandbox
```bash
muaddib sandbox-report <nom-package>
muaddib sandbox-report <nom-package> --strict
```
Identique à `sandbox` mais affiche un rapport réseau détaillé : résolutions DNS, requêtes HTTP, connexions TLS, connexions bloquées (mode strict), et alertes d'exfiltration de données.
### Diff (comparer les versions)
```bash
muaddib diff <ref> [path]
```
Compare les menaces entre la version actuelle et un commit/tag précédent. Affiche uniquement les **NOUVELLES** menaces introduites depuis la référence.
```bash
muaddib diff HEAD~1 # Comparer avec le commit précédent
muaddib diff v1.2.0 # Comparer avec un tag
muaddib diff main # Comparer avec une branche
muaddib diff abc1234 # Comparer avec un commit spécifique
```
Exemple de sortie :
```
[MUADDIB DIFF] Comparing abc1234 -> def5678
Risk Score: 25 -> 45 (+20 worse)
Threats: 3 -> 5
NEW threats: 2
REMOVED threats: 0
Unchanged: 3
NEW THREATS (introduced since v1.2.0)
------------------------------------
1. [HIGH] suspicious_dependency
Known malicious package detected
File: package.json
```
Utilisez en CI pour ne bloquer que sur les **nouvelles** menaces, pas la dette technique existante :
```yaml
- run: muaddib diff ${{ github.event.pull_request.base.sha }} --fail-on high
```
### Hooks pre-commit
```bash
muaddib init-hooks [options]
```
Scanner automatiquement avant chaque commit. Supporte plusieurs systèmes de hooks :
```bash
muaddib init-hooks # Auto-detect (husky/pre-commit/git)
muaddib init-hooks --type husky # Forcer husky
muaddib init-hooks --type pre-commit # Forcer pre-commit framework
muaddib init-hooks --type git # Forcer git hooks natifs
muaddib init-hooks --mode diff # Ne bloquer que les NOUVELLES menaces
```
#### Avec pre-commit framework
Ajoutez à `.pre-commit-config.yaml` :
```yaml
repos:
- repo: https://github.com/DNSZLSK/muad-dib
rev: v2.11.117
hooks:
- id: muaddib-scan # Scanner toutes les menaces
# - id: muaddib-diff # Ou: seulement les nouvelles
# - id: muaddib-paranoid # Ou: mode ultra-strict
```
#### Avec husky
```bash
npx husky add .husky/pre-commit "npx muaddib scan . --fail-on high"
# Ou pour le mode diff :
npx husky add .husky/pre-commit "npx muaddib diff HEAD --fail-on high"
```
#### Supprimer les hooks
```bash
muaddib remove-hooks [path]
```
Supprime tous les hooks MUAD'DIB (husky et git natif).
#### Git hooks natifs
```bash
muaddib init-hooks --type git
# Crée .git/hooks/pre-commit
```
### Moniteur Zero-Day
MUAD'DIB surveille en continu les registres npm et PyPI pour détecter les nouveaux packages en temps réel, en les scannant automatiquement avec analyse sandbox Docker et alertes webhook. Ce monitoring tourne en interne sur notre infrastructure — les menaces détectées alimentent la base IOC et l'API threat feed.
### Décomposition du score
```bash
muaddib scan . --breakdown
```
Affiche la décomposition explicable du score : contribution de chaque finding au score final, avec les poids par règle et multiplicateurs de sévérité.
### Replay ground truth
```bash
muaddib replay
muaddib ground-truth
```
Rejoue des attaques supply-chain réelles contre le scanner pour valider la couverture de détection. Résultat actuel (mesure v2.11.48) : **90/94 détectées (95.74% TPR@3)** sur **96 samples** enrichis (94 actifs, 2 hors-scope : GT-005 colors et GT-009 faker, protestware avec min_threats=0). Enrichissement 2026-05-25 : +22 samples (16 synthétiques pour les règles PYSRC/PYAST/AST-092/AICONF-004/PKG-022, 6 tarballs réels depuis l'archive VPS, 7 reconstructions depuis le benchmark `data/all-review-results.json`). 13 samples PyPI (était 0). **TPR@20 : 88.30%** (83/94, +3.1pp vs v2.11.47 grâce au compound Track D `recon_exfil_direct_ip` qui ferme la gap GT-095).
4 misses incluent les 3 attaques browser-only (lottie-player, polyfill-io, trojanized-jquery) plus 1 autre.
### Version check
MUAD'DIB vérifie automatiquement les nouvelles versions au démarrage et vous notifie si une mise à jour est disponible.
---
## Fonctionnalités
### Support Python / PyPI
MUAD'DIB détecte et scanne automatiquement les projets Python :
- **requirements.txt** - Tous les formats incluant `-r` récursif, extras, marqueurs d'environnement
- **setup.py** - Extraction de `install_requires` et `setup_requires`
- **pyproject.toml** - Dépendances PEP 621 et dépendances Poetry
Les packages Python sont vérifiés contre 14 000+ packages PyPI malveillants connus (depuis OSV.dev) et testés pour le typosquatting contre les packages PyPI populaires (requests, numpy, flask, django, pandas, etc.) via la normalisation PEP 503.
```
[PYTHON] Detected Python project (3 dependency files)
requirements.txt: 12 packages
setup.py: 3 packages
pyproject.toml: 8 packages
[CRITICAL] PyPI IOC match: malicious-pkg (all versions)
[HIGH] PyPI typosquat: "reqeusts" looks like "requests"
```
### Détection typosquatting
MUAD'DIB détecte les packages dont le nom ressemble à un package populaire (npm et PyPI) :
```
[HIGH] Package "lodahs" ressemble à "lodash" (swapped_chars). Possible typosquatting.
```
### Analyse dataflow
Détecte quand du code lit des credentials ET les envoie sur le réseau :
```
[CRITICAL] Flux suspect: lecture credentials (readFileSync, GITHUB_TOKEN) + envoi réseau (fetch)
```
### Scanner GitHub Actions
Détecte les patterns malveillants dans les fichiers YAML `.github/workflows/`, incluant les indicateurs de backdoor Shai-Hulud 2.0.
### Attaques détectées
| Campagne | Packages | Status |
|----------|----------|--------|
| GlassWorm (Mars 2026) | 433+ packages (Unicode invisible + Blockchain C2) | Détecté |
| Shai-Hulud v1 (Sept 2025) | @ctrl/tinycolor, ng2-file-upload | Détecté |
| Shai-Hulud v2 (Nov 2025) | @asyncapi/specs, posthog-node, kill-port | Détecté |
| Shai-Hulud v3 (Dec 2025) | @vietmoney/react-big-calendar | Détecté |
| event-stream (2018) | flatmap-stream, event-stream | Détecté |
| eslint-scope (2018) | eslint-scope | Détecté |
| Protestware | node-ipc, colors, faker | Détecté |
| Typosquats | crossenv, mongose, babelcli | Détecté |
### Techniques détectées
| Technique | MITRE | Détection |
|-----------|-------|-----------|
| Vol credentials (.npmrc, .ssh) | T1552.001 | AST |
| Exfiltration env vars | T1552.001 | AST |
| Exécution code distant | T1105 | Pattern |
| Reverse shell | T1059.004 | Pattern |
| Dead man's switch | T1485 | Pattern |
| Code obfusqué | T1027 | Heuristiques |
| Analyse entropie Shannon | T1027 | Calcul d'entropie |
| Typosquatting (npm + PyPI) | T1195.002 | Levenshtein |
| Supply chain compromise | T1195.002 | IOC matching |
| Package PyPI malveillant | T1195.002 | IOC matching |
| Sandbox analyse dynamique | Multiple | Docker + strace + tcpdump |
| Ajout soudain de script lifecycle | T1195.002 | Analyse temporelle |
| Injection d'API dangereuse entre versions | T1195.002 | Diff AST temporel |
| Anomalie de fréquence de publication | T1195.002 | Métadonnées registre |
| Changement de maintainer/publisher | T1195.002 | Métadonnées registre |
| Exfiltration de canary tokens | T1552.001 | Honey tokens sandbox |
| Weaponisation agent IA | T1059.004 | AST (flags s1ngularity/Nx) |
| Injection prompt config IA | T1059.004 | Scan fichiers (.cursorrules, CLAUDE.md) |
| Vol credentials CLI (gh, gcloud, aws) | T1552.001 | AST |
| Dropper binaire (chmod + exec /tmp) | T1105 | AST |
| Hooking prototype (fetch, XMLHttpRequest) | T1557 | AST |
| Injection workflow (.github/workflows) | T1195.002 | AST |
| Harvest crypto wallets | T1005 | Dataflow |
| Require cache poisoning | T1574.001 | AST |
| Staged eval decode (eval+atob/Buffer) | T1140 | AST |
| Désobfuscation (string concat, charcode, base64, hex) | T1140 | Pré-traitement AST |
| Dataflow cross-fichiers (exfiltration inter-module) | T1041 | Module graph |
---
## Détection d'anomalies supply chain (v2.0)
MUAD'DIB 2.0 introduit un changement de paradigme : de la **détection par IOC** (réactive, nécessite des menaces connues) à la **détection comportementale d'anomalies** (proactive, détecte les menaces inconnues en repérant les changements suspects).
Les scanners supply-chain traditionnels reposent sur des listes de packages malveillants connus. Le problème : ils ne détectent les menaces qu'APRÈS leur identification et signalement. Des attaques comme **ua-parser-js** (2021), **event-stream** (2018) et **Shai-Hulud** (2025) sont passées inaperçues pendant des heures ou des jours car aucun IOC n'existait encore.
MUAD'DIB 2.0 ajoute 5 features de détection comportementale capables d'attraper ces attaques **avant** leur apparition dans une base d'IOC, en analysant ce qui a changé entre les versions d'un package.
### Nouvelles features
#### 1. Détection soudaine de scripts lifecycle (`--temporal`)
Détecte quand des scripts `preinstall`, `install` ou `postinstall` apparaissent soudainement dans une nouvelle version d'un package qui n'en avait jamais. C'est le vecteur d'attaque #1 des attaques supply-chain.
```bash
muaddib scan . --temporal
```
#### 2. Diff AST temporel (`--temporal-ast`)
Télécharge les deux dernières versions de chaque dépendance et compare leur AST (Abstract Syntax Tree) pour détecter les APIs dangereuses nouvellement ajoutées : `child_process`, `eval`, `Function`, `net.connect`, `process.env`, `fetch`, etc.
```bash
muaddib scan . --temporal-ast
```
#### 3. Anomalie de fréquence de publication (`--temporal-publish`)
Détecte les patterns de publication anormaux : rafale de versions en 24h, package dormant soudainement mis à jour après 6+ mois, succession rapide de versions (plusieurs releases en moins d'1h).
```bash
muaddib scan . --temporal-publish
```
#### 4. Détection de changement de maintainer (`--temporal-maintainer`)
Détecte les changements de maintainers entre versions : nouveau maintainer ajouté, seul maintainer remplacé (pattern event-stream), noms de maintainers suspects, nouveau publisher.
```bash
muaddib scan . --temporal-maintainer
```
#### 5. Canary Tokens / Honey Tokens (sandbox)
Injecte de faux credentials dans l'environnement sandbox avant d'installer un package. Si le package tente d'exfiltrer ces honey tokens via HTTP, DNS, filesystem ou stdout, il est signalé comme malveillant confirmé.
6 honeypots sont injectés :
- `GITHUB_TOKEN` / `NPM_TOKEN` — Tokens de registre
- `AWS_ACCESS_KEY_ID` / `AWS_SECRET_ACCESS_KEY` — Credentials cloud
- `SLACK_WEBHOOK_URL` / `DISCORD_WEBHOOK_URL` — Webhooks de messagerie
Les tokens dynamiques (aléatoires par session, depuis `canary-tokens.js`) et les tokens statiques de fallback (dans `sandbox-runner.sh`) sont utilisés pour une défense en profondeur.
```bash
muaddib sandbox suspicious-package
```
### Scan temporel complet
Activer toutes les features d'analyse temporelle en une commande :
```bash
muaddib scan . --temporal-full
```
### Exemples d'utilisation
```bash
# Scan comportemental complet (5 features)
muaddib scan . --temporal-full
# Détection lifecycle scripts uniquement
muaddib scan . --temporal
# Diff AST + changement maintainer
muaddib scan . --temporal-ast --temporal-maintainer
# Sandbox avec canary tokens (activé par défaut)
muaddib sandbox suspicious-package
# Sandbox sans canary tokens
muaddib sandbox suspicious-package --no-canary
```
### Nouvelles règles de détection (v2.0)
| Rule ID | Nom | Sévérité | Feature |
|---------|-----|----------|---------|
| MUADDIB-TEMPORAL-001 | Ajout soudain de script lifecycle (Critique) | CRITICAL | `--temporal` |
| MUADDIB-TEMPORAL-002 | Ajout soudain de script lifecycle | HIGH | `--temporal` |
| MUADDIB-TEMPORAL-003 | Script lifecycle modifié | MEDIUM | `--temporal` |
| MUADDIB-TEMPORAL-AST-001 | API dangereuse ajoutée (Critique) | CRITICAL | `--temporal-ast` |
| MUADDIB-TEMPORAL-AST-002 | API dangereuse ajoutée (High) | HIGH | `--temporal-ast` |
| MUADDIB-TEMPORAL-AST-003 | API dangereuse ajoutée (Medium) | MEDIUM | `--temporal-ast` |
| MUADDIB-PUBLISH-001 | Rafale de publications détectée | HIGH | `--temporal-publish` |
| MUADDIB-PUBLISH-002 | Pic de package dormant | HIGH | `--temporal-publish` |
| MUADDIB-PUBLISH-003 | Succession rapide de versions | MEDIUM | `--temporal-publish` |
| MUADDIB-MAINTAINER-001 | Nouveau maintainer ajouté | HIGH | `--temporal-maintainer` |
| MUADDIB-MAINTAINER-002 | Maintainer suspect détecté | CRITICAL | `--temporal-maintainer` |
| MUADDIB-MAINTAINER-003 | Seul maintainer changé | HIGH | `--temporal-maintainer` |
| MUADDIB-MAINTAINER-004 | Nouveau publisher détecté | MEDIUM | `--temporal-maintainer` |
| MUADDIB-CANARY-001 | Exfiltration de canary token | CRITICAL | sandbox |
### Pourquoi c'est important
Ces features détectent des attaques comme :
- **Shai-Hulud** (2025) : Détecté par temporal lifecycle + AST diff (ajout soudain de `postinstall` + `child_process`)
- **ua-parser-js** (2021) : Détecté par changement maintainer + détection lifecycle
- **event-stream** (2018) : Détecté par changement de seul maintainer + AST diff (nouvelle dépendance `flatmap-stream` avec `eval`)
- **coa/rc** (2021) : Détecté par rafale de publications + détection lifecycle
Le tout sans avoir besoin d'un seul IOC.
---
## Sources IOC
MUAD'DIB agrège la threat intelligence de sources vérifiées uniquement :
| Source | Type | Couverture |
|--------|------|------------|
| [OSV.dev npm dump](https://osv.dev) | Bulk zip | 200 000+ entrées npm MAL-* |
| [OSV.dev PyPI dump](https://osv.dev) | Bulk zip | 14 000+ entrées PyPI MAL-* |
| [GenSecAI Shai-Hulud Detector](https://github.com/gensecaihq/Shai-Hulud-2.0-Detector) | GitHub | 700+ packages Shai-Hulud |
| [DataDog Security Labs](https://github.com/DataDog/indicators-of-compromise) | GitHub | IOCs consolidés de 7 vendors |
| [OSSF Malicious Packages](https://github.com/ossf/malicious-packages) | API OSV | 8000+ rapports malware |
| Snyk Known Malware | Statique | Attaques historiques |
| Socket.dev / Phylum | Statique | Ajouts manuels |
---
## VS Code
L'extension VS Code scanne automatiquement vos projets npm.
### Installation
Cherchez "MUAD'DIB" dans les Extensions VS Code, ou :
```bash
code --install-extension dnszlsk.muaddib-vscode
```
### Commandes
- `MUAD'DIB: Scan Project` - Scanner tout le projet
- `MUAD'DIB: Scan Current File` - Scanner le fichier actuel
### Configuration
- `muaddib.autoScan` - Scanner automatiquement à l'ouverture (défaut: true)
- `muaddib.webhookUrl` - URL webhook Discord/Slack
- `muaddib.failLevel` - Niveau d'alerte (critical/high/medium/low)
---
## CI/CD
### GitHub Actions (Marketplace)
Utilisez l'action officielle MUAD'DIB depuis le GitHub Marketplace :
```yaml
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'
```
#### Inputs de l'action
| Input | Description | Défaut |
|-------|-------------|--------|
| `path` | Chemin à scanner | `.` |
| `fail-on` | Sévérité minimum pour échec (critical/high/medium/low) | `high` |
| `sarif` | Chemin du fichier SARIF | `` |
| `paranoid` | Activer détection ultra-stricte | `false` |
#### Outputs de l'action
| Output | Description |
|--------|-------------|
| `sarif-file` | Chemin du fichier SARIF généré |
| `risk-score` | Score de risque (0-100) |
| `threats-count` | Nombre de menaces détectées |
| `exit-code` | Code de sortie (0 = clean) |
Les alertes apparaissent dans Security > Code scanning alerts.
---
## Architecture
```
MUAD'DIB 2.11.179 Scanner
|
+-- IOC Match (225 000+ packages, JSON DB)
| +-- OSV.dev npm dump (200K+ entrées MAL-*)
| +-- OSV.dev PyPI dump (14K+ entrées MAL-*)
| +-- GenSecAI Shai-Hulud Detector
| +-- DataDog Consolidated IOCs
| +-- OSSF Malicious Packages (via OSV)
| +-- Snyk Known Malware
| +-- Static IOCs (Socket, Phylum)
|
+-- Pré-traitement Désobfuscation (v2.2.5, --no-deobfuscate pour désactiver)
| +-- String concat folding, reconstruction CharCode
| +-- Décodage Base64, résolution Hex array
| +-- Propagation de constantes (Phase 2)
|
+-- Dataflow Inter-module (v2.2.6, --no-module-graph pour désactiver)
| +-- Graphe de dépendances, annotation exports teintés
| +-- Chaînes re-export 3 hops, analyse méthodes de classe
| +-- Détection credential read → network sink cross-fichiers
|
+-- Graphe d'Intention (Intent Graph)
| +-- Analyse cross-scanner des intentions malveillantes
| +-- Corrélation entre signaux faibles de multiples scanners
| +-- Élévation de sévérité sur combinaisons suspectes
|
+-- 22 Scanners Parallèles (277 règles)
| +-- AST Parse (acorn) — eval/Function, credential CLI theft, binary droppers, prototype hooks
| +-- Pattern Matching (shell, scripts)
| +-- Typosquat Detection (npm + PyPI, Levenshtein)
| +-- Python Scanner (requirements.txt, setup.py, pyproject.toml)
| +-- Analyse Entropie Shannon
| +-- GitHub Actions Scanner
| +-- AI Config Scanner (.cursorrules, CLAUDE.md, copilot-instructions.md)
| +-- Package, Dependencies, Hash, Dataflow scanners
| +-- IOC Strings (YARA-style, intel-triage v2.11) — Axios 2026, TeamPCP, GlassWorm, CanisterSprawl
| +-- Anti-Forensic AST (intel-triage v2.11) — XOR loop + self-delete + decoy write (csec autodelete)
| +-- Stub Package (intel-triage v2.11) — main file < 500 octets + dep URL externe + lifecycle hook (ltidi chain)
|
+-- Détection d'Anomalies Supply Chain (v2.0)
| +-- Détection Lifecycle Script Temporelle (--temporal)
| +-- Diff AST Temporel (--temporal-ast)
| +-- Anomalie Fréquence de Publication (--temporal-publish)
| +-- Détection Changement Maintainer (--temporal-maintainer)
| +-- Canary Tokens / Honey Tokens (sandbox)
|
+-- Validation & Observabilité (v2.1)
| +-- Ground Truth Dataset (96 attaques réelles, 94 in-scope, 95.74% TPR@3 v2.11.48)
| +-- Logging Temps de Détection (first_seen, métriques lead time)
| +-- Suivi Taux FP (stats quotidiennes, taux faux positifs)
| +-- Décomposition Score (scoring explicable par règle)
| +-- API Threat Feed (serveur HTTP, flux JSON pour SIEM)
|
+-- Réduction FP Post-traitement (v2.2.8-v2.3.1, v2.5.7-v2.5.8, v2.5.15-v2.5.16)
| +-- Downgrade sévérité par comptage (dynamic_require, dataflow, module_compile, etc.)
| +-- Cap scoring prototype_hook MEDIUM + whitelist HTTP client
| +-- Obfuscation dans dist/build/.cjs/.mjs → LOW
| +-- Filtrage env vars safe + préfixes
| +-- Catégorisation source télémétrie dataflow (os.platform/arch → telemetry_read)
| +-- Whitelist DEP (es5-ext, bootstrap-sass) + skip alias npm
| +-- Audit IOC wildcards (v2.5.8) : FPR 10.8% → 6.0%
| +-- P5 precision heuristique (v2.5.15) : 7 corrections
| +-- P6 precision composes (v2.5.16) : 6 corrections
|
+-- Scoring Per-File Max (v2.2.11)
| +-- Score = max(scores_par_fichier) + score_package_level
| +-- Élimine l'accumulation de score sur de nombreux fichiers
| +-- Menaces package-level (lifecycle, typosquat, IOC) scorées séparément
|
+-- Sandbox Monkey-Patching Preload (v2.4.9)
| +-- Manipulation temps runtime (Date.now, setTimeout→0, setInterval→immédiat)
| +-- Interception réseau/fichiers/processus/env et logging
| +-- Multi-run [0h, 72h, 7j] pour détection time-bomb (T1497.003)
|
+-- Audit Sécurité (v2.5.0-v2.5.6)
| +-- 41 issues remédiées (14 CRITICAL, 18 HIGH, 9 MEDIUM)
|
+-- ML Classifier (v2.10.0-v2.10.5) — INACTIF depuis 2026-04-08
| +-- Jamais appele par `muaddib scan` (rules + FP caps uniquement)
| +-- `muaddib monitor` : LOG-ONLY (modele collapse, p≈0.002 pour tout input)
| +-- `muaddib evaluate` : seule commande qui execute encore le filtre (replay offline)
| +-- Historique: ML1 XGBoost (P=0.978/R=0.933) + ML2 Bundler (P=0.992/R=1.000)
|
+-- Webhook Triage P1/P2/P3 (v2.10.5)
| +-- P1 rouge : IOC, HC types, sandbox, canary tokens
| +-- P2 orange : score >= 50, compounds, lifecycle+intent
| +-- P3 jaune : reste (score 20-49 sans signal fort)
|
+-- Paranoid Mode (ultra-strict)
+-- Docker Sandbox (analyse comportementale, capture réseau, canary tokens, CI-aware, preload)
+-- Moniteur Zero-Day (interne : polling RSS npm + PyPI, alertes Discord, rapport quotidien)
|
v
Dataflow Analysis (credential read -> network send)
|
v
Threat Enrichment (rules, MITRE ATT&CK, playbooks)
|
v
Output (CLI, JSON, HTML, SARIF, Webhook, Threat Feed)
```
---
## Metriques d'evaluation
| Metrique | Resultat | Details |
|----------|----------|---------|
| **Wild TPR** (Datadog 17K) | **92.8%** (13 538/14 587 in-scope) | 17 922 packages. 3 335 sans JS (hors scope). Par categorie : compromised_lib 97.8%, malicious_intent 92.1% |
| **TPR@3** (Ground Truth, mesure v2.11.48) | **95.74%** (90/94 in-scope) | Re-mesure complete sur le GT enrichi. **96 attaques reelles** (94 in-scope + 2 hors-scope : GT-005 colors, GT-009 faker, protestware min_threats=0). +22 samples 2026-05-25 (Track C synthetique PYSRC/PYAST/AST-092/AICONF-004/PKG-022, Track A 6 tarballs reels VPS, Track B 7 reconstructions du benchmark de revue). 13 samples PyPI (etait 0). |
| **TPR@20** (Ground Truth, mesure v2.11.48) | **88.30%** (83/94 in-scope) | Seuil alerte = 20 (threshold operationnel). **+3.1pp vs v2.11.47** grace au compound Track D `recon_exfil_direct_ip` (MUADDIB-COMPOUND-016, sameFile) qui ferme la gap GT-095 (risk 3→50) et `linux_fingerprint_exec` (AST-093) qui boost GT-091 byvendors / GT-092 heloo131313. 2 samples `tpr3-only` restants par design (GT-072, GT-077). |
| **FPR rules** (Benign curated, mesure v2.11.48) | **1.10%** (6/545 scannes, 548 total) | **Inchange apres Track D** — le compound + types nouveaux ont cree zero FP supplementaire (gate sameFile + filtre IP-publique-only). Chute depuis 15.6% (v2.10.95) attribuable aux FP caps F1-F14 (v2.10.97 → v2.11.31) compounded sur 11 versions. Les 6 FP restants sont reels (meteor, prisma, @prisma/client, drizzle-orm, scrypt, liquid). **C'est le chiffre operationnel** — ce qu'un operateur obtient via `muaddib scan` (rules + FP caps, sans ML). |
| **FPR** (Benign random, mesure v2.11.48) | **2.50%** (5/200) | 200 packages npm aleatoires, echantillonnage stratifie. Baisse depuis 7.0% (v2.10.95). |
| **FPR PyPI** (mesure v2.11.48, premiere mesure honnete) | **9.68%** (12/124 scannes, 132 total) | **Track D a fixe le downloader PyPI** — retrait du flag `pip --no-binary :all:` (forcait la compilation des packages wheel-only, timeout 38% des fois) + support `.whl` via `extractArchive()`. 42 packages massifs (numpy/pandas/django/matplotlib/scikit-learn/...) maintenant scannes. Les 12 FP sont TOUS au score 25-35 = signature du bug cap-PyPI-35 (Track E target), pas de nouveaux mis-fires. 8 fails residuels sur les geants >500MB (torch, tensorflow, scipy, opencv-python, ansible, playwright). |
| **ADR** (Adversarial + Holdout, v2.11.48) | **96.26%** (103/107) | 67 adversariaux + 40 holdouts (107 disponibles), seuil global=20. Stable vs v2.10.95. |
**Benchmark Datadog 17K (v2.10.21)** — [DataDog Malicious Software Packages Dataset](https://github.com/DataDog/malicious-software-packages-dataset), 17 922 packages malveillants npm. Wild TPR : **92.8%** (13 538/14 587 in-scope). 3 335 packages sans fichiers JS exclus comme hors scope. Erreurs : 0.
| Metrique | Valeur |
|----------|--------|
| Total packages | 17 922 |
| Hors scope (pas de JS) | 3 335 |
| In-scope | 14 587 |
| Detectes | 13 538 |
| Misses (score=0, in-scope) | 1 049 |
**Par categorie :**
- compromised_lib : **97.8%** (904/924)
- malicious_intent : **92.1%** (12 582/13 663 in-scope, 3 335 hors scope)
Voir [Evaluation Methodology](https://github.com/dnszlsk/muad-dib/blob/master/docs/docs/EVALUATION_METHODOLOGY.md#14-datadog-17k-benchmark).
---
[Read more](https://github.com/dnszlsk/muad-dib)