2.11.154 • Published 12h agoCLI

muaddib-scanner

Licence

MIT

Version

2.11.154

Deps

Size

3.1 MB

Vulns

Weekly

Stars

Summary Dependency Versions

MUAD'DIB Logo

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

Version francaise

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 21 parallel scanners (274 detection rules), a deobfuscation engine, inter-module dataflow analysis, compound scoring (20 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 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

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)

Features

21 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
IOC Strings (intel-triage P1.1)	YARA-style string matching (Axios 2026, TeamPCP, GlassWorm, CanisterSprawl)
Anti-Forensic AST (intel-triage P1.2)	XOR loop + self-delete + decoy write compound (csec autodelete)
Stub Package (intel-triage P1.3)	Tiny main file + external dep URL + lifecycle hook (ltidi chain)
Monorepo Scanner	Lerna/pnpm-workspace/turbo detection (Sprint 1 audit MR-C2 fix)
Trusted-Dep-Diff (opt-in)	Diff against trusted dep tarballs from registry (v2.10.x)
Python Source (PYSRC)	Import-time / install-time RCE patterns in `__init__.py` / `setup.py` (v2.11.41 — closes TrapDoor PyPI gap)
Python AST (PYAST)	Tree-sitter-Python AST with taint-aware detectors (v2.11.42+)
Anti-Scanner Injection (ASI)	Prompt-injection text in comments/strings that coerces an LLM code reviewer into a clean verdict or into skipping an obfuscated payload (ASI-001..004, Hades campaign 2026-06)

274 detection rules

All rules (269 RULES + 5 PARANOID) 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.11.139
    hooks:
      - id: muaddib-scan

Evaluation

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.

Metric	Result
Detection rate (TPR@3)	95.74% (90/94)
Alert rate (TPR@20)	88.30% (83/94)
FPR — curated npm (548)	1.10% (6/545)
FPR — random npm (200)	2.50% (5/200)
FPR — PyPI (132)	9.68% (12/124)
ADR — adversarial + holdout	96.26% (103/107)
Wild TPR (Datadog 17K)	92.8% (13,538/14,587)

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.

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

4500 tests across 147 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.

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

License

MIT

The spice must flow. The worms must die.

Keywords

security npm pypi python supply-chain malware scanner typosquatting shai-hulud detection ast sarif sandbox threat-intelligence