dependency-supply-chain-review

Dependency Supply Chain Review

Purpose

Audit the project's package dependency graph for known CVEs, suspicious install-time scripts, lockfile integrity issues, typosquatting candidates, outdated packages with breaking changes, and transitive dependency risks. Produce a prioritized remediation plan.

When to use

• npm audit, yarn audit, or pip-audit has flagged vulnerabilities and you need a structured remediation plan.
• A PR adds or upgrades packages and you want to verify supply-chain safety before merge.
• The project has not had a dependency review in more than 90 days.
• A postinstall or prepare script in a dependency is executing code at install time.
• The lockfile (package-lock.json, yarn.lock, poetry.lock) is missing or was recently deleted and regenerated.

When not to use

• The project has no third-party dependencies (single-file scripts, standard-library only).
• You need to audit application runtime logic unrelated to packages.
• A dedicated security scanning tool (Snyk, Dependabot, Socket) has already triaged all findings and the task is to implement fixes — use a code-editing skill instead.

Procedure

1. Confirm lockfile presence and integrity. Check that package-lock.json / yarn.lock exists and is committed. A missing lockfile means installs are non-deterministic. Verify it was generated with npm ci semantics (resolves from lock, not from package.json ranges).

2. Run audit non-destructively. Execute npm audit --json or yarn audit --json and capture output. Do not run npm audit fix --force without reviewing the proposed changes.

3. Classify CVEs by exploitability. For each finding, determine:

• Severity (critical/high/moderate/low).
• Is the vulnerable code path reachable in this project? (e.g., a server-side RCE in a browser-only bundle is unexploitable).
• Is a non-breaking fix version available?

4. Inspect install-time scripts. For every dependency with postinstall, prepare, preinstall, or install scripts in its package.json, read what the script does. Flag any that download binaries, execute curl/wget, or modify system files.

5. Check for typosquatting candidates. Compare package names against their intended counterparts: lodash vs lod4sh, express vs expres. Pay special attention to recently added packages with few downloads.

6. Audit transitive dependency pinning. Check if critical transitive packages are pinned via overrides (npm) or resolutions (yarn). Missing overrides for a vulnerable transitive dep means audit fix cannot resolve it without manual intervention.

7. Verify npm ci is used in CI, not npm install. npm install can silently update the lockfile; npm ci fails if the lockfile is out of sync, ensuring reproducibility.

8. Check for outdated major versions. Run npm outdated and flag packages more than one major version behind, especially those with known breaking changes or end-of-life status (Node.js 16, webpack 4, etc.).

9. Review private registry configuration. If .npmrc configures a private registry, confirm it falls back to the public registry only for scoped packages (@company/*), not for all packages, to prevent dependency confusion attacks.

10. Document approved exceptions. For CVEs marked as not exploitable, create or update a npm-audit-exceptions.json or similar file with justification, reviewer, and review date.

Checklist

• Lockfile present, committed, and generated by npm ci / yarn --frozen-lockfile.
• npm audit returns zero critical or high findings, or all findings have documented exceptions.
• No postinstall scripts download remote code or execute curl/wget.
• No package names are suspicious typosquatting candidates.
• Vulnerable transitive deps are addressed via overrides/resolutions where direct upgrade is not possible.
• CI pipeline uses npm ci, not npm install.
• .npmrc scopes private registry to @company/* only.
• All packages with known EOL status (runtime, framework) have a documented upgrade timeline.
• package.json ranges are not * or >=0.0.0 for production dependencies.
• Audit exceptions file exists with justification for each waived finding.

Common issues & anti-patterns

• Deleted and regenerated lockfile: dependency versions silently drift; all transitive versions must be re-reviewed.
• npm install in CI: lockfile can mutate between runs; always use npm ci.
• Unpinned devDependencies promoted to production: require() in application code pulling a dev-only package that is not in dependencies.
• --legacy-peer-deps flag in CI: silently installs incorrect peer versions; treat as a warning signal for outdated dep graph.
• Scoped package confusion: a public package @acme/utils can be published by anyone if the org namespace is not claimed.
• Binary download postinstall: legitimate packages like puppeteer and cypress download large binaries at install; verify checksums and consider vendoring or caching.
• Audit false negatives from bundling: npm audit checks node_modules, but client-side bundles may include vulnerable code that audit does not flag if the package is not in the dep tree directly.

Required output

## Dependency Supply Chain Review

### Critical CVEs requiring immediate fix
| Package | Installed | Safe version | CVE | Exploitable in this project |
|---------|-----------|-------------|-----|----------------------------|

### Suspicious install-time scripts
- package@version: script content summary, risk level.

### Outdated packages (1+ major behind)
| Package | Current | Latest | EOL? |
|---------|---------|--------|------|

### Lockfile status
- Present: yes/no. Generator: npm/yarn. CI uses npm ci: yes/no.

### Audit exceptions (not exploitable)
| CVE | Package | Reason | Reviewer | Date |

### Recommended next commands
1. npm audit fix (safe upgrades only — review diff before committing)
2. ...

Safety

• Run npm audit --json (read-only) only. Do not run npm audit fix --force, npm install, or any script that modifies node_modules or the lockfile without explicit user approval.
• Do not print package registry tokens or .npmrc auth values.
• Do not run postinstall scripts or execute any downloaded binary.