
muad-dib v2.12.0
كشف التهديدات في سلسلة التوريد لـ npm/PyPI في الوقت الفعلي. تحليل السلاسل السلوكية، مسح AST، تغذية مؤشرات الاختراق (IOC)، ومحرك تسجيل مركب.
Installation | Usage | Features | VS Code | CI/CD
Why MUAD'DIB?
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 isolated scanners (run one after the other; a crash in one never stops the others) (277 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).
Positioning
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.
Scope
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.
Installation
npm (recommended)
npm install -g muaddib-scanner
From source
git clone https://github.com/DNSZLSK/muad-dib
cd muad-dib
npm install
npm link
Usage
Basic scan
muaddib scan .
muaddib scan /path/to/project
Scans both npm (package.json, node_modules) and Python (requirements.txt, setup.py, pyproject.toml) dependencies.
Interactive mode
muaddib
Safe install
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.
Risk score
Each scan displays a 0-100 risk score:
[SCORE] 58/100 [***********---------] HIGH
Explain mode
muaddib scan . --explain
Shows rule ID, MITRE ATT&CK technique, references, and response playbook for each detection.
Export
muaddib scan . --json > results.json # JSON
muaddib scan . --html report.html # HTML
muaddib scan . --sarif results.sarif # SARIF (GitHub Security)
Severity threshold
muaddib scan . --fail-on critical # Fail only on CRITICAL
muaddib scan . --fail-on high # Fail on HIGH and CRITICAL (default)
muaddib scan . --fail-on-inconclusive # Also fail when the analysis is INCONCLUSIVE (fail closed)
A scan is INCONCLUSIVE when an internal bound was reached (timeout, graph size, file cap): some code was not fully analyzed and findings may be missing. The JSON carries analysis.status, SARIF carries error-level tool notifications. By default the exit code ignores it; use --fail-on-inconclusive in CI to treat a partial analysis as a failure. Measured with the former 500-file cap: 3.8 % of 395 packages drawn through npm search (14 of the 15 hit that cap; at the current 2 000 cap, 5 of those 14 are complete and the other 9 stop at the module-graph edge limit) and 21.8 % of packages the monitor had already flagged; see CHANGELOG.
Paranoid mode
muaddib scan . --paranoid
Ultra-strict detection with lower tolerance. Detects any network access, subprocess execution, dynamic code evaluation, and sensitive file access.
Webhook alerts
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).
Behavioral anomaly detection (v2.0)
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.
Docker sandbox
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).
Other commands
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 replay, non-regression (90/94 at v2.11.48)