pkgxray 0.5.0 → 0.7.0

package/bin/audit.js

@@ -12,7 +12,7 @@ function printUsage() {
       "  pkgxray < evidence.json",
       "  pkgxray --format json < evidence.json",
       "  pkgxray --file evidence.json --format markdown",
-      "  pkgxray guard <npm-package|npm:name@version|./path> [--promote-to dir] [--no-source-scan]",
+      "  pkgxray guard <npm-package|npm:name@version|github:owner/repo[#ref]|./path> [--promote-to dir] [--no-source-scan]",
       "",
       "Evidence JSON fields:",
       "  packageName, npmMetadata, githubMetadata, webPresence, sourceFiles",
@@ -49,6 +49,8 @@ function parseArgs(argv) {
       options.sourceScan = false;
     } else if (arg === "--no-vulnerability-check") {
       options.vulnerabilityCheck = false;
+    } else if (arg === "--no-github") {
+      options.githubMetadata = false;
     } else {
       throw new Error(`Unknown argument: ${arg}`);
     }

package/bin/mcp-server.js

@@ -102,6 +102,11 @@ function guardToolDefinition() {
           default: true,
           description: "Set false to skip OSV vulnerability intelligence checks."
         },
+        githubMetadata: {
+          type: "boolean",
+          default: true,
+          description: "Set false to skip the GitHub provenance cross-check."
+        },
         outputFormat: {
           type: "string",
           enum: ["markdown", "json"],

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "pkgxray",
-  "version": "0.5.0",
-  "description": "Zero-dep local CLI and MCP server that scans npm packages and AI-agent extensions for supply-chain risk. OSV vuln pre-check, sandboxed quarantine, tarball-integrity verification, calibrated static heuristics.",
+  "version": "0.7.0",
+  "description": "Zero-dep local CLI and MCP server that scans npm packages for supply-chain risk. OSV vuln pre-check, sandboxed quarantine, tarball-integrity verification, calibrated static heuristics, GitHub provenance cross-check.",
   "license": "MIT",
   "author": "Jack Adams-Lovell",
   "type": "commonjs",

package/src/auditor.js

@@ -13,25 +13,24 @@ const SEVERITY_ORDER = {
   high: 3
 };
 
+// Suspicious credential / wallet read targets. Each entry is a regex that
+// requires a path or quote boundary so we don't match identifiers like
+// `process.env` or `someObj.ledger`.
 const SUSPICIOUS_READ_TARGETS = [
-  "~/.ssh",
-  ".ssh/",
-  "id_rsa",
-  "id_dsa",
-  "id_ecdsa",
-  "id_ed25519",
-  "~/.aws",
-  ".aws/credentials",
-  ".npmrc",
-  ".env",
-  "keychain",
-  "login.keychain",
-  "cookies.sqlite",
-  "local state",
-  "metamask",
-  "electrum",
-  "exodus",
-  "ledger"
+  { re: /['"`\/\\]\.?ssh\/(?:id_(?:rsa|dsa|ecdsa|ed25519)|authorized_keys)/i, label: "ssh-private-key" },
+  { re: /['"`\/\\]id_(?:rsa|dsa|ecdsa|ed25519)\b/i, label: "ssh-key-file" },
+  { re: /['"`\/\\]\.ssh(?:\/|['"`])/, label: ".ssh-dir" },
+  { re: /['"`\/\\]\.aws\/credentials\b/, label: ".aws/credentials" },
+  { re: /['"`\/\\]\.aws\/(?:config|credentials)\b/, label: ".aws-files" },
+  { re: /['"`\/\\]\.npmrc(?:['"`]|\s|$)/, label: ".npmrc" },
+  { re: /['"`\/\\]\.env(?:\.[a-z]+)?(?:['"`]|\s|$)/i, label: ".env-file" },
+  { re: /['"`]login\.keychain(?:-db)?['"`]/i, label: "macOS keychain" },
+  { re: /\bsecurity\s+find-(?:generic|internet)-password\b/, label: "macOS security CLI" },
+  { re: /['"`]\/?(?:Cookies|Login Data|Web Data|cookies\.sqlite)['"`]/i, label: "browser-creds" },
+  { re: /['"`]Local State['"`]/, label: "browser local-state" },
+  { re: /\bkeytar\.[a-z]+Password\(/i, label: "keytar API" },
+  { re: /\bmetamask['"`\s\/]/i, label: "metamask wallet" },
+  { re: /\b(?:electrum|exodus|ledger live|atomic wallet)\b/i, label: "crypto wallet" }
 ];
 
 // Persistence destinations. Each pattern requires a quote/slash boundary
@@ -239,7 +238,12 @@ const BAND_DEFINITIONS = [
   { band: "bulk-env", label: "bulk-env-access", categories: ["environment-access"], rationale: "Reads the entire process environment in bulk; risky paired with network." },
   { band: "clipboard", label: "clipboard-access", categories: ["data-access"], rationale: "Reads or writes the system clipboard — can expose copied secrets." },
   { band: "incomplete-evidence", label: "incomplete-evidence", categories: ["missing-evidence", "missing-package-json", "package-metadata"], rationale: "Source or package.json was missing or unparseable — cannot rule the package safe." },
-  { band: "missing-metadata", label: "missing-metadata", categories: ["missing-metadata", "supply-chain-signal"], rationale: "Provenance metadata (npm registry / GitHub) absent or weak; cross-checks skipped." }
+  { band: "missing-metadata", label: "missing-metadata", categories: ["missing-metadata", "supply-chain-signal", "github-fetch"], rationale: "Provenance metadata (npm registry / GitHub) absent or weak; cross-checks skipped." },
+  { band: "github-mismatch", label: "github-mismatch", categories: ["github-mismatch"], rationale: "package.json points at a GitHub repo that doesn't exist or doesn't match — strong typosquat / impersonation signal." },
+  { band: "github-archived", label: "github-archived", categories: ["github-archived"], rationale: "Linked repository is archived or disabled — no maintenance, security issues will not be fixed." },
+  { band: "github-young", label: "github-young", categories: ["github-young"], rationale: "Linked repository was created within the last 30 days — common slopsquat shape." },
+  { band: "github-lonely", label: "github-lonely", categories: ["github-lonely"], rationale: "0 stars + 0 forks + low watcher count on a young repo. Low community signal." },
+  { band: "github-stale", label: "github-stale", categories: ["github-stale"], rationale: "Repository hasn't been pushed to in over two years and isn't formally archived." }
 ];
 
 const SEVERITY_RANK = { info: 0, low: 1, medium: 2, high: 3 };
@@ -285,10 +289,113 @@ function auditMetadata(evidence, findings) {
   }
 
   inspectMetadataObject("NPM_METADATA", evidence.npmMetadata, findings);
-  inspectMetadataObject("GITHUB_METADATA", evidence.githubMetadata, findings);
+  inspectGithubMetadata(evidence, findings);
   inspectKnownVulnerabilities(evidence.knownVulnerabilities, findings);
 }
 
+const YOUNG_REPO_DAYS = 30;
+const STALE_REPO_DAYS = 365 * 2;
+
+function daysAgo(iso) {
+  if (!iso) return null;
+  const ms = Date.now() - new Date(iso).getTime();
+  return Math.floor(ms / 86400000);
+}
+
+function inspectGithubMetadata(evidence, findings) {
+  const meta = evidence.githubMetadata;
+  if (!meta || typeof meta !== "object") {
+    findings.push({
+      severity: "info",
+      category: "missing-metadata",
+      file: "GITHUB_METADATA",
+      snippet: "GITHUB_METADATA was not provided.",
+      rationale: "Supply-chain reputation and repository consistency could not be checked."
+    });
+    return;
+  }
+
+  if (meta.found === false) {
+    const where = meta.owner && meta.repo ? `${meta.owner}/${meta.repo}` : "linked URL";
+    if (meta.reason === "not-found") {
+      findings.push({
+        severity: "high",
+        category: "github-mismatch",
+        file: "GITHUB_METADATA",
+        snippet: `Repository ${where} 404s on GitHub`,
+        rationale:
+          "package.json points at a GitHub repository that does not exist. Strong typosquat / impersonation signal."
+      });
+    } else if (meta.reason === "not-github") {
+      // Not a GitHub URL at all — skip silently.
+    } else {
+      findings.push({
+        severity: "info",
+        category: "github-fetch",
+        file: "GITHUB_METADATA",
+        snippet: meta.message || "Could not reach GitHub API",
+        rationale: "Provenance metadata could not be fetched; cross-checks skipped."
+      });
+    }
+    return;
+  }
+
+  if (meta.archived) {
+    findings.push({
+      severity: "medium",
+      category: "github-archived",
+      file: "GITHUB_METADATA",
+      snippet: `${meta.full_name} is archived (read-only)`,
+      rationale: "Archived repos receive no maintenance; security issues will not be fixed."
+    });
+  }
+
+  if (meta.disabled) {
+    findings.push({
+      severity: "medium",
+      category: "github-archived",
+      file: "GITHUB_METADATA",
+      snippet: `${meta.full_name} is disabled`,
+      rationale: "Disabled repos cannot be updated; maintainer access may be revoked."
+    });
+  }
+
+  const ageDays = daysAgo(meta.created_at);
+  if (ageDays !== null && ageDays < YOUNG_REPO_DAYS) {
+    findings.push({
+      severity: "medium",
+      category: "github-young",
+      file: "GITHUB_METADATA",
+      snippet: `${meta.full_name} created ${ageDays} days ago`,
+      rationale:
+        "Brand-new repository combined with an npm package using a popular-sounding name is a classic slopsquat / impersonation shape."
+    });
+  }
+
+  const lonelySignal = (meta.stars || 0) === 0 && (meta.forks || 0) === 0 && (meta.watchers || 0) <= 1;
+  if (lonelySignal && (ageDays === null || ageDays < 90)) {
+    findings.push({
+      severity: "low",
+      category: "github-lonely",
+      file: "GITHUB_METADATA",
+      snippet: `${meta.full_name} has 0 stars, 0 forks, ${ageDays !== null ? `${ageDays} days old` : "unknown age"}`,
+      rationale:
+        "Very low community signal. Common for new tools, but compounds the slopsquat risk on similarly-named popular packages."
+    });
+  }
+
+  const pushedDaysAgo = daysAgo(meta.pushed_at);
+  if (pushedDaysAgo !== null && pushedDaysAgo > STALE_REPO_DAYS && !meta.archived) {
+    findings.push({
+      severity: "info",
+      category: "github-stale",
+      file: "GITHUB_METADATA",
+      snippet: `${meta.full_name} last push ${pushedDaysAgo} days ago`,
+      rationale: "Repo has not seen a push in over two years; consider whether it's still maintained."
+    });
+  }
+}
+
 function inspectKnownVulnerabilities(vulnerabilities, findings) {
   if (!Array.isArray(vulnerabilities) || vulnerabilities.length === 0) {
     return;
@@ -499,16 +606,16 @@ const BULK_ENV_REGEXES = [
 
 function inspectCredentialAccess(file, content, lower, findings) {
   for (const target of SUSPICIOUS_READ_TARGETS) {
-    const index = lower.indexOf(target.toLowerCase());
-    if (index === -1) continue;
-    if (!looksLikeCredentialRead(content, lower, index)) continue;
+    const match = target.re.exec(content);
+    if (!match) continue;
+    if (!looksLikeCredentialRead(content, lower, match.index)) continue;
     findings.push({
       severity: "high",
       category: "credential-access",
       file: file.path,
-      snippet: clipAround(file.content, index),
+      snippet: clipAround(file.content, match.index),
       rationale:
-        "Package reads (or constructs a path to) a credential / wallet / key store in proximity to a filesystem read primitive."
+        `Reads or references ${target.label} near a filesystem read primitive.`
     });
     return;
   }

package/src/github.js

@@ -0,0 +1,166 @@
+"use strict";
+
+const fsp = require("node:fs/promises");
+const os = require("node:os");
+const path = require("node:path");
+const https = require("node:https");
+
+const USER_AGENT = "pkgxray/0.6.0";
+const CACHE_DIR = path.join(os.homedir(), ".cache", "pkgxray", "github");
+const CACHE_TTL_MS = 60 * 60 * 1000; // 1 hour
+const FETCH_TIMEOUT_MS = 3000;
+
+async function readCache(key) {
+  try {
+    const file = path.join(CACHE_DIR, `${encodeURIComponent(key)}.json`);
+    const stat = await fsp.stat(file);
+    if (Date.now() - stat.mtimeMs > CACHE_TTL_MS) return null;
+    return JSON.parse(await fsp.readFile(file, "utf8"));
+  } catch {
+    return null;
+  }
+}
+
+async function writeCache(key, value) {
+  try {
+    await fsp.mkdir(CACHE_DIR, { recursive: true, mode: 0o700 });
+    const file = path.join(CACHE_DIR, `${encodeURIComponent(key)}.json`);
+    await fsp.writeFile(file, JSON.stringify(value), { mode: 0o600 });
+  } catch {
+    // best-effort cache; never fail the audit because of a cache write
+  }
+}
+
+// Pull owner/repo from common repository.url shapes:
+//   git+https://github.com/owner/repo.git
+//   https://github.com/owner/repo
+//   git@github.com:owner/repo.git
+//   github:owner/repo
+//   git+ssh://git@github.com/owner/repo.git
+function parseGithubRepo(repository) {
+  if (!repository) return null;
+  const url = typeof repository === "string" ? repository : repository.url;
+  if (!url || typeof url !== "string") return null;
+  const cleaned = url.replace(/^git\+/, "").replace(/\.git$/, "");
+  const patterns = [
+    /^github:([^/]+)\/(.+)$/,
+    /^(?:https?|git):\/\/github\.com\/([^/]+)\/([^/?#]+)/,
+    /^git@github\.com:([^/]+)\/([^/?#]+)/,
+    /^ssh:\/\/git@github\.com\/([^/]+)\/([^/?#]+)/
+  ];
+  for (const pattern of patterns) {
+    const match = cleaned.match(pattern);
+    if (match) {
+      return { owner: match[1], repo: match[2].replace(/\.git$/, "") };
+    }
+  }
+  return null;
+}
+
+// Use GITHUB_TOKEN if the user has set it (5000 req/hr). Otherwise fall back
+// to unauthenticated calls (60 req/hr — fine for occasional use). We
+// deliberately do NOT shell out to `gh auth token` — that adds ~150ms on
+// cold runs and speed is a goal.
+function loadToken() {
+  return process.env.GITHUB_TOKEN || process.env.PKGXRAY_GITHUB_TOKEN || null;
+}
+
+function githubApiGet(urlPath, token, hops = 0) {
+  return new Promise((resolve, reject) => {
+    if (hops > 3) return reject(new Error("Too many GitHub redirects"));
+    const headers = {
+      "user-agent": USER_AGENT,
+      accept: "application/vnd.github+json",
+      "x-github-api-version": "2022-11-28"
+    };
+    if (token) headers.authorization = `Bearer ${token}`;
+    const request = https.get(
+      { hostname: "api.github.com", path: urlPath, headers, timeout: FETCH_TIMEOUT_MS },
+      (response) => {
+        // Follow GitHub's 301 redirects (repo transferred / renamed)
+        if ([301, 302, 307, 308].includes(response.statusCode) && response.headers.location) {
+          response.resume();
+          const nextUrl = new URL(response.headers.location, `https://api.github.com${urlPath}`);
+          return githubApiGet(nextUrl.pathname + nextUrl.search, token, hops + 1).then(resolve, reject);
+        }
+        let body = "";
+        response.setEncoding("utf8");
+        response.on("data", (chunk) => {
+          body += chunk;
+        });
+        response.on("end", () => {
+          if (response.statusCode === 404) {
+            const error = new Error(`GitHub 404: ${urlPath}`);
+            error.statusCode = 404;
+            return reject(error);
+          }
+          if (response.statusCode < 200 || response.statusCode >= 300) {
+            return reject(new Error(`GitHub HTTP ${response.statusCode}: ${body.slice(0, 120)}`));
+          }
+          try {
+            resolve(JSON.parse(body));
+          } catch (parseError) {
+            reject(parseError);
+          }
+        });
+      }
+    );
+    request.on("error", reject);
+    request.on("timeout", () => {
+      request.destroy(new Error("GitHub request timed out"));
+    });
+  });
+}
+
+async function fetchRepoMetadata(repository, options = {}) {
+  const parsed = parseGithubRepo(repository);
+  if (!parsed) return { found: false, reason: "not-github" };
+
+  const cacheKey = `${parsed.owner}/${parsed.repo}`;
+  if (options.useCache !== false) {
+    const cached = await readCache(cacheKey);
+    if (cached) return { ...cached, fromCache: true };
+  }
+
+  const token = options.token === undefined ? loadToken() : options.token;
+
+  try {
+    const repo = await githubApiGet(`/repos/${parsed.owner}/${parsed.repo}`, token);
+    const result = {
+      found: true,
+      owner: parsed.owner,
+      repo: parsed.repo,
+      full_name: repo.full_name,
+      description: repo.description,
+      archived: Boolean(repo.archived),
+      disabled: Boolean(repo.disabled),
+      fork: Boolean(repo.fork),
+      stars: repo.stargazers_count || 0,
+      forks: repo.forks_count || 0,
+      open_issues: repo.open_issues_count || 0,
+      watchers: repo.watchers_count || 0,
+      created_at: repo.created_at,
+      updated_at: repo.updated_at,
+      pushed_at: repo.pushed_at,
+      default_branch: repo.default_branch,
+      html_url: repo.html_url,
+      license: repo.license && repo.license.spdx_id,
+      owner_type: repo.owner && repo.owner.type
+    };
+    await writeCache(cacheKey, result);
+    return result;
+  } catch (error) {
+    if (error.statusCode === 404) {
+      const result = { found: false, reason: "not-found", owner: parsed.owner, repo: parsed.repo };
+      await writeCache(cacheKey, result);
+      return result;
+    }
+    // Don't cache transient errors — next call should retry.
+    return { found: false, reason: "fetch-error", message: error.message, owner: parsed.owner, repo: parsed.repo };
+  }
+}
+
+module.exports = {
+  parseGithubRepo,
+  fetchRepoMetadata
+};

package/src/quarantine.js

@@ -8,6 +8,7 @@ const os = require("node:os");
 const path = require("node:path");
 const { spawn } = require("node:child_process");
 const { auditEvidence } = require("./auditor");
+const { fetchRepoMetadata } = require("./github");
 
 const DEFAULT_MAX_FILE_BYTES = 256 * 1024;
 const DEFAULT_MAX_FILES = 600;
@@ -65,6 +66,15 @@ async function guardExtension(reference, options = {}) {
   const resolved = await stageReference(reference, stagedPath, options);
   timings.stageMs = elapsed(stageStart);
 
+  // Start the GitHub metadata fetch the moment we have npm metadata. It runs
+  // concurrently with vuln-check and tarball download so it only adds latency
+  // if it's slower than everything else combined (rare — usually <250ms).
+  const githubStart = now();
+  const githubMetadataPromise = options.githubMetadata === false
+    ? Promise.resolve(null)
+    : fetchRepoMetadata(resolved.npmMetadata && resolved.npmMetadata.repository)
+        .catch(() => null);
+
   const vulnerabilityStart = now();
   const vulnerabilities =
     options.vulnerabilityCheck === false
@@ -89,10 +99,15 @@ async function guardExtension(reference, options = {}) {
     timings.sourceCollectionMs = 0;
   }
 
+  // By now the GitHub fetch is either done or has been running concurrently
+  // with everything above; await whatever remains.
+  const githubMetadata = await githubMetadataPromise;
+  timings.githubMetadataMs = elapsed(githubStart);
+
   const evidence = {
     packageName: resolved.packageName || reference,
     npmMetadata: resolved.npmMetadata || null,
-    githubMetadata: null,
+    githubMetadata,
     webPresence: null,
     knownVulnerabilities: vulnerabilities,
     sourceFiles
@@ -107,6 +122,7 @@ async function guardExtension(reference, options = {}) {
     reference,
     resolved,
     sourceFiles,
+    githubMetadata,
     vulnerabilityPrecheck: {
       enabled: options.vulnerabilityCheck !== false,
       database: "OSV",
@@ -142,6 +158,10 @@ async function stageReference(reference, stagedPath, options) {
     return resolveNpmPackage(parsed.specifier, options);
   }
 
+  if (parsed.type === "github") {
+    return resolveGithubRepo(parsed, options);
+  }
+
   throw new Error(`Unsupported reference type: ${reference}`);
 }
 
@@ -154,6 +174,21 @@ function parseReference(reference) {
     return { type: "local", path: path.resolve(reference.slice("file:".length)) };
   }
 
+  if (reference.startsWith("github:")) {
+    return parseGithubReference(reference.slice("github:".length));
+  }
+
+  // github.com URLs as a convenience shorthand
+  const ghMatch = reference.match(/^https?:\/\/github\.com\/([^/]+)\/([^/?#]+?)(?:\.git)?(?:#(.+))?$/);
+  if (ghMatch) {
+    return {
+      type: "github",
+      owner: ghMatch[1],
+      repo: ghMatch[2],
+      ref: ghMatch[3] || null
+    };
+  }
+
   if (
     reference.startsWith(".") ||
     reference.startsWith("/") ||
@@ -168,6 +203,62 @@ function parseReference(reference) {
   return { type: "npm", specifier: reference };
 }
 
+function parseGithubReference(spec) {
+  // Supports owner/repo[#ref] and owner/repo[@ref]
+  const match = spec.match(/^([^/#@]+)\/([^/#@]+?)(?:[#@](.+))?$/);
+  if (!match) throw new Error(`Invalid github reference: github:${spec}`);
+  return {
+    type: "github",
+    owner: match[1],
+    repo: match[2].replace(/\.git$/, ""),
+    ref: match[3] || null
+  };
+}
+
+async function resolveGithubRepo(parsed, options) {
+  // Resolve default branch if no ref pinned. Uses the existing GitHub metadata
+  // helper which is already cached + parallel-safe.
+  const { fetchRepoMetadata } = require("./github");
+  let ref = parsed.ref;
+  let resolvedMeta = null;
+  if (!ref) {
+    const meta = await fetchRepoMetadata(`https://github.com/${parsed.owner}/${parsed.repo}`).catch(() => null);
+    if (meta && meta.found === false && meta.reason === "not-found") {
+      throw new Error(`GitHub repository not found: ${parsed.owner}/${parsed.repo}`);
+    }
+    if (meta && meta.found) {
+      ref = meta.default_branch || "HEAD";
+      resolvedMeta = meta;
+    } else {
+      ref = "HEAD";
+    }
+  }
+
+  // GitHub's "codeload" endpoint returns a .tar.gz of the repo at the given
+  // ref. Works for branch names, tags, and commit SHAs.
+  const tarballUrl = `https://codeload.github.com/${parsed.owner}/${parsed.repo}/tar.gz/${encodeURIComponent(ref)}`;
+
+  return {
+    type: "github",
+    owner: parsed.owner,
+    repo: parsed.repo,
+    ref,
+    needsDownload: true,
+    tarballUrl,
+    packageName: `${parsed.owner}/${parsed.repo}`,
+    githubArchive: true,
+    npmMetadata: resolvedMeta
+      ? {
+          // Synthetic shape so the downstream auditor still sees a repository
+          // URL and the github cross-check finds the same data we already have.
+          name: parsed.repo,
+          repository: { url: resolvedMeta.html_url, type: "git" },
+          maintainers: []
+        }
+      : null
+  };
+}
+
 async function copyLocalPath(sourcePath, stagedPath) {
   const stat = await fsp.stat(sourcePath);
   if (!stat.isDirectory()) {