lockfile-guardian 🔒

Audit your package-lock.json for supply-chain attacks BEFORE you run npm install.

npx -y lockfile-guardian-mcp   # MCP server, ready for Claude / Cursor / any agent

Your lockfile is the artifact npm install actually executes — the fully resolved dependency tree, with integrity hashes and install-script flags. lockfile-guardian cross-checks every resolved entry against the live npm registry and tells you what is about to run on your machine.

It completes the guardian trio — each one audits a different layer:

• import-guardian — catches hallucinated imports in AI-generated code (a name the model invented).
• npm-guardian — audits a chosen package for CVEs and malicious behaviour.
• license-guardian — audits the licenses of your dependencies (AGPL/BUSL traps) before you ship.
• lockfile-guardian (this) — audits the resolved tree in your package-lock.json.

What it catches

🔴 Integrity mismatch	the lockfile's sha512 doesn't match what npm serves for that exact version — the resolved tarball was swapped under you (lockfile poisoning). BLOCK.
🔴 Not on registry	the lockfile points at a package/version that doesn't exist or was unpublished. BLOCK.
🟠 New install script	a newly-introduced dependency that runs preinstall/install/postinstall — a first-seen dep with an install script is the Axios / plain-crypto-js attack signal. REVIEW.
🟠 Hidden gyp build	native build via binding.gyp / node-gyp, which executes code on install and dodges plain postinstall monitoring. REVIEW.
🟠 Fresh + executing	a version published in the last 30 days that runs an install script — disproportionately used in supply-chain attacks. REVIEW.

Verdicts: 🟢 CLEAN · 🟠 REVIEW · 🔴 BLOCK.

PR-diff mode (the differentiator)

Pass the previous lockfile too and lockfile-guardian audits only what the change introduces. A first-seen dependency that runs an install script is the single highest-signal supply-chain tell — this surfaces it in one call, exactly where a code-review or CI gate needs it.

It runs read-only: it parses the lockfile and reads npm registry metadata. It never installs or executes anything.

Use it as an MCP server (free)

Any MCP-compatible agent (Claude Desktop, Claude Code, Cursor, …) can call it.

{
  "mcpServers": {
    "lockfile-guardian": { "command": "npx", "args": ["-y", "lockfile-guardian-mcp"] }
  }
}

Tools:

• audit_lockfile — give it a package-lock.json (and optionally the previous one); get a CLEAN / REVIEW / BLOCK verdict per package.
• check_install_scripts — for an explicit list of packages, report which run install / native-build scripts (live registry manifest).
• verify_integrity — verify one pinned package: integrity match, install scripts, version age.

Free HTTP API

POST /audit    { "lockfile": "{…package-lock.json…}", "previous_lockfile": "{…}" }
POST /scripts  { "names": ["sharp@0.33.0","esbuild","node-sass"] }
GET  /verify?name=lodash&version=4.17.21&integrity=sha512-...
POST /mcp                                              # MCP-over-HTTP

Hosted at https://lockfile-guardian.vercel.app · try /verify?name=esbuild&version=0.21.5 (runs a postinstall) vs /verify?name=lodash&version=4.17.21 (clean).

Pay-per-call (x402)

The /pro/* routes are gated by x402. Your agent pays $0.02 USDC per call automatically — no sign-up, no API key. Settles on-chain to the operator wallet (Base). The server holds no private key.

POST /pro/audit   { "lockfile": "...", "previous_lockfile": "..." }   # 402 → pay → result

How the moat works

A coding agent reading the lockfile alone cannot know:

• whether the recorded sha512 still matches what npm serves for that version (an integrity mismatch is invisible without the live registry),
• whether a pinned version actually declares install/native-build scripts in its published manifest (the lockfile's hasInstallScript can be absent or stale),
• how old that exact version is.

lockfile-guardian fetches the live per-version manifest and integrity from the registry and applies a curated set of 2026 supply-chain rules. That's data + rules the model can't fabricate.

---

MIT · Part of the guardian trio. Issues and PRs welcome.