# 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.

- **Type:** MCP server
- **Install:** `agentstack add mcp-adamsjack711-ux-pkgxray`
- **Verified:** Pending review
- **Seller:** [adamsjack711-ux](https://agentstack.voostack.com/s/adamsjack711-ux)
- **Installs:** 0
- **Category:** [Developer Tools](https://agentstack.voostack.com/c/developer-tools)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [adamsjack711-ux](https://github.com/adamsjack711-ux)
- **Source:** https://github.com/adamsjack711-ux/pkgxray
- **Website:** https://pkgxray.pages.dev

## Install

```sh
agentstack add mcp-adamsjack711-ux-pkgxray
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# pkgxray

**Supply-chain security for AI agents, npm packages, and Model Context Protocol (MCP) servers.**

Analyze packages *before* you install them. Zero-dependency Node, runs
entirely on your machine, never executes untrusted code.

[](https://www.npmjs.com/package/pkgxray)
[](https://github.com/adamsjack711-ux/pkgxray/actions/workflows/pkgxray-test.yml)
[](https://github.com/adamsjack711-ux/pkgxray/actions/workflows/pkgxray-benchmark.yml)
[](LICENSE)

**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](#demo)**

## Quick start

```bash
npm install -g pkgxray        # or zero-install: npx pkgxray …

pkgxray guard npm:express@4.21.0
```

```text
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.

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.

## Why pkgxray?

AI coding assistants install packages and connect to MCP servers at machine
speed, often without a human ever reading the code — and the registry they
pull from is under industrial-scale attack: roughly **455,000 malicious npm
packages were published in 2025**, one every ~20 seconds by Q4
([Sonatype](https://www.sonatype.com/blog/open-source-malware-index-q4-2025-automation-overwhelms-ecosystems)).
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-false-block calibration is
[regression-gated in CI](docs/benchmark.md).

## 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 |
| 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](docs/threat-model.md).

## Beyond detection

- **Continuous monitoring** — [`pkgxray recheck`](docs/reference.md#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`](docs/mcp.md#per-call-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](https://github.com/CorridorSecurity/hookshot)
  hook runs `guard` on every package an agent tries to install, across Claude
  Code, Cursor, Windsurf, Factory Droid, and Codex ([`examples/hookshot/`](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`](docs/canary-threat-model.md)
  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](docs/reference.md#severity-policy-what-lands-in-block--review--info).

## Usage

**Vet an npm package before installing**

```bash
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](docs/mcp.md)

```bash
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**

```bash
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 workflow and the self-hostable cache server
(`PKGXRAY_CACHE_URL`) are in the [reference](docs/reference.md#monitoring-pkgxray-recheck).

**Guard AI coding agents**

```json
{ "mcpServers": { "pkgxray": { "command": "pkgxray-mcp" } } }
```

Gate installs with the [hookshot integration](examples/hookshot/) and wrap MCP
servers with [`pkgxray mcp-proxy`](docs/mcp.md#per-call-runtime-gate-pkgxray-mcp-proxy).

## Configuration

One optional `.pkgxray.json`, read by every surface. Zero config means
maximum strictness.

```jsonc
{
  "policy": "safe-only",              // or "allow-review" (a loosening — warns)
  "failOn": "review",                 // CI exit threshold
  "scanErrorPolicy": "fail-closed",   // a scan that errors → review, never safe

  "allow": [
    { "pkg": "left-pad@1.3.0", "sha256": "e0b0…",
      "reason": "reviewed 2026-07", "expires": "2026-10-01" }
  ]
}
```

Precedence, `mute` / `mcp` blocks, and enforced invariants:
[docs/configuration.md](docs/configuration.md) ·
[`.pkgxray.example.json`](.pkgxray.example.json)

## Demo

The 60-second walkthrough — the SAFE run, the blocked trojan with its exit
code, then a lockfile audit:

https://github.com/user-attachments/assets/b5a323b1-a9ec-4676-9601-1b284df81b6b

All captures are real runs — reproduction steps in
[`docs/screenshots/`](docs/screenshots/README.md), which also shows the
MCP proxy, hookshot install gate, and browser extension in action.

## Comparison

Designed to run *alongside* `npm audit` and
[OSV-Scanner](https://google.github.io/osv-scanner/), not replace them — they
match dependencies against known vulnerabilities; pkgxray adds the layers
they don't attempt:

| Capability | npm audit | OSV-Scanner | pkgxray |
|---|:-:|:-:|:-:|
| Known-CVE lookup | ✅ | ✅ | ✅ (OSV, blocks before download) |
| Lockfile / project scanning | ✅ | ✅ | ✅ |
| Registry signature / provenance verification | ✅ (`npm audit signatures`) | — | ✅ (sigstore/SLSA + repo cross-check) |
| Static analysis of package code behavior | — | — | ✅ |
| Prompt-injection & Unicode-smuggling detection | — | — | ✅ |
| npm ↔ GitHub artifact divergence | — | — | ✅ |
| Pre-install quarantine of a single package | — | — | ✅ |
| Verdict-drift monitoring vs. a stored baseline | — | — | ✅ |
| MCP server vetting & per-call runtime gating | — | — | ✅ |

Scoped to npm supply-chain vetting, per each tool's public docs.
OSV-Scanner covers many ecosystems beyond npm, which pkgxray does not.

## Architecture

Acquisition (OSV pre-check → fetch) → sandboxed quarantine → static analysis →
policy → verdict. The same engine backs every surface: CLI, MCP server,
runtime proxy, install hook, browser extension, and CI cache server.
Principles: never execute untrusted code · citable evidence only ·
minimize false positives · fail closed · zero runtime dependencies.

Details: [docs/architecture.md](docs/architecture.md) ·
[docs/design.md](docs/design.md)

## Performance

- **Local static analysis: ~25 ms** — a full guard of `express` is ~1.3–1.5 s
  cold-cache, almost all network round-trips (Apple M1, Node 26)
- **Known-vulnerable packages block at the OSV pre-check**, before download
- **Calibration** (precision, recall, the 0-false-block gate) is measured by a
  committed [benchmark corpus](benchmark/) that fails CI when it regresses

Full numbers: [docs/reference.md#performance](docs/reference.md#performance) ·
methodology: [docs/benchmark.md](docs/benchmark.md)

## Documentation

| Doc | What it covers |
|---|---|
| [architecture.md](docs/architecture.md) | Pipeline, surfaces, repo layout |
| [threat-model.md](docs/threat-model.md) | Scope, blind spots, prompt-injection stance |
| [mcp.md](docs/mcp.md) | MCP server, connect-time vetting, runtime proxy |
| [configuration.md](docs/configuration.md) | `.pkgxray.json` schema and invariants |
| [reference.md](docs/reference.md) | Severity policy, `recheck`, JSON output, cache server |
| [benchmark.md](docs/benchmark.md) | Calibration benchmark & real-world validation |
| [compatibility.md](docs/compatibility.md) | The 1.0 compatibility contract |
| [json-schema.md](docs/json-schema.md) | Full `--format json` schema |

Start at the [documentation index](docs/README.md). Longer-term plans:
[adoption playbook](docs/adoption.md) and GitHub issues.

## Development

```bash
npm test                 # zero-dep node --test suite
npm run benchmark        # calibration corpus: precision/recall + 0-false-block gate
npm run build:browser    # build the MV3 browser extension
```

## Security & license

Releases are published to npm with provenance (SLSA attestation), gated on the
test suite, the calibration benchmark, and pkgxray's own supply-chain guard.
To report a vulnerability in pkgxray itself, see [SECURITY.md](SECURITY.md).

[MIT](LICENSE)

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [adamsjack711-ux](https://github.com/adamsjack711-ux)
- **Source:** [adamsjack711-ux/pkgxray](https://github.com/adamsjack711-ux/pkgxray)
- **License:** MIT
- **Homepage:** https://pkgxray.pages.dev

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** yes
- **Filesystem access:** no
- **Shell / process execution:** yes
- **Environment & secrets:** yes
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: flagged — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-adamsjack711-ux-pkgxray
- Seller: https://agentstack.voostack.com/s/adamsjack711-ux
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.