npm Supply Chain Lockdown Framework

// When should I use the npm Supply Chain Lockdown Framework?

Apply this skill whenever you are setting up a new JavaScript/TypeScript project, onboarding a team to a shared repo, or auditing an existing project's dependency security posture. Also invoke it immediately after a publicised npm supply chain attack to check whether your current setup would have protected you.

// What information do I need before applying the npm Supply Chain Lockdown Framework?

• Package manager in userequired
  Which package manager(s) the project uses: npm, pnpm, and/or bun.
• Project typerequired
  Local dev only, CI/CD pipeline, production deployment, or monorepo — affects which tips are highest priority.
• Existing config files
  Current state of .npmrc, pnpm.config.yaml / pnpm-workspace.yaml, bunfig.toml, package.json, and lock files — so gaps can be identified.
• CI environment
  Whether the project runs automated installs in CI (GitHub Actions, CircleCI, etc.).

// What are the core principles behind the npm Supply Chain Lockdown Framework?

// How do you apply the npm Supply Chain Lockdown Framework step by step?

1. 1

   Enable Release Age Gating in your package manager config

   npm: add `minimum-package-age=7` (days) to .npmrc. pnpm: add `minPackageAge: 10080` (minutes) to pnpm.config.yaml or pnpm-workspace.yaml — note pnpm 11+ defaults to 1 day even without this. bun: add `[install] packageAge = 604800` (seconds) to bunfig.toml. Warn your team that npx/bunx do NOT respect this setting — they always pull the latest version. If you must bypass age gating for a legitimate security patch, do so explicitly from the CLI, not via an LLM-generated command.

2. 2

   Block install scripts by default and build an explicit allow list

   pnpm: already off by default. Run `pnpm approve-builds` after install to review and selectively allow scripts (e.g. esbuild). This writes to the `allowBuilds` config. bun: already off by default with a curated safe list. Add a `trustedDependencies` array to package.json listing only packages you explicitly approve. To override bun's built-in curated list, put at least one value in the array (empty array has a known bug that does not override defaults). Run `bun pm untrusted` to audit pending scripts. npm: set `ignore-scripts=true` in .npmrc, then use the `allow-scripts` npm package (Lava Moat) to replicate allow-list behaviour.

3. 3

   Block Git-based and exotic dependencies

   npm: set `allow-git=none` in .npmrc to block all Git-URL deps, or `allow-git=root` to allow only those explicitly declared in your root package.json. pnpm: set `blockExoticSubdependencies=true` — this restricts Git repos and direct tarball URLs to direct dependencies only. bun: no native option yet; watch for the open PR that adds this. As a pnpm bonus: set `trustPolicy=no-downgrade` so pnpm fails if a package's trust level has decreased compared to its prior release, catching compromised publisher accounts.

4. 4

   Install and alias a pre-installation firewall tool

   Choose one: (a) npq — alias your npm/pnpm/bun install commands to npq. It checks Snyk's vulnerability database, flags packages under 22 days old, catches typosquatting, verifies registry signatures and build provenance, warns on install scripts, and checks download count, readme, license, repo URL, and whether the maintainer's email domain is still registered. (b) Socket Firewall — alias your install commands to socket. Blocks human-confirmed malicious packages immediately; warns on AI-detected (unreviewed) threats. Also supports Python (pip, uv) and Rust (cargo). Attackers themselves have confirmed Socket detects malware before the package reaches your machine. After installing either tool, clear your package manager's cache so all previously cached packages are re-scanned on next install.

5. 5

   Validate your lock file with lockfile-lint (if not using pnpm)

   pnpm users: skip this step — pnpm does not store swappable tarball sources in its lock file and will not install lock-file entries that are absent from package.json. npm/bun users: install `lockfile-lint` as a dev dependency and run it as a pre-install or CI check. It validates that every resolved URL points to a trusted host (the npm registry), that resolved URLs match the declared package name, and that integrity hashes are genuine. A tampered lock file fails the install. Ensure your lock file is committed to version control and is NOT in .gitignore.

6. 6

   Switch CI and production installs to clean install mode

   npm: replace `npm install` with `npm ci`. pnpm: use `pnpm install --frozen-lockfile` or `pnpm ci` alias — pnpm auto-detects CI environments and applies this by default. bun: use `bun install --frozen-lockfile` or `bun ci`. Clean install installs exactly what is in the lock file, nothing more, and errors out if lock file and package.json are inconsistent rather than silently resolving the difference.

