Installation | Usage | Features | VS Code | CI/CD
npm and PyPI supply-chain attacks are exploding. Shai-Hulud compromised 25K+ repos in 2025. Existing tools detect threats but don't help you respond.
MUAD'DIB combines 17 parallel scanners (234 detection rules), a deobfuscation engine, inter-module dataflow analysis, compound scoring (16 compound rules), ML classifiers (XGBoost), and gVisor/Docker sandbox to detect known threats and suspicious behavioral patterns in npm and PyPI packages.
MUAD'DIB is an educational tool and a free first line of defense. It detects known npm and PyPI threats (225,000+ IOCs) and suspicious behavioral patterns.
For enterprise protection, use:
- Socket.dev - ML behavioral analysis, cloud sandboxing
- Snyk - Massive vulnerability database, CI/CD integrations
- Opengrep - Advanced dataflow analysis, Semgrep rules
npm install -g muaddib-scannergit clone https://github.com/DNSZLSK/muad-dib
cd muad-dib
npm install
npm linkmuaddib scan .
muaddib scan /path/to/projectScans both npm (package.json, node_modules) and Python (requirements.txt, setup.py, pyproject.toml) dependencies.
muaddibmuaddib install <package>
muaddib install lodash axios --save-dev
muaddib install suspicious-pkg --force # Force install despite threatsScans packages for threats BEFORE installing. Blocks known malicious packages.
Each scan displays a 0-100 risk score:
[SCORE] 58/100 [***********---------] HIGH
muaddib scan . --explainShows rule ID, MITRE ATT&CK technique, references, and response playbook for each detection.
muaddib scan . --json > results.json # JSON
muaddib scan . --html report.html # HTML
muaddib scan . --sarif results.sarif # SARIF (GitHub Security)muaddib scan . --fail-on critical # Fail only on CRITICAL
muaddib scan . --fail-on high # Fail on HIGH and CRITICAL (default)muaddib scan . --paranoidUltra-strict detection with lower tolerance. Detects any network access, subprocess execution, dynamic code evaluation, and sensitive file access.
muaddib scan . --webhook "https://discord.com/api/webhooks/..."Strict filtering (v2.1.2): alerts only for IOC matches, sandbox-confirmed threats, or canary token exfiltration. Priority triage (v2.10.21): P1 (red, IOC/sandbox/canary), P2 (orange, high-score/compounds), P3 (yellow, rest).
muaddib scan . --temporal-full # All 4 temporal features
muaddib scan . --temporal # Sudden lifecycle script detection
muaddib scan . --temporal-ast # AST diff between versions
muaddib scan . --temporal-publish # Publish frequency anomaly
muaddib scan . --temporal-maintainer # Maintainer change detectionDetects supply-chain attacks before they appear in IOC databases by analyzing changes between package versions. See Evaluation Methodology for details.
muaddib sandbox <package-name>
muaddib sandbox <package-name> --strictDynamic analysis in an isolated Docker container: strace, tcpdump, filesystem diff, canary tokens, CI-aware environment, and monkey-patching preload for time-bomb detection (multi-run at [0h, 72h, 7d] offsets).
muaddib watch . # Real-time monitoring
muaddib daemon # Daemon mode (auto-scan npm install)
muaddib update # Update IOCs (fast, ~5s)
muaddib scrape # Full IOC refresh (~5min)
muaddib diff HEAD~1 # Compare threats with previous commit
muaddib init-hooks # Pre-commit hooks (husky/pre-commit/git)
muaddib scan . --breakdown # Explainable score decomposition
muaddib replay # Ground truth validation (61/65 TPR@3)| Scanner | Detection |
|---|---|
| AST Parse (acorn) | eval, Function, credential theft, binary droppers, prototype hooks |
| Pattern Matching | Shell commands, reverse shells, dead man's switch |
| Dataflow Analysis | Credential read + network send (intra-file and cross-file) |
| Obfuscation Detection | JS obfuscation patterns (skip .min.js) |
| Deobfuscation Pre-processing | String concat, charcode, base64, hex array, const propagation |
| Inter-module Dataflow | Cross-file taint propagation (3-hop chains, class methods) |
| Intent Coherence | Intra-file source-sink pairing (credential + eval/network) |
| Typosquatting | npm + PyPI (Levenshtein distance) |
| Python Scanner | requirements.txt, setup.py, pyproject.toml, 14K+ PyPI IOCs |
| Shannon Entropy | High-entropy strings (5.5 bits + 50 chars min) |
| AI Config Scanner | .cursorrules, CLAUDE.md, copilot-instructions.md injection |
| Package/Dependencies | Lifecycle scripts, IOC matching (225K+ packages) |
| GitHub Actions | Shai-Hulud backdoor detection |
| Hash Scanner | Known malicious file hashes |
| IOC Strings (intel-triage P1.1) | YARA-style string matching (Axios 2026, TeamPCP, GlassWorm, CanisterSprawl) |
| Anti-Forensic AST (intel-triage P1.2) | XOR loop + self-delete + decoy write compound (csec autodelete) |
| Stub Package (intel-triage P1.3) | Tiny main file + external dep URL + lifecycle hook (ltidi chain) |
| Monorepo Scanner | Lerna/pnpm-workspace/turbo detection (Sprint 1 audit MR-C2 fix) |
All rules (229 RULES + 5 PARANOID) are mapped to MITRE ATT&CK techniques. See SECURITY.md for the complete rules reference.
| Campaign | Status |
|---|---|
| GlassWorm (2026, 433+ packages) | Detected |
| Shai-Hulud v1/v2/v3 (2025) | Detected |
| event-stream (2018) | Detected |
| eslint-scope (2018) | Detected |
| Protestware (node-ipc, colors, faker) | Detected |
| Typosquats (crossenv, mongose, babelcli) | Detected |
The VS Code extension automatically scans your npm projects.
code --install-extension dnszlsk.muaddib-vscodeMUAD'DIB: Scan Project- Scan entire projectMUAD'DIB: Scan Current File- Scan current file- Settings:
muaddib.autoScan,muaddib.webhookUrl,muaddib.failLevel
See vscode-extension/README.md for full documentation.
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'| Input | Description | Default |
|---|---|---|
path |
Path to scan | . |
fail-on |
Minimum severity to fail | high |
sarif |
SARIF output file path | |
paranoid |
Ultra-strict detection | false |
muaddib init-hooks # Auto-detect (husky/pre-commit/git)
muaddib init-hooks --type husky # Force husky
muaddib init-hooks --mode diff # Only block NEW threatsWith pre-commit framework:
repos:
- repo: https://github.com/DNSZLSK/muad-dib
rev: v2.11.24
hooks:
- id: muaddib-scan| Metric | Result | Details |
|---|---|---|
| ML FPR | 2.85% (239/8,393 holdout) | XGBoost retrained on 56,564 samples, 64 features, threshold=0.710 |
| ML TPR | 99.93% (2,918/2,920 holdout) | 377 confirmed_malicious via OSSF/GHSA/npm correlation |
| Wild TPR (Datadog 17K) | 92.8% (13,538/14,587 in-scope) | 17,922 packages. 3,335 skipped (no JS). By category: compromised_lib 97.8%, malicious_intent 92.1% |
| TPR@3 (detection rate) | 93.85% (61/65) | 67 real attacks (65 active, 2 out-of-scope: GT-005 colors, GT-009 faker — protestware with min_threats=0). Threshold=3: any signal |
| TPR@20 (alert rate) | 86.2% (56/65) | Operational alert threshold=20, aligned with ADR/FPR |
| FPR rules (Benign curated, v2.10.95 measure) | 15.6% (85/545 scanned, 548 total) | npm packages, real source via npm pack; v2.10.74 estimated 6-9% reduction did NOT materialize on rebuilt corpus |
| FPR after ML (v2.10.95 measure) | 10.28% (56/545 scanned) | ML filters 29/30 T1 benign, 0 GT/ADR suppressed |
| FPR (Benign random, v2.10.95 measure) | 7.0% (14/200) | 200 random npm packages, stratified sampling |
| ADR (Adversarial + Holdout) | 96.3% (103/107) | 67 adversarial + 40 holdout (107 available on disk), global threshold=20 |
3602 tests across 93 files. 234 rules (229 RULES + 5 PARANOID).
ML retrain methodology (v2.10.51):
- Ground truth: 377 confirmed_malicious via auto-labeler (OSSF malicious-packages, GitHub Advisory Database, npm registry takedown correlation)
- Dataset: 56,564 samples (14,602 malicious, 41,962 clean). Stratified 80/20 split
- Grid search: depth=4, estimators=300, lr=0.05. AUC-ROC=0.999, F1=0.960
- Leaky feature filter: 23 dead/leaky features removed (source-identity proxies)
Static evaluation caveats:
- TPR measured on 65 active Node.js attack samples (2 out-of-scope: GT-005 colors, GT-009 faker, both protestware with min_threats=0; from 67 total)
- TPR@3 = detection rate (any signal); TPR@20 = operational alert threshold
- FPR measured on 532 curated popular npm packages (not a random sample)
- ADR measured with global threshold (score >= 20) as of v2.6.5
See Evaluation Methodology for the full experimental protocol, holdout history, and Datadog benchmark details.
Edit YAML files in iocs/:
- id: NEW-MALWARE-001
name: "malicious-package"
version: "*"
severity: critical
confidence: high
source: community
description: "Threat description"
references:
- https://example.com/article
mitre: T1195.002git clone https://github.com/DNSZLSK/muad-dib
cd muad-dib
npm install
npm test- 3602 tests across 93 modular test files
- 56 fuzz tests - Malformed inputs, ReDoS, unicode, binary
- Datadog 17K benchmark - 14,587 confirmed malware samples (in-scope)
- Ground truth validation - 67 real-world attacks (93.85% TPR@3, 86.2% TPR@20 — v2.10.95 measure)
- False positive validation (v2.10.95 measure) - 15.6% FPR rules (85/545 scanned), 10.28% after ML (56/545 scanned), 7.0% on 200 random
- Discord: https://discord.gg/y8zxSmue
- Blog - Technical articles on supply-chain threat detection
- Carnet de bord - Development journal (in French)
- Documentation Index - All documentation in one place
- Evaluation Methodology - Experimental protocol, holdout scores
- Threat Model - What MUAD'DIB detects and doesn't detect
- Security Policy - Detection rules reference (234 rules)
- Security Audit - Bypass validation report
- FP Analysis - Historical false positive analysis
MIT
The spice must flow. The worms must die.