🛡️ pnpm-shield

Supply chain attack protection audit tool for pnpm projects.

pnpm-shield audits your pnpm project and developer environment against the most common supply chain attack vectors — postinstall script injection, dependency confusion, phantom dependencies, and accidental npm usage. It runs 13 checks, explains every finding with attack vectors and remediation steps linked to official docs, and can auto-fix all of them interactively.

Why this matters

The npm registry is the largest software registry in the world — and one of the most targeted. Attackers abuse postinstall scripts, typosquatting, and account takeovers to execute arbitrary code on every machine that runs npm install or pnpm install. The attacks below all share one trait: they would have been stopped by a correctly configured pnpm environment.

💡 Every postinstall attack in this list is blocked by ignore-scripts=true. The dependency confusion attacks are mitigated by a strict pnpm-lock.yaml and the packageManager field enforced by Corepack. pnpm-shield checks for all of these protections.

Installation

# Run directly without installing (recommended for one-off audits):
pnpm dlx pnpm-shield

# Install globally:
pnpm add -g pnpm-shield

# Add as a dev dependency in your project:
pnpm add -D pnpm-shield

Zero production dependencies. Everything uses Node.js built-ins.

Usage

# Run in the root of your project:
pnpm-shield

# Same command, shorter alias:
pnpm-check

# CI mode — non-interactive, exits with code 1 on failures:
pnpm-shield --ci

# Show help:
pnpm-shield --help

# Show version:
pnpm-shield --version

Interactive menu

After the audit runs, an interactive prompt lets you explore and fix findings without leaving the terminal.

Commands

Documentation panel

Every check has an integrated documentation panel showing:

• Why it matters — the security rationale
• Attack vector — a concrete attack scenario
• How to fix — step-by-step remediation commands
• Official references — links to pnpm docs, Node.js docs, and security post-mortems

What it checks

pnpm-shield runs 13 security checks across three categories. All non-passing checks support auto-fix.

🖥 Environment

⚙️ pnpm / npm Configuration

📦 package.json Hardening

Grading

After the audit, your project receives a security grade:

Score = passed checks + 0.5 × warnings.

Check details

1. pnpm installed — CRITICAL

pnpm is the only mainstream package manager with onlyBuiltDependencies whitelisting, per-project ignore-scripts, and a content-addressable store with integrity verification.

corepack enable pnpm
# or:
curl -fsSL https://get.pnpm.io/install.sh | sh

📎 pnpm Installation

2. Shell alias npm → pnpm — HIGH ✅

Even with pnpm fully configured, typing npm install by muscle memory invokes the real npm binary. npm ignores your .npmrc, your pnpm-lock.yaml, and your onlyBuiltDependencies whitelist.

echo 'alias npm=pnpm' >> ~/.zshrc && source ~/.zshrc

📎 Typosquatting attacks

3. Corepack managing pnpm — HIGH ✅

Corepack (built into Node.js ≥ 16.9) reads "packageManager" in package.json and blocks npm and yarn project-wide. It also ensures every developer uses the exact same pnpm version.

corepack enable
corepack enable pnpm

📎 Corepack docs · pnpm + Corepack

4. No foreign lockfiles — CRITICAL ✅

A package-lock.json or yarn.lock alongside pnpm-lock.yaml creates two conflicting sources of truth. CI systems may pick the wrong one, installing different (potentially malicious) resolved versions.

rm package-lock.json yarn.lock bun.lockb
pnpm install
git add pnpm-lock.yaml

📎 Dependency confusion attack

5. Global ignore-scripts=true — CRITICAL ✅

Packages can declare postinstall, preinstall, and install lifecycle scripts that run arbitrary shell commands. This is the primary vector for supply chain attacks (event-stream 2018, node-ipc 2022, xz-utils 2024).

pnpm config set ignore-scripts true

Note: With ignore-scripts=true, packages that legitimately need build scripts (e.g. esbuild, sharp) will break. Use check #10 (onlyBuiltDependencies) to whitelist exactly those packages.

📎 pnpm ignore-scripts · event-stream post-mortem

