# lockfile-guardian 🔒

[![npm](https://img.shields.io/npm/v/lockfile-guardian-mcp.svg)](https://www.npmjs.com/package/lockfile-guardian-mcp)
[![license](https://img.shields.io/npm/l/lockfile-guardian-mcp.svg)](./LICENSE)
[![MCP](https://img.shields.io/badge/MCP-server-blue)](https://modelcontextprotocol.io)

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

```bash
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**](https://github.com/Baneado98/import-guardian) — catches *hallucinated* imports in AI-generated code (a name the model invented).
- [**npm-guardian**](https://github.com/Baneado98/npm-guardian) — audits a *chosen* package for CVEs and malicious behaviour.
- [**license-guardian**](https://github.com/Baneado98/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.

```json
{
  "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`](https://lockfile-guardian.vercel.app/verify?name=esbuild&version=0.21.5)
(runs a postinstall) vs
[`/verify?name=lodash&version=4.17.21`](https://lockfile-guardian.vercel.app/verify?name=lodash&version=4.17.21)
(clean).

## Pay-per-call (x402)

The `/pro/*` routes are gated by [x402](https://x402.org). 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.