pkgxray 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jack Adams-Lovell
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,187 @@
+# pkgxray
+
+Local CLI + MCP server for triaging whether an AI coding-agent extension, Codex
+plugin, Claude Code extension, or npm package is safe to install — from supplied
+evidence or by fetching a real npm tarball into a sandboxed quarantine.
+
+## Install
+
+```bash
+npm install -g pkgxray
+# or use one-shot via npx:
+npx pkgxray guard npm:some-package@1.2.3
+```
+
+It is intentionally conservative. It only reports evidence it can cite from
+metadata or source text, and it returns one of:
+
+- `safe`: no high- or medium-risk indicators in the provided evidence
+- `review`: incomplete evidence or privileged capability needing manual review
+- `block`: high-severity indicators such as prompt injection, credential access,
+  persistence, obfuscation plus execution, or likely exfiltration
+
+## CLI
+
+```bash
+pkgxray --file examples/evidence.json
+pkgxray --format json --file examples/evidence.json
+```
+
+Guard an extension before handing it to an agent:
+
+```bash
+pkgxray guard ./some-local-extension
+pkgxray guard npm:some-mcp-server@1.2.3 --format json
+pkgxray guard ./some-local-extension --promote-to ./approved/some-local-extension
+pkgxray guard npm:is-number@7.0.0 --no-source-scan --format json
+```
+
+The guard flow stages the extension in a private quarantine directory, audits
+that staged copy, and only promotes it when policy allows. It does not run
+`npm install`, package lifecycle scripts, build steps, or extension code.
+
+For npm references, guard order is:
+
+1. Resolve package metadata from the npm registry.
+2. Query OSV for the exact package/version.
+3. If OSV reports vulnerabilities, block before tarball download.
+4. If no vulnerabilities are reported, download and extract the tarball into
+   quarantine.
+5. Collect source evidence and run the static audit unless `--no-source-scan`
+   is set.
+
+The JSON output includes timing fields:
+
+- `stageMs`: local copy or npm metadata resolution
+- `vulnerabilityPrecheckMs`: OSV lookup time
+- `downloadMs`: tarball download, hash, and extraction time
+- `sourceCollectionMs`: capped source-file collection time
+- `auditMs`: static audit time
+
+Guard decisions:
+
+- `allow`: safe verdict; promotion can happen
+- `review`: do not promote by default; a human should inspect the quarantine
+- `block`: high-severity evidence; do not install
+
+By default, only `safe` promotes. Use `--policy allow-review` only when you want
+review-grade packages copied into the destination for manual handling.
+
+Input JSON:
+
+```json
+{
+  "packageName": "example-extension",
+  "npmMetadata": {},
+  "githubMetadata": {},
+  "webPresence": {},
+  "sourceFiles": {
+    "package.json": "{\"name\":\"example-extension\"}",
+    "index.js": "module.exports = {}"
+  }
+}
+```
+
+## MCP Server
+
+Use the stdio server from any MCP-capable agent:
+
+```json
+{
+  "mcpServers": {
+    "pkgxray": {
+      "command": "pkgxray-mcp"
+    }
+  }
+}
+```
+
+The server exposes three tools:
+
+- `audit_agent_extension_supply_chain` — zero-dep static heuristics
+- `guard_agent_extension_install` — stage, vuln-check, audit a real package
+- `reason_about_extension_supply_chain` — Claude-powered authoritative verdict (requires `ANTHROPIC_API_KEY`)
+
+Tool arguments:
+
+- `packageName`: optional package or extension name
+- `npmMetadata`: optional npm metadata object or text
+- `githubMetadata`: optional GitHub metadata object or text
+- `webPresence`: optional web presence object or text
+- `sourceFiles`: required map of file path to source text, or array of file objects
+- `outputFormat`: `markdown` or `json`
+
+`guard_agent_extension_install` accepts `reference`, optional `quarantineRoot`,
+optional `promoteTo`, `policy`, `force`, and `outputFormat`.
+
+`reason_about_extension_supply_chain` accepts the same evidence shape as
+`audit_agent_extension_supply_chain`, plus optional `model` (default
+`claude-opus-4-7`) and `maxFiles` (default 200). It returns a JSON verdict per
+the prompt's schema (`verdict`, `summary`, `findings`, `evidenceGaps`,
+`promotable`) plus `usage` and `latencyMs`.
+
+## Reasoning mode (`--reason`)
+
+Layer an LLM-powered authoritative verdict on top of the static heuristics.
+Supports Anthropic (Claude), OpenAI (GPT), and Google (Gemini).
+
+```bash
+# Anthropic (default)
+export ANTHROPIC_API_KEY=sk-ant-...
+npm install -g @anthropic-ai/sdk
+pkgxray --reason --file evidence.json
+pkgxray guard npm:some-pkg --reason --format json
+
+# OpenAI
+export OPENAI_API_KEY=sk-...
+npm install -g openai
+pkgxray guard npm:some-pkg --reason --reason-provider openai
+
+# Gemini
+export GEMINI_API_KEY=...
+npm install -g @google/generative-ai
+pkgxray guard npm:some-pkg --reason --reason-model gemini-2.5-pro
+```
+
+Provider is selected by `--reason-provider <anthropic|openai|gemini>` or
+auto-detected from the model prefix (`claude-*` → anthropic, `gpt-*`/`o*` →
+openai, `gemini-*` → gemini). Defaults: `claude-opus-4-7`, `gpt-5`,
+`gemini-2.5-pro` — overridable with `--reason-model`.
+
+The Anthropic path uses adaptive thinking, `effort: "high"`, and caches the
+system prompt for 5-minute TTL (~90% cheaper on prompt tokens for repeated
+calls in the window). OpenAI uses strict structured outputs against the same
+JSON Schema. Gemini uses JSON-mode responses.
+
+Source files are capped at 200 files / 32 KB each / 500 KB total before
+sending — override with `--reason-max-files`.
+
+The reasoning verdict supersedes the static decision when `--reason` is used.
+Exit codes: `0` = safe, `2` = block, `3` = review.
+
+## Browser Extension
+
+The `browser-extension/` folder is a Chrome-compatible Manifest V3 unpacked
+extension. It runs entirely locally and requests no browser permissions.
+
+Load the `browser-extension/` folder from a checkout of this repo as an
+unpacked extension.
+
+In Chrome:
+
+1. Open `chrome://extensions`.
+2. Enable Developer Mode.
+3. Choose Load unpacked.
+4. Select the `browser-extension` folder above.
+
+In Dia, try the same flow if Dia exposes Chromium extension management. If Dia
+does not currently allow unpacked extensions, use Chrome for testing and keep the
+MCP/CLI version for agent workflows.
+
+## Local Development
+
+```bash
+npm run build:browser
+npm test
+npm run audit:evidence -- --file examples/evidence.json
+```

