# npm-guardian 🛡️

**Vet an npm package for supply-chain attacks BEFORE you run `npm install`.**

`npm-guardian` is a security tool for AI coding agents and developers. Give it a
package name and it returns a **SAFE / SUSPICIOUS / DANGEROUS** verdict with an
explained risk score — catching the attacks that ordinary `npm audit` and CVE
scanners completely miss:

- 🎯 **Typosquatting** — names one or two edits away from popular packages
  (`lodahs` → `lodash`, `expres` → `express`, the 2026 `easy-day-js` → `dayjs` campaign).
- 💀 **Malicious install scripts** — `preinstall`/`postinstall` hooks that pipe
  remote downloads into a shell, spawn child processes, `eval()`, or decode
  base64 droppers.
- 🔑 **Credential & crypto-key exfiltration markers** — scripts that read
  `AWS_*`/`GITHUB_*`/`NPM_TOKEN`/`PRIVATE_KEY` env vars or touch `~/.ssh`,
  `~/.aws`, `.npmrc`, `id_rsa`, `wallet.dat`.
- 🆕 **Freshly-published, low-trust packages** — disproportionately used in
  supply-chain attacks, especially when combined with install scripts.
- 🚫 **Dependency-confusion / not-on-registry** + missing source repo, no
  maintainers, deprecated, etc.

> Traditional vulnerability scanners look for CVE matches in manifests and
> **won't catch a clean-versioned package that downloads a remote script during
> installation.** That's exactly the gap `npm-guardian` fills.

It runs **read-only**: it inspects npm registry metadata and install-script
*source strings*. It never executes package code.

---

## Use it as an MCP server (free)

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

```json
{
  "mcpServers": {
    "npm-guardian": {
      "command": "npx",
      "args": ["-y", "npm-guardian-mcp"]
    }
  }
}
```

Tools exposed:

| Tool | What it does |
|------|--------------|
| `audit_npm_package` | Audit a single package (`name`, optional `version`). |
| `audit_many` | Audit a whole dependency list at once. |

Example agent prompt: *"Before you install `chalk`, run npm-guardian on it."*

---

## Use it as an HTTP API

```
GET /audit?name=<pkg>&version=<v>     # FREE, rate-limited (30/h/IP)
GET /audit_many?names=a,b,c           # FREE, up to 10 packages
GET /pro/audit?name=<pkg>             # PAID per call, no limit
GET /pro/audit_many?names=...         # PAID per call, up to 50 packages
```

Free response:

```jsonc
{
  "package": "expres",
  "verdict": "SUSPICIOUS",
  "score": 40,
  "summary": "SUSPICIOUS — Possible typosquat of \"express\". Review before installing.",
  "findings": [ { "severity": "critical", "title": "Possible typosquat of \"express\"", "detail": "…" } ],
  "meta": { "publishedAgeDays": 4723, "hasInstallScripts": false, "repository": "…" }
}
```

### 💸 Pay-per-call with x402 (USDC, no account, no API key)

The `/pro/*` routes are gated by the [x402](https://x402.org) payment protocol.
Your AI agent pays **$0.02 USDC** per call automatically — no sign-up, no API
key, no subscription. Settlement is on-chain (Polygon) straight to the operator's
wallet on **Base** (USDC). The server holds **no private key**; it only declares
a public receiving address.

Calling `/pro/audit` without payment returns the standard `402 Payment Required`
challenge, which any x402-aware client (e.g. `@x402/axios`, x402 MCP clients)
satisfies transparently.

---

## Run it yourself

```bash
npm install
npm run build

# MCP (stdio)
npm run start:mcp

# HTTP API
PORT=8080 npm run start:http
```

Environment variables for the HTTP server:

| Var | Default | Meaning |
|-----|---------|---------|
| `PORT` | `8080` | HTTP port |
| `X402_PAYTO` | operator wallet | receiving address (public) |
| `X402_NETWORK` | `polygon` | x402 settlement network |
| `X402_PRICE` | `$0.02` | price per paid call |
| `X402_FACILITATOR_URL` | – | facilitator that settles on your network |
| `X402_ENABLED` | `true` | set `false` to disable paid routes (all free) |

---

## Why this exists

2026 has been a brutal year for npm supply-chain attacks: typosquatted
OpenSearch/Elastic packages stealing CI/CD secrets, the `@mastra` org
compromise that backdoored 140+ packages via an `easy-day-js` typosquat, waves
of infostealers hidden in `postinstall` hooks. Agents now `npm install` things
autonomously — they need a cheap, fast pre-flight check. That's `npm-guardian`.

## License

MIT