---
id: secondsky/claude-skills/dependency-upgrade
version: "66543d75"
license: MIT
install: manual
updated: 2026-07-25
---

# dependency-upgrade — This skill automates the process of updating project dependencies while prioritizing security against supply chain threats. It integrates seamlessly with Claude Code CLI to manage package upgrades safely and efficiently.

Publisher: secondsky · Stars: 196 · Updated: 2026-07-25

Install (manual): `git clone https://github.com/secondsky/claude-skills`

## SKILL.md

# 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`):
```ini
min-release-age=7
```

**Bun** (`bunfig.toml`):
```toml
[install]
minimumReleaseAge = 604800  # 7 days in seconds
minimumReleaseAgeExcludes = ["@types/bun", "typescript"]
```

**pnpm** (`pnpm-workspace.yaml`):
```yaml
minimumReleaseAge: 10080  # 7 days in minutes
minimumReleaseAgeExclude:
  - '@types/react'
  - typescript
```

**Yarn** (`.yarnrc.yml`):
```yaml
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**:
```bash
npm config set ignore-scripts true
npm config set allow-git none
```

**Bun**: Disabled by default. Allow specific packages in `package.json`:
```json
{ "trustedDependencies": ["esbuild", "sharp"] }
```

**pnpm (10.0+)**: Disabled by default. Allow specific packages in `pnpm-workspace.yaml`:
```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:

```bash
npm install --save-dev lockfile-lint
```

```json
{
  "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

```bash
npm install -g npq
npq install <package>          # Audit before installing
npq install <package> --dry-run # Audit without installing

# Shell alias for seamless use
alias npm='npq-hero'

# Use with other PMs
NPQ_PKG_MGR=pnpm npq install <package>
NPQ_PKG_MGR=bun npq install <package>
```

### Socket Firewall (sfw) — Real-Time Blocker

```bash
npm install -g sfw
sfw npm install <package>      # Blocks malicious packages
sfw pnpm add <package>
sfw yarn add <package>
```

Load `references/supply-chain-security.md` for full comparison of npq vs sfw and what each validates.

## Socket CLI Integration

Socket CLI provides proactive supply chain security beyond basic vulnerability scanning — covering malware detection, typosquatting, protestware, install script risks, and license compliance.

### Proactive Upgrade Workflow

```
1. PRE-UPGRADE:   socket scan create --report          → establish baseline
2. EVALUATE:      socket package score npm <pkg>@<ver>  → assess target package safety
3. SAFE INSTALL:  socket npm install <pkg>              → block malicious packages
4. POST-UPGRADE:  socket scan create --report          → verify no new alerts
5. DIFF:          socket scan diff <before> <after>     → see exactly what changed
6. FIX:           socket fix --minimum-release-age 7d   → auto-fix any new CVEs
7. OPTIMIZE:      socket optimize                       → apply security overrides
```

### Quick Reference

```bash
# Install
npm install -g socket

# Authenticate (required for scans, fixes, package scores)
socket login

# Check a package before upgrading
socket package score npm <package>

# Scan your whole project
socket scan create --report

# Auto-fix CVEs (complements Dependabot/Renovate)
socket fix --minimum-release-age 7d

# Gate CI on security policy
socket ci

# Safe npm wrapper (free, no auth needed)
socket wrapper on
```

Load `references/socket-cli-guide.md` for comprehensive command reference, CI workflow templates, alert categories, and free vs authenticated feature matrix.

## Dependency Analysis

```bash
# Audit for vulnerabilities
bun audit       # Bun
npm audit       # npm
yarn audit      # Yarn

# Socket: deep security assessment (CVEs + supply chain + license)
socket package score npm <package>
socket scan create --report

# Check for outdated packages
bun outdated
npm outdated

# Interactive upgrade (safe — review each)
bunx npm-check-updates --interactive

# Analyze dependency tree
npm ls <package-name>
yarn why <package-name>
```

## Staged Upgrade Strategy

Upgrade one dependency at a time with testing between each:

```bash
# 1. Create feature branch
git checkout -b upgrade/<package>-<version>

# 2. (Optional) Baseline scan — capture current state
socket scan create --report

