pkgxray 0.3.0 → 0.5.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pkgxray",
-  "version": "0.3.0",
+  "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.",
   "license": "MIT",
   "author": "Jack Adams-Lovell",

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
@@ -175,6 +210,7 @@ function auditEvidence(input) {
 
   const verdict = decideVerdict(findings, evidence);
   const grading = gradeEvidence(findings, evidence);
+  const riskBands = computeRiskBands(findings);
   return {
     verdict,
     grade: grading.grade,
@@ -182,10 +218,58 @@ function auditEvidence(input) {
     parameters: grading.parameters,
     summary: summarizeVerdict(verdict, findings),
     packageName: evidence.packageName || null,
+    riskBands,
     findings: findings.sort(compareFindings)
   };
 }
 
+// Maps the granular finding categories the auditor produces into a smaller
+// set of human-readable "bands" so the verdict explainer can say things like
+// "review because: lifecycle-script + dynamic-eval" instead of dumping the
+// raw category list.
+const BAND_DEFINITIONS = [
+  { band: "prompt-injection", label: "prompt-injection", categories: ["injection-attempt"], rationale: "README/docs contain text aimed at instructing an LLM auditor." },
+  { band: "credential-access", label: "credential-access", categories: ["credential-access"], rationale: "Reads a path to a credential / wallet / key store near a filesystem read." },
+  { band: "persistence", label: "persistence", categories: ["persistence"], rationale: "Writes to a shell rc, crontab, launchagent, systemd unit, or Windows Run key." },
+  { band: "exfiltration", label: "network-exfiltration", categories: ["network-exfil-or-loader"], rationale: "Code reaches a hardcoded public IP / shortener / webhook from a file that also has exec or net capability." },
+  { band: "obfuscation", label: "obfuscation", categories: ["obfuscation"], rationale: "Large encoded blob co-located with an execution primitive — classic malware shape." },
+  { band: "known-vulnerability", label: "known-vulnerability", categories: ["known-vulnerability"], rationale: "OSV reports this package/version as affected by a published vulnerability." },
+  { band: "lifecycle-script", label: "lifecycle-script", categories: ["install-hook"], rationale: "Runs a script at install time with the installing user's privileges." },
+  { band: "dynamic-eval", label: "dynamic-eval", categories: ["code-execution"], severityMin: "medium", rationale: "Uses eval / new Function / vm — can execute strings as code at runtime." },
+  { 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." }
+];
+
+const SEVERITY_RANK = { info: 0, low: 1, medium: 2, high: 3 };
+
+function computeRiskBands(findings) {
+  const result = [];
+  for (const def of BAND_DEFINITIONS) {
+    const matched = findings.filter((finding) => {
+      if (!def.categories.includes(finding.category)) return false;
+      if (def.severityMin && SEVERITY_RANK[finding.severity] < SEVERITY_RANK[def.severityMin]) return false;
+      return true;
+    });
+    if (matched.length === 0) continue;
+    const severity = matched.reduce(
+      (max, f) => (SEVERITY_RANK[f.severity] > SEVERITY_RANK[max] ? f.severity : max),
+      "info"
+    );
+    const examples = matched.slice(0, 3).map((f) => f.file);
+    result.push({
+      band: def.band,
+      label: def.label,
+      severity,
+      count: matched.length,
+      examples,
+      rationale: def.rationale
+    });
+  }
+  return result.sort((a, b) => SEVERITY_RANK[b.severity] - SEVERITY_RANK[a.severity]);
+}
+
 function auditMetadata(evidence, findings) {
   const packageJson = findPackageJson(evidence.sourceFiles);
   if (packageJson) {
@@ -489,7 +573,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 /
@@ -773,6 +857,22 @@ function renderMarkdown(report) {
     lines.push(`Package: \`${report.packageName}\``, "");
   }
 
+  if (report.riskBands && report.riskBands.length > 0) {
+    const verb = report.verdict === "block"
+      ? "Block because"
+      : report.verdict === "review"
+        ? "Review because"
+        : "Notes";
+    lines.push(`${verb}:`);
+    for (const band of report.riskBands) {
+      const examples = band.examples && band.examples.length > 0
+        ? ` (${band.examples.slice(0, 2).map((e) => `\`${e}\``).join(", ")}${band.count > band.examples.length ? `, +${band.count - band.examples.length} more` : ""})`
+        : "";
+      lines.push(`- **${band.severity.toUpperCase()} ${band.label}** — ${band.rationale}${examples}`);
+    }
+    lines.push("");
+  }
+
   lines.push("Parameter grades:");
   for (const [name, parameter] of Object.entries(report.parameters)) {
     lines.push(