Read package-lock.json like a security reviewer

A package-lock.json records the exact dependency tree npm installed, including each package's source URL and an integrity hash. A security reviewer reads the diff of that file in a pull request, looking for new packages, changed sources and install scripts that nobody expected.

What the file holds

The npm documentation says the lockfile records the exact tree so later installs produce the same one. For each package it can include the version, a resolved field saying where the package came from, an integrity field holding a sha512 or sha1 hash of the artifact, and flags such as dev, optional and hasInstallScript. The top level shows lockfileVersion, which is 3 for npm v9 and later.

The same documentation lists why to commit it: teammates, deployments and CI get the same dependencies, and changes to the tree show up as readable diffs. That second point is what makes review possible.

Five things to check in a diff

1. New top level packages. Did the change intend to add them? A small feature that adds forty packages deserves a question.
2. Changed resolved URLs. A package that used to resolve from the public registry and now points at a different host or a git address needs an explanation.
3. Changed integrity values with an unchanged version. The same version should have the same hash. If it changes, find out why.
4. New hasInstallScript flags. Install scripts run code on your machine during install, so a new one is worth reading.
5. Large unrelated churn. Lockfile regeneration can reshuffle many lines. Prefer small, intentional updates.

A quick review routine

Look at the diff with a tool that shows only added and removed package entries. Many teams script this. A minimal approach is to compare the list of names and versions:

git diff main -- package-lock.json | grep '"resolved"'

That prints lines with changed sources so you can scan them. It is crude but fast, and a real pipeline step should do the same with more care.

What a lockfile cannot tell you

It tells you what was installed, not whether it is safe. A pinned version with a known vulnerability is still pinned. The OSV database describes affected ranges with introduced and fixed events, so a scanner can match your locked versions against those ranges. That matching is where the lockfile becomes useful for security.

It also does not describe the build environment, container base images or tools outside npm. For those you need other inventories.

Common failure modes

Teams ignore lockfile diffs because they are long. Make them short by updating one dependency per pull request when you can. Teams also forget that when both an npm-shrinkwrap.json and a package-lock.json exist, npm uses the shrinkwrap file and ignores the lockfile, so reviewing the wrong one gives false comfort.

For the next step, see OSV version ranges explained.

Where Safeguard fits

The free scan at gold.safeguard.sh/scan checks dependency manifests such as package.json for known vulnerabilities, and Safeguard's dependency scanning and SBOM generation cover your projects.

Quick check

Sources

• npm docs, package-lock.json
• OSV, Open Source Vulnerabilities
• Safeguard free scan

Last reviewed: 19 October 2026.