7. 7

   Adopt deliberate dependency hygiene habits

   Three habits to enforce: (1) Never run a bulk update command (npm update, pnpm update, bun update) without reviewing each upgrade individually — ask 'why do I need this upgrade?'. (2) Reduce your dependency count — every package is an attack surface; attacks spread through transitive dependencies. Before adding a package, ask whether a small code snippet or a native API (e.g. fetch instead of axios, native array methods instead of lodash) achieves the same result. In agentic coding contexts, ask the AI to write the utility function instead of importing a package. (3) Pin all direct dependencies to exact versions in package.json so every upgrade is a deliberate choice, not an automatic range resolution. Remember: pinning only locks your direct deps; your dependencies' dependencies still use their own ranges, which is why Release Age Gating (Step 1) remains critical.

// What does the npm Supply Chain Lockdown Framework look like in real projects?

// What mistakes should I avoid when implementing the npm Supply Chain Lockdown Framework?

• npx and bunx do NOT respect Release Age Gating — they always pull the latest package version, bypassing your age window entirely.
• LLM-generated install commands may silently add flags that bypass age gating and install the latest version anyway — always review AI-suggested install commands.
• Setting bun's trustedDependencies to an empty array does NOT override bun's built-in curated allow list (known bug) — put at least one explicit entry in the array to force the override.
• Lockfile-lint is unnecessary if you are already on pnpm, but critical for npm and potentially bun, where lock file URL-swapping attacks are viable.
• Bulk update commands (npm update, pnpm update, bun update) are exactly the behaviour attackers rely on — never run them blindly.
• Pinning direct dependencies to exact versions does NOT protect transitive dependencies — your packages' packages still resolve ranges, which is why Release Age Gating must remain active.
• Not committing your lock file to version control makes Steps 5 and 6 entirely ineffective — confirm the lock file is tracked in git and not gitignored.
• Clearing your package manager cache after installing a firewall tool is mandatory — previously cached packages will not be re-scanned otherwise.
• The trust policy no-downgrade setting is pnpm-only and does not have an equivalent in npm or bun yet.

// What do the key terms in the npm Supply Chain Lockdown Framework mean?

Release Age Gating

A package manager configuration that prevents installation of packages newer than a specified age threshold (set in days for npm, minutes for pnpm, seconds for bun), causing the manager to install the most recent version that is older than the threshold instead.

Install Scripts

Lifecycle hooks (pre-install, post-install, etc.) that a package is permitted to execute immediately after being installed. Used legitimately for compiling native code or fetching binaries, but the execution vector used in nearly every supply chain attack.

Exotic Dependencies

Dependencies declared as Git URLs or direct tarball URLs rather than registry package names. They bypass the npm registry, can ship their own .npmrc overrides, and can re-enable install scripts — a known attack vector.

Socket Firewall

A pre-installation auditing tool that aliases over package manager install commands and blocks human-confirmed malicious packages while warning on AI-detected (unreviewed) threats, supporting npm, pnpm, bun, pip, uv, and cargo.

npq

A pre-installation auditing tool that aliases over npm/pnpm/bun install commands and checks packages against Snyk's vulnerability database, flags packages under 22 days old, detects typosquatting, verifies registry signatures and build provenance, and audits maintainer metadata.

Typosquatting

An attack where a malicious package is published under a name nearly identical to a popular package (e.g. 'expresss' instead of 'express'), hoping developers make a typo and install the attacker's package.

lockfile-lint

A dev-dependency tool that validates a project's lock file by checking all resolved URLs point to a trusted registry host, that resolved URLs match declared package names, and that integrity hashes are genuine — failing the install if tampering is detected.

Clean Install

A package manager command (npm ci, pnpm ci / --frozen-lockfile, bun ci / --frozen-lockfile) that installs exactly the dependency tree recorded in the lock file and throws an error rather than resolving discrepancies between lock file and package.json.

Trust Policy (no-downgrade)

A pnpm-specific setting that causes installation to fail if a package's trust level has decreased compared to its previous published release, catching attacks that compromise a previously trusted publisher account.

allow-scripts (Lava Moat)

An npm package that replaces npm's native install script behaviour with an explicit allow-list declared in package.json, giving npm users the same per-package script approval workflow that pnpm and bun provide natively.

// FREQUENTLY ASKED QUESTIONS