🚨 Shai Hulud 2.0 Scanner

796+ npm packages compromised in November 2025. Is your project infected?

Fast, comprehensive scanner to detect the fastest-spreading npm supply chain attack ever observed. Scans for malicious files, stolen credentials, and automated worm propagation patterns.

🚨 About Shai Hulud 2.0

Shai Hulud 2.0 is one of the fastest-spreading npm supply chain attacks ever observed. The automated worm:

• Hijacked 796+ unique npm packages (1,092+ total versions)
• Stole credentials (npm tokens, GitHub tokens, cloud credentials)
• Created malicious GitHub repositories
• Exfiltrated secrets using TruffleHog
• Spread automatically to maintainer's other packages

Timeline: Active November 2025 Vector: Stolen npm credentials → automated package hijacking → credential harvesting loop

⚡ Quick Start (30 seconds)

# Download and run (no installation required)
curl -sSL https://raw.githubusercontent.com/nxgn-kd01/shai-hulud-scanner/main/scan.sh | bash -s /path/to/your/project

# Or clone and run
git clone https://github.com/nxgn-kd01/shai-hulud-scanner.git
cd shai-hulud-scanner
chmod +x scan.sh
./scan.sh /path/to/your/project

Results in seconds: 🚨 Critical findings | ⚠️ Warnings | ✅ All clear

📋 What This Scanner Checks

This tool performs 8 comprehensive security checks:

1. Malicious File Detection 🔴 Critical

• setup_bun.js - Malicious preinstall script
• bun_environment.js - Obfuscated payload (6 known variants)

2. File Hash Verification 🔴 Critical

Validates files against known malicious SHA-256 hashes:

• a3894003ad1d293ba96d77881ccd2071446dc3f65f434669b49b3da92421901a (setup_bun.js)
• 6 known hashes for bun_environment.js variants

3. Lifecycle Script Analysis 🟡 Warning

• Detects suspicious lifecycle scripts in package.json:
  • preinstall (highest risk - runs before npm install)
  • postinstall (runs after npm install)
  • install (runs during npm install)
  • prepare (runs after package is packed)
• Identifies references to setup_bun or bun_environment
• Flags unexpected script modifications

4. Compromised Package Ecosystems 🟡 Warning

Checks for packages from affected ecosystems:

• @asyncapi/* (~60 compromised packages)
• @voiceflow/* (~90 compromised packages)
• posthog-* (~80 compromised packages)
• @ensdomains/* (~40 compromised packages)
• quickswap-* (~10 compromised packages)
• zapier-* (~15 compromised packages)

5. TruffleHog Detection 🟡 Warning

• Scans for TruffleHog secret scanning tool
• Used by malware for credential harvesting

6. Recent Modifications Analysis 🔵 Info

• Reviews package.json changes in last 30 days
• Identifies suspicious patch version bumps
• Helps spot unexpected modifications

7. GitHub Repository Patterns 🟡 Warning

• Detects repos with description: "Sha1-Hulud: The Second Coming."
• Identifies suspicious 18-character lowercase alphanumeric repo names
• Flags unusual repository creation patterns

8. Package Lockfile Integrity 🟡 Warning

• Checks for non-standard registry URLs in lockfiles
• Detects git-based dependencies (potential supply chain risk)
• Validates package-lock.json and yarn.lock integrity

🚀 Getting Started

Prerequisites

Required:

• macOS or Linux (Bash 4.0+)
• find command (pre-installed)

Optional (recommended for full scanning):

• git - For analyzing modification history
• gh (GitHub CLI) - For scanning GitHub repositories
• shasum or sha256sum - For file hash verification (usually pre-installed)

Step 1: Get the Scanner

Option A: Clone (Recommended for users)

# Clone the repository
git clone https://github.com/nxgn-kd01/shai-hulud-scanner.git
cd shai-hulud-scanner

# Make script executable
chmod +x scan.sh

Option B: Fork (Recommended for contributors)

# Fork on GitHub (click "Fork" button on repository page)
# Then clone your fork
git clone https://github.com/YOUR_USERNAME/shai-hulud-scanner.git
cd shai-hulud-scanner

# Make script executable
chmod +x scan.sh

# Add upstream remote to stay updated
git remote add upstream https://github.com/nxgn-kd01/shai-hulud-scanner.git

Option C: Quick Download (No git required)

# Download and run directly
curl -sSL https://raw.githubusercontent.com/nxgn-kd01/shai-hulud-scanner/main/scan.sh -o scan.sh
chmod +x scan.sh
./scan.sh /path/to/your/project

Step 2: Setup GitHub CLI (Optional but Recommended)

To scan your GitHub repositories for suspicious patterns, you'll need the GitHub CLI:

Install GitHub CLI:

# macOS
brew install gh

# Linux (Debian/Ubuntu)
curl -fsSL https://cli.github.com/packages/githubcli-archive-keyring.gpg | sudo dd of=/usr/share/keyrings/githubcli-archive-keyring.gpg
echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/githubcli-archive-keyring.gpg] https://cli.github.com/packages stable main" | sudo tee /etc/apt/sources.list.d/github-cli.list > /dev/null
sudo apt update
sudo apt install gh

# Linux (RHEL/Fedora)
sudo dnf install gh

Authenticate with GitHub:

# Login to GitHub
gh auth login

# Follow the prompts:
# 1. Select "GitHub.com"
# 2. Select "HTTPS" or "SSH" (HTTPS recommended)
# 3. Select "Login with a web browser"
# 4. Copy the one-time code shown
# 5. Press Enter to open browser
# 6. Paste code and authorize

# Verify authentication
gh auth status

Step 3: Run Your First Scan

Scan a Local Project:

# Scan the current directory
./scan.sh

# Scan a specific project
./scan.sh /path/to/your/project

# Example: Scan your Node.js project
./scan.sh ~/code/my-app

Scan Multiple Projects:

# Scan all projects in a directory
for dir in ~/code/*/; do
    echo "===================="
    echo "Scanning: $(basename $dir)"
    echo "===================="
    ./scan.sh "$dir"
    echo ""
