Supply Chain Hardening Guidebook

A supply-chain payload can run at three moments: when you install a package, when
you import it, and—since 2026—when you merely open a repo.
This guidebook gives you concrete controls for each moment. Copy-pasteable playbooks
for npm, PyPI, crates.io, and Go modules, plus CI/CD pipelines and AI agent workspaces;
zero-dependency audit scripts; and a curated watch list of recent compromises.
Written so both developers and AI agents can execute it directly.

Author: Joshua Levy (github.com/jlevy) with agent assistance

Last verified 2026-08-04 against npm 12.0.2, pnpm 11.20, Yarn 4.10, Bun 1.3, pip
26.2, uv 0.12, and the current Claude Code and VS Code trust models
(full version table; Cargo and Go
rows verified 2026-05-12).

Start Here

Supply-chain payloads no longer share a single execution moment.
When the payload runs determines which control stops it, so this table is the
primary map of the repo:

The install-side setup is one command per tool you use
(details, verification, and the remaining tools):

npm config set min-release-age 14 --location=user         # npm 11.10+; days
pnpm config set minimumReleaseAge 20160 --location=user   # pnpm 10.16+; minutes
yarn config set --home npmMinimalAgeGate 20160            # Yarn 4.10+; minutes
export UV_EXCLUDE_NEWER="14 days"                         # uv; put in shell init

(Bun needs a per-repo bunfig.toml; pip 26.1+ takes PIP_UPLOADED_PRIOR_TO="P14D";
Cargo and Go have no age gate, so commit the lockfile and build --locked /
-mod=readonly.)

Before opening any repo you did not write:

uv run scripts/audit_workspace.py ./REPO   # or: python3 scripts/audit_workspace.py ./REPO

If you do only one thing: copy
SUPPLY-CHAIN-SECURITY.md into your repo root and reference
it from your project’s AGENTS.md—the same one-file motion as adding a
CODE_OF_CONDUCT.md. It is a self-contained statement of the install rules, so every
developer and AI agent working in your codebase sees them before installing anything.
Everything below is reference and rationale.

Map of This Document

Each section below opens with its takeaway, so you can stop reading at any depth:

• Choosing Your Path—which playbook applies to your situation
  (consumer repo, publisher, agent user, high-risk machine).
• For AI Agents—the intent-to-action table: what to apply when a user
  says “harden my X”.
• What This Repo Is (and Is Not)—a methodology resource
  with a curated watch list, not a real-time incident feed.
• The Layered Model—where enforcement
  lives (L1 shell defaults through L6 incident response), and why open-time attacks are
  a new surface rather than a new layer.
• Why the Hardening Pattern Is Stable—most
  incidents are fast-yanked, so delay plus pinning neutralises the class; what that does
  not cover.
• The Default Policy: A 14-Day Cool-Off—the one
  rule, the per-tool one-liners, the exception process, and update discipline.
• Related Projects—similar guides and how this repo differs.
• Authoritative Sources—where every incident claim gets
  verified.

Choosing Your Path

Read the Safety Note before applying anything, and validate every recipe
against the Authoritative Sources.

Which Path Do I Follow?

• Consumer-only repo (you install dependencies, you do not publish packages): apply
  the ecosystem playbook, commit lockfiles, and add a CI
  scanner gate.
• Repo that publishes packages or releases via GitHub Actions: apply
  guidelines/hardening-ci-cd.md first, then the
  ecosystem playbook. The minimum GitHub Actions defaults: top-level
  permissions: contents: read; no pull_request_target workflow that checks out PR
  head code; restore-only cache on PRs (and avoid implicit cache saves from setup
  actions); SHA-pin actions; OIDC trusted publishing plus npm staged publishing; publish
  job behind a GitHub Environment with required reviewers.
• Agent working in an untrusted repo: follow
  guidelines/untrusted-repo-first-run.md
  before any install / build / test / run command, and
  guidelines/hardening-agent-workspaces.md
  before opening it.
• Anyone running an AI coding agent or opening third-party repos in an editor: apply
  guidelines/hardening-agent-workspaces.md.
