npm-vulnerability-remediation

NPM Vulnerability Remediation

Use this skill when assessing or fixing vulnerabilities reported for NPM dependencies.

Identify the Package Manager and Lockfile

1. Inspect the repository root for package.json and package-manager metadata:
   • packageManager in package.json
   • engines in package.json
   • CI workflows, contributor documentation, and existing scripts
2. Identify the authoritative lockfile before changing dependencies:
   • package-lock.json for npm
   • npm-shrinkwrap.json for npm, which takes precedence over package-lock.json
   • yarn.lock for Yarn
   • pnpm-lock.yaml for pnpm
3. Use only the repository's configured package manager. Do not introduce, replace, or regenerate an unrelated lockfile.
4. Match the runtime and package-manager versions required by the project. Prefer Corepack when the repository declares a supported package manager version.

Assess the Audit

1. Install dependencies using the lockfile's immutable mode where supported:
   • npm: npm ci
   • Yarn: yarn install --immutable
   • pnpm: pnpm install --frozen-lockfile
2. Run the package manager's audit command and record each actionable advisory:
   • npm: npm audit --json
   • Yarn: use the repository's configured audit workflow or yarn npm audit --json for modern Yarn
   • pnpm: pnpm audit --json
3. Determine the vulnerable package's role:
   • Direct runtime dependency
   • Direct development dependency
   • Transitive dependency
   • Optional dependency
   • Tooling-only dependency
4. Confirm the affected dependency path, installed version, fixed version, severity, exploitability, and whether the vulnerable code is reachable in the application.
5. Do not use automatic force fixes until their resulting dependency, API, and runtime changes have been reviewed.

Choose the Smallest Safe Remediation

Direct Dependencies

1. Update the direct dependency to the lowest supported version containing the fix.
2. Respect the existing semver policy and avoid unrelated version upgrades.
3. Review release notes and migration guidance for breaking changes.
4. Update package.json and the authoritative lockfile together using the configured package manager.

Transitive Dependencies

1. First update the nearest direct parent package if that brings in a fixed transitive version without a breaking change.
2. If no compatible parent update exists, use the package manager's scoped constraint mechanism:
   • npm: overrides in package.json
   • Yarn: resolutions in package.json
   • pnpm: pnpm.overrides in package.json
3. Pin only the vulnerable package or vulnerable dependency edge to a version known to be compatible with the installed parents.
4. Keep every override narrowly scoped, explain why it is needed, and remove it once upstream packages include the fix.
5. Never hand-edit a lockfile except as an unavoidable, package-manager-documented consequence of a constrained update.

Apply Constrained Updates

1. Make the minimal manifest change required for the chosen remediation.
2. Regenerate only the authoritative lockfile with the configured package manager.
3. Inspect the manifest and lockfile diff:
   • Confirm the intended fixed version is installed on every vulnerable path.
   • Ensure unrelated packages were not updated, removed, or added.
   • Reject broad lockfile churn and retry with a more constrained command or override.
4. Re-run the audit and verify the advisory is absent or reduced exactly as expected.

Validate

1. Run the repository's documented dependency installation command from a clean state.
2. Run the smallest relevant validation commands already provided by the repository:
   • Type checking
   • Linting
   • Unit or integration tests
   • Build or packaging checks
3. Run the full validation suite when the remediated package affects runtime behavior, build tooling, shared configuration, or the project's existing CI requires it.
4. Report the exact remediation, advisories resolved, remaining advisories, validation results, and any compatibility considerations.

Handle Unresolvable Advisories

When no safe fix is currently available, do not suppress or misrepresent the finding.

1. Document the advisory identifier, severity, vulnerable and fixed ranges, dependency path, and the reason a safe update is unavailable.
2. State the reachability assessment, including whether vulnerable code is shipped, invoked, or exposed in the deployed environment.
3. Describe mitigations such as disabling the affected feature, restricting untrusted input, isolating build-only tooling, or avoiding the vulnerable code path.
4. Link or reference the upstream issue and define a concrete follow-up condition, such as a fixed parent release or a new advisory version.
5. Keep any temporary exception narrowly scoped, time-bound where policy permits, and visible in the remediation report or tracked issue.
6. Do not modify audit configuration, ignore files, or severity thresholds solely to hide an unresolved vulnerability.