@otaviomarcal/npm-supply-chain-detector

v3.0.9

Published

8 days ago

Local-first npm supply-chain detector CLI for known malicious packages, workflows, and IoCs.

0High
0Medium
0Low

otaviohm

npm security supply-chain cli bash incident-response appsec devsecops

npm Supply Chain Detector

This repository started as a fork of shai-hulud-detect, originally created around the September 2025 campaign, and evolved into a broader detector for real npm supply-chain incidents.

The goal is simple: give you a fast, local way to answer "did this repo pull something known-bad?" without waiting for a SaaS integration, a vendor dashboard, or a postmortem thread to catch up.

It currently covers major campaigns from September 2025 through March 2026, including the chalk/debug crypto theft incident, the September 2025 self-propagating npm campaign, the fake Bun runtime attacks, SANDWORM_MODE, and the March 2026 axios maintainer account takeover. Under the hood it cross-checks 1,706+ confirmed malicious package versions, suspicious workflow patterns, installer hooks, hashes, and related IoCs.

Why this exists

Because lockfiles, CI logs, and node_modules tell the truth faster than speculation.
Because supply-chain incidents keep changing names, but the responder workflow is always the same: identify exposure, isolate the blast radius, and move.
Because I wanted a tool that is transparent, hackable, and easy to extend the same day a new campaign drops.

Who this is for

Engineers doing incident triage on JavaScript/TypeScript repos
AppSec and DevSecOps teams auditing fleets of npm projects
Anyone who wants a local detector they can read, patch, and run in CI

Overview

Covers multiple npm supply chain attacks from September 2025 through March 2026:

Chalk/Debug Crypto Theft Attack (September 8, 2025)

Scope: 18+ packages with 2+ billion weekly downloads
Attack: Cryptocurrency wallet address replacement in browsers
Duration: ~2 hours before detection
Packages: chalk, debug, ansi-styles, color-, supports-, and others
Method: XMLHttpRequest hijacking to steal crypto transactions

September 2025 Self-Propagating npm Campaign (September 14-16, 2025)