• Machine with publish tokens or production access: enter Strict mode
  (guidelines/strict-mode.md).

Harden a Single Ecosystem

Pick the playbook for the ecosystem you use.
Each opens with a short, copy-pasteable setup and pushes the edge cases behind an
explicit “only if you need it” boundary.

The four per-ecosystem playbooks harden the install side.
If you publish packages, or your repo releases via GitHub Actions, also apply the
cross-ecosystem CI/CD playbook: most 2026 incidents
(TanStack, @antv, Megalodon, durabletask) compromised the publish pipeline, not a
consumer.

If you use an AI coding agent or open third-party repos in an editor, also apply the
agent-workspace playbook.
From April 2026 the attack moved to committed repository config that runs when a folder
is opened: .claude/settings.json SessionStart hooks, .vscode/tasks.json
folderOpen tasks, and agent instruction files carrying hidden text.
No install happens, so no install-side control in this repo applies.

Ecosystems not yet covered: RubyGems / Bundler and Homebrew have no copy-pasteable
playbook here yet. The same methodology applies—commit Gemfile.lock and install with
bundle install --frozen; use a committed Brewfile with brew bundle, and disable
Homebrew auto-update (HOMEBREW_NO_AUTO_UPDATE=1) for reproducible installs; verify
before upgrading—but neither has a native release-age gate, so treat them like Cargo and
Go (pin, commit the lockfile, review before updating).
Adding a full playbook follows
self-update-instructions.md → “Adding a New Ecosystem”.

Harden All Ecosystems

For an agent or human walking through every ecosystem on a workstation, in order:

1. Inventory. Identify which of npm, PyPI, crates.io, Go is installed and used.
   Skip the rest.
2. Per ecosystem, open the playbook above and:
   1. Apply the Setup section verbatim, including shell-init and per-platform variants
      where your situation needs them.
   2. Run the verification commands.
      Confirm each control reports the expected value.
   3. Run the “Compromise Assessment” commands once to baseline the current state.
   4. Append an entry to the user’s supply-chain-audit-log.md (copy from
      supply-chain-audit-log-template.md)
      recording what was set and any hits found.
3. Cross-check installed packages against
   compromised-packages.md for any package@version in the
   watch list.
4. For npm specifically, run an OSV-API scan against the global tree:
   uv run scripts/audit_npm.py. The script reports [MALICIOUS] separately from
   ordinary CVEs and has zero third-party dependencies; see
   scripts/README.md.
5. Scan for open-time and load-time persistence, which no lockfile scan will find:
   uv run scripts/audit_workspace.py --scan-site-packages . in each repo you have
   opened. It reports planted agent and editor autostart config, hidden Unicode in agent
   instruction files, .pth interpreter hooks, and known host persistence.
6. If any hit lands, follow the “If You Have Hits” section in the relevant playbook
   for credential rotation, downgrade, and post-incident steps.
   If the hit is host persistence, remove it before rotating credentials: the
   2026-08-04 keyv worm’s watcher runs an operator-supplied handler when a stolen token
   stops working.

The long-form companions live in research/: threat model, attack
timeline, per-shell setup detail, and severity assessment per ecosystem.

Drop a Reminder Into Your Own Codebase

SUPPLY-CHAIN-SECURITY.md is a self-contained, portable
version of the install rules (no newer than 14 days, no unthinking installs, audit after
every install, link back here for detail).
Copy it to your own project root and reference it from your project’s AGENTS.md so any
AI agent working in your codebase sees the rules before installing anything.

For AI Agents

When the user asks you to harden, audit, or assess a package-manager supply chain:

AGENTS.md carries the same table plus a Safety Rule For Agents block, for
IDEs and agents that auto-load that filename.

Safety Note

[!WARNING]
It is increasingly unsafe to trust even seemingly trustworthy packages or GitHub
repos. Validate instructions before following them, and validate packages before
installing them. Have your agent cross-check every recipe in this repo against the
Authoritative Sources.

What This Repo Is (and Is Not)

This repo is a methodology resource for agents and humans:

