supply-chain-hardening

name	supply-chain-hardening
description	Install-time cooldowns for npm/bun plus a sandboxed pre-install scan for bypasses. Use for supply-chain attacks or npm security.

Supply-chain hardening

Defends a journalism toolchain against the dominant npm/bun supply-chain attack pattern: a maintainer account or CI pipeline is compromised, a malicious version ships, and machines install it before anyone notices. Recent example: the Mini Shai-Hulud TanStack attack (2026-05-11) compromised 84 versions across 42 @tanstack/* packages and exfiltrated AWS / GCP / Vault / GitHub / SSH credentials via a postinstall script.

The defense is layered and intentionally simple:

1. Install-time cooldown, only install package versions older than N days (default 7). This is the primary defense. By the time the cooldown expires, the security community has almost always flagged a compromised version and the registry has yanked it.
2. Sandboxed pre-install scan, when the cooldown has to be bypassed (CVE patch, fresh dep, urgent install), run the candidate tarball through a static-analysis scan that looks for the diagnostic signatures of supply-chain malware. The scan runs inside bwrap/firejail/unshare so a malicious package can't escape the inspection.
3. --ignore-scripts at install, postinstall is the #1 attack vector. Skip lifecycle scripts on every cooldown-bypass install.

These three together would have blocked the Mini Shai-Hulud TanStack attack on a stock laptop with no human in the loop.

Configure the cooldown

Verified config keys (npm v11+ and bun 1.3+):

Manager	File	Key	Units	Exclusion key
npm	~/.npmrc (or project .npmrc)	min-release-age	days	none yet, proposed in npm/cli#8994
bun	~/.bunfig.toml (or project bunfig.toml)	[install] minimumReleaseAge	seconds	[install] minimumReleaseAgeExcludes = [] (exact names, no globs)

Minimal config:

# ~/.npmrc
min-release-age=7

# ~/.bunfig.toml
[install]
minimumReleaseAge = 604800  # 7 days
minimumReleaseAgeExcludes = []

Requires npm 11+. Older npm silently ignores unknown keys, so the config looks correct but does nothing. Check with npm --version and npm config get min-release-age (should echo 7, not null).

Per-command bypass

When the cooldown blocks an install you actually want:

npm install <pkg>@<version> --min-release-age=0 --ignore-scripts
bun add     <pkg>@<version> --minimum-release-age=0 --ignore-scripts

The bun add --minimum-release-age=0 CLI flag works in 1.3+ even though the docs don't list it, it follows bun's bunfig key → kebab-case flag convention.

Always pair the bypass with --ignore-scripts. Postinstall is the most common payload-execution path in supply-chain malware (Mini Shai-Hulud, event-stream, ua-parser-js, coa, all used it). Native modules that legitimately need postinstall can have the script run manually after a human-readable review:

(cd node_modules/<pkg> && cat package.json | jq .scripts) # eyeball it
(cd node_modules/<pkg> && npm run postinstall)            # run if it checks out

When to scan before bypassing

The scan is for the dangerous moment: you've decided to bypass the cooldown and need a sanity check. The skill ships a reference script (scripts/hotpatch.example.sh) implementing the heuristics. Adapt it to your machine, Bash assumes bwrap (Linux); macOS users substitute sandbox-exec or skip the sandbox layer with the trade-off documented.

Static checks the scan should perform (each backed by a real attack):

Check	Diagnostic of	Severity
optionalDependencies / dependencies containing github: or git+ URLs	Mini Shai-Hulud (delivered payload via github:tanstack/router#<sha> ref)	RED
Large JS file at package root not referenced by main/module/exports/bin/files	Planted payload pattern (router_init.js in Mini Shai-Hulud)	RED
Unpacked size >3x the prior stable version	Bulk payload smuggling	RED
fileCount delta of 1–4 paired with >2x size jump	Single planted file	RED
preinstall/install/postinstall/prepare scripts present	Lifecycle-script attack vector (event-stream, ua-parser-js, etc.)	YELLOW
JS files referencing .ssh/, .aws/, .npmrc, GITHUB_TOKEN, AWS_SECRET, kube config	Credential exfiltration	YELLOW
Version flagged deprecated in npm registry with "security"/"compromised"/"malicious" wording	Maintainer/registry yank	RED
OSV.dev returns known vulnerabilities for <pkg>@<version>	Disclosed CVE	RED (severity-dependent)

Why prerelease versions are skipped from the size-delta baseline: dev/beta/rc versions have wildly different sizes than stable releases and produce false positives.

What the cooldown does not catch

Be honest about the limits with whoever you're configuring this for:

• Old packages with new malicious versions still in the cooldown window are blocked, but if the bad version also passes the cooldown (rare but possible, a compromise that goes >7 days undetected), the cooldown alone won't help. The scan catches most of those.
• Transitive deps. A clean <pkg> you install can pull in a compromised transitive. Defenses: scan against the resolved tree (npm audit, osv-scanner), and keep the cooldown active globally so transitive resolution also waits.
• npm ci against an existing lockfile. The cooldown applies during resolution, not installation of already-pinned versions. If your lockfile pins a compromised version, npm ci will install it. Mitigation: scan lockfiles in CI with osv-scanner --lockfile=package-lock.json.
• Pre-existing compromised packages in node_modules. Hardening protects future installs, not past ones. Audit existing deps separately (npm audit, osv-scanner, manual review of recently-published deps in your tree).

Quick-start workflow for a new machine

1. Verify npm >= 11: npm --version. If older, upgrade (sudo npm i -g npm@latest or tarball-swap if self-upgrade races).
2. Write ~/.npmrc and ~/.bunfig.toml with the config above.
3. Verify: npm config get min-release-age returns 7. cat ~/.bunfig.toml shows the [install] block.
4. Copy scripts/hotpatch.example.sh to ~/.claude/hotpatch.sh (or wherever fits). Make executable. Run ./hotpatch.sh --self-test against the synthetic Mini Shai-Hulud fixture (also shipped) to confirm the heuristics fire.
5. Document the bypass workflow somewhere your team will find it. The whole skill assumes the bypass is rare and reviewed, not the default.

Threat model: what this defends and what it doesn't

Defends against	Doesn't defend against
Maintainer account compromise (npm token theft)	Targeted attack tailored to wait through the cooldown
CI/CD pipeline hijack (Mini Shai-Hulud, valid OIDC tokens, SLSA-attested malice)	Compromise of a transitive dep already pinned in a lockfile
Typosquatting (lookalike package names), when paired with npm pkg fix and lockfile review	Malicious code in your own dev dependencies that you authored
Postinstall payload execution (cooldown + --ignore-scripts = belt and suspenders)	Runtime supply-chain attacks (e.g., dynamic loading of bad code from a CDN)
Drive-by npm install of a brand-new transitive	Compromise of the registry itself (very rare; out of scope)

Further reading

• Original Mini Shai-Hulud StepSecurity analysis (TanStack attack, 2026-05-11): https://www.stepsecurity.io/blog/mini-shai-hulud-is-back-a-self-spreading-supply-chain-attack-hits-the-npm-ecosystem
• npm min-release-age config: https://docs.npmjs.com/cli/v11/using-npm/config
• bun minimumReleaseAge config: https://bun.com/docs/runtime/bunfig
• OSV.dev API (free, unauth): https://osv.dev/docs/#tag/api
• Earlier Shai-Hulud worm context: https://github.com/advisories?query=shai-hulud