locksift
Exact, local review of dependency lockfiles, as three Hermes tools.
A one-line dependency bump can rewrite thousands of lockfile lines: entries
reorder, hashes churn, packages move between nesting levels. That diff is
unreadable in review, and it is exactly where a supply-chain change hides: a
package that now comes from a git URL, a checksum that changed under the same
version, a new install script. locksift reads both versions of the lockfile and
returns the dependency changes themselves.
| ecosystem | lockfiles |
|---|---|
| npm | package-lock.json / npm-shrinkwrap.json (lockfileVersion 1-3, both sections of v2), pnpm-lock.yaml (5.x, 6, 9, including pnpm 11+'s env document), yarn.lock (v1 and Berry) |
| Python | uv.lock, poetry.lock (1.x and 2.x), Pipfile.lock |
| Rust | Cargo.lock |
| PHP | composer.lock |
| Ruby | Gemfile.lock |
| Go | go.sum |
The format is detected from the content. locksift never runs git or a package
manager: you pass the files. To get the base version of a lockfile:
git show origin/main:package-lock.json > /tmp/base-package-lock.json
Why a tool and not a prompt or skill
-
The real change, not the text change. Real output on two versions of
Hermes' ownuv.lock(354 packages, 9.6 MB):{"counts": {"added": 0, "removed": 1, "upgraded": 5, "major_upgrades": 2}, "upgraded": [{"name": "filelock", "from": "3.32.7", "to": "4.2.6", "major": true}, {"name": "setuptools", "from": "83.0.0", "to": "84.1.0", "major": true}, {"name": "tornado", "from": "6.5.10", "to": "6.6"}, ...], "removed": [{"name": "tenacity", "versions": ["9.2.1"]}], "signals": {}} -
Supply-chain signals. Each installed copy is compared with its
counterpart (the same install path, or the same name and version), never with
a pool of all copies.signalslists:source_changed: what changed (kind,host,aliasorref) and from
what to what. That covers registry to git or a URL; another registry host,
including a package moving from a private registry to the default one at a
new version; a different tarball, git commit or URL at the same version; and
an alias ("foo": "npm:bar@1") that now names a different real package, in
npm, pnpm and Yarn.same_version_checksum: the same version with a changed checksum, a new
artifact (a uv wheel, a Poetry file or a Pipfile hash), a removed checksum,
or a weaker algorithm (sha512 to sha1).new_install_scripts: a package that runs install scripts and did not in
any earlier version. This includes a new Composer plugin. Formats that do
not record scripts are named innotes.new_non_registry: new git, URL and local-path packages.new_registry_hosts: registries the lockfile never used before, including
sources a Pipfile or Gemfile declares.sections_disagree: npm lockfileVersion 2 keeps two copies of the tree:
packagesfor npm 7+ anddependenciesfor npm 6. Their versions, URLs
or checksums disagree.
source_changedalso covers:- a local patch added or changed (pnpm
patchedDependencies, Yarnpatch:); - a registry package replaced by a local project of the same name (a Cargo
[patch]path, an npm link, a uv editable); - a git dependency whose commit changed. The same commit spelled differently
(github:o/r#sha,git+ssh://…/o/r.git#sha, a codeload URL) is not a change.
It does not cry wolf on churn:
- A format change is not a checksum change:
sha1becomingsha512, or a new
Yarn cache key. - A field only one lockfile records is not compared, so moving from Yarn v1
to Berry is quiet. registry.yarnpkg.comandregistry.npmjs.orgare the same registry, as
are crates.io's two index URLs.- On 74 real version-to-version diffs of the lockfiles in the test corpus, the
only signals are two real ones: a pnpm patch and a Yarn patch added by the
project.
What it does not detect
A quiet diff means none of the signals above fired. It does not mean nothing
risky changed:
-
Compromised code published to the registry under a new version looks like
an ordinary upgrade. Checksums vouch for bytes, not intent. -
Registries are compared by host. A different project or tenant on the same
host (two GitLab package registries, for example) is not told apart. -
Some formats do not record install scripts: pnpm 9, Yarn Berry, uv, Poetry,
Pipfile, Cargo build scripts and go.sum.notesnames them. -
Cargo.lock does not distinguish a workspace member from a path dependency, so
a brand-new path crate is not reported (a registry crate replaced by one is). -
Only the lockfile is read. A change made only in
package.json,
pyproject.tomlor.npmrc(a registry setting, say) is outside it. -
Why is this installed?
lock_whyfollows the lockfile's own dependency
graph, with npm's nestednode_modulesresolution, pnpm peer suffixes,
Yarn ranges and PEP 503 names. It returns the chains from a direct
dependency or workspace project down to a package:{"version": "3.20", "required_by": [{"by": "httpx@0.28.1"}, {"by": "requests@2.34.2"}, ...], "chains": [["project hermes-agent", "httpx@0.28.1", "idna@3.20"], ...]}
Tools
All three always return a JSON string. A bad path or a file that is not a
lockfile returns { "ok": false, "error": "..." } rather than raising.
lock_summary
| arg | type | required | default | meaning |
|---|---|---|---|---|
path | string | yes | - | lockfile |
max_items | integer | no | 50 | entries per list (cap 1,000) |
Returns:
packages(unique name and version) andnames.direct_dependenciesandworkspace_projects, when the lockfile records them.dev_only.multiple_versions: names locked at several versions.non_registry: git, URL and local-path packages, with their host and ref.registry_hosts: installed copies per host.aliases,install_scripts, andregistry_without_checksum.- For
go.sum,go_mod_only: modules recorded only for theirgo.mod.
lock_diff
| arg | type | required | default | meaning |
|---|---|---|---|---|
base | string | yes | - | the older lockfile |
head | string | yes | - | the newer lockfile (same ecosystem) |
max_items | integer | no | 50 | entries per list (cap 1,000) |
Returns:
counts.added,removed,upgradedanddowngraded, each with amajorflag when
the breaking part of the version changed (X for X.y.z, 0.Y for 0.y.z, 0.0.Z
for 0.0.z).versions_changed: names locked at several versions where the set changed.direct: added and removed direct dependencies, when recorded.signals.
Version order follows:
- semver for npm, Cargo, Composer and Go:
2.0.0-1 < 2.0.0, and
1.0.0-alpha < 1.0.0-alpha.1 < 1.0.0-beta. A Go pseudo-version is a
pre-release of its base version. - PEP 440 for Python:
1.0rc1 < 1.0 < 1.0.post1 < 1.0.1. - RubyGems for Ruby.
A version that is not a version, such as a git commit, has no direction: the
change is listed under versions_changed.
lock_why
| arg | type | required | default | meaning |
|---|---|---|---|---|
path | string | yes | - | lockfile |
package | string | yes | - | package name (@babel/core, requests, serde, ...) |
version | string | no | - | only this locked version |
max_paths | integer | no | 5 | chains per version (cap 50) |
Returns every locked version of the package, each with:
sourceandrequired_by(the dependent and the requested range);- the shortest
chainsfromproject <name>(a direct dependency) down to it; direct_in, when it is a direct dependency.
Some lockfiles do not record the project's direct dependencies: npm v1, Yarn,
Poetry and Composer. There a chain starts at a package nothing else requires,
and notes says so. Pipfile.lock and go.sum have no dependency graph, so
only whether the package is locked is returned.
Safety
- Read-only. It reads only the lockfile paths you pass, and only regular files
up to 256 MiB. - No network, no credentials, no subprocess (it never runs git or a package
manager), no background work, no self-update. Standard library only
(json,tomllib). pnpm and Berry YAML is read by a small reader that
accepts only the YAML those tools write: anchors, tags and multi-line
scalars are refused. - Checksums are compared, never echoed in full.
- Honours Hermes' core read denylist (credential stores, project
.envfiles,
NT/device namespace paths). The path is checked as given and as an absolute
path before anything is opened. Device, fd and/procpaths are refused,
also through symlinks.
Install
hermes plugins install rodricksz4h5/locksift --enable
License
MIT
README from the reviewed commit 1f09443; it updates when the author re-pins.

rodricksz4h5