# 3. Evaluate target package before upgrading
socket package score npm <package>@<version>

# 4. Upgrade single package
bun add <package>@<version>

# 5. Test immediately
bun test && bunx tsc --noEmit && bun run build

# 6. (Optional) Post-upgrade scan — verify no new alerts
socket scan create --report

# 7. Commit and continue
git add -A && git commit -m "chore: upgrade <package> to <version>"
```

Load `references/staged-upgrades.md` for codemod automation, custom migration scripts, and peer dependency handling.

Load `references/compatibility-matrix.md` for version compatibility tables (React 18/19, Next.js 13-15, TypeScript, Tailwind 3/4).

## Automated Updates with Cooldown

Configure CI/CD tools to respect cooldown periods:

### Dependabot (`.github/dependabot.yml`)

```yaml
version: 2
updates:
  - package-ecosystem: "npm"
    directory: "/"
    schedule:
      interval: "weekly"
    cooldown:
      default-days: 7
```

### Renovate (`renovate.json`)

```json
{
  "extends": ["config:base"],
  "minimumReleaseAge": "7 days",
  "packageRules": [
    {
      "matchUpdateTypes": ["minor", "patch"],
      "automerge": true
    },
    {
      "matchUpdateTypes": ["major"],
      "automerge": false,
      "minimumReleaseAge": "14 days"
    }
  ]
}
```

### Snyk

Snyk includes a built-in 21-day cooldown for upgrade PRs. No configuration needed.

### Socket Fix (complements Dependabot/Renovate)

Socket Fix automatically resolves CVEs with intelligent upgrade planning. Runs alongside other automation tools — it focuses on CVE remediation specifically:

```bash
# Fix all fixable CVEs with cooldown alignment
socket fix --minimum-release-age 7d

# Conservative: no major version bumps
socket fix --minimum-release-age 7d --no-major-updates

# Target specific CVEs
socket fix --id GHSA-hhq3-ff78-jv3g --minimum-release-age 7d

# Preview without applying
socket fix --no-apply-fixes --minimum-release-age 7d
```

For CI autopilot mode (auto-creates and auto-merges fix PRs), use `templates/socket-fix-ci.tmpl`.

Load `references/socket-cli-guide.md` for full `socket fix` options including `--autopilot`, `--range-style`, and `--pr-limit`.

Use `templates/dependabot-security.tmpl` or `templates/renovate-security.tmpl` for complete config files.

## Publishing Security

For package maintainers:

```bash
# Enable 2FA
npm profile enable-2fa auth-and-writes

# Publish with provenance (cryptographic build proof)
npm publish --provenance

# Trusted publishing via OIDC (eliminates long-lived tokens)
# Configure on npmjs.com, then:
# In GitHub Actions: permissions: id-token: write
```

Load `references/supply-chain-security.md` for full publishing security guide including OIDC setup and dependency tree reduction.

## Dev Environment Hardening

Isolate dependency execution from the host system:

- **Dev containers** — limit blast radius of malicious packages
- **Secrets management** — use 1Password CLI or Infisical instead of plaintext `.env` files
- **Dependency tree reduction** — replace common packages with native JS

Use `templates/devcontainer-security.tmpl` for a hardened dev container config.

Load `references/secrets-and-containers.md` for dev container setup, secrets management, and dependency reduction patterns.

## Testing Strategy

Run tests at every level after each upgrade:

```bash
# 1. Static analysis (fastest)
bunx tsc --noEmit && bun run lint

# 2. Unit tests
bun test

# 3. Build check
bun run build

# 4. Integration / E2E (after major upgrades)
bun run test:e2e
```

Load `references/testing-strategy.md` for full testing pyramid, CI integration, and bundle analysis.

## Rollback Plan

```bash
#!/bin/bash
git stash
git checkout -b upgrade/<package>

bun add <package>@latest

if bun test && bun run build; then
  git add package.json bun.lock
  git commit -m "chore: upgrade <package>"
else
  echo "Upgrade failed, rolling back"
  git checkout main
  git branch -D upgrade/<package>
  bun install
