Why MUAD'DIB?

npm supply-chain attacks are exploding. Shai-Hulud compromised 25K+ repos in 2025. Existing tools detect threats but don't help you respond.

MUAD'DIB detects AND guides your response.

Positioning

MUAD'DIB is an educational tool and a free first line of defense. It detects known npm threats (1500+ IOCs) and basic suspicious 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

MUAD'DIB does not replace these tools. It complements them for devs who want a quick, free check before installing an unknown package.

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

Interactive mode

muaddib

Launches an interactive menu to guide you through all features.

Safe install

muaddib install <package>
muaddib install lodash axios --save-dev
muaddib i express -g

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 (full details)

muaddib scan . --explain

Shows for each detection:

• Rule ID
• MITRE ATT&CK technique
• References (articles, CVEs)
• Response playbook

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 medium    # Fail on MEDIUM, HIGH, CRITICAL

Paranoid mode

muaddib scan . --paranoid

Ultra-strict detection with lower tolerance. Useful for critical projects. Detects any network access, subprocess execution, dynamic code evaluation, and sensitive file access.

Discord/Slack webhook

muaddib scan . --webhook "https://discord.com/api/webhooks/..."

Sends an alert with score and threats to Discord or Slack.

Real-time monitoring

muaddib watch .

Daemon mode

muaddib daemon
muaddib daemon --webhook "https://discord.com/api/webhooks/..."

Automatically monitors all npm install commands and scans new packages.

Update IOCs

muaddib update

Scrape new IOCs

muaddib scrape

Fetches latest malicious packages from multiple verified threat intelligence sources:

• GenSecAI Shai-Hulud 2.0 Detector - Consolidated list of 700+ Shai-Hulud packages
• DataDog Security Labs - Consolidated IOCs from multiple vendors
• OSSF Malicious Packages - OpenSSF database (8000+ reports via OSV.dev)
• GitHub Advisory Database - Malware-tagged advisories
• Snyk Known Malware - Historical malware packages
• Static IOCs - Socket.dev, Phylum, npm-removed packages

Docker Sandbox

muaddib sandbox <package-name>

Analyzes a package in an isolated Docker container. Captures:

• Network connections (detects exfiltration to suspicious hosts)
• File access (detects credential theft: .npmrc, .ssh, .aws, .env)
• Process spawns (detects reverse shells, curl/wget abuse)

Requires Docker Desktop installed.

muaddib sandbox lodash          # Safe package
muaddib sandbox suspicious-pkg  # Analyze unknown package

Features

Typosquatting detection

MUAD'DIB detects packages with names similar to popular packages:

[HIGH] Package "lodahs" looks like "lodash" (swapped_chars). Possible typosquatting.

Dataflow analysis

Detects when code reads credentials AND sends them over the network:

[CRITICAL] Suspicious flow: credential read (readFileSync, GITHUB_TOKEN) + network send (fetch)

Detected attacks

| Campaign | Packages | Status | |----------|----------|--------| | Shai-Hulud v1 (Sept 2025) | @ctrl/tinycolor, ng2-file-upload | Detected | | Shai-Hulud v2 (Nov 2025) | @asyncapi/specs, posthog-node, kill-port | Detected | | Shai-Hulud v3 (Dec 2025) | @vietmoney/react-big-calendar | Detected | | event-stream (2018) | flatmap-stream, event-stream | Detected | | eslint-scope (2018) | eslint-scope | Detected | | Protestware | node-ipc, colors, faker | Detected | | Typosquats | crossenv, mongose, babelcli | Detected |

Detected techniques

| Technique | MITRE | Detection | |-----------|-------|-----------| | Credential theft (.npmrc, .ssh) | T1552.001 | AST | | Env var exfiltration | T1552.001 | AST | | Remote code execution | T1105 | Pattern | | Reverse shell | T1059.004 | Pattern | | Dead man's switch | T1485 | Pattern | | Obfuscated code | T1027 | Heuristics | | Typosquatting | T1195.002 | Levenshtein | | Supply chain compromise | T1195.002 | IOC matching |

IOC Sources

MUAD'DIB aggregates threat intelligence from verified sources only:

| Source | Type | Coverage | |--------|------|----------| | GenSecAI Shai-Hulud Detector | GitHub | 700+ Shai-Hulud packages | | DataDog Security Labs | GitHub | Consolidated IOCs from 7 vendors | | OSSF Malicious Packages | OSV API | 8000+ malware reports | | GitHub Advisory | OSV API | Malware-tagged advisories | | Snyk Known Malware | Static | Historical attacks | | Socket.dev / Phylum | Static | Manual additions |

VS Code

The VS Code extension automatically scans your npm projects.

Installation

Search "MUAD'DIB" in VS Code Extensions, or:

code --install-extension dnszlsk.muaddib-vscode

Commands

• MUAD'DIB: Scan Project - Scan entire project
• MUAD'DIB: Scan Current File - Scan current file

Settings

• muaddib.autoScan - Auto-scan on project open (default: true)
• muaddib.webhookUrl - Discord/Slack webhook URL
• muaddib.failLevel - Alert level (critical/high/medium/low)

CI/CD

GitHub Actions

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: actions/setup-node@v4
        with:
          node-version: '20'
      - run: npm install -g muaddib-scanner
      - run: muaddib scan . --sarif results.sarif
      - uses: github/codeql-action/upload-sarif@v3
        with:
          sarif_file: results.sarif

Alerts appear in Security > Code scanning alerts.

Architecture

MUAD'DIB Scanner
|
+-- IOC Match (1500+ packages, JSON DB)
|   +-- GenSecAI Shai-Hulud Detector
|   +-- DataDog Consolidated IOCs
|   +-- OSSF Malicious Packages (via OSV)
|   +-- GitHub Advisory (malware)
|   +-- Snyk Known Malware
|   +-- Static IOCs (Socket, Phylum)
|
+-- AST Parse (acorn)
+-- Pattern Matching (shell, scripts)
+-- Typosquat Detection (Levenshtein)
+-- Paranoid Mode (ultra-strict)
+-- Docker Sandbox (behavioral analysis)
|
v
Dataflow Analysis (credential read -> network send)
|
v
Threat Enrichment (rules, MITRE ATT&CK, playbooks)
|
v
Output (CLI, JSON, HTML, SARIF, Webhook)

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

Community

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

Documentation

• Threat Model - What MUAD'DIB detects and doesn't detect
• IOCs YAML - Threat database

License

MIT