Worm Buster

Security scanner for detecting the Shai-Hulud 2 npm supply chain attack (November 2025).

Quick Start

# Install dependencies
npm install

# Scan current directory (generates JSON, Markdown, and HTML reports)
npm run scan

# Full scan with process and credential checks
npm run scan:full

Installation

As a Project Dependency

npm install worm-buster

Global Installation

npm install -g worm-buster
worm-buster --help

From Source

git clone <repository-url>
cd worm-buster
npm install
npm link  # Makes 'worm-buster' command available globally

Usage

worm-buster [options] [directory1] [directory2] ...

Pass one or more directory paths to scan. If no directories are specified, scans the current directory.

Run Directly (no install)

# From the worm-buster directory
node index.js ~/code
node index.js /path/to/project
node index.js --full .

Command Line

# After npm link or global install
# Scan current directory (generates JSON, Markdown, and HTML reports)
worm-buster
worm-buster .

# Scan a specific directory
worm-buster /path/to/project

# Scan multiple directories
worm-buster ~/code/app1 ~/code/app2 ~/code/app3

# Scan all common project directories (~/{code,projects,dev,...})
worm-buster --all

# Full scan with process and credential checks
worm-buster --full ~/projects

# Output reports to a specific directory
worm-buster . -o ./reports

# JSON output only (for CI/CD pipelines)
worm-buster --json /path/to/project

Screenshots of report

CRITICAL	WARNING	INFO

Options

Option	Description
[directories...]	One or more directories to scan (default: current directory)
-h, --help	Show help message
-v, --verbose	Show verbose output including parse errors
--all	Scan all common project directories
--processes	Check for suspicious running processes
--credentials	Check credential files that may have been compromised
--full	Enable all checks (--processes + --credentials)
--json	Output results in JSON format only (no reports)
-o, --output DIR	Output directory for reports (default: current directory)

Programmatic Usage

const { scan, loadInfectedPackages, checkPackageJson } = require('worm-buster');

// Full scan
const findings = await scan({
  directories: ['/path/to/project'],
  verbose: true,
  checkProcesses: true,
});

// Check specific package.json
const infectedPackages = loadInfectedPackages('./worm.md');
const results = checkPackageJson('./package.json', infectedPackages);

npm Scripts

npm run scan          # Basic scan (generates all report formats)
npm run scan:full     # Full scan with all checks
npm run scan:all      # Scan all common directories
npm run test          # Run tests
npm run lint          # Run ESLint

What It Detects

Infected Packages (Critical)

Checks against 1000+ known infected npm packages from the Shai-Hulud 2 campaign. If your project has an exact infected version, this is flagged as CRITICAL.

Targeted Packages (Caution)

If you have a package that was targeted in the attack but you have a SAFE version, the tool shows a CAUTION notice. This warns you not to upgrade to the infected versions.

Malicious Artifacts (IoCs)

• .github/workflows/discussion.yaml - Backdoor workflow
• setup_bun.js, bun_environment.js - Malware payload files
• cloud.json, environment.json, truffleSecrets.json - Exfiltrated data
• formatter_*.yml workflows - Suspicious automated workflows

Suspicious Scripts

Detects potentially malicious npm lifecycle scripts (preinstall, postinstall) containing:

• bun, setup_, curl, wget, eval patterns

System Checks (with --full)

• Running processes matching malware patterns
• Credential files that may have been exfiltrated

Report Formats

All three report formats are generated by default in the current directory (or use -o to specify output directory).

JSON (worm-buster-report.json)

Machine-readable format for automation and CI/CD integration.

Markdown (worm-buster-report.md)

Human-readable report suitable for documentation and tickets.

HTML (worm-buster-report.html)

Styled report for sharing with IT/security teams via browser.

Exit Codes

Code	Meaning
0	No critical issues found
1	Critical issues detected
2	Fatal error occurred

Project Structure

worm-buster/
├── index.js           # Main entry point and CLI
├── lib/
│   ├── config.js      # IOC definitions and constants
│   ├── loader.js      # Infected packages database loader
│   ├── scanner.js     # File system scanning
│   ├── analyzer.js    # Package analysis
│   ├── system.js      # Process and credential checks
│   ├── output.js      # Console output formatting
│   └── reporter.js    # Report generation (JSON/MD/HTML)
├── test/              # Unit tests
├── worm.md            # Infected packages database
└── package.json

Response Actions

If infected packages are found:

1. DO NOT run npm install in affected projects
2. Remove infected packages from package.json
3. Delete node_modules and package-lock.json
4. Check .github/workflows for suspicious files
5. Rotate ALL credentials immediately:
   • AWS, Azure, GCP credentials
   • GitHub tokens
   • npm tokens
6. Review GitHub Actions for unauthorized workflows
7. Check for unauthorized Bun installation: which bun

CI/CD Integration

GitHub Actions

- name: Scan for Shai-Hulud 2
  run: |
    npx worm-buster --json . > scan-results.json
    if [ $? -eq 1 ]; then
      echo "::error::Infected packages detected!"
      exit 1
    fi

Pre-commit Hook

#!/bin/sh
npx worm-buster --json . > /dev/null
if [ $? -eq 1 ]; then
  echo "Error: Infected packages detected. Run 'npx worm-buster' for details."
  exit 1
fi

Testing

npm test                    # Run all tests
npm run test:watch          # Watch mode
npm run test:coverage       # With coverage

References

• Wiz Security - Shai-Hulud 2.0 Analysis
• Datadog Security Labs - npm Worm Analysis
• Check Point Research - Technical Deep Dive

License

MIT