pkgradar 0.1.1 → 0.1.3

package/bin/pkgradar.js

@@ -2,13 +2,30 @@
 'use strict';
 const os = require('os');
 const { scan, SEV } = require('../lib/scan');
+const PKG = require('../package.json');
 
-const args = process.argv.slice(2);
-const has = (f) => args.includes(f);
-const val = (f, d) => { const i = args.indexOf(f); return i >= 0 && args[i + 1] ? args[i + 1] : d; };
+// ----------------------------------------------------------------------------
+// args
+// ----------------------------------------------------------------------------
+const argv = process.argv.slice(2);
+
+/**
+ * Returns true if the given flag is present in argv.
+ * @param {string} f - Flag string, e.g. "--online".
+ * @returns {boolean}
+ */
+const has = (f) => argv.includes(f);
+
+/**
+ * Returns the value of a flag argument, or a default if absent.
+ * @param {string} f   - Flag string, e.g. "--min-sev".
+ * @param {string} def - Default value when flag is missing or has no argument.
+ * @returns {string}
+ */
+const val = (f, def) => { const i = argv.indexOf(f); return i >= 0 && argv[i + 1] ? argv[i + 1] : def; };
 
 if (has('-h') || has('--help')) {
-  console.log(`pkgradar  -  content-based supply-chain scanner for npm / pnpm / yarn / bun
+  process.stdout.write(`pkgradar  -  content-based supply-chain scanner for npm / pnpm / yarn / bun
 
 It opens the package files you actually installed and looks for what malware
 does (install hooks, obfuscated payloads, known worm artifacts), instead of
@@ -20,6 +37,7 @@ USAGE
 OPTIONS
   --online            also cross-reference OSV.dev for known advisories (network)
   --json              machine-readable output
+  --full              expanded per-finding output instead of the summary table
   --min-sev LEVEL     report findings at or above LEVEL
                       critical | high | medium | low | info        [default: medium]
   --stores LIST       comma list to limit which stores are scanned
@@ -40,28 +58,127 @@ const SEV_FROM_NAME = { critical: SEV.CRITICAL, high: SEV.HIGH, medium: SEV.MEDI
 const minSevName = (val('--min-sev', 'medium') || 'medium').toLowerCase();
 const minSev = SEV_FROM_NAME[minSevName] ?? SEV.MEDIUM;
 
-const useColor = process.stdout.isTTY && !process.env.NO_COLOR;
-const e = (code) => useColor ? `\x1b[${code}m` : '';
-const wrap = (code) => (s) => useColor ? `\x1b[${code}m${s}\x1b[0m` : `${s}`;
+// ----------------------------------------------------------------------------
+// colour helpers
+// ----------------------------------------------------------------------------
+const COLOR = process.stdout.isTTY && !process.env.NO_COLOR;
+
+/**
+ * Returns a function that wraps a string in the given ANSI escape code.
+ * Falls back to a no-op when COLOR is disabled.
+ * @param {string} code - ANSI code fragment, e.g. "31" for red.
+ * @returns {(s: string) => string}
+ */
+const paint = (code) => (s) => COLOR ? `\x1b[${code}m${s}\x1b[0m` : `${s}`;
+
 const C = {
-  bold: wrap('1'), dim: wrap('2'), red: wrap('31'), grn: wrap('32'), ylw: wrap('33'),
-  blu: wrap('34'), mag: wrap('35'), cyan: wrap('36'), gray: wrap('90'),
+  bold: paint('1'), dim: paint('2'), red: paint('31'), grn: paint('32'), ylw: paint('33'),
+  blu: paint('34'), mag: paint('35'), cyan: paint('36'), gray: paint('90'),
 };
-// severity badge: white text on a coloured background, padded
-const badge = (sev) => {
+
+/**
+ * Returns a fixed-width, coloured severity cell string for use inside a table.
+ * Uses white-on-colour background in TTY mode.
+ * @param {string} sev   - Severity name: "CRITICAL" | "HIGH" | "MEDIUM" | "LOW" | "INFO".
+ * @param {number} width - Total cell width in characters.
+ * @returns {string}
+ */
+function sevCell(sev, width) {
   const bg = { CRITICAL: '41', HIGH: '45', MEDIUM: '43', LOW: '100', INFO: '100' }[sev] || '100';
   const fg = sev === 'MEDIUM' ? '30' : '97';
-  const label = ` ${sev} `.padEnd(10);
-  return useColor ? `\x1b[${bg};${fg};1m${label}\x1b[0m` : `[${sev}]`.padEnd(10);
-};
+  const label = sev.padStart((width + sev.length) >> 1).padEnd(width);
+  return COLOR ? `\x1b[${bg};${fg};1m${label}\x1b[0m` : label;
+}
+
+/** Maps severity name to a colouring function for plain-text severity mentions. */
 const SEV_TEXT = { CRITICAL: C.red, HIGH: C.mag, MEDIUM: C.ylw, LOW: C.gray, INFO: C.gray };
+
+/**
+ * Replaces the home-directory prefix of a path with "~" for compact display.
+ * @param {string|null} p - Absolute path, or null/undefined.
+ * @returns {string|null}
+ */
 const homeShort = (p) => (p && p.startsWith(os.homedir())) ? '~' + p.slice(os.homedir().length) : p;
 
-function rule(ch = '─', n = 64) { return C.gray(ch.repeat(n)); }
+// ----------------------------------------------------------------------------
+// foreground spinner (writes to stderr so stdout stays pipe-clean)
+// ----------------------------------------------------------------------------
+
+/**
+ * Creates a TTY spinner that writes to stderr.
+ * @returns {{start: Function, set: Function, stop: Function}}
+ */
+function makeSpinner() {
+  const frames = ['⠋', '⠙', '⠹', '⠸', '⠼', '⠴', '⠦', '⠧', '⠇', '⠏'];
+  const on = process.stderr.isTTY && !process.env.NO_COLOR;
+  let i = 0, msg = 'starting', timer = null;
+  const render = () => process.stderr.write(`\r\x1b[2K${C.cyan(frames[i = (i + 1) % frames.length])} ${C.gray(msg + ' …')}`);
+  return {
+    /** Start the spinner interval. */
+    start() { if (!on) return; timer = setInterval(render, 80); render(); },
+    /** Update the status message shown next to the spinner. @param {string} m */
+    set(m) { msg = m; },
+    /** Stop the spinner and clear the line. */
+    stop() { if (timer) clearInterval(timer); if (on) process.stderr.write('\r\x1b[2K'); },
+  };
+}
+
+// ----------------------------------------------------------------------------
+// table renderer
+// ----------------------------------------------------------------------------
+
+/**
+ * Clip string s to at most n chars, appending "…" if truncated.
+ * @param {*}      s - Value to stringify and clip.
+ * @param {number} n - Maximum character count.
+ * @returns {string}
+ */
+const clip = (s, n) => { s = String(s == null ? '' : s); return s.length <= n ? s : s.slice(0, Math.max(0, n - 1)) + '…'; };
 
+/**
+ * Pad string s with trailing spaces to exactly n characters.
+ * @param {string} s
+ * @param {number} n
+ * @returns {string}
+ */
+const padTo = (s, n) => s + ' '.repeat(Math.max(0, n - s.length));
+
+/**
+ * Render an array of row objects as a box-drawn table.
+ * @param {{key:string, label:string, width:number, color?:Function, raw?:boolean}[]} cols - Column definitions.
+ * @param {object[]} rows - Row data objects keyed by col.key.
+ * @returns {string} Rendered table string (no trailing newline).
+ */
+function table(cols, rows) {
+  const B = COLOR ? C.gray : (s) => s;
+  const line = (l, m, r) => B(l + cols.map((c) => '─'.repeat(c.width + 2)).join(m) + r);
+  const out = [];
+  out.push('  ' + line('┌', '┬', '┐'));
+  out.push('  ' + B('│') + cols.map((c) => ' ' + C.bold(padTo(clip(c.label, c.width), c.width)) + ' ').join(B('│')) + B('│'));
+  out.push('  ' + line('├', '┼', '┤'));
+  for (const row of rows) {
+    const cells = cols.map((c) => {
+      const v = clip(row[c.key], c.width);
+      if (c.raw) return ' ' + row[c.key] + ' ';       // pre-formatted (already padded/coloured)
+      const txt = padTo(v, c.width);
+      return ' ' + (c.color ? c.color(txt) : txt) + ' ';
+    });
+    out.push('  ' + B('│') + cells.join(B('│')) + B('│'));
+  }
+  out.push('  ' + line('└', '┴', '┘'));
+  return out.join('\n');
+}
+
+// ----------------------------------------------------------------------------
+// main
+// ----------------------------------------------------------------------------
+/** Entry point: parses CLI flags, calls scan(), then renders results to stdout. */
 (async () => {
+  const spin = makeSpinner();
+  spin.start();
+  spin.set('discovering package stores');
   let res;
-  const started = Date.now();
+  const t0 = Date.now();
   try {
     res = await scan({
       cwd: val('--cwd', process.cwd()),
@@ -70,89 +187,109 @@ function rule(ch = '─', n = 64) { return C.gray(ch.repeat(n)); }
       maxDepth: parseInt(val('--max-depth', '12'), 10) || 12,
       stores: (val('--stores', '') || '').split(',').map((s) => s.trim()).filter(Boolean),
       noAllowlist: has('--no-allowlist'),
+      onPhase: (m) => spin.set(m),
     });
   } catch (err) {
-    console.error(C.red('pkgradar error: ') + (err && err.stack || err));
+    spin.stop();
+    process.stderr.write(C.red('pkgradar error: ') + (err && err.stack || err) + '\n');
     process.exit(2);
   }
-  const secs = ((Date.now() - started) / 1000).toFixed(1);
+  spin.stop();
+  const secs = ((Date.now() - t0) / 1000).toFixed(1);
 
   if (has('--json')) {
-    console.log(JSON.stringify({ ...res, durationSeconds: Number(secs) }, null, 2));
+    process.stdout.write(JSON.stringify({ ...res, durationSeconds: Number(secs) }, null, 2) + '\n');
     process.exit(res.findings.some((f) => f.sevNum >= minSev) ? 1 : 0);
   }
 
   const counts = { CRITICAL: 0, HIGH: 0, MEDIUM: 0, LOW: 0, INFO: 0 };
   for (const f of res.findings) counts[f.severity]++;
-  const localFindings = res.findings.filter((f) => f.code !== 'osv-advisory');
-  const osvFindings = res.findings.filter((f) => f.code === 'osv-advisory');
-  const hits = res.findings.length;
   const worst = ['CRITICAL', 'HIGH', 'MEDIUM', 'LOW', 'INFO'].find((k) => counts[k]) || null;
 
+  // Shorthand to write a line to stdout.
+  const p = (...a) => process.stdout.write(a.join(' ') + '\n');
+
   // ---- header ----
-  console.log('');
-  console.log(`  ${C.bold('pkgradar')} ${C.gray('v' + require('../package.json').version)}   ${C.gray('content-based supply-chain scan')}`);
-  console.log(`  ${C.gray('project')} ${homeShort(res.cwd)}   ${C.gray(res.stores.length + ' stores, ' + secs + 's')}`);
-  console.log('');
+  p('');
+  p(`  ${C.bold('pkgradar')} ${C.gray('v' + PKG.version)}   ${C.gray('content-based supply-chain scan')}   ${C.gray(secs + 's')}`);
+  p(`  ${C.gray('project')} ${homeShort(res.cwd)}`);
+  p('');
 
   // ---- stores table ----
-  const nameW = Math.max(...res.stores.map((s) => s.kind.length), 6);
-  for (const s of res.stores) {
-    console.log(`  ${C.cyan(s.kind.padEnd(nameW))}  ${C.dim(String(s.packages).padStart(5) + ' pkgs')}  ${C.gray(homeShort(s.root))}`);
-  }
-  console.log(`  ${C.gray('total:')} ${C.bold(res.totalPackages)} ${C.gray('unique package@version,')} ${C.bold(res.totalScanned)} ${C.gray('locations inspected')}`);
-  if (res.osv && res.osv.error) console.log(`  ${C.ylw('OSV lookup failed:')} ${C.dim(res.osv.error)}`);
-  if (!res.osv && !has('--online')) console.log(`  ${C.gray('tip: add')} ${C.dim('--online')} ${C.gray('to also cross-check known advisories on OSV.dev')}`);
-  console.log('');
-
-  // ---- verdict line ----
-  if (!hits) {
-    console.log(`  ${C.grn('●')} ${C.bold('Verdict:')} ${C.grn('clean')} ${C.gray('- nothing tripped the heuristics at')} ${C.dim(minSevName)} ${C.gray('and above')}`);
-    console.log(`  ${C.gray('  (this inspects installed bytes; a clean run is not a proof of safety)')}`);
-    console.log('');
+  p(table(
+    [
+      { key: 'kind', label: 'STORE', width: 14, color: C.cyan },
+      { key: 'pkgs', label: 'PKGS', width: 6, color: C.dim },
+      { key: 'root', label: 'PATH', width: Math.max(28, (process.stdout.columns || 120) - 32) },
+    ],
+    res.stores.map((s) => ({ kind: s.kind, pkgs: String(s.packages), root: homeShort(s.root) })),
+  ));
+  p(`  ${C.gray('total:')} ${C.bold(res.totalPackages)} ${C.gray('unique package@version,')} ${C.bold(res.totalScanned)} ${C.gray('locations inspected')}`);
+  if (res.osv && res.osv.error) p(`  ${C.ylw('OSV lookup failed:')} ${C.dim(res.osv.error)}`);
+  else if (!has('--online')) p(`  ${C.gray('tip: add')} ${C.dim('--online')} ${C.gray('to cross-check known advisories on OSV.dev')}`);
+  p('');
+
+  // ---- verdict ----
+  if (!res.findings.length) {
+    p(`  ${C.grn('●')} ${C.bold('Verdict:')} ${C.grn('clean')}  ${C.gray('nothing tripped the heuristics at ' + minSevName + ' and above')}`);
+    p(`  ${C.gray('  (this inspects installed bytes; a clean run is not a proof of safety)')}`);
+    p('');
     process.exit(0);
   }
-  const summaryBits = ['CRITICAL', 'HIGH', 'MEDIUM', 'LOW', 'INFO'].filter((k) => counts[k]).map((k) => SEV_TEXT[k](`${counts[k]} ${k.toLowerCase()}`));
-  const dot = worst === 'CRITICAL' || worst === 'HIGH' ? C.red('●') : worst === 'MEDIUM' ? C.ylw('●') : C.gray('●');
-  console.log(`  ${dot} ${C.bold('Verdict:')} ${C.bold(hits + (hits === 1 ? ' finding' : ' findings'))}  ${C.gray('(')}${summaryBits.join(C.gray(', '))}${C.gray(')')}`);
-  if (localFindings.length && osvFindings.length) {
-    console.log(`  ${C.gray('  ' + localFindings.length + ' from inspecting installed code, ' + osvFindings.length + ' known advisories (OSV.dev)')}`);
-  }
-  console.log('');
-
-  // ---- findings, grouped by severity, local first then OSV ----
-  const ORDER = ['CRITICAL', 'HIGH', 'MEDIUM', 'LOW', 'INFO'];
-  const printGroup = (title, list) => {
-    if (!list.length) return;
-    console.log(`  ${rule()}`);
-    console.log(`  ${C.bold(title)}`);
-    console.log('');
-    list.sort((a, b) => b.sevNum - a.sevNum || a.package.localeCompare(b.package));
-    for (const f of list) {
-      console.log(`  ${badge(f.severity)} ${C.bold(f.package + '@' + f.version)}  ${C.gray(f.store)}  ${C.cyan(f.code)}`);
-      console.log(`     ${f.message}`);
-      if (f.evidence) console.log(`     ${C.gray('→ ' + f.evidence)}`);
-      if (f.note) console.log(`     ${C.gray('note: ' + f.note)}`);
-      if (f.dir) console.log(`     ${C.gray(homeShort(f.dir))}`);
-      console.log('');
+  const bits = ['CRITICAL', 'HIGH', 'MEDIUM', 'LOW', 'INFO'].filter((k) => counts[k]).map((k) => SEV_TEXT[k](`${counts[k]} ${k.toLowerCase()}`));
+  const dot = (worst === 'CRITICAL' || worst === 'HIGH') ? C.red('●') : worst === 'MEDIUM' ? C.ylw('●') : C.gray('●');
+  p(`  ${dot} ${C.bold('Verdict:')} ${C.bold(res.findings.length + ' ' + (res.findings.length === 1 ? 'finding' : 'findings'))}  ${C.gray('(')}${bits.join(C.gray(', '))}${C.gray(')')}`);
+  p('');
+
+  // ---- findings ----
+  const sorted = res.findings.slice().sort((a, b) => b.sevNum - a.sevNum || a.code.localeCompare(b.code) || a.package.localeCompare(b.package));
+
+  if (has('--full')) {
+    for (const f of sorted) {
+      p(`  ${sevCell(f.severity, 10)} ${C.bold(f.package + '@' + f.version)}  ${C.gray(f.store)}  ${C.cyan(f.code)}`);
+      p(`     ${f.message}`);
+      if (f.evidence) p(`     ${C.gray('-> ' + f.evidence)}`);
+      if (f.note) p(`     ${C.gray('note: ' + f.note)}`);
+      if (f.dir) p(`     ${C.gray(homeShort(f.dir))}`);
+      p('');
     }
-  };
-  printGroup('From inspecting installed code', localFindings);
-  printGroup('Known advisories (OSV.dev)', osvFindings);
+  } else {
+    const term = process.stdout.columns || 120;
+    const W_PKG = 28, W_TYPE = 21, W_WHERE = 16;
+    const W_DETAIL = Math.max(24, term - (2 + 3 + 10 + W_PKG + W_TYPE + W_WHERE + 3 * 5 + 1));
+    const SHOW = 60;
+    const rows = sorted.slice(0, SHOW).map((f) => ({
+      sev: sevCell(f.severity, 10),
+      pkg: f.package + '@' + f.version,
+      type: f.code,
+      where: f.store,
+      detail: (f.evidence ? f.evidence + '  ' : '') + f.message,
+    }));
+    p(table(
+      [
+        { key: 'sev', label: 'SEVERITY', width: 10, raw: true },
+        { key: 'pkg', label: 'PACKAGE', width: W_PKG, color: C.bold },
+        { key: 'type', label: 'TYPE', width: W_TYPE, color: C.cyan },
+        { key: 'where', label: 'WHERE', width: W_WHERE, color: C.dim },
+        { key: 'detail', label: 'DETAIL', width: W_DETAIL, color: C.gray },
+      ],
+      rows,
+    ));
+    if (sorted.length > SHOW) p(`  ${C.gray('... and ' + (sorted.length - SHOW) + ' more (use --json for the full list)')}`);
+    p(`  ${C.gray('use')} ${C.dim('--full')} ${C.gray('for untruncated details and on-disk paths')}`);
+  }
+  p('');
 
-  // ---- next steps ----
-  console.log(`  ${rule()}`);
-  console.log(`  ${C.bold('What to do')}`);
+  // ---- what to do ----
+  p(`  ${C.bold('What to do')}`);
   if (counts.CRITICAL || counts.HIGH) {
-    console.log(`  ${C.red('•')} Treat ${C.bold('CRITICAL / HIGH "installed code" findings')} as suspect: do not run install`);
-    console.log(`    scripts, remove the package, clear the relevant cache, and rotate any npm /`);
-    console.log(`    GitHub / cloud tokens this machine has held.`);
+    p(`  ${C.red('•')} Treat ${C.bold('CRITICAL / HIGH "installed code" findings')} as suspect: don't run install`);
+    p(`    scripts, remove the package, clear the relevant cache, rotate npm / GitHub / cloud tokens.`);
   }
-  console.log(`  ${C.gray('•')} Check a flagged version against the registry: ${C.dim('npm view <pkg> versions')} ${C.gray('and look at')}`);
-  console.log(`    ${C.gray('publish dates and provenance.')}`);
-  if (osvFindings.length) console.log(`  ${C.gray('•')} OSV findings are the usual "known CVE in a dependency" set: ${C.dim('npm audit fix')} ${C.gray('/ bump.')}`);
-  if (!has('--online')) console.log(`  ${C.gray('•')} Re-run with ${C.dim('--online')} ${C.gray('to add OSV.dev advisory matching by exact version.')}`);
-  console.log('');
+  p(`  ${C.gray('•')} Check a flagged version against the registry: ${C.dim('npm view <pkg> versions')} ${C.gray('(publish dates, provenance).')}`);
+  if (sorted.some((f) => f.code === 'osv-advisory')) p(`  ${C.gray('•')} OSV rows are the usual "known CVE in a dependency" set: ${C.dim('npm audit fix')} ${C.gray('/ bump.')}`);
+  if (!has('--online')) p(`  ${C.gray('•')} Re-run with ${C.dim('--online')} ${C.gray('to add OSV.dev advisory matching by exact version.')}`);
+  p('');
 
   process.exit(res.findings.some((f) => f.sevNum >= minSev) ? 1 : 0);
 })();

package/lib/checks.js

@@ -14,7 +14,7 @@ const WORM_FILENAMES = [
   'truffleSecrets.json', 'actionsSecrets.json',
 ];
 // High-confidence exfiltration endpoints / payload constants seen in Shai-Hulud-family
-// worms. A mention of the string "shai-hulud" alone is NOT here on purpose — security
+// worms. A mention of the string "shai-hulud" alone is NOT here on purpose -- security
 // tools (including this one) legitimately contain that word.
 const WORM_HARD_MARKERS = [
   'webhook.site/bb8ca5f6-4175-45d2-b042-fc9ebb8170b7',
@@ -37,6 +37,13 @@ const NET_TOKENS = ['curl ', 'wget ', 'http://', 'https://', 'fetch(', 'net.conn
 const EXEC_TOKENS = ['child_process', 'execSync', 'spawnSync', 'exec(', 'spawn(', 'node -e', 'node --eval', 'eval(', 'Function(', 'vm.runInThisContext'];
 const ENCODE_TOKENS = ['base64 -d', "from('", 'Buffer.from(', 'atob(', 'fromCharCode', 'unescape('];
 
+/**
+ * Reads a file safely, returning its text and metadata.
+ * Truncates to `max` bytes if the file is larger.
+ * @param {string} p - Absolute path to the file.
+ * @param {number} [max=2_000_000] - Maximum bytes to read.
+ * @returns {{ truncated: boolean, text: string, size: number } | null} File contents, or null on error.
+ */
 function readSafe(p, max = 2_000_000) {
   try {
     const st = fs.statSync(p);
@@ -45,7 +52,25 @@ function readSafe(p, max = 2_000_000) {
   } catch { return null; }
 }
 
+/**
+ * Checks whether a token string appears in a source string.
+ * Iterates over a list of tokens and collects all matches.
+ * @param {string[]} tokens - List of substrings to look for.
+ * @param {string} src - Source string to search.
+ * @param {Set<string>} hits - Set to accumulate matching tokens into.
+ * @returns {void}
+ */
+function collectTokenHits(tokens, src, hits) {
+  for (const t of tokens) if (src.includes(t)) hits.add(t);
+}
+
 // 1. Lifecycle install hooks (the #1 detonation vector)
+/**
+ * Checks package.json lifecycle hooks for suspicious behaviour.
+ * Only inspects hooks that fire when a package is installed as a registry dependency.
+ * @param {{ manifest: { scripts?: Record<string, string> } }} pkg - Package object.
+ * @returns {{ sev: number, code: string, msg: string, evidence: string }[]} Array of findings.
+ */
 function checkLifecycleHooks(pkg) {
   const out = [];
   const s = (pkg.manifest && pkg.manifest.scripts) || {};
@@ -61,8 +86,8 @@ function checkLifecycleHooks(pkg) {
       || /^(node\s+)?(scripts\/)?install(\.js)?$/.test(c)
       || /^(ng-?ccc?|ngcc)\b/.test(c);
     const hits = new Set();
-    for (const t of [...NET_TOKENS, ...EXEC_TOKENS, ...ENCODE_TOKENS]) if (cmd.includes(t)) hits.add(t);
-    for (const t of SECRET_NAMES) if (cmd.toUpperCase().includes(t)) hits.add(t);
+    collectTokenHits([...NET_TOKENS, ...EXEC_TOKENS, ...ENCODE_TOKENS], cmd, hits);
+    collectTokenHits(SECRET_NAMES, cmd.toUpperCase(), hits);
     if (cmd.includes('.npmrc') || cmd.includes('/.ssh/') || cmd.includes('.aws/credentials')) hits.add('credential-file');
     const piped = /\b(curl|wget|fetch)\b[^|;&]*[|;&]+\s*(ba|z|d)?sh\b/.test(cmd) || /\|\s*node\b/.test(cmd);
 
@@ -70,13 +95,19 @@ function checkLifecycleHooks(pkg) {
     if (hits.size >= 3 || piped) sev = SEV.CRITICAL;
     else if (hits.size >= 1) sev = SEV.HIGH;
     else if (benign) sev = SEV.INFO;
-    else sev = SEV.LOW; // an unrecognised install hook — worth a glance, not an alarm
+    else sev = SEV.LOW; // an unrecognised install hook -- worth a glance, not an alarm
     out.push({ sev, code: 'lifecycle-hook', msg: `${h} script${hits.size ? ', touches: ' + [...hits].join(', ') : (benign ? ' (recognised build tool)' : ' (unrecognised command)')}`, evidence: `"${h}": ${cmd.slice(0, 240)}` });
   }
   return out;
 }
 
 // 2. Worm IOC files sitting inside the package
+/**
+ * Walks the package directory tree looking for known worm artifact filenames
+ * and embedded GitHub Actions workflow files.
+ * @param {{ dir: string }} pkg - Package object with a resolved directory path.
+ * @returns {{ sev: number, code: string, msg: string, evidence: string }[]} Array of findings.
+ */
 function checkWormFiles(pkg) {
   if (!pkg.dir) return [];
   const out = [];
@@ -107,11 +138,18 @@ function checkWormFiles(pkg) {
 }
 
 // 3. Obfuscated / packed JS payload heuristics on the package's own JS
+/**
+ * Scans JS files in the package for obfuscation patterns, worm IOC strings,
+ * and suspicious combinations of credential access and network calls.
+ * Applies per-file and per-package byte budgets to bound scan time.
+ * @param {{ dir: string }} pkg - Package object with a resolved directory path.
+ * @returns {{ sev: number, code: string, msg: string, evidence: string }[]} Array of findings.
+ */
 function checkObfuscation(pkg) {
   if (!pkg.dir) return [];
   const out = [];
   // Collect candidate JS files, then scan them under a strict per-package budget so a
-  // package full of huge vendored bundles (typescript.js, lighthouse bundles, …) can't
+  // package full of huge vendored bundles (typescript.js, lighthouse bundles, ...) can't
   // make a scan run for minutes.
   const files = [];
   const stack = [pkg.dir];
@@ -152,7 +190,7 @@ function checkObfuscation(pkg) {
       pkgByteBudget -= st.size;
     }
     const strong = [];   // each strong reason alone is reportable
-    const weak = [];      // weak reasons only matter in combination
+    const weak = [];     // weak reasons only matter in combination
     let critical = false;
 
     // --- "executable payload" context: dynamic code execution over decoded data, or
@@ -206,6 +244,12 @@ function checkObfuscation(pkg) {
 }
 
 // 4. Manifest oddities (cheap, offline)
+/**
+ * Inspects package.json for structural anomalies that warrant attention.
+ * Currently checks bin entries that point outside the package or to shell scripts.
+ * @param {{ manifest: object, name?: string }} pkg - Package object.
+ * @returns {{ sev: number, code: string, msg: string, evidence: string }[]} Array of findings.
+ */
 function checkManifestAnomalies(pkg) {
   const out = [];
   const m = pkg.manifest || {};
@@ -224,6 +268,12 @@ function checkManifestAnomalies(pkg) {
 let SELF = null;
 try { SELF = require('../package.json').name; } catch { /* ignore */ }
 
+/**
+ * Runs all checks against a single package and returns the combined findings.
+ * Skips pkgradar's own package to avoid false positives from IOC strings in this file.
+ * @param {{ name?: string, version?: string, dir?: string, store?: string, manifest?: object }} pkg - Package to inspect.
+ * @returns {{ sev: number, code: string, msg: string, evidence: string }[]} Combined findings from all checks.
+ */
 function runAll(pkg) {
   // Don't scan our own package: this file necessarily contains the IOC strings it
   // searches for, so scanning a cached copy of pkgradar would flag pkgradar.

package/lib/osv.js

@@ -1,11 +1,20 @@
 'use strict';
-// Optional online cross-reference against OSV.dev — precise (package, version) matching,
+// Optional online cross-reference against OSV.dev. Precise (package, version) matching,
 // no API key. Used only when --online is passed. Two phases:
-//   1. /v1/querybatch  — fast: which (name@version) have advisories at all
-//   2. /v1/query       — for just those packages, fetch full vuln objects so we can
-//                        read each advisory's real severity instead of blanket-HIGH.
+//   1. /v1/querybatch  fast: which (name@version) have advisories at all
+//   2. /v1/query       for just those packages, fetch full vuln objects so we can
+//                      read each advisory's real severity instead of blanket-HIGH.
 const https = require('https');
 
+/**
+ * Sends an HTTPS request and resolves with the parsed JSON response body.
+ * Rejects on HTTP 4xx/5xx, JSON parse error, network error, or 15 s timeout.
+ * @param {string} method - HTTP method (e.g. 'POST').
+ * @param {string} host - Hostname (e.g. 'api.osv.dev').
+ * @param {string} pathname - URL path (e.g. '/v1/querybatch').
+ * @param {object|null} body - Request body, serialised as JSON, or null for no body.
+ * @returns {Promise<object>} Parsed response JSON.
+ */
 function request(method, host, pathname, body) {
   return new Promise((resolve, reject) => {
     const data = body ? Buffer.from(JSON.stringify(body)) : null;
@@ -27,19 +36,32 @@ function request(method, host, pathname, body) {
 
 // CVSS v3 vector -> approximate numeric base score is non-trivial; instead bucket by the
 // vector's impact + exploitability shape. Good enough to pick LOW/MEDIUM/HIGH/CRITICAL.
+/**
+ * Approximates a severity bucket from a CVSS v3 vector string without full scoring math.
+ * Examines Confidentiality/Integrity/Availability impact and network/privilege/UI metrics.
+ * @param {string} vec - CVSS v3 vector string (e.g. 'CVSS:3.1/AV:N/AC:L/...').
+ * @returns {'CRITICAL'|'HIGH'|'MEDIUM'|'LOW'|null} Severity bucket, or null if unparseable.
+ */
 function bucketFromCvssVector(vec) {
   if (!vec || typeof vec !== 'string') return null;
-  const m = Object.fromEntries(vec.split('/').map((p) => p.split(':')).filter((a) => a.length === 2));
-  const impactHigh = ['C', 'I', 'A'].filter((k) => m[k] === 'H').length;
-  const network = m.AV === 'N';
-  const noPriv = m.PR === 'N' || m.PR === undefined;
-  const noUI = m.UI === 'N' || m.UI === undefined;
-  if (impactHigh >= 2 && network && noPriv && noUI) return 'CRITICAL';
-  if (impactHigh >= 1 && network && noPriv) return 'HIGH';
-  if (impactHigh >= 1) return 'MEDIUM';
+  const metrics = Object.fromEntries(vec.split('/').map((p) => p.split(':')).filter((a) => a.length === 2));
+  const impactHighCount = ['C', 'I', 'A'].filter((k) => metrics[k] === 'H').length;
+  const network = metrics.AV === 'N';
+  const noPriv = metrics.PR === 'N' || metrics.PR === undefined;
+  const noUI = metrics.UI === 'N' || metrics.UI === undefined;
+  if (impactHighCount >= 2 && network && noPriv && noUI) return 'CRITICAL';
+  if (impactHighCount >= 1 && network && noPriv) return 'HIGH';
+  if (impactHighCount >= 1) return 'MEDIUM';
   return 'LOW';
 }
 
+/**
+ * Derives a severity label for a single OSV vulnerability object.
+ * Tries database_specific.severity first, then numeric score, then CVSS vector bucketing.
+ * Defaults to MEDIUM when the data is ambiguous to avoid both over- and under-claiming.
+ * @param {object} v - OSV vulnerability object.
+ * @returns {'CRITICAL'|'HIGH'|'MEDIUM'|'LOW'}
+ */
 function severityOfVuln(v) {
   const ds = v.database_specific && (v.database_specific.severity || v.database_specific.cvss);
   if (typeof ds === 'string') {
@@ -58,14 +80,21 @@ function severityOfVuln(v) {
         if (num >= 4) return 'MEDIUM';
         return 'LOW';
       }
-      const b = bucketFromCvssVector(s.score);
-      if (b) return b;
+      const bucket = bucketFromCvssVector(s.score);
+      if (bucket) return bucket;
     }
   }
   return 'MEDIUM'; // unknown -> don't over- or under-claim
 }
 
-// pkgs: [{name, version}]. Returns Map "name@version" -> [{ id, severity, summary }]
+/**
+ * Queries OSV.dev for known advisories for a list of npm packages.
+ * Phase 1: batched querybatch to find which packages have any advisories.
+ * Phase 2: parallel per-package queries (up to 8 concurrent) to fetch full details.
+ * @param {{name:string, version:string}[]} pkgs - Packages to look up.
+ * @returns {Promise<Map<string, {id:string, severity:string, summary:string}[]>>}
+ *   Map from "name@version" to list of advisory summaries.
+ */
 async function queryOSV(pkgs) {
   const uniq = new Map();
   for (const p of pkgs) if (p.name && p.version) uniq.set(`${p.name}@${p.version}`, p);
@@ -90,7 +119,7 @@ async function queryOSV(pkgs) {
         const resp = await request('POST', 'api.osv.dev', '/v1/query', { package: { ecosystem: 'npm', name: p.name }, version: p.version });
         const vulns = (resp.vulns || []).map((v) => ({ id: v.id, severity: severityOfVuln(v), summary: v.summary || '' }));
         if (vulns.length) result.set(`${p.name}@${p.version}`, vulns);
-      } catch { /* skip this one */ }
+      } catch { /* skip this package if its individual query fails */ }
     }
   };
   await Promise.all(Array.from({ length: Math.min(8, queue.length) }, worker));

package/lib/scan.js

@@ -3,32 +3,62 @@ const { discoverStores, packagesInStore } = require('./stores');
 const { runAll, SEV } = require('./checks');
 const { queryOSV } = require('./osv');
 
+/** Maps numeric severity level to display name. */
 const SEV_NAME = { 4: 'CRITICAL', 3: 'HIGH', 2: 'MEDIUM', 1: 'LOW', 0: 'INFO' };
 
+// Load the optional allowlist. Names ending with "/*" are treated as scope prefixes.
 let ALLOW_EXACT = new Set(), ALLOW_SCOPES = [];
 try {
   const a = require('../data/allowlist.json');
   for (const n of a.names || []) { if (n.endsWith('/*')) ALLOW_SCOPES.push(n.slice(0, -1)); else ALLOW_EXACT.add(n); }
 } catch { /* allowlist optional */ }
+
+/**
+ * Returns true if the given package name is on the static allowlist.
+ * @param {string} name - npm package name
+ * @returns {boolean}
+ */
 function isAllowlisted(name) {
   if (ALLOW_EXACT.has(name)) return true;
   return ALLOW_SCOPES.some((s) => name.startsWith(s));
 }
 
+/**
+ * Scan installed packages for supply-chain indicators of compromise.
+ *
+ * @param {object} [opts]
+ * @param {string}   [opts.cwd]          - Project root to scan (defaults to process.cwd()).
+ * @param {boolean}  [opts.online]       - If true, cross-check OSV.dev for known advisories.
+ * @param {number}   [opts.minSev]       - Minimum severity number to include (SEV.* constants).
+ * @param {number}   [opts.maxDepth]     - Max node_modules nesting depth passed to packagesInStore.
+ * @param {string[]} [opts.stores]       - Allowlist of store kinds to scan; empty means all.
+ * @param {boolean}  [opts.noAllowlist]  - If true, skip allowlist downgrade logic.
+ * @param {Function} [opts.onPhase]      - Progress callback receiving a status string.
+ * @returns {Promise<{cwd:string, stores:object[], totalPackages:number, totalScanned:number, findings:object[], osv:object|null}>}
+ */
 async function scan(opts = {}) {
   const cwd = opts.cwd || process.cwd();
   const stores = discoverStores(cwd);
   const kindFilter = Array.isArray(opts.stores) && opts.stores.length ? new Set(opts.stores) : null;
   const storeStats = [];
-  const seen = new Map();        // "name@version@dir" -> pkg (dedupe)
+  // Keyed by "name@version@dir" to deduplicate packages seen in the same location.
+  const seen = new Map();
   const findings = [];
   const allPkgList = [];
 
+  const tick = typeof opts.onPhase === 'function' ? opts.onPhase : () => {};
+
+  /** Yields to the event loop so spinner frames can render between heavy iterations. */
+  const yieldToLoop = () => new Promise((r) => setImmediate(r));
+
   for (const store of stores) {
     if (kindFilter && !kindFilter.has(store.kind)) continue;
+    tick(`scanning ${store.kind}`);
+    await yieldToLoop();
     let count = 0;
     for (const pkg of packagesInStore(store, { maxDepth: opts.maxDepth })) {
       count++;
+      if (count % 100 === 0) { tick(`scanning ${store.kind} (${count} packages)`); await yieldToLoop(); }
       const key = `${pkg.name}@${pkg.version}@${pkg.dir || store.root}`;
       if (seen.has(key)) continue;
       seen.set(key, pkg);
@@ -37,7 +67,7 @@ async function scan(opts = {}) {
       const allow = !opts.noAllowlist && isAllowlisted(pkg.name);
       for (const f of runAll(pkg)) {
         let sev = f.sev, note;
-        // allowlist downgrades benign-looking findings — but NEVER suppresses a hard worm
+        // Allowlist downgrades benign-looking findings, but NEVER suppresses a hard worm
         // IOC (worm-ioc-file / CRITICAL suspicious-js), since that's the compromise case.
         if (allow && sev < SEV.CRITICAL) { sev = SEV.INFO; note = 'allowlisted package, heuristic likely benign; review only if context warrants'; }
         if (sev < (opts.minSev ?? SEV.MEDIUM)) continue;
@@ -53,12 +83,14 @@ async function scan(opts = {}) {
   let osv = null;
   if (opts.online) {
     try {
-      const map = await queryOSV(allPkgList);
+      tick('cross-checking OSV.dev advisories');
+      const osvMap = await queryOSV(allPkgList);
       osv = [];
       const SEV_RANK = { CRITICAL: SEV.CRITICAL, HIGH: SEV.HIGH, MEDIUM: SEV.MEDIUM, LOW: SEV.LOW };
-      for (const [nv, vulns] of map) {
+      for (const [nv, vulns] of osvMap) {
         const [name, version] = splitNV(nv);
         const top = vulns.reduce((m, v) => Math.max(m, SEV_RANK[v.severity] ?? SEV.MEDIUM), SEV.LOW);
+        // Build a "3 high, 1 medium" style breakdown string.
         const bySev = {};
         for (const v of vulns) bySev[v.severity] = (bySev[v.severity] || 0) + 1;
         const breakdown = ['CRITICAL', 'HIGH', 'MEDIUM', 'LOW'].filter((k) => bySev[k]).map((k) => `${bySev[k]} ${k.toLowerCase()}`).join(', ');
@@ -94,6 +126,12 @@ async function scan(opts = {}) {
   return { cwd, stores: storeStats, totalPackages, totalScanned: seen.size, findings: deduped, osv };
 }
 
+/**
+ * Split a "name@version" key produced by queryOSV back into its parts.
+ * Uses the last "@" so scoped names like "@scope/pkg@1.0.0" work correctly.
+ * @param {string} nv - Combined name-at-version string.
+ * @returns {[string, string]} Tuple of [name, version].
+ */
 function splitNV(nv) { const i = nv.lastIndexOf('@'); return [nv.slice(0, i), nv.slice(i + 1)]; }
 
 module.exports = { scan, SEV };

package/lib/stores.js

@@ -6,10 +6,33 @@ const path = require('path');
 const os = require('os');
 const cp = require('child_process');
 
+/**
+ * Returns true if the path exists and is accessible, false otherwise.
+ * @param {string} p - Filesystem path to test.
+ * @returns {boolean}
+ */
 const exists = (p) => { try { fs.accessSync(p); return true; } catch { return false; } };
+
+/**
+ * Returns directory entries for a path, or an empty array on any error.
+ * @param {string} p - Directory path.
+ * @returns {fs.Dirent[]}
+ */
 const readdir = (p) => { try { return fs.readdirSync(p, { withFileTypes: true }); } catch { return []; } };
+
+/**
+ * Runs a shell command and returns its trimmed stdout, or '' on failure.
+ * @param {string} cmd - Shell command to execute.
+ * @returns {string}
+ */
 const sh = (cmd) => { try { return cp.execSync(cmd, { stdio: ['ignore', 'pipe', 'ignore'] }).toString().trim(); } catch { return ''; } };
 
+/**
+ * Finds all package-manager store roots relevant to the given working directory.
+ * Checks project-local node_modules, npm/pnpm/yarn/bun global and cache locations.
+ * @param {string} cwd - Project root directory.
+ * @returns {{kind:string, root:string, note:string}[]} List of discovered stores.
+ */
 function discoverStores(cwd) {
   const home = os.homedir();
   const out = [];
@@ -17,7 +40,7 @@ function discoverStores(cwd) {
 
   add('project', path.join(cwd, 'node_modules'), 'current project node_modules');
   add('pnpm-project', path.join(cwd, 'node_modules', '.pnpm'), 'pnpm in-project store');
-  const g = sh('npm root -g'); if (g) add('npm-global', g, 'npm global packages');
+  const npmGlobal = sh('npm root -g'); if (npmGlobal) add('npm-global', npmGlobal, 'npm global packages');
   add('npx-cache', path.join(home, '.npm', '_npx'), 'npx ephemeral installs');
   add('bun-cache', path.join(home, '.bun', 'install', 'cache'), 'bun global cache');
   add('bun-cache', path.join(home, '.cache', 'bun', 'install', 'cache'), 'bun cache (xdg)');
@@ -26,26 +49,47 @@ function discoverStores(cwd) {
     path.join(home, '.local', 'share', 'pnpm', 'store'),
     process.env.PNPM_HOME && path.join(process.env.PNPM_HOME, 'store'),
   ].filter(Boolean)) add('pnpm-store', p, 'pnpm global content store (count only)');
-  const yc = sh('yarn cache dir'); if (yc) add('yarn-cache', yc, 'yarn v1 cache');
+  const yarnCache = sh('yarn cache dir'); if (yarnCache) add('yarn-cache', yarnCache, 'yarn v1 cache');
   add('yarn-berry', path.join(cwd, '.yarn', 'cache'), 'yarn berry zip cache (names only)');
   return out;
 }
 
+/**
+ * Reads and parses the package.json inside a directory.
+ * @param {string} dir - Directory that should contain package.json.
+ * @returns {object|null} Parsed manifest, or null if missing or unparseable.
+ */
 function readManifest(dir) {
   try { return JSON.parse(fs.readFileSync(path.join(dir, 'package.json'), 'utf8')); } catch { return null; }
 }
+
+/**
+ * Builds a pkg object from a directory and a store, or null if no valid manifest.
+ * @param {string} dir - Extracted package directory.
+ * @param {{kind:string, root:string, note:string}} store - Parent store object.
+ * @returns {{name:string, version:string, dir:string, store:object, manifest:object}|null}
+ */
 function pkgFromDir(dir, store) {
   const m = readManifest(dir);
   if (!m) return null;
   return { name: m.name || path.basename(dir), version: m.version || '', dir, store, manifest: m };
 }
 
+/**
+ * Recursively yields pkg objects from a node_modules tree, handling scoped packages.
+ * @param {string} nmDir - node_modules directory to walk.
+ * @param {{kind:string, root:string, note:string}} store - Owning store.
+ * @param {number} maxDepth - Maximum recursion depth for nested node_modules.
+ * @param {number} [depth=0] - Current recursion depth.
+ * @yields {{name:string, version:string, dir:string, store:object, manifest:object}}
+ */
 function* walkTree(nmDir, store, maxDepth, depth = 0) {
   if (depth > maxDepth || !exists(nmDir)) return;
   for (const ent of readdir(nmDir)) {
     if (ent.name.startsWith('.')) continue;
     const full = path.join(nmDir, ent.name);
     if (ent.name.startsWith('@')) {
+      // scoped packages: one more level for "@scope/pkg-name"
       for (const sub of readdir(full)) {
         const d = path.join(full, sub.name);
         const p = pkgFromDir(d, store); if (p) yield p;
@@ -58,6 +102,14 @@ function* walkTree(nmDir, store, maxDepth, depth = 0) {
   }
 }
 
+/**
+ * Yields every pkg found in the given store, adapting traversal to the store kind.
+ * Handles bun-cache, yarn-berry (zip names only), pnpm-store (skipped, content-addressed),
+ * npx-cache, pnpm-project, and conventional node_modules trees.
+ * @param {{kind:string, root:string, note:string}} store - Store to enumerate.
+ * @param {{maxDepth?:number}} [opts={}] - Options; maxDepth limits node_modules nesting.
+ * @yields {{name:string, version:string, dir:string|null, store:object, manifest?:object}}
+ */
 function* packagesInStore(store, opts = {}) {
   const maxDepth = opts.maxDepth || 12;
   switch (store.kind) {
@@ -72,6 +124,7 @@ function* packagesInStore(store, opts = {}) {
       return;
     }
     case 'yarn-berry': {
+      // zip archives: parse name and version from filename, no extracted tree to walk
       for (const ent of readdir(store.root)) {
         if (ent.isFile() && ent.name.endsWith('.zip')) {
           const m = ent.name.match(/^(.*)-npm-(.+)-[a-f0-9]{8,}\.zip$/);
@@ -83,6 +136,7 @@ function* packagesInStore(store, opts = {}) {
     case 'pnpm-store': return; // content-addressed blobs; not extracted trees
     case 'npx-cache':
     case 'pnpm-project': {
+      // each subdirectory is a separate install hash; node_modules lives one level in
       for (const ent of readdir(store.root)) {
         if (ent.isDirectory()) yield* walkTree(path.join(store.root, ent.name, 'node_modules'), store, maxDepth);
       }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pkgradar",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "Content-based supply-chain scanner for npm/pnpm/yarn/bun: inspects the bytes you actually installed (lifecycle hooks, obfuscated payloads, worm IOCs) instead of just matching package names against an advisory list.",
   "bin": {
     "pkgradar": "bin/pkgradar.js"