/dependency-upgrade

name: dependency-upgrade
description: "Secure dependency upgrades with supply chain protection, cooldowns, and staged rollout. Use when upgrading deps, configuring security policies, or preventing supply chain attacks."
license: MIT

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`):