6. Local .npmrc: ignore-scripts=true — HIGH ✅

The global config can differ across machines and CI environments. A local .npmrc commits the rule into the repository, protecting every developer and every CI runner regardless of their global config.

echo "ignore-scripts=true" >> .npmrc
git add .npmrc

7. save-exact=true — MEDIUM ✅

By default pnpm saves deps with a ^ prefix (e.g. ^1.2.3), allowing any compatible update. An attacker who compromises a package can publish 1.2.4 with malicious code and every project using ^1.2.3 adopts it on the next install.

echo "save-exact=true" >> .npmrc

📎 Semver hijacking

8. shamefully-hoist=false — LOW ✅

pnpm uses a strict, isolated node_modules layout by default. shamefully-hoist=true flattens it like npm, allowing packages to import dependencies they never declared (phantom dependencies).

echo "shamefully-hoist=false" >> .npmrc

📎 Phantom dependencies

9. engine-strict=true — MEDIUM ✅

Some security patches are Node.js-version-specific. Running code on an EOL Node version may miss critical fixes.

echo "engine-strict=true" >> .npmrc

📎 Node.js release schedule

10. pnpm.onlyBuiltDependencies — HIGH ✅

Even with ignore-scripts=true, you may need certain packages to run build scripts (e.g. esbuild, sharp). This whitelist gives surgical, auditable control over which packages may run scripts.

// package.json
{
  "pnpm": {
    "onlyBuiltDependencies": ["esbuild", "sharp"]
  }
}

An empty array [] blocks all postinstall scripts without exception.

📎 onlyBuiltDependencies

11. packageManager field — HIGH ✅

Tells Corepack the exact package manager and version the project requires. Corepack will then block npm and yarn and auto-download the correct pnpm version for any contributor.

// package.json
{
  "packageManager": "pnpm@11.1.1"
}

📎 packageManager field

12. engines.node range — MEDIUM ✅

Declares the minimum Node.js version. Combined with engine-strict=true, pnpm refuses to install on incompatible environments, preventing use of EOL runtimes with known CVEs.

// package.json
{
  "engines": { "node": ">=20" }
}

📎 engines field

13. pnpm-lock.yaml present — HIGH ✅

The lockfile pins exact resolved versions AND SHA-512 integrity hashes for every package in the full dependency tree. Without it, pnpm install resolves versions fresh each time and can silently adopt a compromised release.

pnpm install      # generates pnpm-lock.yaml
git add pnpm-lock.yaml
# Never add pnpm-lock.yaml to .gitignore!

📎 pnpm lockfile format · Should lockfiles be committed?

CI/CD integration

GitHub Actions

# .github/workflows/security.yml
name: Security Audit

on: [push, pull_request]

jobs:
  pnpm-shield:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
      - run: pnpm dlx pnpm-shield --ci

Native git pre-commit hook (no extra dependencies)

cat > .git/hooks/pre-commit << 'EOF'
#!/bin/sh
pnpm-shield --ci
EOF
chmod +x .git/hooks/pre-commit

Recommended baseline configuration

.npmrc

ignore-scripts=true
save-exact=true
shamefully-hoist=false
engine-strict=true

package.json additions

{
  "packageManager": "pnpm@11.1.1",
  "engines": { "node": ">=20" },
  "pnpm": {
    "onlyBuiltDependencies": []
  }
}

Project structure

pnpm-shield.js        ← Entry point (20 lines)
lib/
  colors.js           ← ANSI color constants
  docs.js             ← Per-check documentation + official references
  checks.js           ← Runs all 13 security checks
  ui.js               ← Terminal output (header, results, doc panel, summary)
  selector.js         ← Raw TTY arrow-key interactive selector (zero deps)
  fixes.js            ← Auto-fix implementations for all 13 checks
  runner.js           ← Orchestrates the full audit + interactive menu

Contributing

Pull requests are welcome. To add a new check:

1. Add the result in lib/checks.js with a docKey and fix key
2. Add documentation in lib/docs.js with why, attack, fix, and refs
3. Add a fix handler in lib/fixes.js

License

MIT