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

Inspect an npm package or MCP server before you install it or connect to it. You get a SAFE, REVIEW, or BLOCK verdict, decided by fixed rules and backed by cited evidence. The analysis is static, runs on your machine, and has no dependencies. Normal scans never execute package code.

Website · Documentation · Calibration · Report a bug

pkgxray guard clearing express@4.21.0 with a SAFE A+ verdict, then blocking a trojaned sample with a BLOCK F verdict and a HIGH credential-access finding

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

Highlights

• No runtime dependencies — pure Node, and it all runs on your machine (~25 ms static pass).
• Normal scans never execute package code — the tarball is read as bytes in quarantine.
• Cited verdicts from fixed rules — every finding names the file and the evidence. No model decides the verdict, so text planted in a package cannot steer it.
• Built for the agent era — check MCP servers before you connect, gate the installs an agent runs, and re-audit live MCP traffic.
• Calibrated, with a CI gate against regressions — zero heuristic false blocks on the top-1000 most-downloaded packages.

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 quickly, and often no person reads the code first. Sonatype counted more than 454,600 new malicious open-source packages across monitored ecosystems in 2025, over 99% of them on npm (Sonatype). npm audit asks whether a package has a known CVE. pkgxray also asks what the code does, 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. There is no npm install, no lifecycle script, and 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 that models 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, so package code is never executed. Three surfaces are different: listing an MCP server's tools may spawn it, mcp-proxy runs it behind a gate, and the opt-in canary executes the package in a sandbox to confirm what it does. The canary can confirm that a package is malicious, but it can never prove one is safe. Full boundary: SECURITY.md.

What it scans & detects

Scans — pkgxray guard npm:name@version or pypi:name@version, github:owner/repo, a local directory, whole lockfiles across two ecosystems (npm: package-lock.json, yarn.lock, pnpm-lock.yaml, package.json; PyPI: requirements.txt, poetry.lock, Pipfile.lock, pyproject.toml), 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), npm install-hook and PyPI setup.py install-time execution, obfuscated computed-arg execution, hallucinated / slopsquat names (a lockfile pin the registry never published), known CVEs (via OSV, before download), npm↔GitHub artifact divergence, trojaned updates (recheck), and MCP capability-surface abuse.

The full coverage matrix is in the threat model, along with the known blind spot: a package that downloads its payload later. 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 guard pypi:some-package@1.2.3                  # same, for a PyPI package (sdist staged + scanned)
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 audit requirements.txt [--deep]                # PyPI: also poetry.lock, Pipfile.lock, pyproject.toml
pkgxray recheck package-lock.json                      # scheduled: non-zero only on a regression

One optional .pkgxray.json tunes policy, and every surface reads it. No config means the strictest settings. Config can never allow a CVE away, every loosening is printed, and a scan that errors fails closed to review. Schema and rules: 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

npm audit and OSV-Scanner check for published CVEs, and pkgxray does not replace them. Run it alongside them. The tools in the same lane are Socket.dev, OpenSSF Package Analysis, and Cisco MCP Scanner, which also analyze what package code does. The full capability comparison is in docs/comparison.md and on the website.

Evidence

pkgxray records zero heuristic false blocks on the top-1000 most-downloaded packages, and CI gates against a regression (scope and methodology). The published runs live at pkgxray.ca/stats. The claim covers the most-installed set only. It is 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 first. Report vulnerabilities privately, as SECURITY.md describes. Releases publish to npm with provenance (SLSA attestation), and each one is gated on the tests, the calibration benchmark, and pkgxray's own supply-chain guard.