fi
```

## Upgrade Checklist

```markdown
Pre-Upgrade:
- [ ] Review current dependency versions
- [ ] Read changelogs for breaking changes
- [ ] Create feature branch
- [ ] Tag current state (git tag pre-upgrade)
- [ ] Run full test suite (baseline)
- [ ] Verify cooldown period is configured

Security Pre-Checks:
- [ ] Post-install scripts are disabled
- [ ] Lockfile validation is active
- [ ] Install auditing tools configured (if applicable)
- [ ] CI uses frozen-lockfile install
- [ ] Run `socket scan create --report` for baseline (if Socket available)

During Upgrade:
- [ ] Upgrade one dependency at a time
- [ ] Check target package: `socket package score npm <pkg>` (if Socket available)
- [ ] Respect cooldown period (don't force latest)
- [ ] Update peer dependencies
- [ ] Fix TypeScript errors
- [ ] Run test suite after each upgrade
- [ ] Check bundle size impact

Post-Upgrade:
- [ ] Post-upgrade scan: `socket scan diff` to verify no new alerts (if Socket available)
- [ ] Consider `socket fix --minimum-release-age 7d` for any new CVEs
- [ ] Full regression testing
- [ ] Performance testing
- [ ] Update documentation
- [ ] Deploy to staging
- [ ] Monitor for errors
- [ ] Deploy to production
```

## Common Pitfalls

- Upgrading all dependencies at once (use incremental upgrades)
- Blindly running `npm update` or `npm-check-updates -u` without review
- Not testing after each individual upgrade
- Ignoring peer dependency warnings
- Forgetting to update or commit the lock file
- Not reading breaking change notes in changelogs
- Skipping major versions instead of stepping through them
- Not having a rollback plan
- Trusting npmjs.org displayed source code (can differ from actual tarball)
- Leaving post-install scripts enabled (most common attack vector)
- Not configuring a cooldown period for new package versions

## When to Load References

Load these reference files when the user needs detailed information beyond the quick-reference in SKILL.md:

| Load This File | When |
|---------------|------|
| `references/cooldown-config-guide.md` | Configuring cooldown for a specific PM, CI tool integration, or exclusion patterns |
| `references/package-manager-security.md` | Full per-PM hardening guide including pnpm trust policy, blockExoticSubdeps, cross-PM cheat sheet |
| `references/supply-chain-security.md` | Understanding attack vectors, incident history, npq vs sfw vs Socket CLI comparison, publisher security (2FA, provenance, OIDC) |
| `references/secrets-and-containers.md` | Setting up dev containers, secrets management with 1Password/Infisical |
| `references/socket-cli-guide.md` | Using Socket CLI for scans, fixes, package scoring, CI integration, wrapper mode, alert categories |
| `references/compatibility-matrix.md` | Checking version compatibility for React, Next.js, TypeScript, Tailwind upgrades |
| `references/staged-upgrades.md` | Codemod automation, custom migration scripts, peer dependency handling, workspace upgrades |
| `references/testing-strategy.md` | Full testing pyramid, CI integration, bundle analysis, performance testing |

## Template Files

Ready-to-use config files in `templates/`:

| Template | Purpose |
|----------|---------|
| `npmrc-security.tmpl` | Secure `.npmrc` with scripts disabled + cooldown |
| `bunfig-security.tmpl` | Secure `bunfig.toml` with cooldown + exclusions |
| `pnpm-workspace-security.tmpl` | Secure `pnpm-workspace.yaml` with cooldown, allowBuilds, trustPolicy |
| `yarnrc-security.tmpl` | Secure `.yarnrc.yml` with age gate + preapproved packages |
| `dependabot-security.tmpl` | Dependabot config with 7-day cooldown |
| `renovate-security.tmpl` | Renovate config with minimumReleaseAge + automerge rules |
| `devcontainer-security.tmpl` | Hardened dev container with security options |
| `socket-fix-ci.tmpl` | GitHub Actions: Socket Fix autopilot with cooldown-aligned CVE remediation |
| `socket-scan-ci.tmpl` | GitHub Actions: Socket CI security gate for every push/PR |


[View on SkillFed](https://skillfed.io/secondsky/claude-skills/dependency-upgrade) · [View on GitHub](https://github.com/secondsky/claude-skills)