dnszlsk/muad-dibReal-time npm/PyPI supply-chain threat detection. Behavioral chain analysis, AST scanning, IOC feeds, and compound scoring engine.
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 22 parallel scanners (278 detection rules), a deobfuscation engine, inter-module dataflow analysis, compound scoring (21 compound rules), and a gVisor/Docker sandbox to detect known threats and suspicious behavioral patterns in npm and PyPI packages. An XGBoost classifier exists in the codebase but is currently inactive (see Evaluation).
MUAD'DIB is a free, open, and fully auditable supply-chain scanner for npm and PyPI. It detects known threats (225,000+ IOCs), install-time RCE, credential-then-exfiltration flows, obfuscated payloads, and other suspicious behavioral patterns — locally, with no telemetry.
It is licensed under the AGPL-3.0; a commercial license is available for organizations that need to embed it in a proprietary product or run it as a closed hosted service (see License).
It deliberately does not try to do everything — see Scope for exactly what it catches and what it does not.
Detects (npm & PyPI): known-malicious packages (name + SHA256 IOC match), typosquats, install-time RCE (lifecycle preinstall/postinstall, curl | sh, Python import-time, binding.gyp), credential read then network exfiltration (intra- and cross-file), obfuscated / high-entropy / stub-loader payloads, binary droppers (chmod +x + exec/spawn), and anti-analysis evasion markers.
Out of scope: browser-only attacks (DOM/window, no Node.js API), the contents of native binaries / WASM (no binary analysis), zero-day unknown packages (the IOC feed is reactive), and non-npm/PyPI ecosystems (RubyGems, Maven, Go). Determined anti-sandbox fingerprinting and multi-stage remote payloads are known false-negative risks. Full detail: Threat Model.
No telemetry. Your code and scan results never leave your machine — MUAD'DIB only downloads threat-intel feeds (muaddib update) and, for scoring, reads public npm registry metadata. Webhook alerts are opt-in.
npm install -g muaddib-scanner
git clone https://github.com/DNSZLSK/muad-dib
cd muad-dib
npm install
npm link
muaddib scan .
muaddib scan /path/to/project
Scans both npm (package.json, node_modules) and Python (requirements.txt, setup.py, pyproject.toml) dependencies.
muaddib
muaddib install <package>
muaddib install lodash axios --save-dev
muaddib install suspicious-pkg --force # Force install despite threats
Scans packages for threats BEFORE installing. Blocks known malicious packages.
Each scan displays a 0-100 risk score:
[SCORE] 58/100 [***********---------] HIGH
muaddib scan . --explain
Shows 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 . --paranoid
Ultra-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 detection
Detects 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> --strict
Dynamic 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 (90/94 TPR@3, v2.11.48)