done

What Happens During a Scan:

1. 🔍 Searches for malicious files (setup_bun.js, bun_environment.js)
2. 🔐 Verifies file hashes against known malware
3. 📦 Checks package.json for suspicious scripts
4. 🌐 Scans dependencies for compromised packages
5. 🔨 Looks for TruffleHog secret scanner
6. 📅 Analyzes recent package.json modifications
7. 🐙 Checks your GitHub repos for suspicious patterns (if gh authenticated)

Step 4: Review the Results

Console Output:

The scanner displays color-coded results:

• 🚨 RED (Critical) - Immediate action required, malware detected
• ⚠️ YELLOW (Warning) - Suspicious patterns, review recommended
• ✅ GREEN (Success) - Check passed, no issues
• ℹ️ BLUE (Info) - Informational findings

Detailed Report:

A full report is saved to shai-hulud-scan-report.txt in the current directory:

# View the report
cat shai-hulud-scan-report.txt

# Or open in your editor
code shai-hulud-scan-report.txt

Step 5: Scan Remote Repositories

Scan GitHub Repos Without Cloning:

# List your repos
gh repo list --limit 100

# Clone and scan a specific repo
gh repo clone YOUR_ORG/repo-name /tmp/scan-temp
./scan.sh /tmp/scan-temp
rm -rf /tmp/scan-temp

# Or create a helper script
cat > scan-remote.sh <<'EOF'
#!/bin/bash
REPO=\$1
TEMP_DIR=$(mktemp -d)
echo "Cloning $REPO to temporary directory..."
gh repo clone "$REPO" "$TEMP_DIR"
echo "Scanning..."
./scan.sh "$TEMP_DIR"
echo "Cleaning up..."
rm -rf "$TEMP_DIR"
EOF
chmod +x scan-remote.sh

# Use it:
./scan-remote.sh YOUR_USERNAME/repo-name

Common Issues & Solutions

Issue: "Permission denied"

# Make script executable
chmod +x scan.sh

Issue: "gh: command not found"

# Install GitHub CLI (see Step 2)
# Or skip GitHub repo scanning (other checks will still run)

Issue: "shasum: command not found"

# Install coreutils (usually pre-installed on macOS)
# Linux:
sudo apt-get install coreutils  # Debian/Ubuntu
sudo yum install coreutils       # RHEL/CentOS

# Or use sha256sum instead (scanner auto-detects)

Issue: Scan shows "INFO" items but you want details

# View the full report file
less shai-hulud-scan-report.txt

