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'DIB Logo

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 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).

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)

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 validation (90/94 TPR@3, v2.11.48)