• Per-ecosystem hardening guides (the four
  playbooks above) with copy-pasteable shell and CI
  configuration, plus a cross-ecosystem
  CI/CD and publish-pipeline guide for the GitHub
  Actions and release-token vectors behind the 2026 worm campaigns.
• Per-ecosystem research docs in research/ explaining the threat
  model, attack mechanisms, and defensive trade-offs.
• A strict-mode reference at
  guidelines/strict-mode.md for agents and high-risk
  environments, plus an
  untrusted-repo sandbox procedure for the
  first run of any third-party code.
• A curated watch list at compromised-packages.md for
  spot-checking installed packages and recognising attack patterns by name.
• Zero-dependency audit scripts: scripts/audit_npm.py
  checks installed npm trees against OSV, and
  scripts/audit_workspace.py checks a repo and host for
  open-time and load-time persistence.
  Plus an audit-log template at
  supply-chain-audit-log-template.md.
• A self-update procedure at
  self-update-instructions.md so any human or agent
  revisiting the repo months later can refresh it predictably.

This repo is not a real-time feed of supply-chain compromises.
For that, use the Authoritative Sources.
The watch list is curated, not exhaustive: notable named incidents that defenders should
recognise, plus enough context to make the hardening guides concrete.

The Layered Model (Where Enforcement Lives)

The repo organises its controls along two orthogonal axes:

• Trigger class: when the payload runs (install-, load-, or open-time).
  This is the primary lens—the table in Start Here—because it maps
  one-to-one onto which control stops an attack.
• Layer: where enforcement lives (developer shell, project config, CI, registry,
  sandbox, incident response).
  Use this second lens to decide where to put a control so that it cannot be bypassed or
  overridden.

Supply-chain hardening is a stack of six layers.
This repo covers L1-L3 and L6 directly, names L5 with a concrete recipe, and points
elsewhere for L4. Everything in the repo maps to one of these layers.

How to read the stack:

• L1 alone is enough for personal workstations and small teams against the
  fast-yanked-incident class of attack.
• L1, L2, and L3 together are the minimum for any shared codebase: L1 protects the
  individual developer, and L2’s committed lockfile plus L3’s CI gate close the gap when
  a peer skips L1.
• L4 is the strongest team-level control because it is the only layer that enforces
  policy across every developer, agent, CI job, and tool that resolves packages.
  If you can stand up a delayed internal mirror, do so.
  This repo describes what the controls should enforce, not how to stand up the mirror.
• L5 is critical for AI agents and for anyone routinely cloning third-party repos:
  install scripts, source builds, build.rs, proc-macros, and test files all execute
  code with ambient credentials.
• L6 is the difference between “a malicious package landed on a developer machine”
  and “a malicious package compromised production.”
  Treat the audit log as the record; do not rely on memory.
• The agent and editor workspace is a surface, not a seventh layer. Open-time
  attacks are stopped by ordinary L1 controls (your user-level and managed settings,
  which a repository cannot override) and L5 controls (pre-open triage, sandboxed first
  runs) applied at a new surface.
  The agent-workspace playbook is the L1 and
  L5 recipe for that surface.

Mapping the two axes together:

guidelines/strict-mode.md documents the Strict and
Emergency-Exception modes that sit on top of the Balanced default; agents and high-risk
environments should consult that file before installing anything.

Why the Hardening Pattern Is Stable Even When the Incident List Changes

The dominant pattern in the 2025-2026 wave is fast-yanked named incidents: malicious
package versions live for minutes to hours before researchers detect them and the
maintainer or registry yanks the bad release (qix, Shai-Hulud 1.0/2.0, Axios, TanStack,
Ultralytics, LiteLLM, Mini Shai-Hulud).

Core pattern: delay newly-published versions where the package manager supports it;
otherwise prevent unintentional re-resolution, pin exact versions, verify checksums and
advisories, and require explicit human review for dependency updates.

Gate at two layers, not one. A bot cool-off (Dependabot, Renovate) and a package
manager cool-off gate different events, so neither substitutes for the other.
The bot gates when an update is proposed; the package manager gates what a resolution
may install. A bot-only window is bypassed by npm install pkg@latest typed by hand,
by any CI job that regenerates a lockfile, and by transitive dependencies the bot never
proposed. Renovate’s own documentation recommends configuring the window in both places.
Set both, at the same number.

