GitHub - adamsjack711-ux/pkgxray: Supply-chain security for AI agents, npm packages, and MCP servers. Analyze packages before you install them — zero-dep Node, runs locally, never executes untrusted code.

pkgxray — pre-install security for npm packages, MCP servers, and AI agents. Use local, zero-dependency package static analysis to inspect npm packages and Model Context Protocol (MCP) servers before installation or connection. pkgxray reports cited SAFE, REVIEW, or BLOCK evidence without executing package code during normal scans.

Static analysis · Supply-chain intelligence · Prompt-injection detection · MCP security · SAFE / REVIEW / BLOCK Real runs: guard clears express@4.21.0, then blocks a sample modeled on the 2024 @solana/web3.js compromise. ▶ 60-second walkthrough

Quick start 1. Scan a known-safe package without installing pkgxray npx --yes pkgxray@1.0.4 guard npm:express@4.21.0 This downloads pkgxray through npm's temporary npx cache, stages the target tarball in quarantine, and performs the static and supply-chain checks. It does not globally install pkgxray, run npm install, execute lifecycle scripts, or execute package code. 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) …

Real output, abridged. A BLOCK verdict instead lists every finding with the file and evidence that produced it. 2. Read the verdict Point it at a package, get a verdict with cited evidence — before a single line of that package runs. guard stages the package in a sandboxed quarantine, audits the staged copy, and only promotes it when policy allows. It never runs npm install, lifecycle scripts, build steps, or package code.

Verdict Exit Meaning

SAFE 0 No high- or medium-risk indicators were found; default policy permits promotion.

REVIEW 3 Evidence is incomplete or a privileged capability needs human review.

BLOCK 2 High-severity cited evidence requires rejection or deep investigation.

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 From a repository checkout: npx --yes pkgxray@1.0.4 --file examples/onboarding-malicious.json --format markdown The fixture contains inert source text that models a split-string SSH-key read and network exfiltration. It is never executed. The command returns BLOCK (exit 2) and cites the matching file and evidence. 4. Add it to your workflow

Scan pull requests and schedule dependency rechecks. Expose pkgxray's tools to an MCP-capable coding agent. Evaluate the experimental Hookshot install gate.