Scope: 517+ packages across multiple namespaces
Attack: Credential harvesting and self-propagation
Method: Uses Trufflehog to scan for secrets, publishes stolen data to GitHub
Propagation: Self-replicates using stolen npm tokens
Packages: @ctrl/, @crowdstrike/, @operato/*, and many others

November 2025 Fake Bun Runtime Attack (November 24, 2025)

Scope: 300+ packages with millions of weekly downloads
Attack: Fake Bun runtime installation with credential harvesting
Method: Uses fake setup_bun.js preinstall hook to download and execute TruffleHog
Exfiltration: Creates GitHub Actions runners named "SHA1HULUD" and repositories with attacker-controlled descriptions used for credential staging
Packages: @zapier/, @posthog/, @asyncapi/, @postman/, @ensdomains/*, and many others
Files: setup_bun.js, bun_environment.js (10MB+ obfuscated payload), actionsSecrets.json (double Base64 encoded)
Workflow: .github/workflows/formatter_*.yml files using SHA1HULUD runners

December 2025 Golden Path Variant (December 28, 2025)

Scope: Continuation of the November 2025 fake Bun attack with renamed files
Attack: Same fake Bun runtime technique with obfuscated file names
Method: Uses bun_installer.js and environment_source.js (renamed from setup_bun.js and bun_environment.js)
Exfiltration: Obfuscated JSON files for staging stolen credentials: 3nvir0nm3nt.json, cl0vd.json, c9nt3nts.json, pigS3cr3ts.json
Packages: @vietmoney/react-big-calendar (versions 0.26.0-0.26.2)
Repo Description: "Goldox-T3chs: Only Happy Girl"

SANDWORM_MODE AI Toolchain Poisoning (February 17, 2026)

Scope: 19 confirmed malicious npm packages + workflow propagation IoCs
Attack: Typosquatted AI toolchain packages and poisoned CI workflow distribution
Method: Malicious GitHub Action ci-quality/code-quality-check@v1 injects .github/workflows/quality.yml
Threat actor aliases: official334, javaorg
Packages: claud-code, cloude-code, cloude, opencraw, veim, yarsg, and others
Source: Socket.dev analysis

Axios Maintainer Account Takeover (March 31, 2026)

Scope: Official axios npm package compromised for roughly 3 hours via hijacked maintainer access
Attack: Malicious dependency injection delivering a cross-platform RAT during install
Method: [email protected] and [email protected] shipped with malicious [email protected]
Related packages: @qqbrowser/[email protected], @shadanai/[email protected], @shadanai/[email protected]
Primary network IOC: sfrclak[.]com:8000 / 142.11.206.73
Source: The Hacker News coverage

Quick Start

# Clone the repository
git clone https://github.com/otaviomarcal/npm-supply-chain-detector
cd npm-supply-chain-detector

# Make the script executable
chmod +x nsc-scan.sh

# Open the guided launcher
./nsc-scan.sh

# Scan your project for known supply-chain indicators
./nsc-scan.sh /path/to/your/project

# For comprehensive security scanning
./nsc-scan.sh --paranoid /path/to/your/project

# Save findings to a log file for review or CI/CD artifacts
./nsc-scan.sh --save-log report.log /path/to/your/project

# Check exit code for CI/CD integration
./nsc-scan.sh /path/to/your/project
echo "Exit code: $?"  # 0=clean, 1=high-risk, 2=medium-risk

nsc-scan.sh is the short day-to-day entrypoint. It now provides a guided launcher when you run it with no arguments in a terminal. npm-supply-chain-detector.sh and the legacy upstream script name remain available for compatibility.

Global npm install

npm install -g @otaviomarcal/npm-supply-chain-detector

# Then run from anywhere
nsc-scan /path/to/your/project

On Windows, the npm package uses a small Node launcher that looks for a compatible Bash runtime. WSL or Git Bash is recommended. You can override the detected runtime with NSC_BASH_PATH.

Philosophy

High signal over novelty: exact compromised versions and concrete IoCs beat vague "AI risk scoring"
Local-first: the scanner should work on a laptop, in CI, and inside a messy incident response shell session
Easy to update: new package versions and test fixtures should be cheap to add when a campaign breaks
Better operator UX: fast presets and guided scans matter when someone is triaging under pressure

Guided Launcher

Run ./nsc-scan.sh with no arguments to open an interactive launcher instead of memorizing flags.

Example menu:

npm Supply Chain Detector

  1) Quick triage
  2) Deep audit
  3) Semver exposure
  4) Incident response bundle
  5) Custom guided scan
  q) Quit

Available scan profiles:

Quick triage: runs the default core scan. Best for a fast answer to "is this repo obviously exposed right now?"
Deep audit: adds --paranoid checks for typosquatting and suspicious network/exfiltration patterns. Useful when you want broader coverage and can tolerate more noise.
Semver exposure: adds --check-semver-ranges to find packages that could resolve to compromised versions during install/update, even if the exact bad version is not locked today.
Incident response bundle: combines --paranoid and --check-semver-ranges, then asks where to save a log file. This is the preset for real incident handling and evidence capture.
Custom guided scan: lets you choose each option interactively, including whether to save a log and which grep engine to use.

Typical flow:

Run ./nsc-scan.sh
Pick the scan profile that matches the situation
Enter the target directory
Choose the grep engine (auto, git grep, ripgrep, or grep)
Let the launcher execute the underlying detector with the right flags

If you already know the flags you want, nsc-scan.sh still passes them straight through to the detector engine.

CI/CD Integration: The script returns appropriate exit codes (0=clean, 1=high-risk, 2=medium-risk) for seamless integration into automated security pipelines.

What it Detects

High Risk Indicators

Malicious workflow files: shai-hulud-workflow.yml files in .github/workflows/ (September 2025), formatter_*.yml files using SHA1HULUD runners (November 2025), and SANDWORM_MODE workflow IoCs including ci-quality/code-quality-check@v1 and poisoned quality.yml workflow references (February 2026)
Known malicious file hashes: Files matching any of 7 SHA-256 hashes from tracked September-December 2025 variants (V1-V7), sourced from Socket.dev's comprehensive attack analysis
November 2025 Bun attack files: setup_bun.js/bun_installer.js (fake Bun runtime installer) and bun_environment.js/environment_source.js (10MB+ obfuscated credential harvesting payload)
Obfuscated exfiltration files: 3nvir0nm3nt.json, cl0vd.json, c9nt3nts.json, pigS3cr3ts.json (December 2025 variant - stolen credentials staged for exfiltration)
Compromised package versions: Specific versions of 1,706+ packages from multiple attacks (September 2025 through March 2026), including [email protected], [email protected], and [email protected]
Suspicious postinstall hooks: Package.json files with postinstall scripts containing curl, wget, eval commands, or fake Bun installation ("preinstall": "node setup_bun.js")
Trufflehog activity: Files containing trufflehog references, credential scanning patterns, or November 2025 enhanced patterns (automated TruffleHog download and execution)
Malicious exfiltration repositories: Git repositories named "Shai-Hulud" or with "Sha1-Hulud: The Second Coming" or "Goldox-T3chs: Only Happy Girl" descriptions
Secrets exfiltration files: actionsSecrets.json files with double Base64 encoded credentials (November 2025)
SHA1HULUD GitHub Actions runners: GitHub Actions workflows using malicious runners for credential theft
SANDWORM_MODE workflow IoCs: Workflow files containing ci-quality/code-quality-check@v1, actor aliases (official334, javaorg), or related propagation module references

Medium Risk Indicators

Suspicious content patterns: References to webhook.site and the malicious endpoint bb8ca5f6-4175-45d2-b042-fc9ebb8170b7
Suspicious git branches: Branches matching known exfiltration naming patterns such as shai-hulud
Semver pattern matching: Packages that could become compromised during npm update due to caret (^) or tilde (~) version patterns

Low Risk Indicators

Namespace warnings: Packages from namespaces known to be affected (@ctrl, @crowdstrike, @art-ws, @ngx, @nativescript-community) but at safe versions

Package Detection Method

The script loads a list of the compromised packages from an external file (compromised-packages.txt) which contains:

1,706+ confirmed compromised package versions with exact version numbers (September 2025 through March 2026 campaigns)
18+ affected namespaces for broader detection of packages from compromised maintainer accounts

Maintaining and Updating the Package List

Important: New malicious versions keep surfacing after the first headline. The compromised packages list is stored in compromised-packages.txt for easy maintenance:

Format: package_name:version (one per line)
Comments: Lines starting with # are ignored
Updates: The file can be updated as new compromised packages are discovered
Fallback: If the file is missing, the script uses a core embedded list

Staying Updated on New Compromised Packages

Check these security advisories regularly for newly discovered compromised packages:

StepSecurity Blog - Original comprehensive analysis
Semgrep Security Advisory - Detailed technical analysis
JFrog Security Research: September 2025 incident updates - Ongoing detection of new packages from the September 2025 incident
Wiz Security Blog: September 2025 campaign appendix - Attack analysis with package appendix
Socket.dev Blog - CrowdStrike package analysis
Socket.dev Blog - SANDWORM_MODE AI toolchain poisoning campaign
HelixGuard: November 2025 fake Bun follow-up - Follow-up analysis of the November 2025 attack
The Hacker News - March 2026 axios compromise coverage

How to Add Newly Discovered Packages

Check the security advisories above for new compromised packages
Add them to compromised-packages.txt in the format package_name:version
Test the script to ensure detection works
Consider contributing updates back to this repository

Coverage Note: Multiple campaigns from September 2025 through March 2026 affected 1,706+ package versions total. This detector aims to cover real-world exposure across the September 2025 self-propagating campaign (517+ packages), Chalk/Debug crypto theft (26+ packages), the November 2025 fake Bun runtime attack (1,100+ packages), the Golden Path variant, the February 2026 SANDWORM_MODE campaign, and the March 2026 axios compromise.

Core vs Paranoid Mode

Core Mode (Default)

Focuses on high-confidence supply-chain incident indicators
Recommended for most users who want fast triage with minimal noise
Clean, focused output with minimal false positives

Paranoid Mode (--paranoid)

Includes all core supply-chain detection plus additional security checks
Adds typosquatting detection and network exfiltration pattern analysis
Important: Paranoid features are general security tools, not specific to a single campaign
May produce more false positives from legitimate code
Useful for comprehensive security auditing

Semver Range Checking (--check-semver-ranges)

Checks if package.json semver ranges (^, ~) could resolve to compromised versions
Reports LOW risk in both cases (informational warning about latent risk)
Useful for identifying latent risk in private npm caches that may still have malicious versions

Requirements

macOS or Unix-like system
Bash 5.0 or newer (required for associative arrays and performance features)
- macOS: brew install bash then run with /opt/homebrew/bin/bash ./nsc-scan.sh
- Linux: Most modern distributions include Bash 5.x by default
- Check your version: bash --version
Standard Unix tools: find, grep, shasum

Grep Tool Selection

The script automatically selects the fastest available grep tool in this priority order:

git grep (default) - Uses a DFA-based regex engine with no backtracking, fastest for our patterns (~40% faster than ripgrep)
ripgrep (fallback) - Also DFA-based, excellent performance
grep (last resort) - May experience catastrophic backtracking on complex patterns

You can override the auto-selection with flags:

--use-git-grep - Force git grep
--use-ripgrep - Force ripgrep
--use-grep - Force standard grep

Why git grep is default: Our testing shows git grep is ~40% faster than ripgrep on large codebases. Both use DFA-based regex engines that avoid the catastrophic backtracking that causes standard grep to hang on complex patterns.

Output Interpretation

Clean System

✅ No indicators of known npm supply-chain compromise detected.
Your system appears clean for the campaigns covered by this detector.

Compromised System

The script will show:

🚨 HIGH RISK: Definitive indicators of compromise
⚠️ MEDIUM RISK: Suspicious patterns requiring manual review
Summary: Count of issues found

What to Do if Issues are Found

High Risk Issues

Immediate action required
Update or remove compromised packages
Review and remove malicious workflow files
Scan for credential theft
Consider full system audit

Medium Risk Issues

Manual investigation needed
Review flagged files for legitimacy
Check if webhook.site usage is intentional
Verify git branch purposes

Exit Codes for CI/CD Integration

The script returns specific exit codes to enable proper CI/CD pipeline integration:

Exit Code 0: Clean system - no significant security findings
Exit Code 1: High-risk findings detected - immediate action required
Exit Code 2: Medium-risk findings detected - manual investigation needed

CI/CD Pipeline Examples

GitHub Actions

- name: Security Scan with npm Supply Chain Detector
  run: |
    chmod +x ./nsc-scan.sh
    ./nsc-scan.sh .
  # Pipeline will automatically fail on exit codes 1 or 2

GitLab CI

security_scan:
  script:
    - chmod +x ./nsc-scan.sh
    - ./nsc-scan.sh .
  # Job fails automatically on non-zero exit codes

Jenkins

stage('Security Scan') {
  steps {
    sh '''
      chmod +x ./nsc-scan.sh
      ./nsc-scan.sh .
    '''
  }
  // Build fails automatically on non-zero exit codes
}

Custom Handling by Exit Code

#!/bin/bash
./nsc-scan.sh .
exit_code=$?

case $exit_code in
    0) echo "✅ Security scan passed - no issues found" ;;
    1) echo "🚨 CRITICAL: High-risk security issues found - blocking deployment"
       exit 1 ;;
    2) echo "⚠️ WARNING: Medium-risk issues found - review required"
       # Could choose to continue with warnings
       ;;
esac

Saving Findings to a Log File

Use --save-log FILE to save all detected file paths to a structured log file:

./nsc-scan.sh --save-log findings.log /path/to/project

The log file contains file paths grouped by severity level:

# HIGH
/path/to/malicious-workflow.yml
/path/to/compromised-package.json
# MEDIUM
/path/to/suspicious-content.js
# LOW
/path/to/namespace-warning.json

This format is designed for:

CI/CD artifacts: Store scan results as build artifacts for review
Programmatic parsing: Easy to parse with simple scripts
Full coverage: Includes ALL findings without display truncation

Testing

The repository includes a growing regression suite with targeted fixtures for real campaigns. Use the automated test runner to validate the detector behavior:

# Run the full test suite (recommended)
./run-tests.sh

# The test suite validates expected exit codes and risk levels for the maintained fixtures
# Exit codes: 0=clean, 1=high-risk, 2=medium-risk

You can also run individual test cases manually:

# Test on clean project (should show no issues)
./nsc-scan.sh test-cases/clean-project

# Test on infected project (should show multiple issues)
./nsc-scan.sh test-cases/infected-project

# Test November 2025 fake Bun runtime attack (should show HIGH risk for all new patterns)
./nsc-scan.sh test-cases/november-2025-attack

# Test on mixed project (should show medium risk issues)
./nsc-scan.sh test-cases/mixed-project

# Test namespace warnings (should show LOW risk namespace warnings only)
./nsc-scan.sh test-cases/namespace-warning

# Test semver matching (should show MEDIUM risk for packages that could match compromised versions)
./nsc-scan.sh test-cases/semver-matching

# Test legitimate crypto libraries (should show MEDIUM risk only)
./nsc-scan.sh test-cases/legitimate-crypto

# Test chalk/debug attack patterns (should show HIGH risk compromised packages + MEDIUM risk crypto patterns)
./nsc-scan.sh test-cases/chalk-debug-attack

# Test common crypto libraries (should not trigger HIGH risk false positives)
./nsc-scan.sh test-cases/common-crypto-libs

# Test legitimate XMLHttpRequest modifications (should show LOW risk only)
./nsc-scan.sh test-cases/xmlhttp-legitimate

# Test malicious XMLHttpRequest with crypto patterns (should show HIGH risk crypto theft + MEDIUM risk XMLHttpRequest patterns)
./nsc-scan.sh test-cases/xmlhttp-malicious

# Test lockfile false positive (should show no issues despite other package having compromised version)
./nsc-scan.sh test-cases/lockfile-false-positive

# Test actual compromised package in lockfile (should show HIGH risk)
./nsc-scan.sh test-cases/lockfile-compromised

# Test packages with safe lockfile versions (should show LOW risk with lockfile protection message)
./nsc-scan.sh test-cases/lockfile-safe-versions

# Test mixed lockfile scenario (should show HIGH risk for compromised + LOW risk for safe)
./nsc-scan.sh test-cases/lockfile-comprehensive-test

# Test packages without lockfile (should show MEDIUM risk for potential update risks)
./nsc-scan.sh test-cases/no-lockfile-test

# Test typosquatting detection with paranoid mode (should show MEDIUM risk typosquatting warnings)
./nsc-scan.sh --paranoid test-cases/typosquatting-project

# Test network exfiltration detection with paranoid mode (should show HIGH risk credential harvesting + MEDIUM risk network patterns)
./nsc-scan.sh --paranoid test-cases/network-exfiltration-project

# Test clean project with paranoid mode (should show no issues - verifies no false positives)
./nsc-scan.sh --paranoid test-cases/clean-project

# Test semver wildcard parsing (should correctly handle 4.x, 1.2.x patterns without errors)
./nsc-scan.sh test-cases/semver-wildcards

# Test discussion workflow detection (should show CRITICAL risk for malicious discussion-triggered workflows)
./nsc-scan.sh test-cases/discussion-workflows

# Test SANDWORM_MODE workflow IOC detection (should show HIGH risk for poisoned ci-quality action usage)
./nsc-scan.sh test-cases/sandworm-mode-workflow

# Test March 2026 axios compromise coverage
./nsc-scan.sh test-cases/axios-compromise

# Test GitHub Actions runner detection (should show CRITICAL risk for SHA1HULUD self-hosted runners)
./nsc-scan.sh test-cases/github-actions-runners

# Test file hash verification (should validate benign files against malicious hashes)
./nsc-scan.sh test-cases/hash-verification

# Test destructive pattern detection (should show CRITICAL risk for data destruction commands)
./nsc-scan.sh test-cases/destructive-patterns

Paranoid Mode Testing

The --paranoid flag enables additional security checks beyond the core incident signatures:

Typosquatting Detection: Identifies packages with names similar to popular packages (e.g., "raect" instead of "react", "lodsh" instead of "lodash")
Network Exfiltration Patterns: Detects suspicious domains (webhook.site, pastebin.com), hardcoded IP addresses, WebSocket connections to external endpoints
Enhanced Security Auditing: Useful for comprehensive project security reviews

Note: Paranoid mode may produce more false positives from legitimate code patterns, so review findings carefully.

How it Works

The script performs these checks:

Package Database Loading: Loads 1,706+ compromised packages from compromised-packages.txt into O(1) lookup maps
Workflow Detection: Searches for shai-hulud-workflow.yml files (September 2025), formatter_*.yml files with SHA1HULUD runners (November 2025), and SANDWORM_MODE workflow IoCs (February 2026)
Hash Verification: Calculates SHA-256 hashes against 7 known malicious bundle.js variants (V1-V7)
Package Analysis: Parses package.json files for compromised versions and affected namespaces
Semver Range Checking (opt-in with --check-semver-ranges): Checks if version ranges could resolve to compromised versions
Postinstall Hook Detection: Identifies suspicious postinstall/preinstall scripts containing curl, wget, eval, or fake Bun patterns
Content Scanning: Searches for suspicious URLs, webhook endpoints, and malicious patterns
Cryptocurrency Theft Detection: Identifies wallet replacement patterns, XMLHttpRequest hijacking, and crypto theft functions
Trufflehog Activity Detection: Looks for credential scanning tools and secret harvesting patterns
Git Analysis: Checks for suspicious branch names tied to known exfiltration patterns
Repository Detection: Identifies known malicious repository descriptions and exfiltration repo patterns
November 2025 Bun Attack Detection: Identifies setup_bun.js/bun_installer.js and bun_environment.js/environment_source.js attack files
GitHub Actions Runner Detection: Identifies malicious SHA1HULUD runners
Discussion Workflow Detection: Identifies workflows that trigger on discussion events (stealth persistence)
Destructive Payload Detection: Identifies destructive fallback patterns (rm -rf, fs.rmSync, etc.)
Lockfile Integrity Checking: Analyzes package-lock.json, yarn.lock, and pnpm-lock.yaml for compromised packages
Typosquatting Detection (paranoid mode): Identifies packages with names similar to popular packages
Network Exfiltration Detection (paranoid mode): Detects suspicious domains and hardcoded IPs
Obfuscated Exfiltration Detection: Identifies December 2025 staging files (3nvir0nm3nt.json, cl0vd.json, etc.)

Limitations

Hash Detection: Only detects files with exact matches to the 7 known malicious hashes
Package Versions: Detects specific compromised versions; new variants may not be detected until the package list is updated
False Positives: Legitimate use of webhook.site, Trufflehog, or postinstall hooks may trigger alerts
Campaign Evolution: New variants may emerge with different signatures
Semver Ranges: The --check-semver-ranges flag is informational only; compromised versions are largely unpublished from npm

Security Note

This script is for detection only. It does not:

Automatically remove malicious code
Fix compromised packages
Prevent future attacks

Always verify findings manually and take appropriate remediation steps.

References

Primary Sources

Additional Resources

Contributing

Contributions are welcome, especially when a new incident breaks and the ecosystem needs coverage before the tooling catches up.

How to Contribute

Adding New Compromised Packages

Fork the repository on GitHub, then clone your fork:

git clone https://github.com/YOUR_USERNAME/npm-supply-chain-detector.git
cd npm-supply-chain-detector

Update the package list
- Add new packages to compromised-packages.txt in the format package_name:version
- Include a source/reference for where you found the compromised package

Test your changes

./run-tests.sh
# All 37 tests should pass

Submit a Pull Request
- Push to your fork and open a PR against the upstream project you want to contribute to
- Include the source of the information (security advisory, blog post, etc.)

Other Contributions

Bug fixes: Report and fix issues with detection accuracy
New IoCs: Add detection for additional indicators of compromise
Documentation: Improve clarity and add examples
Test cases: Add new test scenarios for edge cases

Contribution Guidelines

Verify sources: Only add packages confirmed by reputable security firms or official project incident threads
Test thoroughly: Ensure changes don't break existing functionality
Document changes: Update relevant documentation and changelog
Follow patterns: Match existing code style and organization
Security first: Never include actual malicious code in test cases

Reporting New Compromised Packages

If you can't submit a PR, you can still help by reporting new compromised packages:

Open an issue with the title "New compromised package: [package-name]"
Include the package name, version, and source of information
Provide links to security advisories or reports
We'll review and add verified packages to the detection list

Release Notes

For a complete list of changes and version history, see the CHANGELOG.md.

License

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