npm supply chain: how to audit your lockfile

npm supply chain: how to audit your lockfile

TL;DR

Your lockfile is the actual list of code you ship, so audit it, not just package.json. Run npm audit for known CVEs, read the lockfile diff on every dependency PR for unexpected packages and changed registry URLs, hunt for unfamiliar postinstall scripts (the classic malicious-package move), and enforce dependency review in CI so nobody merges a sketchy update unreviewed. Most supply-chain attacks arrive as boring-looking version bumps.

npm supply chain: how to audit your lockfile

Use this when

• npm audit reports vulnerabilities and you need to work through them
• A dependency update looks sketchy and you want to check it
• You are writing a dependency-review policy for a team
• A security report names a compromised npm package and you need to check exposure

Not for this skill when

• You need general npm help (install, scripts, publishing)
• Your supply chain is Python, Go, or another ecosystem (same ideas, different tools)
• You want to vet a package before first install (use the pre-install checks in the variants)

Steps

1. Run the audit and read it properly

npm audit

Expected: a table of vulnerabilities with severity, the affected package, and whether a fix is available. Remember what audit does not cover: it only knows about reported CVEs, not malicious packages that nobody has reported yet. A clean audit is not a clean bill of health.

2. Fix what is fixable, carefully

npm audit fix

Expected: the lockfile updates for non-breaking fixes. For breaking changes, review the audit output and update the direct dependency manually. Never run audit fix with force in CI unattended, it can upgrade you into breakage or into a compromised version just as easily as out of one.

3. Read the lockfile diff on every dependency PR

git diff package-lock.json | grep -E "^[+-].*(resolved|version)" | head -30

Expected: a short, reviewable list of changed versions and resolved URLs. Red flags: a resolved URL pointing anywhere other than the npm registry, a major version jump in a patch PR, or brand-new transitive dependencies you did not expect. This diff is where compromised-package updates are visible.

4. Hunt for unfamiliar install scripts

grep -o '"postinstall": "[^"]*"' package-lock.json | sort | uniq -c | sort -rn | head

Expected: a short list of postinstall scripts. Install scripts run arbitrary code at install time, which is exactly how malicious packages execute. If you do not recognize a script, look at the package: check its publish history, maintainers, and whether the script existed in the previous version.

5. Find out why a package is even there

npm ls [package-name]

Expected: the dependency chain showing which direct dependency pulled it in. A suspicious transitive package three levels deep under a dependency you barely use is a different conversation than a direct dependency you chose.

Variant: enforce review in CI

Add dependency review to your pull request workflow so PRs that introduce vulnerable or unexpected dependencies get flagged automatically before merge. Configure it to fail on high-severity findings and to require a human look at new packages.

Variant: vetting a package before first install

Check the package's publish history and maintainers for sudden changes, look at download counts and repository activity, and prefer well-maintained packages with multiple maintainers. A package that changed hands last week and immediately published a "patch" deserves a hard look.

Variant: npm audit signatures

Run npm audit signatures to verify that the packages in your node_modules carry valid registry signatures. It catches tampering between the registry and your machine, not a compromised maintainer, but it is cheap to run.

Why this happens

Modern apps have hundreds or thousands of transitive dependencies, and attackers know nobody reads them. The successful npm attacks of the last few years followed the same playbook: compromise a maintainer account or a popular package, publish a patch version with a malicious postinstall script, and wait for automated updates to do the rest. The lockfile diff is the cheapest place to catch it.

Edge cases and pitfalls

• npm audit is noisy about dev-only dependencies that never ship. Triage by what reaches production.
• False positives happen, especially with bundled or vendored copies. Confirm before burning a day.
• npm ci respects the lockfile exactly, npm install can update it. CI should always use npm ci.
• Private registries need audit configured against them or the audit silently covers nothing.
• Lockfile version matters. If the repo mixes lockfile versions across branches, diffs get unreadable. Standardize on one.
• A compromised package with no CVE will sail through npm audit. The diff review and script hunt are your backstop.

Tool notes: npm 9+ for current audit output. The dependency review action runs on GitHub Actions.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_RpMcT6S39zmFD8Ua052XPg