pkgradar 0.1.2 → 0.1.4

package/bin/pkgradar.js

@@ -8,8 +8,21 @@ const PKG = require('../package.json');
 // 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);
-const val = (f, d) => { const i = argv.indexOf(f); return i >= 0 && argv[i + 1] ? argv[i + 1] : d; };
+
+/**
+ * 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')) {
   process.stdout.write(`pkgradar  -  content-based supply-chain scanner for npm / pnpm / yarn / bun
@@ -24,7 +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
+  --compact           one terse line per finding instead of full blocks
   --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
@@ -49,32 +62,50 @@ const minSev = SEV_FROM_NAME[minSevName] ?? SEV.MEDIUM;
 // 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: 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'),
 };
-// coloured "  CRITICAL  " cell: white-on-colour, fixed width
-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.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;
 
 // ----------------------------------------------------------------------------
 // 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'); },
   };
 }
@@ -82,13 +113,28 @@ function makeSpinner() {
 // ----------------------------------------------------------------------------
 // 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
- * @param {object[]} rows
+ * @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;
@@ -100,7 +146,7 @@ function table(cols, rows) {
   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)
+      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) + ' ';
     });
@@ -110,9 +156,45 @@ function table(cols, rows) {
   return out.join('\n');
 }
 
+/**
+ * Word-wrap a plain string to a column width, returning an array of lines.
+ * Tokens longer than the width are hard-split so nothing overflows.
+ * @param {string} text  - Text to wrap (no ANSI codes).
+ * @param {number} width - Max characters per line.
+ * @returns {string[]}
+ */
+function wrap(text, width) {
+  const words = String(text || '').split(/\s+/).filter(Boolean);
+  const lines = [];
+  let cur = '';
+  for (let w of words) {
+    while (w.length > width) { if (cur) { lines.push(cur); cur = ''; } lines.push(w.slice(0, width)); w = w.slice(width); }
+    if (!cur) cur = w;
+    else if (cur.length + 1 + w.length <= width) cur += ' ' + w;
+    else { lines.push(cur); cur = w; }
+  }
+  if (cur) lines.push(cur);
+  return lines.length ? lines : [''];
+}
+
+/** One-line plain-language explanation of why each finding type matters. */
+const WHY = {
+  'lifecycle-hook': 'install hooks run automatically on npm/yarn/pnpm install; this one does something a normal build step would not',
+  'worm-ioc-file': 'this filename is a known artifact of the Shai-Hulud worm family',
+  'suspicious-js': 'code that decodes and then executes a payload, or hard-coded worm exfiltration constants',
+  'embedded-gh-workflow': 'harmless on its own; just noting the package ships a CI workflow file',
+  'malicious-gh-workflow': 'a bundled GitHub Actions workflow that pipes a remote script straight into a shell',
+  'odd-bin': 'a bin entry pointing outside the package or at a shell script is unusual for a dependency',
+  'osv-advisory': 'a publicly known vulnerability affects this exact version; check whether a patched release exists',
+};
+
+/** ●-marker colour by severity, used at the start of each finding block. */
+const SEV_DOT = { CRITICAL: C.red('●'), HIGH: C.mag('●'), MEDIUM: C.ylw('●'), LOW: C.gray('●'), INFO: C.gray('○') };
+
 // ----------------------------------------------------------------------------
 // main
 // ----------------------------------------------------------------------------
+/** Entry point: parses CLI flags, calls scan(), then renders results to stdout. */
 (async () => {
   const spin = makeSpinner();
   spin.start();
@@ -145,6 +227,8 @@ function table(cols, rows) {
   const counts = { CRITICAL: 0, HIGH: 0, MEDIUM: 0, LOW: 0, INFO: 0 };
   for (const f of res.findings) counts[f.severity]++;
   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 ----
@@ -180,41 +264,41 @@ function table(cols, rows) {
   p('');
 
   // ---- findings ----
+  // Grouped by severity, one readable block per finding. A fixed-width table would
+  // truncate the detail text, so we wrap it to the terminal instead.
   const sorted = res.findings.slice().sort((a, b) => b.sevNum - a.sevNum || a.code.localeCompare(b.code) || a.package.localeCompare(b.package));
+  const term = Math.max(60, Math.min(process.stdout.columns || 100, 120));
+  const ORDER = ['CRITICAL', 'HIGH', 'MEDIUM', 'LOW', 'INFO'];
 
-  if (has('--full')) {
+  if (has('--compact')) {
+    // one terse line per finding
+    const pkgW = Math.min(34, Math.max(...sorted.map((f) => (f.package + '@' + f.version).length)));
     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('');
+      p(`  ${SEV_DOT[f.severity]} ${SEV_TEXT[f.severity](f.severity.padEnd(8))} ${C.bold(padTo(clip(f.package + '@' + f.version, pkgW), pkgW))}  ${C.cyan(padTo(f.code, 21))} ${C.gray(clip(f.evidence || f.message, term - pkgW - 36))}`);
     }
   } 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')}`);
+    const FW = term - 13;                                    // width available for wrapped field text
+    /** Print a labelled, word-wrapped field under a finding (label only on the first line). */
+    const field = (key, text, paint) => {
+      if (text == null || text === '') return;
+      wrap(text, FW).forEach((ln, i) => p(`      ${C.gray((i === 0 ? key : '').padEnd(9))} ${paint ? paint(ln) : ln}`));
+    };
+    for (const sev of ORDER) {
+      const group = sorted.filter((f) => f.severity === sev);
+      if (!group.length) continue;
+      p(`  ${SEV_TEXT[sev](C.bold(sev))} ${C.gray('· ' + group.length)}`);
+      p(`  ${C.gray('─'.repeat(term - 2))}`);
+      for (const f of group) {
+        p(`  ${SEV_DOT[sev]} ${C.bold(f.package + '@' + f.version)}   ${C.cyan(f.code)}   ${C.gray('in ' + f.store)}`);
+        field('what', f.message);
+        field('evidence', f.evidence, C.gray);
+        field('why', WHY[f.code], C.gray);
+        field('note', f.note, C.gray);
+        if (f.dir) p(`      ${C.gray('path'.padEnd(9))} ${C.gray(homeShort(f.dir))}`);
+        p('');
+      }
+    }
+    p(`  ${C.gray('use')} ${C.dim('--compact')} ${C.gray('for a one-line-per-finding view, or')} ${C.dim('--json')} ${C.gray('for machine output')}`);
   }
   p('');
 

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,28 +3,52 @@ 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) {
@@ -43,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;
@@ -60,12 +84,13 @@ async function scan(opts = {}) {
   if (opts.online) {
     try {
       tick('cross-checking OSV.dev advisories');
-      const map = await queryOSV(allPkgList);
+      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(', ');
@@ -101,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.2",
+  "version": "0.1.4",
   "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"