secondsky/claude-skills / plugins/dependency-upgrade/skills/dependency-upgrade
dependency-upgrade
UnverifiedSecure dependency upgrades with supply chain protection, cooldowns, and staged rollout. Use when upgrading deps, configuring security policies, or preventing supply chain attacks.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 18.5 KB |
| references/compatibility-matrix.md | markdown | 3.6 KB |
| references/cooldown-config-guide.md | markdown | 5.2 KB |
| references/package-manager-security.md | markdown | 5.2 KB |
| references/secrets-and-containers.md | markdown | 3.3 KB |
| references/socket-cli-guide.md | markdown | 12.0 KB |
| references/staged-upgrades.md | markdown | 4.5 KB |
| references/supply-chain-security.md | markdown | 10.4 KB |
| references/testing-strategy.md | markdown | 4.1 KB |
| scripts/generate-dependency-upgrades.shexecutable | script | 14 B |
| templates/bunfig-security.tmpl | other | 727 B |
| templates/dependabot-security.tmpl | other | 1.0 KB |
| templates/devcontainer-security.tmpl | other | 639 B |
| templates/npmrc-security.tmpl | other | 851 B |
| templates/pnpm-workspace-security.tmpl | other | 1.6 KB |
| templates/renovate-security.tmpl | other | 1.1 KB |
| templates/socket-fix-ci.tmpl | other | 1.3 KB |
| templates/socket-scan-ci.tmpl | other | 900 B |
| templates/yarnrc-security.tmpl | other | 762 B |
references/supply-chain-security.md
View on GitHub# Supply Chain Security Reference
Comprehensive guide to preventing supply chain attacks during dependency installation and upgrades.
## Threat Landscape
Recent supply chain incidents demonstrate why hardening dependency workflows is critical:
| Incident | Year | Attack Vector | Impact |
|----------|------|---------------|--------|
| event-stream | 2018 | Malicious maintainer | Stole Bitcoin wallets |
| eslint-scope | 2018 | Stolen credentials | Published malicious versions |
| ua-parser-js | 2021 | Account takeover | Cryptomining + credential theft |
| node-ipc | 2022 | Protestware | Deleted files on Russian IPs |
| colors/faker | 2022 | Maintainer sabotage | Infinite loop DOS |
| Shai-Hulud | 2024 | Postinstall worm | Propagated via lifecycle scripts |
| Nx | 2025 | Compromised postinstall | Weaponized AI coding agents |
## Security Principles
### 1. Trust Nothing by Default
Every package — direct or transitive — is a potential attack vector. Configure package managers to block unsafe behavior and only allow what is explicitly reviewed.
### 2. Delay Before Installing
Newly published packages may contain malicious code discovered within hours or days. A cooldown period lets the community catch threats before they reach production.
### 3. Freeze and Validate
Lockfiles are the contract between development and production. Protect them from injection and validate their integrity in CI.
### 4. Minimize Attack Surface
Fewer dependencies = fewer potential vulnerabilities. Each transitive dependency inherits all risks of its own dependency tree.
### 5. Audit Before Trusting
Don't rely solely on npmjs.org — the displayed source code can differ from the actual tarball. Use security tools to audit packages before installation.
## Disabling Post-Install Scripts
Post-install scripts are the most common supply chain attack vector. They execute arbitrary code during `npm install` with full system access.
### npm
```bash
# Global config (recommended — applies to all projects)
npm config set ignore-scripts true
npm config set allow-git none
# Per-command
npm install --ignore-scripts --allow-git=none <package>
# .npmrc file
ignore-scripts=true
allow-git=none
```
Even with `--ignore-scripts`, git-based dependencies can ship `.npmrc` files that re-enable lifecycle scripts. Use `--allow-git=none` (npm CLI 11.10.0+) alongside `--ignore-scripts` to fully close this vector.
### Bun
Bun disables postinstall scripts by default and maintains an internal allow-list. Allow specific packages via `trustedDependencies` in `package.json`:
```json
{
"trustedDependencies": [
"esbuild",
"sharp"
]
}
```
### pnpm (10.0+)
pnpm disables postinstall scripts by default since v10.0. Control which packages can run build scripts:
```yaml
# pnpm-workspace.yaml
# Preferred (pnpm 10.26+): single map of package → true/false
allowBuilds:
esbuild: true
fsevents: true
nx@21.6.4 || 21.6.5: true
core-js: false
# Legacy (still supported):
# onlyBuiltDependencies:
# - esbuild
# - fsevents
# Make unreviewed scripts a hard error (pnpm 10.3+)
strictDepBuilds: true
```
### Allowlist with @lavamoat/allow-scripts
For projects that need some post-install scripts, use `@lavamoat/allow-scripts` to create an auditable allowlist:
```bash
npm install --save-dev @lavamoat/allow-scripts
npx allow-scripts auto
```
This scans the dependency tree and creates a `package.json` entry listing which packages are permitted to run scripts, blocking all others.
## Lockfile Injection Prevention
### The Threat
Malicious actors can submit PRs that modify lockfiles to point to compromised packages or change the `resolved` URL + integrity hash to their own payload.
### Validation with lockfile-lint
```bash
npm install --save-dev lockfile-lint
# Validate npm lockfile
npx lockfile-lint \
--path package-lock.json \
--type npm \
--allowed-hosts npm yarn \
--validate-https
# Validate yarn lockfile
npx lockfile-lint \
--path yarn.lock \
--type yarn \
--allowed-hosts npm yarn \
--validate-https
```
### CI Integration
```json
{
"scripts": {
"lint:lockfile": "lockfile-lint --path package-lock.json --type npm --allowed-hosts npm --validate-https",
"preinstall": "npm run lint:lockfile"
}
}
```
### pnpm Specific Hardening
pnpm is inherently more resistant to lockfile injection:
- Doesn't maintain tarball sources that can be maliciously modified
- Won't install packages in the lockfile that aren't in `package.json`
Additional protection (pnpm 10.26+):
```yaml
# pnpm-workspace.yaml
# Block transitive deps from using exotic sources (git repos, tarball URLs)
blockExoticSubdeps: true
```
### Trust Policy (pnpm 10.21+)
Detect when a package's publish-time trust level has decreased — an early signal of account compromise:
```yaml
# pnpm-workspace.yaml
trustPolicy: no-downgrade
# Allow specific packages to bypass
trustPolicyExclude:
- 'chokidar@4.0.3'
# Ignore check for packages published >30 days ago (pnpm 10.27+)
trustPolicyIgnoreAfter: 43200 # minutes (30 days)
```
Trust levels (strongest → weakest):
1. **Trusted Publisher** — published via OIDC/GitHub Actions
2. **Provenance** — published with npm provenance attestation
3. **Signatures** — registry signature present
4. **No evidence** — no trust signals
### Bun Lockfile Notes
Bun uses `bun.lock` (text-based, default since v1.2) or `bun.lockb` (binary). `lockfile-lint` does not currently support Bun lockfile formats. Monitor the [lockfile-lint repo](https://github.com/lirantal/lockfile-lint) for future support.
## Pre-Install Security Auditing
### npq — Pre-Install Package Auditor
[npq](https://github.com/lirantal/npq) audits packages before installation using multiple security "marshalls":
```bash
# Install globally
npm install -g npq
# Use instead of npm
npq install express
# Dry run (audit without installing)
npq install express --dry-run
# Shell alias for seamless integration
alias npm='npq-hero'
echo "alias npm='npq-hero'" >> ~/.zshrc
# Use with other package managers
NPQ_PKG_MGR=pnpm npq install fastify
NPQ_PKG_MGR=bun npq install fastify
# Permanent aliases for other PMs
alias pnpm="NPQ_PKG_MGR=pnpm npq-hero"
```
What npq validates:
- Vulnerability scanning (Snyk CVE database)
- Package age analysis (flags packages < 22 days old)
- Typosquatting detection
- Registry signature verification
- Provenance attestation checks
- Pre/post-install script warnings
- Package health (README, LICENSE, repo URL, downloads)
- Binary introduction warnings
- Deprecation status
- Maintainer domain validation (expired domains)
### Socket Firewall (sfw) — Real-Time Package Firewall
[sfw](https://socket.dev/blog/introducing-socket-firewall) intercepts package manager commands and blocks malicious packages:
```bash
# Install globally
npm install -g sfw
# Prefix any package manager command
sfw npm install express
sfw pnpm add express
sfw yarn add express
sfw pip install requests
sfw cargo fetch
```
What sfw checks:
- Malicious code detection
- Install script risks
- Typosquatting detection
- Dependency confusion attacks
- Known vulnerabilities
- Protestware and env variable access
- Network and filesystem access patterns
### Comparison
| Feature | npq | sfw | Socket CLI (`socket npm`) |
|---------|-----|-----|---------------------------|
| Analysis | Pre-install marshalls | Real-time deep analysis | Full transitive scan via npm integration |
| Data sources | Snyk CVE, npm metadata | Socket proprietary intelligence | Socket proprietary intelligence |
| Interactivity | Prompts before install | Blocks and prompts flagged packages | Prompts before installing flagged packages |
| PM support | npm, pnpm, Bun (env vars) | npm, yarn, pnpm, pip, uv, cargo | npm, npx (wrapper mode) |
| Open source | Yes | Client only | Client only (open source on GitHub) |
| Free tier | Yes | No | Yes (beta, default issues only) |
| CI integration | No | No | Yes (`socket ci`, `socket fix --autopilot`) |
| Package scoring | No | No | Yes (`socket package score`) |
| CVE auto-fixing | No | No | Yes (`socket fix`) |
| Requires auth | No | Yes | No for wrapper, Yes for scans/fix |
See `references/socket-cli-guide.md` for full Socket CLI documentation.
## Publisher Security
### Enable 2FA for npm Accounts
```bash
# Enable for auth + publishing
npm profile enable-2fa auth-and-writes
# Enable for auth only
npm profile enable-2fa auth-only
```
### Publish with Provenance Attestations
Provides cryptographic proof of where and how packages were built:
```yaml
# GitHub Actions
permissions:
id-token: write
steps:
- run: npm publish --provenance
```
Requires npm CLI 9.5.0+ and GitHub Actions or GitLab CI/CD.
### Publish with OIDC (Trusted Publishing)
Eliminates long-lived npm tokens by using short-lived OIDC tokens from CI:
```yaml
# GitHub Actions
permissions:
id-token: write
steps:
- run: npm publish
```
Configure trusted publisher on npmjs.com first. Automatically generates provenance attestations (OpenSSF compliant).
## Avoiding Blind Upgrades
### Anti-Patterns
```bash
# DANGEROUS — upgrades everything without review
npm update
npx npm-check-updates -u
```
Incidents like colors/faker and node-ipc demonstrate why blind upgrades are dangerous.
### Safe Alternatives
```bash
# Interactive — review each upgrade
npx npm-check-updates --interactive
# Use automated tools with security policies
# - Snyk: 21-day cooldown built-in
# - Dependabot: configurable cooldown
# - Renovate: minimumReleaseAge config
```
## Package Health Assessment
### Snyk Security Database
Before adopting any package, check [security.snyk.io](https://security.snyk.io):
```
https://security.snyk.io/package/npm/<package-name>
```
Provides: security vulnerabilities, popularity trends, maintenance activity, community signals.
### Don't Trust npmjs.org Alone
The npmjs.org website:
- Omits git and HTTPS-based dependencies from displayed `package.json`
- Source code display can drift from the actual installed tarball
Always inspect the actual tarball:
```bash
npm pack <package-name> --dry-run
npm pack <package-name>
tar -tzf <package-name>-<version>.tgz
```
## Dependency Tree Reduction
Replace common dependencies with native JavaScript:
```javascript
// Instead of lodash
const unique = [...new Set(array)];
// Instead of axios
const response = await fetch(url);
// Instead of utility libraries
const isEmpty = obj => Object.keys(obj).length === 0;
const clone = structuredClone(original);
```
Each dependency adds transitive attack surface. Evaluate necessity, maintenance burden, and bundle size before adding any dependency.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| rea-analysis-optimizationmorluto/reaOptimize REA providers and shared analysis workflows for agent context, latency, CPU, and memory while preserving correctness and Evidence. Use for analysis bottlenecks and cache or query design; CI/test-suite optimization belongs to rea-ci-tests-audit. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| rea-ci-tests-auditmorluto/reaAudit REA CI and test suites for correctness, fixture drift, false passes, and measured performance; use for suite or workflow investigations and efficiency changes, rather than ordinary feature testing or a single test failure. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |