The Lockfile Is a Crime Scene: Practical NPM Supply-Chain Triage

The Lockfile Is a Crime Scene

Most JavaScript supply-chain investigations start in the same uncomfortable place: something changed, nobody remembers approving it, and the lockfile is suddenly a thousand-line wall of noise.

The useful mental model is simple: treat package-lock.json, pnpm-lock.yaml, or yarn.lock like a crime scene. Do not immediately clean it up. Preserve it, compare it, and ask what changed with enough structure that the answer is not just "npm did npm things."

Triage Mindset

The first goal is not attribution. The first goal is blast-radius reduction. You want to know which dependency moved, how it entered the tree, whether it can execute code during install, and whether the current environment exposed credentials while the install happened.

• Preserve evidence: keep the suspicious lockfile, package manager logs, CI logs, and the exact Node/package-manager versions.
• Reduce movement: pause deploys, rotate CI tokens if install scripts ran, and disable publish tokens that were available to the job.
• Find the entry point: identify the package, version, maintainer event, or transitive dependency that introduced the change.
• Check execution paths: inspect lifecycle scripts, binary shims, optional dependencies, and postinstall downloaders.

What To Diff First

Do not read the entire lockfile line by line. Start with the fields that change behavior.

Signal	Why it matters
version	A minor patch bump can hide a compromised release or dependency confusion event.
resolved	Registry or tarball URL changes can reveal mirror abuse or unexpected package sources.
integrity	A changed checksum means the installed artifact is no longer identical.
hasInstallScript	Install scripts are where many supply-chain payloads get their first execution.
bin	Binary shims can turn a normal developer command into an execution path.

A Small Command Trail

For a fast first pass, I usually want these answers: which packages moved, which of them can execute code, and whether the published package contains unexpected files.

git diff -- package.json package-lock.json
npm ls --all
npm query ".scripts"
npm pack suspicious-package@1.2.3 --dry-run
npm view suspicious-package@1.2.3 scripts dist maintainers time

That is not a complete investigation, but it cuts through the fog quickly. If a package gained a preinstall hook, started shipping a giant minified file, or changed maintainers right before a release, you have a better target than "the dependency tree feels weird."

Containment Checklist

• Re-run the install in a clean, network-restricted environment and compare filesystem writes.
• Rotate tokens that were present in the shell, CI runner, or package manager config.
• Pin or override the suspicious version while you continue the investigation.
• Search for new files in build artifacts, generated clients, and committed vendor folders.
• Open an advisory or internal incident note with exact package names and versions.

Takeaway

A lockfile is noisy, but it is not meaningless. The trick is to read it like a timeline: who entered, what changed, what can execute, and what secrets were nearby when it happened.