pkgxray — Analyze packages before you install them

The 30-second version

What pkgxray actually does

Three things, in order, every time you point it at a package.

01 · Read

Ask what the code does

CVE scanners answer "any known bug?". pkgxray reads the tarball's bytes for credential access, exfiltration, obfuscated payloads, install hooks, and persistence — including in a package nobody has reported yet.

02 · Cite

Point at the evidence

Every finding names a file and a line. The verdict path is deterministic heuristics — there is no LLM in it, so text planted in a README can't argue its way to a pass.

03 · Gate

Decide before install

The package sits in quarantine and is promoted only if policy allows. Exit 0, 2, or 3 wires straight into CI, an install hook, or an agent's tool call.

The threat

npm is the primary target for open-source malware.

Agents install packages and connect to MCP servers at machine speed. The registry they pull from is under industrial-scale attack. Pick a number for the detail behind it.

npm shipped 7.97 trillion downloads in 2025 — about 21.8 billion a day.

That is over 80% of all traffic across npm, PyPI, Maven Central, and NuGet combined. The registry holds 5.59 million packages and shipped 11.18 million new releases last year.

Sonatype 2026 State of the Software Supply Chain. npm downloads up 65% year over year.

Source: Sonatype: software infrastructure growth

CVE scanners find known bugs. pkgxray asks what the code does — before a single line runs on your machine.

Sources for these figures

Each figure links to its supporting report from the panel above. Sources include Sonatype's 2026 State of the Software Supply Chain, its open-source malware chapter and Q4 2025 OSS Malware Index, Palo Alto Networks' incident analysis, and NimbleBrain's MCP registry analysis.

Calibration · scanned 2026-07-21

So how often does it call it right?

We ran the scanner over 5,000 published packages — code only, no execution — read every block by hand, and measured recall against a committed, reconstructed known-malware corpus.

5,000

packages scanned

top-1,000 list + 4,000 deeper sweep, one static pass

0

false blocks, top 1,000

14 found and fixed in the next 4,000

20 of 21

corpus samples blocked

0 passed as safe

Full calibration & methodology →

Live demo

Watch a verdict form

Pick a package. This demo replays real fixtures — it does not download or execute anything in your browser.

Choose a package

pkgxray guard

Three verdicts. Stable exit codes.

Click a verdict to see what it means for install, CI, and agents.

No high- or medium-risk indicators. Default policy promotes out of quarantine. Install. Exit code 0.

Real terminal recording — express clears, then a corpus trojan is blocked with cited evidence.

Coverage

What it catches

Deterministic heuristics — no LLM in the verdict path, so injected text can't steer them.

detected
partial / indirect

Code & payloads

Obfuscation — detected packed blob + computed-arg execution; minification alone is deliberately not flagged
Base64 payloads — detected encoded envelopes in docs/comments; blobs decoded into computed-arg eval / new Function / child_process
Unicode smuggling — detected invisible tag-block characters + Trojan Source bidi / zero-width
Prompt injection — detected tiered detection in docs, comments, metadata; deterministic verdict path can't be steered

Secrets & persistence

Credential theft — detected reads of .ssh / .aws / .npmrc / .env / keychains / wallets, incl. split-fragment paths (".s"+"sh")
Exfiltration & loaders — detected cross-file correlation: stage-2 loaders, curl | sh, process.env harvesting near a network sink
Persistence — detected writes to shell rc files, cron, launch agents

Supply-chain integrity

Known CVEs — detected OSV batch pre-check before download; never mutable by config
Trojaned updates / takeover — detected recheck verdict-drift + version-drift monitoring
Artifact divergence — detected published npm tarball diffed against the tagged GitHub source
Dependency confusion / typosquats — partial callback beacons, repo- and provenance-mismatch signals; no name-similarity heuristic

Agents & MCP

MCP capability abuse — detected capability-surface mismatch in the manifest audit (a get_weather that also takes a command)
Runtime tool drift — detected mcp-proxy re-audits on tools/list_changed; pinned-manifest drift is denied
Sequence-level tool-call chains — partial mcp-proxy gates each call and scans results; no cross-call flow analysis

Known blind spot

A package that downloads its real payload after install can ship a clean tree — pair pkgxray with runtime sandboxing when that risk matters. Full threat model →

Surfaces

One engine. Every surface.

CLI, MCP, install hook, and CI all share the same policy and the same evidence rules — four commands cover the lot.

guard
Quarantine a package, audit bytes, promote only if allowed.
mcp
Vet a server before connect — most public MCP servers ship with static keys and little verification.
hookshot
Intercept agent npm install with a cited deny.
recheck
Catch trojaned updates against a stored baseline.

Where pkgxray fits

One engine, wherever packages enter your stack. Each path has a setup guide in the repo.

Coding agents

Gate package installs before an agent runs them — Codex, Claude Code, Cursor, Windsurf.

Coding-agent guide →

MCP

Audit a server's package and declared capabilities before connecting; gate live traffic with mcp-proxy.

MCP guide →

CI/CD

Fail builds when a dependency crosses policy; scan the whole lockfile and re-vet on a schedule with recheck.

GitHub Actions guide →

Developers

Inspect an npm package before installation — one command, a cited verdict, no account.

Try it →

Comparison

How pkgxray compares

Run it alongside npm audit and OSV-Scanner, not instead of them — they answer "known CVE?". The comparison that matters is against tools in the same lane: behavioral supply-chain vetting.

Capability	Socket.dev	OpenSSF Pkg Analysis	Cisco MCP Scanner	pkgxray
Fully local, zero-dependency, no account or cloud upload	—	◑	◑	✅
Static behavior analysis of package code	✅	✅	✅	✅
Sandboxed execution (dynamic analysis)	—	✅	◑	◑ opt-in `canary`
npm ↔ GitHub artifact divergence	unknown	—	—	✅
Deterministic verdict path — no LLM an injection can steer	—	✅	◑	✅
Pre-install gate with a quarantined copy to review	◑	—	—	✅
MCP server vetting before connect	—	—	✅	✅
Per-call runtime gating of live MCP traffic	—	—	—	✅ `mcp-proxy`
Verdict-drift monitoring vs. a stored baseline	✅ cloud	—	—	✅ local `recheck`

How to read this table · last reviewed 2026-07-21

Last reviewed against public documentation: 2026-07-21 (re-reviewed every 60–90 days). A — means no equivalent capability was found in the public documentation reviewed on that date — not that it was tested and found absent; unknown means not publicly documented either way.

Full per-tool notes: comparison.md →

Install

Scan your first package

Lowest friction first contact — no global install, no account, no upload. Click a line to copy it.

Try it once

Keep it around

Give it to your agent

MIT · Node ≥ 18 · zero runtime dependencies.