For Cargo and Go, “cool-off” can still be implemented through Renovate/Dependabot
policy, internal mirrors, or update wrappers, but it is not a flag the toolchain
exposes. The playbooks translate the per-ecosystem pattern into copy-pasteable commands;
the methodology is what the repo is really about.

What this neutralises: the fast-yanked named incidents above.

What it does not neutralise on its own:

• Long-lived compromises that outlast the window. BoltDB and shopsprint/decimal
  sat in the Go module proxy for around three years; the ctx takeover was live ~10
  days.
• Lockfiles that already captured a malicious version before the control was active.
• Load-time payloads. Code that runs at require() (node-ipc), at import
  (TrapDoor’s PyPI packages), or at every interpreter start (the June 2026 Hades
  .pth wheels). A wheel-only or no-build policy does nothing here, because nothing is
  built and, for .pth, nothing is even imported.
• Open-time payloads. Committed .claude/settings.json hooks, .vscode/tasks.json
folderOpen tasks, and agent instruction files carrying zero-width Unicode.
  These arrive through a git repository rather than a registry, so there is no version
  to age and no lockfile entry to review.
  See the agent-workspace playbook.
• Publish-pipeline compromises, where the malicious version ships from the
  legitimate maintainer’s own CI. By mid-2026 these routinely carry provenance that
  verifies: @antv forged Sigstore attestations at runtime, and Miasma, IronWorm, and the
  keyv worm republished through stolen OIDC credentials.
  A green badge attests to which pipeline built a package, not that the pipeline was
  clean.
• Bring-your-own-runtime payloads. The keyv and Hades loaders download a standalone
  Bun binary, so “we don’t have Bun installed” is not a control and Node-shaped
  detection misses them.

Those require additional controls: lockfile review, typo-resistance checks, the
per-ecosystem build-time controls in the playbooks, the publish-side controls in the
CI/CD playbook (OIDC trusted publishing, staged
publishing, runner hardening, provenance monitoring), and the workspace controls in the
agent-workspace playbook.

The Default Policy: A 14-Day Cool-Off

Never install or upgrade to a package version less than 14 days old, unless a
documented exception applies. This is the single default this repo recommends across
every ecosystem.
The control differs by tool (the per-ecosystem playbooks have the exact,
version-specific recipes and verification):

The cool-off applies to your toolchain as well as your dependencies.
It is also the only control in this table that does anything about load-time payloads
such as the Hades .pth wheels, since those execute without an install script, a source
build, or an import.

The general principle. A cool-off works because the registry and researchers detect
and yank malicious versions while legitimate versions keep accruing age.
So the only thing the window length trades off is detection coverage against how stale
your dependencies are: a longer window catches more of the slow-detection tail, and its
only cost is waiting longer for legitimate updates.
The benefit curve flattens out (most incidents die in hours to a few days), while the
staleness cost grows roughly linearly, so there is a knee in the curve rather than a
single magic number.
14 days is the recommended floor, not a ceiling.

Why at least 14 days:

• Detection window. Most malicious publishes are reported and yanked within 3-7
  days; 14 days is a generous buffer past that median.
• It covers the realistic tail, not just the fast cases. Many incidents die in
  minutes (Bitwarden ~93 min, @antv ~22 min), but the value of a cool-off is set by the
  slowest-detected incidents.
  The ctx PyPI takeover was malicious for ~10 days.
  A 7-day window misses it; a 14-day window catches it.
• Patch bumps are where malware hides. Many compromises arrive as a 1.2.3 -> 1.2.4
  patch. A trailing-age window neutralises the whole “fresh patch is malicious” class
  regardless of which dependency moved.
• The cost is asymmetric. Waiting 14 days on a routine upgrade is essentially free;
  the only real cost is an urgent security patch, which the exception process handles.

