Installation | Usage | Features | VS Code | CI/CD

Version francaise

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

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)

All rules (272 RULES + 5 PARANOID) are mapped to MITRE ATT&CK techniques. See SECURITY.md for the complete rules reference.

The VS Code extension automatically scans your npm projects.

code --install-extension dnszlsk.muaddib-vscode

• MUAD'DIB: Scan Project - Scan entire project
• MUAD'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'

muaddib init-hooks                        # Auto-detect (husky/pre-commit/git)
muaddib init-hooks --type husky           # Force husky
muaddib init-hooks --mode diff            # Only block NEW threats

With pre-commit framework:

repos:
  - repo: https://github.com/DNSZLSK/muad-dib
    rev: v2.11.139
    hooks:
      - id: muaddib-scan

Last measured v2.11.48 (2026-05-26), rules-only (the ML classifier is inactive — see below). Ground truth: 94 in-scope real-world attacks + 200 random npm + 124 PyPI + 107 adversarial/holdout.

ML classifier: inactive. An XGBoost model lives in src/ml/ but is never wired into muaddib scan, and runs LOG-ONLY in the monitor since 2026-04-08 (the trained model collapsed, pending retrain). All numbers above are rules-only.

Full protocol, per-track history, the PyPI cap-35 caveat, operational (GHSA-denominated) coverage, and the ML retrain methodology: Evaluation Methodology.

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

git clone https://github.com/DNSZLSK/muad-dib
cd muad-dib
npm install
npm test

• 4539 tests across 152 modular test files
• 56 fuzz tests - Malformed inputs, ReDoS, unicode, binary
• Datadog 17K benchmark - 14,587 confirmed malware samples (in-scope)
• Ground truth validation - 96 real-world attacks (95.74% TPR@3, 88.30% TPR@20 — v2.11.48 full measure on 94 in-scope)
• False positive validation (v2.11.48 measure) - 1.10% FPR rules (6/545 scanned), 2.50% on 200 random, 9.68% on 124/132 PyPI (first honest measurement post-Track-D download fix). ML classifier currently inactive — see Evaluation Metrics → ML Classifier.

• 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 (277 rules)
• Security Audit - Bypass validation report
• FP Analysis - Historical false positive analysis

MUAD'DIB is licensed under the GNU Affero General Public License v3.0 only (AGPL-3.0-only) — see LICENSE and NOTICE.

You are free to use, study, modify, and redistribute it — including over a network — provided that derivative works and network-deployed modifications are released under the same license.

Commercial licensing: to embed MUAD'DIB in a proprietary / closed-source product, or to offer it as a hosted service without the AGPL's source-disclosure obligations, a separate commercial license is available. Open an issue or contact the author (DNSZLSK).

Copyright (C) 2026 DNSZLSK.

The spice must flow. The worms must die.