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 and runs on your machine without
installing npm dependencies. A pinned MIT-licensed Acorn parser is bundled. Normal scans never execute package code.
Pre-install security for AI agents, npm packages, and MCP servers. Zero-dep local static analysis; normal scans never execute package code.
Real runs: guard clears [email protected], then blocks a sample modeled on the 2024 @solana/web3.js compromise.
Highlights
No npm dependency installation — local Node analysis with a bundled, pinned JavaScript parser.
Install approved bytes — pkgxray install scans the npm lockfile, installs held archives offline with scripts disabled, and verifies the resulting files.
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.
Adversarial gaps tracked openly — 200 additional synthetic cases track detected attacks and benign contrasts; this is internal testing, not an independent audit.
Regression gates — calibration and adversarial corpora run in CI; historical top-1000 results remain available for comparison.
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):
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:
Verdict
Exit
Meaning
SAFE
0
No high- or medium-risk indicators; default policy permits promotion.
REVIEW
3
Evidence is incomplete or a privileged capability needs human review.
BLOCK
2
High-severity cited evidence — reject or investigate.
SAFE is not a proof that a package is harmless; static analysis cannot see a
payload downloaded only at runtime. See the threat model.
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.
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
canaryexecutes 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
Verdict
You should
SAFE
No blocking findings within the reported checks. Review coverage before installing.
REVIEW
Inspect the quarantined copy before promoting.
BLOCK
Do not install. Every finding names the file and evidence.
Exit codes are stable and CI-friendly: 0 safe/allow · 2 block ·
3 review.
Usage
pkgxray guard npm:[email protected] [--format json] # vet a package before install
pkgxray guard pypi:[email protected] # same, for a PyPI package (sdist staged + scanned)
pkgxray mcp --package npm:[email protected] npx some-mcp-server # vet an MCP server; --recheck catches the rug-pull
pkgxray audit package-lock.json [--deep-all] # 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
audit checks resolved dependencies against OSV. --deep adds source scans for
blocked dependencies; --deep-all requests source scans for all resolved dependencies.
Failed deep scans and incomplete source collection return REVIEW unless already BLOCK.
guard --deps includes direct-dependency findings in its decision; only exact pins
are checked, with ranges and other unresolved sources left at REVIEW. Guard output
lists completed, partial, disabled and failed checks so a passing verdict does not
imply checks that never ran.
PyPI scans cover source-distribution manifests, vulnerability metadata, and text-level
injection checks; they do not provide full Python module behavioral analysis or wheel inspection.
Python source adds an unsupported-behavior REVIEW finding. Behavioral coverage gaps
cannot be muted or promoted with allow-review; a pinned artifact approval remains
an explicit operator override. Archives containing links or special files are rejected.
One optional .pkgxray.json tunes policy on the Node-based surfaces. The browser
extension scans supplied evidence using engine defaults and cannot read project configuration. 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.
Where
What it does
Guide
Coding agents — Codex, Claude Code, Cursor, Windsurf
Gate installs and expose the audit tools to the agent
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
Historical top-1000 runs and their scope and methodology
remain available at pkgxray.ca/stats. Those results
predate the parser-based flow engine and have not been rerun for this change.
The current engine passes all 270 internal synthetic calibration/challenge
fixtures without a malicious SAFE or benign BLOCK; many malicious cases produce
REVIEW. This is regression evidence, not a real-world detection-rate estimate.
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.
P
Pkgxray
adamsjack711-ux·12 スター·
Pre-install security for AI agents, npm packages, and MCP servers. Zero-dep local static analysis; normal scans never execute package code.
最終チェックは 2026-11-05 です。 Pre-install security for AI agents, npm packages, and MCP servers. Zero-dep local static analysis; normal scans never execute package code.