Pick a larger number if you can. Nothing here caps the window at 14: a 30-, 60-, or
90-day cool-off is strictly safer, and high-risk environments (machines with publish
tokens or production access) should go higher.
The “Live X hours” timings in compromised-packages.md are
the evidence base, so treat 14 days as a balanced minimum and lengthen it to taste.

What The Ecosystems Now Ship By Default

The argument for a cool-off is no longer contrarian.
Between late 2025 and mid-2026 most of the JavaScript toolchain turned one on by
default, and the automated update bots followed.
Verified against vendor documentation on 2026-08-04:

Three things follow from this table:

• npm is the outlier in its own ecosystem. pnpm, Yarn, and Bun all gate by default;
  npm ships null. If you use npm, you are the one who has to opt in.
• Python has no default anywhere. uv and pip both support a cool-off and neither
  turns it on, so every Python project starts unprotected.
• The 14-day recommendation is now a modest step past the defaults, not a leap.
  Yarn’s shipped default is already 7 days, and Dependabot’s is 3.

Defaults do not replace the setting.
A default protects the tool that ships it, on the machine that has it; a committed
policy protects the whole team, and only an explicit value tells a reader which window
you actually chose.

Scope: applies to dependencies, devDependencies (historically more dangerous,
since build tooling runs with full developer privileges), peerDependencies, and
optionalDependencies; to new installs and upgrades; and to transitive dependencies to
the extent the package manager enforces it.
The cool-off applies to the whole resolved set, not just the package you named:
adding or upgrading one dependency can pull in many transitive packages, any of which
may be brand-new, so review the full lockfile diff and confirm the window for every
newly added package.
To fix a single violator without re-resolving the whole graph, pin it forward in place
(e.g. uv lock --upgrade-package <name>==<version>, pnpm update <pkg>@<version>).
Pins resolved before adopting the policy are grandfathered until their next planned
upgrade.

The Exception Process

When a version inside the 14-day window is genuinely needed (for example a CVE patch
published yesterday that fixes a vulnerability you are exposed to), take the exception
explicitly and on the record:

• State the reason in the commit message or PR description: the CVE ID (or vulnerability
  description if none yet), a link to the upstream release notes, and a Reviewed-by:
  sign-off line.

• Pin the exact package@version, not a range.
  Verify it against the authoritative sources: publisher,
  publish time, and integrity hash.

• Scope the exception to the one package using the tool’s own per-package exclude,
  rather than relaxing the global cool-off for the whole dependency graph.
  Every major tool now has one, and a committed entry is reviewable in a way an unset
  environment variable never is:

Delete the entry once the version ages past the window.
An exclude left behind turns a one-off exception into a permanent hole.

• Otherwise install it surgically, via a direct tarball / wheel URL or a pinned git
  ref, rather than relaxing the gate.
  Each playbook’s “When You Intentionally Need A Fresh Package” step has the
  verify-then-install commands
  (npm,
  PyPI;
  crates
  and Go verify
  before pinning instead, since they have no cool-off to relax).

• Log it in supply-chain-audit-log.md with a follow-up to confirm the version was not
  yanked after the fact.

No exception is “trivial” (even a prettier patch is in scope): the point of the rule
is that we do not trust ourselves to eyeball which fresh versions are safe.
Agents never self-approve an exception; they prepare the record above and a human
signs off. See guidelines/strict-mode.md for the full
Emergency-Exception record format.

Update Discipline: The Safest Update Is the One You Skip

A cool-off decides when to take an update.
The prior question is whether to update at all.
Each update is fresh attack surface, and updating has repeatedly proven riskier than the
latent bugs it fixes.
Mitchell Hashimoto (HashiCorp, Ghostty) puts the strong form of this well:

Fork your dependencies, trim them to only your use case, never update unless it breaks
for your users. [...] updating is way riskier than latent bugs (which can be tracked
and CVEs monitored).
If you are updating a dependency, it’s on you to analyze every single commit in the
full transitive set of dependencies.
If you don’t see anything compelling, don’t update!
[...] Don’t update for the sake of it.

This is one influential school, and the absolutist version trades supply-chain risk for
the risk of not applying a needed security fix.
The balance this repo recommends:

