dependency-upgrade

Dependency Upgrade

Manage dependency upgrades with supply chain security, compatibility analysis, staged rollout, and comprehensive testing across all major package managers.

When to Use This Skill

• Upgrading major framework or library versions
• Configuring supply chain attack prevention (cooldown, script blocking, lockfile hardening)
• Setting up secure package manager configuration
• Resolving dependency conflicts or peer dependency issues
• Planning incremental upgrade paths with testing
• Automating dependency updates with Renovate, Dependabot, or Snyk
• Auditing dependencies for vulnerabilities
• Setting up CI/CD dependency security workflows

Two Modes of Operation

Interactive — Walk through setup questions to generate tailored config. Use for fresh setup.

Default — Apply recommended defaults immediately: 7-day cooldown, block all scripts, frozen-lockfile, lockfile-lint, Dependabot with cooldown. Customization optional.

Interactive Setup Flow

When the user wants tailored configuration, walk through these decisions. Skip this section entirely if using default mode.

Tier 1: Required Decisions

Always ask these 3 questions before generating any config:

1. Package Manager

"Which package manager does this project use?"

| Answer | Generates | |--------|-----------| | npm | .npmrc | | Bun | bunfig.toml | | pnpm | pnpm-workspace.yaml | | Yarn | .yarnrc.yml | | Deno | deno.json config |

2. Cooldown Period

"How many days should newly published packages age before install? This prevents supply chain attacks where malicious packages are discovered and unpublished within days."

| Option | Days | Use Case | |--------|------|----------| | Aggressive | 3 | Catches most typosquatting | | Recommended | 7 | Good balance for most projects | | Conservative | 14 | Critical/production systems | | Paranoid | 21 | Matches Snyk's built-in default | | Custom | N | User specifies |

3. Post-Install Script Policy

"How should lifecycle scripts (postinstall, preinstall) be handled? These are the #1 attack vector for supply chain attacks."

| Option | Behavior | |--------|----------| | Block all (recommended) | --ignore-scripts + allow-git=none | | Allowlist | Block by default, allow specific trusted packages | | Review only | Warn but don't block |

Tier 2: Security Tooling (Offer as Batch)

"Which of these security features would you like to configure? Select any that apply."

4. CI/CD Automation Tool

| Answer | Generates | |--------|-----------| | Dependabot | .github/dependabot.yml with cooldown | | Renovate | renovate.json with minimumReleaseAge | | Snyk | No config needed (21-day cooldown built-in) | | None | Skip |

5. Automerge Policy

| Option | Behavior | |--------|----------| | None | All updates require manual review | | Minor+Patch only | Auto-merge safe updates, review majors | | All with approval | Auto-merge after team approval |

6. Update Schedule

| Option | Config Value | |--------|-------------| | Daily | "daily" | | Weekly (default) | "weekly" | | Biweekly | "biweekly" | | Monthly | "monthly" |

7. Install-Time Security Tooling

"Which security tools should protect dependency installation?"

| Option | Free? | What It Does | |--------|-------|-------------| | socket npm wrapper | Yes (beta) | Wraps npm/npx, blocks malicious packages before install. Run socket wrapper on to enable system-wide. | | npq | Yes | Pre-install auditor (CVE, typosquat, age, provenance checks) | | Socket Firewall (sfw) | No | Real-time deep analysis, blocks malicious packages | | socket npm + npq | Yes | Both free tools combined | | None | — | Skip |

Load references/socket-cli-guide.md for full Socket CLI setup including authentication and free vs authenticated features.

8. Lockfile Validation

| Option | Behavior | |--------|----------| | Yes (recommended) | Adds lockfile-lint + CI script | | No | Skip |

Tier 3: Advanced Options (Only If User Opts In)

"Would you like to configure any advanced options?"

9. Dev Containers — Generate hardened .devcontainer/devcontainer.json (Yes/No)

10. Secrets Manager — 1Password CLI / Infisical / None

11. pnpm Trust Policy — Enable trustPolicy: no-downgrade (pnpm 10.21+ only, Yes/No)

12. Cooldown Exclusions — Package names that bypass cooldown (e.g., @types/react, typescript, esbuild)

Security-First Upgrade Principles

1. Cooldown before installing — Wait 7 days for new package versions to be vetted by the community
2. Block post-install scripts — Prevent arbitrary code execution during npm install
3. Freeze lockfiles in CI — Use deterministic installs (npm ci, --frozen-lockfile)
4. Validate lockfile integrity — Use lockfile-lint to detect injection
5. Audit before trusting — Use npq or Socket CLI to check packages before installing
6. Upgrade incrementally — One major version at a time with testing between each
7. Never blindly upgrade — Avoid npm update or npm-check-updates -u without review
8. Scan before and after — Use socket scan to detect supply chain issues beyond CVEs

Cooldown Period: Prevent Supply Chain Attacks

Newly published packages may contain malicious code discovered within hours. Configure a cooldown period to delay installation.

Quick Setup

npm (.npmrc):

min-release-age=7

Bun (bunfig.toml):

[install]
minimumReleaseAge = 604800  # 7 days in seconds
minimumReleaseAgeExcludes = ["@types/bun", "typescript"]

pnpm (pnpm-workspace.yaml):

minimumReleaseAge: 10080  # 7 days in minutes
minimumReleaseAgeExclude:
  - '@types/react'
  - typescript

Yarn (.yarnrc.yml):

npmMinimalAgeGate: "7d"
npmPreapprovedPackages:
  - "@types/react"
  - "typescript"

Load references/cooldown-config-guide.md for detailed per-PM configuration, CI tool integration, and exclusion patterns.

Use templates/<pm>-security.tmpl for copy-paste ready config files.

Disable Post-Install Scripts

Post-install scripts are the most common supply chain attack vector (Shai-Hulud, Nx, event-stream incidents).

Quick Setup

npm:

npm config set ignore-scripts true
npm config set allow-git none

Bun: Disabled by default. Allow specific packages in package.json:

{ "trustedDependencies": ["esbuild", "sharp"] }

pnpm (10.0+): Disabled by default. Allow specific packages in pnpm-workspace.yaml:

allowBuilds:
  esbuild: true
strictDepBuilds: true  # Hard error on unreviewed scripts

Load references/package-manager-security.md for full per-PM hardening including pnpm trustPolicy, blockExoticSubdeps, and @lavamoat/allow-scripts.

Deterministic & Frozen Installs

Always use frozen install commands in CI to ensure reproducible builds:

| Package Manager | Command | What It Does | |----------------|---------|-------------| | npm | npm ci | Deletes node_modules, installs exact lockfile versions | | Bun | bun install --frozen-lockfile | Fails if lockfile is out of sync | | pnpm | pnpm install --frozen-lockfile | Fails if lockfile is out of sync | | Yarn | yarn install --immutable --immutable-cache | Validates lockfile and cache | | Deno | deno install --frozen | Frozen installation |

Commit all lockfiles to version control: package-lock.json, bun.lock, pnpm-lock.yaml, yarn.lock, deno.lock.

Lockfile Validation

Install and configure lockfile-lint to detect lockfile injection attacks:

npm install --save-dev lockfile-lint

{
  "scripts": {
    "lint:lockfile": "lockfile-lint --path package-lock.json --type npm --allowed-hosts npm --validate-https",
    "preinstall": "npm run lint:lockfile"
  }
}

Note: lockfile-lint does not currently support Bun's bun.lock / bun.lockb formats.

Pre-Install Security Auditing

npq — Pre-Install Auditor

npm install -g npq
npq install <pac