# Or use grep to find specific issues
grep -A 5 "WARNING\|CRITICAL" shai-hulud-scan-report.txt

📖 Usage

Basic Scan

Scan the current directory:

./scan.sh

Scan Specific Directory

./scan.sh /path/to/your/project

Scan Multiple Projects

# Scan all projects in a parent directory
for dir in /Users/username/code/*/; do
    echo "Scanning $dir"
    ./scan.sh "$dir"
done

JSON Output (v1.1.0+)

For automation and SIEM integration:

# Get JSON output
./scan.sh /path/to/project --json

# Pipe to jq for processing
./scan.sh /path/to/project --json | jq '.summary'

# Save results
./scan.sh /path/to/project --json > scan-results.json

Example JSON output:

{
  "scanner": "shai-hulud-scanner",
  "version": "1.1.0",
  "scanDate": "2025-01-02T12:00:00Z",
  "scanDirectory": "/path/to/project",
  "summary": {
    "critical": 0,
    "warning": 1,
    "info": 2
  },
  "findings": [
    {
      "severity": "warning",
      "category": "scripts",
      "message": "postinstall script found",
      "file": "/path/to/project/package.json"
    }
  ],
  "references": [...]
}

CI/CD Integration

Quick Integration:

name: Security Scan

on: [push, pull_request]

jobs:
  shai-hulud-scan:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3

      - name: Run Shai Hulud Scanner
        run: |
          curl -sSL https://raw.githubusercontent.com/nxgn-kd01/shai-hulud-scanner/main/scan.sh | bash -s .

Full Example Workflow:

See examples/github-actions-workflow.yml for a complete workflow with:

• Artifact uploads
• PR comments with scan results
• Automatic issue creation on detection
• Scheduled daily scans

📊 Output

Console Output

The scanner provides color-coded results:

• 🚨 RED (Critical): Immediate action required
• ⚠️ YELLOW (Warning): Review recommended
• ✅ GREEN (Success): Check passed
• ℹ️ BLUE (Info): Informational findings

Report File

A detailed report is saved to shai-hulud-scan-report.txt containing:

• Scan metadata (date, directory, version)
• Detailed findings for each check
• Recommended actions if issues found
• References to security resources

Exit Codes

• 0 - No issues found or warnings only
• 1 - Critical issues detected

🎯 Example Output

=== Shai Hulud 2.0 Scanner v1.1.0 ===
Scanning directory: /Users/username/project

=== 1. Scanning for Malicious Files ===
✅ No malicious files found

=== 2. Checking File Hashes ===
✅ No known malicious file hashes detected

=== 3. Checking package.json for Suspicious Scripts ===
✅ No suspicious scripts found

=== 4. Checking for Compromised Package Ecosystems ===
✅ No packages from compromised ecosystems found

=== 5. Scanning for TruffleHog ===
✅ No TruffleHog installations found

=== 6. Analyzing Recent package.json Changes ===
✅ No recent package.json modifications

=== 7. Checking GitHub Repository Patterns ===
✅ No suspicious repository descriptions
✅ No suspicious repository names

=== 8. Checking Package Lockfile Integrity ===
✅ Lockfile integrity checks passed

=== Scan Summary ===

Critical Issues: 0
Warnings: 0
Info Items: 0

✅ All clear! No indicators of compromise found.
ℹ️  Detailed report saved to: shai-hulud-scan-report.txt

🔧 Troubleshooting

"shasum: command not found"

Install shasum (usually part of coreutils):

# macOS (built-in)
# Linux
sudo apt-get install coreutils  # Debian/Ubuntu
sudo yum install coreutils       # RHEL/CentOS

"gh: command not found"

Install GitHub CLI:

# macOS
brew install gh

# Linux
curl -fsSL https://cli.github.com/packages/githubcli-archive-keyring.gpg | sudo dd of=/usr/share/keyrings/githubcli-archive-keyring.gpg
echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/githubcli-archive-keyring.gpg] https://cli.github.com/packages stable main" | sudo tee /etc/apt/sources.list.d/github-cli.list > /dev/null
sudo apt update
sudo apt install gh

# Authenticate
gh auth login

🛡️ What To Do If Compromise Is Detected

⚠️ CRITICAL: If the scanner detects issues, follow our comprehensive remediation guide immediately.

📖 Complete Incident Response Guide

Read the full guide: REMEDIATION.md

The guide includes:

• ✅ Immediate response steps (first 15 minutes)
• ✅ Complete credential rotation procedures (npm, GitHub, AWS, GCP, Azure, etc.)
• ✅ Code cleanup instructions
• ✅ Investigation and forensics procedures
• ✅ Disclosure and reporting requirements
• ✅ Post-incident hardening measures
• ✅ Recovery checklist

Quick Response (First 15 Minutes)

1. Isolate Affected Systems

   # Stop deployments immediately
   # Move compromised code to quarantine
   mkdir ~/quarantine-$(date +%Y%m%d)
   mv /path/to/compromised-project ~/quarantine-$(date +%Y%m%d)/
   

2. Rotate ALL Credentials Immediately

   # npm tokens
   npm token revoke --all
   
   # GitHub tokens
   gh auth logout && gh auth login
   
   # AWS/GCP/Azure - see REMEDIATION.md for full instructions
   

3. Remove Malicious Code

   find . -name "setup_bun.js" -delete
   find . -name "bun_environment.js" -delete
   git add -A && git commit -m "SECURITY: Remove malicious files"
   

4. Report the Incident

   • npm security: security@npmjs.com
   • GitHub security: security@github.com
   • Follow disclosure guidelines in REMEDIATION.md

5. Follow Complete Guide

   • See REMEDIATION.md for detailed step-by-step instructions
   • Use the recovery checklist to track progress
   • Document everything for post-mortem

For Warnings

If you get warnings (not critical issues):

1. Review the scan report

   cat shai-hulud-scan-report.txt
   

2. Verify legitimacy of flagged items

3. Update dependencies if needed: npm audit && npm update

4. Re-run scanner to confirm: ./scan.sh .

Need Help?

• Detailed Guide: REMEDIATION.md - Complete incident response procedures
• Community: GitHub Discussions
• Professional IR: If severe, consider engaging professional incident response
• CISA: Report to https://www.cisa.gov/report

📚 Resources

Official IOC Sources

• DataDog IOC Repository: github.com/DataDog/indicators-of-compromise
• DataDog Analysis: securitylabs.datadoghq.com/articles/shai-hulud-2.0-npm-worm
• Microsoft Security Blog: Shai-Hulud 2.0 Guidance
• Wiz Research: Shai-Hulud 2.0 Ongoing Attack
• CISA Alert: Widespread Supply Chain Compromise
• Consolidated IOC List: 1,000+ compromised packages tracked

Community Tools

Shai Hulud 2.0 Detection:

• Shai-Hulud-2.0-Detector - GitHub Action with SARIF support
• sha1-hulud-scanner - npm package scanner

Related Vulnerability Scanners:

• react2shell-scanner - Detect CVE-2025-55182 (React2Shell) RCE vulnerability in React Server Components

Security Best Practices

• npm Security Best Practices
• OWASP Supply Chain Security
• GitHub Security Advisories

🤝 Contributing

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/improvement)
3. Commit your changes (git commit -m 'Add new detection')
4. Push to the branch (git push origin feature/improvement)
5. Open a Pull Request

Ideas for Contributions

• Add support for additional IOC sources
• Implement JSON output format (v1.1.0)
• Add lockfile integrity checks (v1.1.0)
• Detect all lifecycle scripts (v1.1.0)
• Add Docker container support
• Create npm package version
• Add integration tests
• Support for other package managers (pip, cargo, etc.)

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

⚠️ Disclaimer

This tool is provided "as is" for security research and defensive purposes only. While we make every effort to keep the IOC list current, new variants may emerge. Always:

• Keep the scanner updated
• Follow official security advisories
• Report suspected compromises to npm security
• Maintain defense-in-depth security practices

🙏 Acknowledgments

• DataDog Security Labs for comprehensive IOC research and analysis
• npm Security Team for rapid response
• Community security researchers: Koi.ai, StepSecurity, ReversingLabs, HelixGuard, SocketDev, Wiz

📞 Support

• Issues: GitHub Issues
• Security: Report vulnerabilities privately to security@yourdomain.com
• Discussions: GitHub Discussions

---

Stay Safe! 🛡️

Remember to run this scanner:

• ✅ Before npm install operations
• ✅ Before merging dependency updates
• ✅ Regularly in CI/CD pipelines
• ✅ After inheriting or acquiring projects