• Default to not updating. Don’t bump a dependency without a concrete reason ("show
  me the commit we need"). Minimise the dependency count, and prefer vendoring or
  pinning for small, stable libraries.
• Monitor CVEs so the exception is data-driven. The post-install audit commands
  (npm audit, pip-audit, cargo audit, govulncheck) and the IOC feeds are how you
  learn a real security update is needed, which is exactly when the 14-day exception
  applies.
• When you do update, review the change set, not just the version number, and then
  still wait out the 14-day window unless it is a security exception.

Maintaining This Repo

All doc-update procedures live in
self-update-instructions.md, including the table of
package-manager versions the playbooks have been validated against and the
re-verification procedure for major-version bumps.
At a glance:

Every doc follows common-doc-guidelines.md (author: jlevy, upstream
practical-prose), flagged by the footer at
the bottom of each file and readable with tbd guidelines common-doc-guidelines. Style
for additions: Title Case headings, no spaced em dashes, concrete examples over
generalities, no “talking about talking”, cite primary sources.

Contributing

Each new ecosystem guide must:

1. Cite multiple independent sources for any named-incident claim.
2. Be specific enough to copy-paste: exact env-var names, exact filenames, exact version
   numbers.
3. Cover macOS, Linux, and Windows where the underlying tooling supports them.
4. End with the standard doc-guidelines footer.
5. Follow the procedure in self-update-instructions.md.

Related Projects

Good guides exist in adjacent lanes—use them; several are cited throughout this repo.
What none of them covers is the combination here: four ecosystems plus CI/CD plus
agent workspaces in one place, organised by when the payload runs, and written so an AI
agent can execute it directly.

The trigger-class framing (Start Here) is what makes the difference
practical: install-time advice is plentiful elsewhere, but load-time payloads (Hades
.pth) and open-time payloads (poisoned CLAUDE.md, committed editor tasks) defeat
install-side controls entirely, and the playbooks for those two classes—plus a
scanner that checks for them—exist only here.
The freshness protocol is the other differentiator: every
version claim carries a verification date, because in this genre stale advice is
indistinguishable from wrong advice.

Authoritative Sources

Every cross-reference in this repo points back here.
Verify any new incident against at least two of the “Incident Reporting Feeds” before
adding it to compromised-packages.md.

Per-Ecosystem Vulnerability Databases (System Of Record)

• npm: OSV.dev npm feed,
  GHSA npm filter,
  npm audit.
• PyPI: OSV.dev PyPI feed,
  PyPA Advisory DB,
  GHSA PyPI filter,
  pip-audit.
• crates.io: RustSec Advisory DB,
  OSV.dev crates.io feed,
  GHSA Rust filter,
  cargo audit.
• Go modules: Go Vulnerability DB
  (machine-readable),
  OSV.dev Go feed,
  GHSA Go filter,
  govulncheck.
• Cross-ecosystem programmatic: OSV.dev API
  (POST /v1/query for one package, POST /v1/querybatch for up to 1000),
  deps.dev API.

Incident Reporting Feeds (Free, Public, Two-Source Verification)

• Aikido Intel: live tracker with per-incident package
  lists.
• StepSecurity Blog: often the first public
  detector; publishes file-level IOCs.
• Socket Security Blog: sandboxed-execution analysis.
• Datadog Security Labs: worm-pattern technical
  deep-dives.
• ReversingLabs Blog: malware analysis with
  file-level IOCs.
• Unit 42 living doc:
  Palo Alto’s tracking of the ongoing wave.
• Phylum Blog: package-registry-attack focus.
• JFrog Security Research: npm and
  PyPI coverage; first to publish the IronWorm teardown.
• SafeDep: registry-backed campaign counts and per-campaign
  tracking pages.
• Wiz Threat Research: cloud-credential impact analysis.
• CISA Alerts: US-CERT
  advisories for major incidents.
• Maintainer postmortems (e.g.
  TanStack postmortem):
  primary sources when available.

Commercial (Paid or Mostly-Paid)

Snyk Vulnerability DB,
Sonatype OSS Index,
JFrog Xray, Wiz Threat Intel.

License

MIT.