pkgxray 0.4.0 → 0.6.0

package/bin/audit.js

@@ -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.4.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.6.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

@@ -57,19 +57,54 @@ const PERSISTENCE_REGEXES = [
 const EXEC_REGEX = /\b(?:child_process\.(?:exec|execSync|spawn|spawnSync|fork)|require\(['"]child_process['"]\)|os\.system\(|subprocess\.(?:Popen|run|call|check_output)|Runtime\.getRuntime\(\)\.exec)/;
 const DYNAMIC_EVAL_REGEX = /\b(?:eval\s*\(|new\s+Function\s*\(|vm\.runIn[A-Za-z]+Context\b)/;
 
-const NETWORK_REGEX = /\b(?:fetch\s*\(|axios\.[a-z]+\s*\(|got\s*\(|node-fetch|undici|https?\.request\s*\(|XMLHttpRequest|new\s+WebSocket|requests\.[a-z]+\s*\(|urllib(?:\.request)?|net\/http)/i;
+const NETWORK_REGEX = /\b(?:fetch\s*\(|axios\.[a-z]+\s*\(|got\s*\(|node-fetch|undici|https?\.(?:request|get|post|put|delete)\s*\(|XMLHttpRequest|new\s+WebSocket|requests\.[a-z]+\s*\(|urllib(?:\.request)?|net\/http|httpx\.[a-z]+\s*\()/i;
 const SHELL_NETWORK_REGEX = /(?:^|[\s;&|`$(])(?:curl|wget|Invoke-WebRequest)\s/m;
 
-const URL_SHORTENER_PATTERNS = [
+// Domains that are almost never legitimate destinations from production code.
+// Three buckets: URL shorteners (data hiding), paste/webhook services
+// (drop sites), and OAST/tunneling services (Burp Collaborator-style
+// out-of-band callbacks used in dependency-confusion PoCs and credential
+// staging). A real library would not call any of these.
+const EXFIL_AND_CALLBACK_DOMAINS = [
+  // URL shorteners
   "bit.ly",
   "tinyurl.com",
   "t.co/",
   "goo.gl",
+  "is.gd",
+  "ow.ly",
+  // Paste / drop sites
   "pastebin.com",
   "hastebin",
+  "transfer.sh",
+  // Webhooks
   "webhook.site",
   "discord.com/api/webhooks",
-  "hooks.slack.com"
+  "hooks.slack.com",
+  "discordapp.com/api/webhooks",
+  // OAST / collaborator services (Burp, Caido, ProjectDiscovery)
+  "oast.live",
+  "oast.fun",
+  "oast.online",
+  "oast.pro",
+  "oast.me",
+  "oast.site",
+  "oastify.com",
+  "interact.sh",
+  "burpcollaborator.net",
+  // Pipe / request inspector services
+  "requestbin.com",
+  "requestbin.net",
+  "pipedream.net",
+  "pipedream.com",
+  "rce.ee",
+  // Tunneling / reverse proxies
+  "ngrok-free.app",
+  "ngrok.io",
+  "serveo.net",
+  "lhr.life",
+  "loca.lt",
+  "trycloudflare.com"
 ];
 
 // Directive phrases targeting an LLM / auditor. Kept narrow on purpose — generic
@@ -204,7 +239,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 };
@@ -250,10 +290,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;
@@ -538,7 +681,7 @@ function inspectExecNetworkCombinations(file, content, lower, findings) {
   const hasDynamicEval = DYNAMIC_EVAL_REGEX.test(content);
   const hasNetwork = NETWORK_REGEX.test(content) || SHELL_NETWORK_REGEX.test(content);
   const hardcodedIp = findPublicIpInCode(content);
-  const shortener = URL_SHORTENER_PATTERNS.find((pattern) => lower.includes(pattern));
+  const shortener = EXFIL_AND_CALLBACK_DOMAINS.find((pattern) => lower.includes(pattern));
   const hasBulkEnv = BULK_ENV_REGEXES.some((re) => re.test(content));
 
   // HIGH: real exfil/loader signal — execution OR network plus a hardcoded IP /

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",