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 14 parallel scanners (209 detection rules), a deobfuscation engine, inter-module dataflow analysis, compound scoring, ML classifiers (XGBoost), and gVisor/Docker sandbox to detect known threats and suspicious behavioral patterns in npm and PyPI packages.

Positioning

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

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 (61/65 TPR@3)

Features

14 parallel scanners

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

209 detection rules

All rules are mapped to MITRE ATT&CK techniques. See SECURITY.md for the complete rules reference.

Detected campaigns

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

VS Code

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.

CI/CD

GitHub Actions (Marketplace)

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 |

Pre-commit hooks

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.10.97
    hooks:
      - id: muaddib-scan

Evaluation Metrics

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

3280 tests across 69 files. 209 rules (204 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.

Contributing

Add IOCs

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

Development

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

Testing

• 3280 tests across 69 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

Community

• Discord: https://discord.gg/y8zxSmue

Documentation

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

License

MIT