npm-guardian 🛡️

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

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

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. It does what no single tool does in one call — combines a known-vulnerability lookup with behavioural supply-chain detection:

• 🛡️ Known CVEs / GHSA advisories — cross-references the exact version against the OSV.dev database (Google's open-source vulnerability feed: CVEs, GitHub advisories, npm advisories and malware records) and tells you the precise fixed version to upgrade to. This is fact, not heuristic.
• 🎯 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 stop at CVE matches and won't catch a clean-versioned package that typosquats a popular name or downloads a remote script during installation. npm-guardian does the CVE check and the behavioural check in a single call — the full pre-install picture an agent needs.

🔬 Deep tarball inspection (the differentiator)

Metadata only tells you what the author declared. With deep mode, npm-guardian downloads the actual published .tgz, unpacks it in memory (no shell, no temp files, nothing executed) and scans the real source files for malicious patterns the manifest hides — plus it flags index-vs-tarball tampering (a package.json whose install scripts differ between the registry index and the shipped tarball, a known stealth technique). Most npm scanners never look inside the tarball; this one does.

It runs read-only: it inspects npm registry metadata, install-script source and (in deep mode) the published file contents. 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:

Tool	What it does
audit_npm_package	Audit a single package (name, optional version, optional deep for real-tarball inspection).
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, metadata audit, rate-limited (30/h/IP)
GET /audit_many?names=a,b,c           # FREE, up to 10 packages
GET /pro/audit?name=<pkg>             # PAID, DEEP tarball-source audit, no limit
GET /pro/audit_many?names=...         # PAID, DEEP, up to 50 packages

The free tier is a fast audit: registry metadata, typosquat detection and the known-CVE lookup (OSV.dev). The paid /pro/* tier adds the full deep tarball inspection (downloads and statically scans the real published files), the heavier, higher-signal check.

Free response (known-vulnerable version):

{
  "package": "lodash",
  "version": "4.17.20",
  "verdict": "SUSPICIOUS",
  "score": 25,
  "summary": "SUSPICIOUS — 5 known vulnerabilities for lodash@4.17.20. Review before installing. (fix available: upgrade to 4.17.21+)",
  "meta": { "knownVulns": 5, "hasInstallScripts": false, "repository": "git+https://github.com/lodash/lodash.git" },
  "knownVulns": [
    { "id": "CVE-2021-23337", "severity": "high", "summary": "Command Injection in lodash", "fixedIn": "4.17.21" },
    { "id": "CVE-2020-8203",  "severity": "high", "summary": "Prototype Pollution in lodash", "fixedIn": "4.17.19" }
  ]
}

💸 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 to the operator's wallet in USDC on Base (the network the x402 Bazaar and the bulk of paying agents use). 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:

Var	Default	Meaning
PORT	8080	HTTP port
X402_PAYTO	operator wallet	receiving address (public)
X402_NETWORK	base	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.

See also

import-guardian — the companion that works one step earlier: it reads a block of AI-generated code and flags hallucinated / slopsquatted imports (packages the model invented that don't exist on npm). Use import-guardian on freshly generated code, then npm-guardian to audit the packages you decide to keep.

license-guardian — the third guardian: it audits the licenses of your dependencies (GPL/AGPL copyleft, BUSL/SSPL source-available, unlicensed) against how you distribute, before you ship.

lockfile-guardian — the fourth guardian: it audits your resolved package-lock.json against the live npm registry, blocking integrity (sha512) mismatches (lockfile poisoning) and flagging new dependencies that run install or native node-gyp scripts.

License

MIT