Shai-Hulud Supply Chain Attack Scanner

A Python tool to scan your GitHub organizations' repositories for indicators of compromise (IOCs) related to the Shai-Hulud npm supply chain attack.

Background

The Shai-Hulud attack is an ongoing supply chain attack targeting npm packages. It compromises packages to exfiltrate sensitive data (environment variables, secrets, tokens) from development environments and CI/CD pipelines.

References

• Wiz.io: Shai-Hulud 2.0 Supply Chain Attack
• SecurityWeek: 640 NPM Packages Infected
• CISA Alert

What This Scanner Detects

1. Malicious Files - Known malicious files like setup_bun.js, bun_environment.js, bundle.js
2. Malicious Branches - Checks for shai-hulud branches
3. Compromised Packages - Dependencies known to be infected (fetched from external sources)
4. Suspicious Scripts - preinstall/postinstall scripts with exfiltration patterns
5. Malicious Workflows - GitHub Actions workflows containing suspicious patterns
6. Known Malicious Hashes - Checks file SHAs against known malicious hashes

Key Features

• Auto-updating IOCs - Fetches the latest compromised package list from external sources
• Local caching - Caches IOCs locally for 24 hours to reduce network calls
• Fallback list - Uses a hardcoded fallback if external sources are unavailable
• Multiple sources - Tries multiple external IOC sources for reliability

Installation

cd shai-hulud-scanner
pip install -r requirements.txt

Usage

Basic Usage

# Set your GitHub Personal Access Token
export GITHUB_TOKEN=ghp_your_token_here

# Scan all your organizations
python shai_hulud_scanner.py

# Scan specific organizations
python shai_hulud_scanner.py --orgs myorg1 myorg2

# Scan personal repos only
python shai_hulud_scanner.py --personal-only

# Include personal repos with org repos
python shai_hulud_scanner.py --include-personal

IOC Management

# Force refresh IOC list from external sources
python shai_hulud_scanner.py --refresh-iocs

# List all known compromised packages
python shai_hulud_scanner.py --list-iocs

Generate a Report

# Output findings to JSON
python shai_hulud_scanner.py --output report.json

Options

Flag	Description
--token, -t	GitHub PAT (or set GITHUB_TOKEN env var)
--orgs, -o	Specific organizations to scan
--personal-only	Only scan personal repositories
--include-personal	Include personal repos with org repos
--output, -O	Output JSON report file
--verbose, -v	Show all repos, not just those with issues
--skip-archived	Skip archived repositories
--refresh-iocs	Force refresh IOC list from external sources
--list-iocs	List all known compromised packages and exit

IOC Sources

This scanner does NOT maintain any hardcoded IOC lists. All indicators of compromise are fetched from external security researchers who actively track the attack.

The scanner tries these sources (in order):

1. StepSecurity GitHub - Comprehensive IOC data including packages, files, patterns
2. Cobenian shai-hulud-detect - Community detection project
3. Socket.dev - Professional malware database

If ALL external sources fail, the scanner will error out rather than use stale data. This ensures you're always scanning against the latest threat intelligence.

IOCs are cached locally at ~/.cache/shai-hulud-scanner/iocs.json for 6 hours.

Required GitHub Token Scopes

Your Personal Access Token needs these scopes:

• repo - Full control of private repositories (to read contents)
• read:org - Read organization membership

Risk Levels

Level	Description
🚨 Critical	Known malicious files/branches detected (active compromise)
🔴 High	Suspicious files or compromised packages in dependencies
🟠 Medium	Suspicious scripts in package.json
🟡 Low	Suspicious patterns in workflows
✅ None	No issues detected

Mitigation Steps

If the scanner finds issues:

Immediate Actions

1. Remove malicious files - Delete any files identified in the scan
2. Delete malicious branches - Remove any malicious branches identified
3. Remove compromised packages - Update package.json to remove infected packages
4. Clean install - Delete node_modules and package-lock.json, then reinstall
5. Rotate secrets - Assume ALL environment variables and secrets are compromised
6. Review workflows - Check GitHub Actions for unauthorized changes
7. Block exfil domains - Block outbound connections to domains identified in scan

Long-term Actions

1. Enable Dependabot alerts
2. Use npm audit in CI/CD pipelines
3. Pin dependencies to specific versions
4. Review and limit GitHub App permissions
5. Implement least-privilege for CI/CD tokens

No Hardcoded Lists

Important: This scanner intentionally does NOT maintain any hardcoded IOC lists.

Why? Security researchers at StepSecurity, Socket.dev, and others are actively tracking this attack and updating their databases. They do this better than any static list we could maintain.

If external sources are unavailable, the scanner will fail rather than give you a false sense of security with outdated data.

Example Output

📋 Loading Indicators of Compromise...
  🌐 Fetching compromised package list from external sources...
     Trying StepSecurity GitHub... ✅ Found 156 packages
  ✅ Loaded 156 compromised packages (source: StepSecurity GitHub)

🔍 Scanning 150 repositories for Shai-Hulud indicators...
--------------------------------------------------------------------------------

  🚨 myorg/infected-repo [CRITICAL]
     URL: https://github.com/myorg/infected-repo
     🔥 MALICIOUS FILES/BRANCHES DETECTED:
        - branch:shai-hulud (⚠️  KNOWN MALICIOUS)
        - setup_bun.js (⚠️  KNOWN MALICIOUS)

  🔴 myorg/backend-api [HIGH]
     URL: https://github.com/myorg/backend-api
     📦 COMPROMISED PACKAGES:
        - @poppinss/colors@3.0.0
        - posthog-node@2.1.0

================================================================================
                              SCAN SUMMARY
================================================================================

    IOC Source:                   StepSecurity GitHub
    Total repositories scanned:   150
    Node.js repositories found:   45
    Repositories with issues:     2

    Risk Breakdown:
      🚨 Critical:  1
      🔴 High:      1
      🟠 Medium:    0
      🟡 Low:       0

    ⚠️  IMMEDIATE ACTION REQUIRED!

License

MIT