npm Security Tools

Zero-dependency detection and mitigation tools for npm supply chain attacks. Targets Shai-Hulud 2.0 (November 2025), CanisterWorm (March 2026), and GlassWorm (March 2026).

Install

# npx (zero-install, recommended)
npx npm-security-tools scan

# Global install via npm
npm install -g npm-security-tools

# Homebrew (macOS/Linux)
brew tap DrFrankieD-AI/npm-security-tools
brew install npm-security-tools

# Direct install
curl -fsSL https://raw.githubusercontent.com/DrFrankieD-AI/npm-security-tools/main/install.sh | bash

# Or clone
git clone https://github.com/DrFrankieD-AI/npm-security-tools.git
cd npm-security-tools && chmod +x *.sh

Quick Start

# Run ALL scanners at once
npx npm-security-tools scan

# Individual scanners
npx npm-security-tools detect-shai-hulud
npx npm-security-tools detect-canisterworm
npx npm-security-tools detect-glassworm

# JSON output for CI/CD pipelines
npx npm-security-tools scan --format json

# Check if dependencies were recently published (supply chain risk)
npx npm-security-tools freshness

# Verify package provenance/signatures
npx npm-security-tools provenance

# Harden npm config
npx npm-security-tools harden --apply

# CI/CD security gate
npx npm-security-tools ci-check /path/to/project

GitHub Actions

Add to any workflow with one line:

- uses: DrFrankieD-AI/npm-security-tools@main

Full example:

name: Security Check
on: [push, pull_request]

jobs:
  npm-security:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
      - run: npm ci

      # Run CI security checks (default)
      - uses: DrFrankieD-AI/npm-security-tools@main

      # Or run all detection scanners
      - uses: DrFrankieD-AI/npm-security-tools@main
        with:
          mode: scan-all
          quick: true

      # Or a specific scanner with JSON output
      - uses: DrFrankieD-AI/npm-security-tools@main
        with:
          mode: detect-glassworm
          format: json

Action Inputs

Input	Default	Description
scan-path	.	Path to the project to scan
mode	ci-check	ci-check, scan-all, detect-shai-hulud, detect-canisterworm, detect-glassworm
format	text	text or json
quick	false	Skip deep scanning for faster results

Action Outputs

Output	Description
status	clean, warning, or critical

Why This Tool?

Most npm security tools (Socket, Snyk) check packages before install. This toolkit checks if your system is already compromised - critical for incident response when you can't trust your local Node.js runtime. Zero dependencies, pure bash + standard Unix utilities.

Threats Detected

Shai-Hulud 2.0 (November 2025)

A self-propagating npm worm that:

• Compromised 492+ packages (132M monthly downloads)
• Affected Zapier, ENS Domains, PostHog, Postman
• Steals credentials via TruffleHog, exfiltrates to GitHub
• Can infect up to 100 npm packages you maintain
• Wipes home directory if it cannot authenticate

CanisterWorm (March 2026)

A supply chain attack by TeamPCP that:

• Exploited stolen npm tokens to compromise 47+ packages
• Uses postinstall hooks as infection vector
• Deploys Python backdoors with ICP blockchain canister C2
• Establishes persistence via systemd user service ("pgmon")
• Self-propagates by harvesting npm tokens from infected machines
• Affected scopes: @EmilGroup, @opengov, @teale.io, @airtm, @pypestream

GlassWorm (March 2026)

A cross-ecosystem worm targeting npm, VS Code, Open VSX, and GitHub:

• Compromised 433+ components across multiple ecosystems
• Uses invisible Unicode (Private Use Area characters) to encode payloads
• Payloads invisible in all editors and code review tools
• Solana blockchain as dead-drop C2 (untakeable infrastructure)
• Google Calendar as fallback C2 channel
• Deploys multi-stage RAT stealing crypto wallets, SSH keys, CI/CD tokens
• AI-generated cover commits to evade code review

Tools