Why pkgxray? AI coding assistants install packages and connect to MCP servers at machine speed, often without a human ever reading the code. Sonatype reported 454,648 newly identified malicious open-source packages across monitored ecosystems in 2025. Its Q4 report counted 394,877 in that quarter and said 99.8% of Q4 malware originated from npm (annual figure; Q4 scope). Traditional antivirus inspects what executes; pkgxray inspects what gets installed. npm audit and OSV-Scanner answer an essential question — does this package have a known CVE? — and pkgxray asks it too (via OSV, before anything downloads). But a freshly trojaned package has no CVE yet, so pkgxray also analyzes trust: what the code actually does, whether the published npm artifact matches the tagged GitHub source, whether the provenance attestation is consistent with the claimed repository, and whether the docs carry a prompt-injection payload aimed at the agent reading them. It is intentionally conservative: verdicts come from deterministic heuristics (no LLM in the verdict path, so injected text can't steer them), only citable evidence is reported, and the zero-heuristic-false-block calibration on the top-1000 most-downloaded packages is regression-gated in CI.

That claim is scoped to the most-installed set — it is not a claim of zero false blocks on every package; the newer MCP/agent-tooling ecosystem is over-blocked and being reconciled per-case (details). What it catches

Threat Coverage How pkgxray sees it

Credential theft ✅ reads of .ssh / .aws / .npmrc / .env / keychains / wallets, incl. split-fragment paths (".s"+"sh")

Prompt injection ✅ tiered detection in docs, comments, metadata; deterministic verdict path can't be steered

Unicode smuggling ✅ invisible tag-block characters + Trojan Source bidi / zero-width

Base64 payloads ✅ encoded envelopes in docs/comments; blobs decoded into computed-arg eval / new Function / child_process

Exfiltration & loaders ✅ cross-file correlation: stage-2 loaders, curl | sh, process.env harvesting near a network sink, EtherHiding

Persistence ✅ writes to shell rc files, cron, launch agents

Obfuscation ✅ packed blob + computed-arg execution; minification alone is deliberately not flagged

Known CVEs ✅ OSV batch pre-check before download; never mutable by config

Trojaned updates / maintainer takeover ✅ recheck verdict-drift + version-drift monitoring

Artifact divergence ✅ published npm tarball diffed against the tagged GitHub source

MCP capability abuse ✅ capability-surface mismatch in the manifest audit (a get_weather that also takes a command)

Runtime tool drift ✅ mcp-proxy re-audits on tools/list_changed; pinned-manifest drift is denied

Sequence-level tool-call chains ◑ mcp-proxy gates each call and scans results; no cross-call flow analysis — honest limits

Dependency confusion / typosquats ◑ callback beacons, repo-mismatch and provenance-mismatch signals; no name-similarity heuristic

✅ detected · ◑ partial / indirect Known blind spot: pkgxray reasons about bytes in the tarball.

A package that downloads its real payload after install can ship a clean tree — pkgxray flags the capability when its shape is unambiguous, but pair it with runtime sandboxing when that risk matters. Full analysis: docs/threat-model.md. Beyond detection

Continuous monitoring — pkgxray recheck diffs installed deps against a stored verdict baseline and pre-vets newer versions MCP vetting — pkgxray mcp audits a server's tool manifest before you connect; --pin / --recheck catch the rug-pull; pkgxray-mcp gives any agent the audit tools directly Runtime gate — pkgxray mcp-proxy wraps a live MCP server on the wire: denied tools stripped, ~0.05 µs per-call verdict, injection scan of tool results Install gate — a hookshot hook runs guard on every package an agent tries to install, across Claude Code, Cursor, Windsurf, Factory Droid, and Codex (examples/hookshot/) Policy engine — one .pkgxray.json read by every surface; tighten freely, every loosening is printed; CVEs can never be allowed away; fail closed Opt-in behavioral canary — pkgxray canary runs lifecycle scripts in an OS sandbox with decoy credentials; it can confirm malice, never clear a package

Verdicts

Verdict Meaning You should

🟢 SAFE No high- or medium-risk indicators. Install. Only safe promotes out of quarantine by default.

🟡 REVIEW Incomplete evidence, or a privileged capability that needs a human. Inspect the quarantined copy before promoting.

🔴 BLOCK High-severity, cited evidence. Do not install. Every finding names the file and evidence.

Exit codes are stable and CI-friendly: 0 safe/allow · 2 block · 3 review. The full signal-to-severity mapping is in the severity policy.

Usage Vet an npm package before installing pkgxray guard npm:some-package@1.2.3 [--format json] pkgxray guard ./ext --promote-to ./approved/ext # local dir, promote if policy allows Vet an MCP server before connecting — full guide: docs/mcp.md pkgxray mcp --package npm:some-mcp-server@1.4.2 npx some-mcp-server pkgxray mcp --recheck npx some-mcp-server # catch the rug-pull Enforce in CI/CD pkgxray audit package-lock.json [--deep] # also: yarn.lock, pnpm-lock.yaml, package.json npx pkgxray recheck package-lock.json # scheduled: exits non-zero only on a regression A ready-made GitHub Actions integration and the self-hostable cache server (PKGXRAY_CACHE_URL) are documented in the reference. Guard AI coding agents pkgxray is published on the MCP Registry as io.github.adamsjack711-ux/pkgxray. Add it to any MCP client — locally installed (pkgxray-mcp) or zero-install via npx: { "mcpServers": { "pkgxray": { "command": "npx", "args": ["--yes", "--package", "pkgxray@1.0.4", "pkgxray-mcp"], "env": { "PKGXRAY_MCP_ALLOWED_ROOTS": "/absolute/path/to/project" } } } } The MCP guide explains the operator-owned filesystem boundary. Product-specific setup is in the coding-agent integration guide. Gate installs with the Hookshot integration and wrap MCP servers with pkgxray mcp-proxy. Configuration One optional .pkgxray.json, read by every surface.