pkgxray — pre-install security for npm packages, MCP servers, and AI agents

Inspect an npm package or MCP server before you install or connect to it, and get a deterministic, evidence-backed SAFE, REVIEW, or BLOCK verdict. Local, zero-dependency static analysis — normal scans never execute package code.

Website · Documentation · Calibration · Report a bug

_{Real runs: guard clears express@4.21.0, then blocks a sample modeled on the 2024 @solana/web3.js compromise.}

Highlights

• Zero runtime dependencies — pure Node, runs entirely on your machine (~25 ms static pass).
• Normal scans never execute package code — the tarball is read as bytes in quarantine.
• Deterministic, cited verdicts — every finding names the file and evidence; no LLM in the verdict path, so injected text can't steer it.
• Built for the agent era — vet MCP servers before connect, gate the installs an agent runs, and re-audit live MCP traffic.
• Calibrated and regression-gated — zero heuristic false blocks on the top-1000 most-downloaded packages, enforced in CI.

1. Quick start · 2. What it scans & detects · 3. Verdicts · 4. Usage · 5. Integrations · 6. How it compares · 7. Documentation

Why

AI coding assistants install packages and connect to MCP servers at machine speed, often without a human reading the code. Sonatype identified more than 454,600 new malicious open-source packages across monitored ecosystems in 2025, over 99% of them on npm (Sonatype). npm audit asks does this have a known CVE?; pkgxray also asks what does the code actually do — before anything installs.

Quick start

1. Scan a known-benign package (no install of pkgxray needed):

npx --yes pkgxray@1.0.5 guard npm:express@4.21.0

It stages the tarball in quarantine and runs the static and supply-chain checks — no npm install, no lifecycle scripts, no package code executed.

Decision: SAFE   Grade: A+ (99/100)
No high- or medium-risk indicators were found in the provided evidence.

Notes:
- INFO npm-vs-github-clean — npm tarball matches the linked GitHub repo at the
  published version. (15/16 files match GitHub @4.21.0)

2. Read the verdict:

SAFE is not a proof that a package is harmless; static analysis cannot see a payload downloaded only at runtime. See the threat model.

3. See a BLOCK on the supplied inert fixture:

npx --yes pkgxray@1.0.5 --file examples/onboarding-malicious.json --format markdown

The fixture is inert source text modeling a split-string SSH-key read and exfiltration — it is never executed. It returns BLOCK (exit 2) with the cited file and evidence.

4. Add it to your workflow — rechecks & CI, MCP, Hookshot install gate.

Two execution models. Default guard and audit scans are static — package code is never executed. Enumerating an MCP server may spawn it and mcp-proxy runs it behind a gate; the opt-in canary is the one deliberate exception that executes the package in a sandbox to confirm behavior — it can confirm malice but never prove a package safe. Full boundary: SECURITY.md.

What it scans & detects

Scans — pkgxray guard npm:name@version, github:owner/repo, a local directory, whole lockfiles (npm, yarn, pnpm), MCP servers, and AI-agent extensions.

Detects — credential theft (incl. split-fragment paths), cloud instance-metadata and secret-store harvesting, prompt injection, Unicode smuggling, base64 payloads and stage-2 loaders, exfiltration, persistence (shell profile, OS scheduler, and injected CI/CD workflows), self-deleting droppers, registry worm replication (install-time npm publish), obfuscated computed-arg execution, known CVEs (via OSV, before download), npm↔GitHub artifact divergence, trojaned updates (recheck), and MCP capability-surface abuse.

The full coverage matrix — and the known download-later blind spot — is in the threat model; a side-by-side comparison table is on the website.

Verdicts

Exit codes are stable and CI-friendly: 0 safe/allow · 2 block · 3 review.

Usage

pkgxray guard npm:some-package@1.2.3 [--format json]   # vet a package before install
pkgxray mcp --package npm:some-mcp-server@1.4.2 npx some-mcp-server   # vet an MCP server; --recheck catches the rug-pull
pkgxray audit package-lock.json [--deep]               # also: yarn.lock, pnpm-lock.yaml, package.json
pkgxray recheck package-lock.json                      # scheduled: non-zero only on a regression

One optional .pkgxray.json (read by every surface) tunes policy; zero config means maximum strictness. CVEs can never be allowed away, every loosening is printed, and a scan that errors fails closed to review. Schema and invariants: configuration.md · .pkgxray.example.json.

Integrations

One engine behind every entry point. "Works with" means a documented setup guide, not a vendor-endorsed integration.

How it compares

Run pkgxray alongside npm audit / OSV-Scanner, not instead of them — they answer "known CVE?". Against tools in the same lane (behavioral supply-chain vetting — Socket.dev, OpenSSF Package Analysis, Cisco MCP Scanner), the full capability comparison is in docs/comparison.md and on the website.

Evidence

The zero-heuristic-false-block calibration on the top-1000 most-downloaded packages is regression-gated in CI (scope & methodology), and the published runs live at pkgxray.ca/stats. That claim is scoped to the most-installed set — not a claim of zero false blocks on every package.

Documentation

Start at the documentation index.

Contributing

npm test                 # zero-dep node --test suite
npm run benchmark        # calibration corpus: precision/recall + 0-false-block gate
npm run validate:website # regenerate + validate the calibration pages

Pull requests are welcome — read CONTRIBUTING.md and the Code of Conduct. Report vulnerabilities privately per SECURITY.md. Releases publish to npm with provenance (SLSA attestation), gated on tests, the calibration benchmark, and pkgxray's own supply-chain guard.