Script	npx Command	Purpose
detect-shai-hulud.sh	npx npm-security-tools detect-shai-hulud	Scan for Shai-Hulud 2.0 IOCs
detect-canisterworm.sh	npx npm-security-tools detect-canisterworm	Scan for CanisterWorm IOCs
detect-glassworm.sh	npx npm-security-tools detect-glassworm	Scan for GlassWorm IOCs
npm-hardening.sh	npx npm-security-tools harden	Apply npm security hardening
monitor-npm-network.sh	npx npm-security-tools monitor	Monitor network during npm ops
ci-security-check.sh	npx npm-security-tools ci-check	CI/CD pipeline security checks
check-package-freshness.sh	npx npm-security-tools freshness	Flag recently published packages
check-provenance.sh	npx npm-security-tools provenance	Verify package signatures/provenance

Package Freshness Checking

Flags dependencies published within a configurable time window. Recently published versions are higher risk since malicious packages are often caught within 24-72 hours. Equivalent to pnpm's minimumReleaseAge.

# Default: flag packages published < 72 hours ago
npx npm-security-tools freshness

# Custom threshold: 24 hours
./check-package-freshness.sh --min-age 24

# JSON output
./check-package-freshness.sh --format json /path/to/project

Provenance Verification

Wraps npm audit signatures with human-readable output and reports what percentage of your dependencies have provenance attestations (SLSA Build Level 2 via Sigstore).

npx npm-security-tools provenance

# JSON output
./check-provenance.sh --format json /path/to/project

JSON Output

All detection scripts support --format json for programmatic consumption:

npx npm-security-tools scan --format json

{
  "scanner": "detect-glassworm",
  "version": "1.2.0",
  "timestamp": "2026-03-24T15:00:00Z",
  "scan_path": "/home/user",
  "status": "clean",
  "summary": {
    "critical": 0,
    "warnings": 0,
    "total_findings": 0
  },
  "findings": []
}

Status values: clean, warning, critical

Scan Modes

All detection scripts support:

./detect-shai-hulud.sh                           # Full scan
./detect-shai-hulud.sh --quick                   # Fast scan
./detect-shai-hulud.sh --scan-path /path         # Scan specific dir
./detect-shai-hulud.sh --format json             # JSON output
./detect-shai-hulud.sh --quick --format json     # Combine options

Exit Codes

Code	Meaning
0	Clean - no issues detected
1	Warnings found - manual investigation recommended
2	Critical IOCs found - immediate action required

If Compromised

Shai-Hulud 2.0

1. Disconnect from network immediately
2. Revoke npm tokens: npm token list then npm token revoke <id>
3. Revoke GitHub PATs: https://github.com/settings/tokens
4. Rotate SSH keys
5. Check for unauthorized publishes: npm access ls-packages
6. Rotate cloud provider credentials

CanisterWorm

1. Disconnect from network immediately
2. Stop and remove persistence:

   systemctl --user stop pgmon
   systemctl --user disable pgmon
   rm ~/.config/systemd/user/pgmon.service
   pkill -f pgmon

3. Revoke ALL npm tokens
4. Rotate all credentials
5. Audit published packages: npm access ls-packages
6. Report to npm: npm@npmjs.com

GlassWorm

1. Disconnect from network immediately
2. Uninstall malicious VS Code extensions: code --uninstall-extension <id>
3. Remove persistence: rm -f ~/init.json
4. Check Chrome extensions (GlassWorm installs a keylogging extension)
5. Revoke ALL tokens and credentials
6. Check crypto wallets for unauthorized transactions
7. Scan VS Code extensions: grep -rP '[\x{FE00}-\x{FE0F}]' ~/.vscode/extensions/

Requirements

• Bash 4.0+
• Standard Unix utilities (find, grep, ss)
• npm (for hardening, audit, freshness, and provenance features)
• Optional: GitHub CLI (gh) for repo scanning
• Optional: jq for JSON parsing in CI checks
• Optional: lsof for detailed process network info

Contributing

Contributions welcome! See Contributing Guidelines and Code of Conduct.

Security

See our Security Policy. Do not open public issues for vulnerabilities.

References

• Datadog Security Labs - Shai-Hulud
• Wiz Research
• Unit42
• Elastic Security
• The Hacker News - CanisterWorm
• The Hacker News - GlassWorm
• Aikido Security - GlassWorm Returns
• Truesec - GlassWorm Analysis

License

MIT License - see LICENSE.