wormhook

wormhook

A Claude Code plugin that catches npm/node supply-chain malware at the hook — before it can run. It binds to Claude Code's tool lifecycle and blocks npm/pnpm/ yarn/bun/npx/node commands when it finds a known indicator of compromise. Named for the threat it headlines: Shai-Hulud, the self-replicating npm worm — stopped at the hook.

This is one lock, not the whole door. It's not a replacement for an install-layer firewall (Socket Firewall) or a dependency auditor (safedep/vet) — it's an independent layer at the Claude Code agent boundary. Run it alongside those, not instead of them; the value is independence — a worm that slips one lock still has to beat the others.

Why this and not just pnpm/Socket? The install layer is now well-served: pnpm 11 ships a release-age cooldown by default and Socket Firewall blocks malicious versions as you install. wormhook deliberately cedes that boundary. Its distinct, currently-unoccupied job is blocking — not warn-only — on agent-boundary persistence / AGENT-HIJACK: rogue SessionStart hooks and mcpServers entries injected into .claude/.cursor/.continue/.vscode configs, .vscode/tasks.json folderOpen auto-exec, weaponized Python .pth startup hooks, poisoned git hooks, and login-persistent LaunchAgent/systemd units. That is the half of the supply-chain kill-chain the registry-layer tools do not see — and the half that re-runs every time you open the project.

Built and maintained by NoTambourine.

Install

claude plugin marketplace add notambourine/wormhook
claude plugin install wormhook@notambourine --scope user

Requires jq and bash. ripgrep is optional but strongly recommended — content scans use it when present (43× faster than BSD grep on large trees) and fall back to grep otherwise. There's nothing to invoke; it runs automatically. At SessionStart a row of doctor status lights (🟢/🟡/🔴/⚪, one per check, every session) reports your runtime deps, version drift, out-of-band coverage, CI supply-chain-gate coverage, the recommended companion firewalls (Socket Firewall / vet), and a blast-radius exposure audit — each non-green light carries the one-liner to fix it.

Run it outside Claude

The Claude hook only fires inside a Claude Code session. wormhook-scan runs the same engine (Tiers 0–2, same malware-patterns.sh) from any shell — for the moments Claude is not watching: a git pull in a plain terminal, coming back to the machine after a while, or a morning fleet check. It is a thin adapter: no detection logic is duplicated, so every signature update reaches it for free.

The fastest way to set it all up is from inside Claude Code: /wormhook-setup runs an interactive installer (it asks which pieces you want and wires them) — the SessionStart doctor points you to it. Or do it by hand:

# link wormhook-scan onto your PATH (~/.local/bin)
bash "$(claude plugin root wormhook 2>/dev/null || echo .)/scripts/wormhook-scan.sh" install-cli

wormhook-scan ~/code/*/            # scan every git repo under ~/code (node_modules pruned)
wormhook-scan                      # no args -> roots from your config (see below)
wormhook-scan --deep ~/code/myapp  # force the Tier-2 node_modules walk
wormhook-scan --persistence        # only the machine-wide ($HOME) persistence checks

Each path resolves to the git repo(s) at or under it (an org dir of repos expands to its repos; node_modules is pruned), so you point at parents, not individual repos. A machine-wide persistence finding (a poisoned ~/.claude, a rogue LaunchAgent) is reported once at the top, not repeated per repo. Exit code: 0 clean · 1 critical (or machine persistence) · 2 degraded — so it gates a script or CI step.

Config (team-shareable, per-machine roots). With no path args, wormhook-scan reads newline-delimited paths/globs from ${XDG_CONFIG_HOME:-~/.config}/wormhook/scan-roots (or $WORMHOOK_SCAN_ROOTS). wormhook-scan config --init seeds a commented sample to edit.

Two automatic triggers (opt-in, both local, zero tokens):

wormhook-scan install-launchd            # hourly background sweep (macOS launchd)
                                         #   notifies + logs; --every SECONDS to retune
wormhook-scan install-git-hook           # post-merge/checkout/rewrite audit on EVERY
                                         #   `git pull` in ANY terminal (not just Claude)