package/bin/audit.js

@@ -0,0 +1,240 @@
+#!/usr/bin/env node
+"use strict";
+
+const fs = require("node:fs");
+const { auditEvidence, renderMarkdown } = require("../src/auditor");
+const { guardExtension } = require("../src/quarantine");
+const { reasonAbout } = require("../src/reasoner");
+
+function printUsage() {
+  process.stderr.write(
+    [
+      "Usage:",
+      "  pkgxray < evidence.json",
+      "  pkgxray --format json < evidence.json",
+      "  pkgxray --file evidence.json --format markdown",
+      "  pkgxray --reason --file evidence.json",
+      "  pkgxray guard <npm-package|npm:name@version|./path> [--reason] [--promote-to dir] [--no-source-scan]",
+      "",
+      "Evidence JSON fields:",
+      "  packageName, npmMetadata, githubMetadata, webPresence, sourceFiles",
+      "",
+      "--reason consults an LLM as an authoritative verdict on top of the static",
+      "heuristics. Provider auto-detected from --reason-model, or pass",
+      "--reason-provider <anthropic|openai|gemini>. Defaults: anthropic +",
+      "claude-opus-4-7. Each provider needs its own env key (ANTHROPIC_API_KEY,",
+      "OPENAI_API_KEY, GEMINI_API_KEY) and SDK installed.",
+      ""
+    ].join("\n")
+  );
+}
+
+function parseArgs(argv) {
+  const options = { command: "audit", format: "markdown", file: null };
+  if (argv[0] === "guard") {
+    options.command = "guard";
+    options.reference = argv[1];
+    argv = argv.slice(2);
+  }
+
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
+    if (arg === "--help" || arg === "-h") {
+      options.help = true;
+    } else if (arg === "--format") {
+      options.format = argv[++i];
+    } else if (arg === "--file") {
+      options.file = argv[++i];
+    } else if (arg === "--quarantine-root") {
+      options.quarantineRoot = argv[++i];
+    } else if (arg === "--promote-to") {
+      options.promoteTo = argv[++i];
+    } else if (arg === "--policy") {
+      options.policy = argv[++i];
+    } else if (arg === "--force") {
+      options.force = true;
+    } else if (arg === "--no-source-scan") {
+      options.sourceScan = false;
+    } else if (arg === "--no-vulnerability-check") {
+      options.vulnerabilityCheck = false;
+    } else if (arg === "--reason") {
+      options.reason = true;
+    } else if (arg === "--reason-model") {
+      options.reasonModel = argv[++i];
+    } else if (arg === "--reason-provider") {
+      options.reasonProvider = argv[++i];
+    } else if (arg === "--reason-max-files") {
+      options.reasonMaxFiles = Number(argv[++i]);
+    } else {
+      throw new Error(`Unknown argument: ${arg}`);
+    }
+  }
+  if (!["json", "markdown"].includes(options.format)) {
+    throw new Error("--format must be json or markdown");
+  }
+  return options;
+}
+
+function readInput(file) {
+  if (file) {
+    return fs.readFileSync(file, "utf8");
+  }
+  return fs.readFileSync(0, "utf8");
+}
+
+async function maybeReason(evidence, options) {
+  if (!options.reason) return null;
+  try {
+    return await reasonAbout(evidence, {
+      provider: options.reasonProvider,
+      model: options.reasonModel,
+      maxFiles: options.reasonMaxFiles
+    });
+  } catch (error) {
+    return { error: { code: error.code || "REASONER_ERROR", message: error.message } };
+  }
+}
+
+function reasoningExitCode(reasoning) {
+  if (!reasoning || reasoning.error) return null;
+  if (reasoning.verdict === "block") return 2;
+  if (reasoning.verdict === "review") return 3;
+  return 0;
+}
+
+async function main() {
+  const options = parseArgs(process.argv.slice(2));
+  if (options.help) {
+    printUsage();
+    return;
+  }
+
+  if (options.command === "guard") {
+    if (!options.reference) {
+      throw new Error("guard requires an extension reference");
+    }
+    const result = await guardExtension(options.reference, options);
+    if (options.reason) {
+      const evidenceForReason = {
+        packageName: result.resolved && result.resolved.packageName,
+        npmMetadata: result.resolved && result.resolved.npmMetadata,
+        githubMetadata: null,
+        webPresence: null,
+        sourceFiles: result.sourceFiles || {}
+      };
+      const reasoning = await maybeReason(evidenceForReason, options);
+      result.reasoning = reasoning;
+      if (reasoning && !reasoning.error && reasoning.verdict) {
+        result.decision = reasoning.verdict === "block"
+          ? "block"
+          : reasoning.verdict === "safe"
+            ? "allow"
+            : "review";
+      }
+    }
+    if (options.format === "json") {
+      process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+    } else {
+      process.stdout.write(`${renderGuardMarkdown(result)}\n`);
+    }
+    process.exitCode = result.decision === "block" ? 2 : result.decision === "review" ? 3 : 0;
+    return;
+  }
+
+  const raw = readInput(options.file).trim();
+  if (!raw) {
+    throw new Error("No evidence JSON provided");
+  }
+
+  const evidence = JSON.parse(raw);
+  const report = auditEvidence(evidence);
+  const reasoning = await maybeReason(evidence, options);
+
+  const payload = reasoning ? { report, reasoning } : report;
+
+  if (options.format === "json") {
+    process.stdout.write(`${JSON.stringify(payload, null, 2)}\n`);
+  } else if (reasoning) {
+    process.stdout.write(`${renderMarkdown(report)}\n\n---\n\n${renderReasoningMarkdown(reasoning)}\n`);
+  } else {
+    process.stdout.write(`${renderMarkdown(report)}\n`);
+  }
+
+  const exitFromReason = reasoningExitCode(reasoning);
+  if (exitFromReason !== null) {
+    process.exitCode = exitFromReason;
+  }
+}
+
+function renderGuardMarkdown(result) {
+  const lines = [
+    `Decision: **${result.decision.toUpperCase()}**`,
+    `Reference: \`${result.reference}\``,
+    `Quarantine: \`${result.quarantinePath}\``,
+    ""
+  ];
+
+  if (result.promotedPath) {
+    lines.push(`Promoted to: \`${result.promotedPath}\``, "");
+  }
+
+  lines.push(renderMarkdown(result.report));
+
+  if (result.reasoning) {
+    lines.push("", "---", "", renderReasoningMarkdown(result.reasoning));
+  }
+
+  return lines.join("\n");
+}
+
+function renderReasoningMarkdown(reasoning) {
+  if (reasoning.error) {
+    return `Reasoning: **unavailable** (${reasoning.error.code}: ${reasoning.error.message})`;
+  }
+  const lines = [
+    `Reasoning verdict: **${(reasoning.verdict || "?").toUpperCase()}**`,
+    `Provider: \`${reasoning.provider || "?"}\` · Model: \`${reasoning.model}\` · latency: ${reasoning.latencyMs} ms`,
+    "",
+    reasoning.summary || "",
+    ""
+  ];
+  if (reasoning.usage) {
+    const u = reasoning.usage;
+    const parts = [
+      `in=${u.input_tokens ?? "?"}`,
+      `out=${u.output_tokens ?? "?"}`,
+      `cache_read=${u.cache_read_input_tokens ?? 0}`,
+      `cache_write=${u.cache_creation_input_tokens ?? 0}`
+    ];
+    lines.push(`Tokens: ${parts.join(" · ")}`, "");
+  }
+  if (reasoning.findings && reasoning.findings.length > 0) {
+    lines.push("Findings:");
+    for (const finding of reasoning.findings) {
+      lines.push(
+        `- **${finding.severity.toUpperCase()} - ${finding.category}**: ${finding.reasoning}`,
+        `  Evidence: \`${finding.evidence}\``
+      );
+    }
+    lines.push("");
+  } else {
+    lines.push("Findings: none reported.", "");
+  }
+  if (reasoning.evidenceGaps && reasoning.evidenceGaps.length > 0) {
+    lines.push("Evidence gaps:");
+    for (const gap of reasoning.evidenceGaps) {
+      lines.push(`- ${gap}`);
+    }
+  }
+  return lines.join("\n");
+}
+
+try {
+  main().catch((error) => {
+    process.stderr.write(`pkgxray: ${error.message}\n`);
+    process.exitCode = 1;
+  });
+} catch (error) {
+  process.stderr.write(`pkgxray: ${error.message}\n`);
+  process.exitCode = 1;
+}