Shai-Hulud Supply Chain Attack Detector

A Bash script that scans a project — or many projects at once — for known traces of the September 2025 → October 2026 npm, PyPI, Composer, Crates, Go, Hex, and RubyGems supply-chain attacks. Cross-checks 5,791 confirmed bad package versions and a library of content-pattern IoCs (file hashes, C2 domains, dead-man's-switch artifacts, wipe-threat strings, AI-assistant config droppers, etc.).

Quick Start

git clone https://github.com/Cobenian/shai-hulud-detect
cd shai-hulud-detect
chmod +x shai-hulud-detector.sh

# Scan one project
./shai-hulud-detector.sh /path/to/your/project

# Scan every project under one or more parent dirs and get one aggregate report
./shai-hulud-detector.sh --bulk ~/dev ~/work

# Save findings to a file (same format as CI-friendly logs)
./shai-hulud-detector.sh --save-log report.log /path/to/project

Exit codes (drop straight into CI): 0 clean · 1 high-risk · 2 medium-risk · 3 per-project scan errored (bulk mode only).

What it catches

The detector looks for two kinds of evidence on disk:

1. Compromised package versions — every package.json, lockfile, pyproject.toml, requirements.txt, Pipfile, poetry.lock, uv.lock, etc. is parsed and the resolved versions are checked against the 5,791-entry list in compromised-packages.txt. Transitive deps inside node_modules/ are checked too, not skipped.
2. Content-pattern IoCs — known-malicious file hashes, payload filenames, C2 domains, dead-man's-switch artifacts, marker repo names, malicious workflow files, forged orphan-commit references, suspicious lifecycle hooks, and threat-actor publisher fingerprints. These don't depend on the package list and fire even if the bad package has been uninstalled but the dropper traces remain.

For per-wave IoC inventories, payload hashes, source advisories, and version-by-version lists, see CHANGELOG.md.

⚠️ Dead-man's-switch warning

Two waves (May 11 and May 19, 2026) install a persistence daemon (gh-token-monitor / kitty-monitor) that wipes the host if its monitored GitHub token is revoked. Run with --check-host to detect the persistence artifacts. If they're present, stop and remove the service BEFORE rotating any tokens. The console summary and aggregate report both print a safe remediation order.

Ecosystems

Auto-detection looks for marker files in your tree, skipping node_modules/, vendor/, .venv/, venv/, .tox/, site-packages/, dist/, build/, and similar trees. That exclusion only decides which checks to run — content inside node_modules/ is still fully scanned for compromised versions and malware indicators. Override auto-detection with --ecosystem=npm, --ecosystem=pypi, --ecosystem=all, or a comma-separated list.

CI/CD

- name: Shai-Hulud scan
  run: |
    chmod +x ./shai-hulud-detector.sh
    ./shai-hulud-detector.sh --save-log shai-hulud-report.log .
  # Job fails on exit 1 (high-risk) or 2 (medium-risk)
- uses: actions/upload-artifact@v4
  if: always()
  with:
    name: shai-hulud-report
    path: shai-hulud-report.log

For GitLab CI, Jenkins, and a custom exit-code handler in shell, see docs/ci-examples.md — or just call the script and switch on $?, the exit-code contract is the same everywhere.

Common scenarios

Scan many projects at once (--bulk)

./shai-hulud-detector.sh --bulk ~/dev ~/work                 # auto-discover all projects
./shai-hulud-detector.sh --bulk --paranoid --bulk-output ./audit ~/dev
./shai-hulud-detector.sh --bulk --bulk-list ~/dev            # dry-run: print what would be scanned

Project discovery is content-aware: a directory with .git, a package.json, a pyproject.toml, Cargo.toml, go.mod, etc. is one scan unit (monorepos stay whole). "Bucket" folders like ~/dev/clients/<client>/<project> are descended into. node_modules, vendor, dist, build dirs, and hidden dirs are never entered. The detector's own repo is skipped automatically. Unreadable directories are reported instead of silently skipped.

Output goes to ./shai-hulud-bulk-report-<timestamp>/ (or --bulk-output DIR):

shai-hulud-bulk-report-<timestamp>/
├── aggregate-report.md      # summary tables + per-project results + remediation
└── per-repo/
    ├── <project>.findings.log    # severity-grouped file paths
    └── <project>.console.txt     # full scan output, ANSI-stripped

Paranoid mode (--paranoid)

Adds typosquatting detection and network-exfiltration heuristics on top of the core checks. These are general-purpose security signals, not Shai-Hulud-specific, and produce more false positives — useful for audits, not recommended for CI gating.

Host-level persistence scan (--check-host)

Walks $HOME for the May 2026 dead-man's-switch artifacts (gh-token-monitor, kitty-monitor). Off by default. See the warning above before remediating any findings.

Save findings to a log file (--save-log FILE)

Writes flagged file paths grouped by severity, in a format friendly to grep and CI artifact uploads:

# HIGH
/path/to/router_init.js
/path/to/package.json
# MEDIUM
/path/to/suspicious-content.js
# LOW
/path/to/namespace-warning.json

Machine-readable JSON output (--json FILE)

For CI gates and tooling that consume findings as data (rather than parsing console text), --json writes a structured report. It uses the same severity tiers as --save-log but keeps the reason for each finding (which --save-log drops):

./shai-hulud-detector.sh --json report.json /path/to/project

{
  "schema_version": "1.0",
  "tool": "shai-hulud-detector",
  "tool_version": "3.9.0",
  "generated_at": "2026-06-26T00:00:00Z",
  "scan_path": "/path/to/project",
  "summary": { "high": 7, "medium": 0, "low": 0 },
  "risk_level": "high",
  "findings": [
    { "severity": "HIGH", "file": "package.json", "line": 6, "message": "[email protected]" }
  ]
}

line is a best-effort pointer at the dependency line in the manifest for package-shaped findings (name@version, @scope/name@version); it is null for prose findings or when no match is found. The exit-code contract (0/1/2) is unchanged and remains the authoritative CI signal — --json and --save-log can be combined.

--json is the only mode that requires jq; it fails fast with a clear message if jq is missing. The default text output keeps the tool's zero-runtime-dependency guarantee.

Other flags

How it works

1. Collect the file inventory (one find pass, categorized by extension).
2. Detect ecosystems from marker files, decide which package-level checks to run.
3. Match every resolved package version against compromised-packages.txt via a sorted set-intersection (comm -12).
4. Hash priority files (bundle.js, setup_bun.js, router_init.js, tanstack_runner.js, cat.py, node-ipc.cjs, etc.) and compare against 20 known-malicious SHA-256s.
5. Grep for content-pattern IoCs: C2 domains, threat-actor accounts, dead-man's-switch service names, wipe-threat strings, malicious commit SHAs, beacon strings, payload filenames, orphan-commit optionalDependencies patterns.
6. (Opt-in) scan $HOME for persistence artifacts (--check-host); run typosquatting + network-exfil heuristics (--paranoid); flag latent semver-range risk (--check-semver-ranges).
7. Report in three severity tiers (HIGH/MEDIUM/LOW), with remediation order for the safety-critical findings.

Detection is read-only. The script never modifies, deletes, or quarantines anything — manual review and remediation are on you.

Output

✅ No indicators of Shai-Hulud compromise detected.   ← clean, exit 0
🚨 HIGH RISK: ...                                     ← exit 1, immediate action
⚠️  MEDIUM RISK: ...                                  ← exit 2, manual review

HIGH: definitive indicators — compromised package version, known-malicious file hash, malicious workflow, dead-man's-switch artifact. Stop and remediate.

MEDIUM: suspicious patterns that warrant a look — semver range that could match a compromised version, references to webhook redirector domains, suspicious git branches.

LOW: informational notes — namespace warnings (packages from affected namespaces at safe versions), legitimate-looking patterns that share shape with attack techniques.

Requirements

• Bash 5.0+ (associative arrays, mapfile). macOS ships 3.x; install with brew install bash and invoke via /opt/homebrew/bin/bash.
• Standard Unix tools: find, grep, awk, sed, sort, comm, shasum (or sha256sum), xargs. All POSIX-portable.
• Tested on macOS (Bash 5), Linux, and Git Bash for Windows.

The script auto-selects the fastest available grep tool (git grep > ripgrep > grep). No runtime dependencies on Python, Node, or anything else.

Limitations

• Hash detection only catches exact SHA-256 matches against the 20 known-malicious hashes.
• Compromised-package detection requires the version to be in compromised-packages.txt — new variants need a list update.
• Paranoid-mode heuristics produce false positives on legitimate code.
• The detector reads filesystem state; it doesn't query npm/PyPI registries for live data.

Updating the compromised-packages list

compromised-packages.txt is a flat text file:

# Comments start with #
axios:1.14.1                            # bare entry = npm (back-compat)
npm:@tanstack/react-router:1.169.5      # explicit npm prefix
pypi:mistralai:2.4.6                    # PyPI entry
composer:laravel-lang/lang:15.29.5      # Composer / Packagist entry
crates:sui-move-build-helper:0.1.0      # Crates.io / Cargo entry
go:github.com/verana-labs/verana-blockchain:v0.10.1-dev.20  # Go module (version keeps its leading "v")
hex:some_pkg:1.2.3                      # Elixir / Hex.pm entry
gem:some_gem:1.2.3                      # RubyGems entry

For campaigns where every version of a package is malicious (e.g. TrapDoor, Laravel-Lang's tag rewrite), per-version entries can't keep up — detection is done version-agnostically by a dedicated check_*_indicators function that name-matches the dependency in any manifest.

To add new packages from a fresh advisory: append entries in that format, run ./run-tests.sh, open a PR. Source the additions from a reputable security firm (Socket, StepSecurity, Aikido, Snyk, JFrog, Wiz, Semgrep, SafeDep, GitGuardian, OX Security) and cite them.

Testing

./run-tests.sh                          # full suite, 296 checks
./shai-hulud-detector.sh test-cases/<fixture-name>   # run one fixture manually

Each subdirectory of test-cases/ is a self-contained fixture (clean projects, infected projects with the various attack signatures, ecosystem-specific tests, paired clean/dirty pairs). Run ls test-cases/ to see them all.

Contributing

PRs welcome — especially new compromised-package entries as fresh waves are disclosed.

1. Fork, branch, edit.
2. For new packages: append to compromised-packages.txt, add a fixture under test-cases/, register it in run-tests.sh.
3. For new content-pattern IoCs: extend the relevant check_* function in shai-hulud-detector.sh, add an assertion in run-tests.sh.
4. ./run-tests.sh must pass.
5. Cite your sources (security advisories, vendor blog posts) in the PR description.

Don't include actual malware in test fixtures — inert string constants and synthetic files only.

Security note

Detection only. The script does not remove malicious code, downgrade packages, or block installs. Verify findings, then remediate manually.

For the dead-man's-switch waves (May 11 + May 19, 2026), follow the remediation order printed by --check-host: stop the persistence service first, delete its files, then rotate credentials. Revoking a monitored token before stopping the service is designed to trigger a destructive wipe.

References

For per-wave source advisories with IoC enumerations, see the ### Security section of each release entry in CHANGELOG.md. The original Shai-Hulud disclosures live at:

• StepSecurity — CTRL, tinycolor and 40 NPM packages compromised
• JFrog — Largest npm attack in history
• Aikido — npm debug and chalk packages compromised
• Semgrep — Secret-scanning-tool credential theft

Sources we monitor for new waves

When a new wave lands, check these first. Primary research teams publish the per-package version lists, file hashes, and C2 IoCs we add to this repo — always source additions from one of these and cite it in the PR. News aggregators are where a wave usually surfaces first; use them to learn a wave exists, then pull the actual IoCs from a primary source.

Primary threat-research teams (IoC enumerations):

• Socket — blog · JFrog Security Research · StepSecurity — blog
• Aikido — blog · Snyk — blog · Wiz — blog
• Microsoft Security (MSTIC) · Datadog Security Labs · Unit 42 (Palo Alto)
• SafeDep · OX Security — blog · Orca Security — blog · Semgrep — blog · GitGuardian — blog
• GitHub Advisory Database (filter by ecosystem)

News aggregators (early awareness):

• BleepingComputer — supply-chain attack tag
• The Hacker News · SecurityWeek · Dark Reading — App Security

License

MIT — see LICENSE.