lockfile-lint treats the lockfile as the policy boundary

The lockfile is a whitelist nobody reads

Every JavaScript project that installs from npm or yarn carries a lockfile, and that file is effectively a trusted whitelist of every resource the build will fetch. The project description puts it plainly: lockfiles are used as a trusted whitelist of resources to fetch packages from. The weakness is that lockfiles are written for machines to consume, so reviewing them by hand is not a realistic practice, and changes introduced to them are easy to miss. The specific attack the project names is a pull request that sneaks in a malicious resource package where a real library used to be. Nothing about the lockfile looks wrong to a reviewer skimming a diff of thousands of resolved lines. lockfile-lint exists to turn that review problem into a policy check, and it sits in the npm and yarn ecosystem specifically, which is why it appears in the nodejs and npm topic tags alongside lint and lockfile terms.

How the policy check reads a lockfile

The mechanism is deliberately simple. You point the tool at a lockfile path, you declare which hosts are permitted, and you require HTTPS for the resolved sources. Each resolved entry in the lockfile is compared against those rules, and anything that violates them is reported as an exception to the policy. The output contract is worth noting because it affects how you wire it into CI: if you get no results, the file passes. A silent run means success, so a CI step has to be written so that a non-zero exit is the failure signal rather than parsing text output. Two rule types exist. The host allowlist is about which registries a package is allowed to come from, and the HTTPS validation is about whether the resolved source uses a secure transport. Both are configured per invocation, which keeps the rule set next to the pipeline that enforces it rather than buried in a shared config file.

Running the first check with npx

The project is designed to be run without installing anything, since the usage section presents npx invocation on any project as the normal entry point. This checks a yarn lockfile against the npm and yarn hosts with HTTPS required:

npx lockfile-lint --path yarn.lock --allowed-hosts npm yarn --validate-https

The same check against an npm shrinkwrap file needs the type flag, because the file format differs:

npx lockfile-lint --path npm-shrinkwrap.json --type npm --allowed-hosts npm yarn --validate-https

Expect a clean run with no output when the lockfile complies, and a report of the offending entries when it does not. For more detail on the available flags, the usage section points at the CLI package page under packages/lockfile-lint, and the repository also ships a lockfile-lint.config.js file at the root, so a team with several repositories can settle on one policy file rather than repeating flags on every job.

A CLI package and an API package in one workspace

The repository ships two published npm packages, and the distinction matters when you integrate it. lockfile-lint is the CLI tool, and the usage section describes it as something that can be easily integrated as a pre-commit hook or part of a CI or build step. lockfile-lint-api is a library providing a programmatic API, for the case where you want the policy check inside your own tooling rather than as a subprocess. Internally the project is a monorepo: the root package.json declares workspaces at packages/*, and the scripts run through turbo, with lint and test mapped to turbo lint and turbo test. Versioning uses changesets, so a release is produced by changeset version and published by changeset publish. The npm packages for the CLI and the API have moved independently, with lockfile-lint-api at 5.10.0 and lockfile-lint at 5.0.1 in the recent release list, so pin the one you actually depend on rather than assuming the two share a version.

What the check cannot see, stated plainly

The project publishes a security disclaimer because a lockfile linter has limits that are outside of its control, and it is unusually direct about them. When you whitelist hosts such as npmjs, yarnpkg or github, you are implicitly conveying that you trust all the packages originating from those sources. A malicious package can exist inside a registry you have whitelisted, and lockfile-lint will report nothing about it, because it checks the source, not the contents. For that separate question the project points at npq as a tool for vetting direct dependencies before adding them. The other blind spot is that the check works on the lockfile as written, so it reports on what is committed rather than on what happens at install time, and a policy that allows the npm registry by definition permits anything published there. Read the tool as a guard against source substitution and unexpected host additions, not as a dependency security scanner.

pnpm lockfiles fall outside the model

The FAQ section addresses pnpm directly, and the answer explains why the tool does not cover it rather than simply omitting support. pnpm does not maintain the tarball source of an npm package, so unlike yarn and npm there is no way to inject an attacker-controlled malicious source file into pnpm-lock.yaml. Other vectors were explored, such as injecting new packages into the lockfile that are not in package.json, and pnpm is not prone to those attempts and would not install them. So the absence of a pnpm mode is a property of the format rather than a gap in the implementation. The project invites reports of possible pnpm attack vectors with reproducible steps. That reasoning also tells you what to check when you add a new registry or a private scope, since the attack model depends on the package manager resolving and recording source URLs at all.

Where lockfile-lint sits against npm audit

The comparison the project draws with npm audit is about scope, not quality. npm audit is a tool to audit dependencies for known vulnerabilities, and it does not address the issue of malicious packages being injected into a lockfile. lockfile-lint is designed specifically for that second case. Both tools are useful in a pipeline and they are not substitutes: audit looks up vulnerability data for the packages you depend on, while lockfile-lint checks where those packages are being fetched from. The distribution angle is the same, since a compromised dependency that is already in your lockfile can affect every consumer regardless of transport security, and an https-only rule will not catch it. The project also references the Secure Node.js Guidelines section on lockfile attacks and the pnpm and yarn lockfile injection issues as background reading, which is useful for understanding the concrete advisory this check is modelled on.

Apache-2.0, recent releases and the Node version floor

Maintenance and dependency cost are both visible in the repository. The last push was on 2026-10-09, the repository is not archived, and the release list shows lockfile-lint 5.0.0 on 2026-01-25, lockfile-lint 5.0.1 on 2026-08-13 and lockfile-lint-api 5.10.0 on 2026-10-09, so both packages are moving. The licence is Apache-2.0, which the README states directly, and it applies to the code rather than to the packages your project installs. The cost side sits in the root package.json, which sets an engines field requiring Node 24.0.0 or newer and npm 11.10.0 or newer. That floor is the real upgrade consideration for a team adding this to an older toolchain. The repository also ships SECURITY.md, CONTRIBUTING.md, RELEASE.md, AGENTS.md and a docs directory with a project document covering development, testing, architecture and conventions, so the project expects contributions rather than treating the CLI as a finished artifact.

Editorial conclusion

lockfile-lint earns a slot in any CI pipeline that commits a package-lock.json or yarn.lock, because a single npx call with an allowed-hosts list and --validate-https fails the build when a package source changes unexpectedly. It is the wrong tool for judging whether a dependency is safe to use, since whitelisting npmjs or yarnpkg means trusting everything published there, and it does not apply to pnpm lockfiles. Verify first that your own registry hostname is in the allowed list, that your project runs Node 24 or newer and npm 11.10 or newer per the package.json engines field, and that the lockfile-lint.config.js file at the repository root is where your team keeps the policy.

Frequently asked questions

Official sources

1. Issues
2. License: Apache-2.0
3. lirantal/lockfile-lint on GitHub
4. README
5. Releases