polin-guard 0.2.0 → 0.3.0

package/README.md

@@ -123,20 +123,48 @@ Drop [`scan-injection.sh`](scan-injection.sh) into your repo (works with the
 ## Usage
 
 ```text
-polin-guard [options] [paths...]
+polin-guard [scan] [options] [paths...]   Scan files for injected payloads (default)
+polin-guard install-audit [--strict]      Audit dependencies for supply-chain risk
+polin-guard harden [--fix]                Check/enable install-time hardening
 
+Scan options:
   --staged     Scan staged content (default; for pre-commit hooks; covers --amend)
   --all        Scan all git-tracked files
   --ci         Alias for --all (use in CI)
   [paths...]   Scan specific files (no git required)
   --strict     Treat warnings as blocking too
-  --quiet      Only print on findings
-  -h, --help   Show help
-  -v, --version
+  -h, --help   ·   -v, --version
 
 Exit 0 = clean · 1 = blocking finding · 2 = usage error
 ```
 
+## Supply-chain audit (root-cause defense)
+
+The scanner catches a payload that's already in your tree. **`install-audit`
+attacks the entry point** — the malicious dependency that runs code at
+`npm install`/build time — without installing anything:
+
+```bash
+npx polin-guard install-audit
+```
+
+It flags, by reading `package.json` and your lockfile:
+
+- 🔴 **malicious lifecycle scripts** — `postinstall`/`prepare`/… that pipe the
+  network to a shell, `eval`, `node -e`, base64, raw-IP URLs, `child_process`
+- 🔴 **non-default registry** resolutions in the lockfile (registry hijack)
+- 🔴 **typosquat / homoglyph** dependency names (one edit away from popular packages)
+- 🟡 **non-registry sources** (git/http/tarball/file) dependencies
+- ℹ️ a **count of packages that declare install/build scripts** — your real attack surface
+
+Then **shut the door** so dependency scripts can't execute at all:
+
+```bash
+npx polin-guard harden --fix     # writes ignore-scripts=true to .npmrc
+```
+
+Run `install-audit` in CI too — see [`examples/github-action.yml`](examples/github-action.yml).
+
 ## Configuration
 
 Optional `.polinguardrc.json` in your repo root:

package/bin/cli.js

@@ -2,17 +2,20 @@
 'use strict';
 
 const { run } = require('../src/scan');
+const { auditInstall, harden } = require('../src/supplychain');
 
-const HELP = `polin-guard — block obfuscated code-injection payloads before they are committed
+const HELP = `polin-guard — stop obfuscated injection & malicious dependencies
 
 Usage:
-  polin-guard [options] [paths...]
+  polin-guard [scan] [options] [paths...]   Scan files for injected payloads (default)
+  polin-guard install-audit [options]       Audit dependencies for supply-chain risk
+  polin-guard harden [--fix]                Check/enable install-time hardening
 
-Modes:
-  --staged        Scan files staged for commit (default; use in pre-commit hooks).
+Scan modes:
+  --staged        Scan files staged for commit (default; for pre-commit hooks).
   --all           Scan all git-tracked files.
   --ci            Alias for --all (use in CI).
-  [paths...]      Scan specific files/globs (no git required).
+  [paths...]      Scan specific files (no git required).
 
 Options:
   --strict        Treat warnings as blocking (exit non-zero on warnings too).
@@ -21,95 +24,113 @@ Options:
   -h, --help      Show this help.
   -v, --version   Show version.
 
-Exit codes:
-  0  clean (or only warnings without --strict)
-  1  blocking finding(s) detected
-  2  usage / runtime error
+Exit codes:  0 clean · 1 blocking finding(s) · 2 usage/runtime error
 
-Docs & allowlisting: see README. Add a config via .polinguardrc.json.`;
+Docs & allowlisting: see README. Scan config via .polinguardrc.json.`;
 
-function parseArgs(argv) {
-  const o = { mode: 'staged', paths: [], strict: false, quiet: false, color: true };
+function paint(s, code, enabled) {
+  const ESC = String.fromCharCode(27);
+  return enabled ? ESC + '[' + code + 'm' + s + ESC + '[0m' : s;
+}
+const useColor = (argv) => !argv.includes('--no-color') && process.stdout.isTTY;
+
+/** Shared pretty-printer for a list of {severity, ruleId, message, where|file,line}. */
+function printFindings(title, findings, blocking, c) {
+  const header = blocking
+    ? paint(`✖ ${title}`, '1;31', c)
+    : paint(`⚠ ${title}`, '33', c);
+  process.stderr.write(`\n${header}\n\n`);
+  for (const f of findings) {
+    const tag = f.severity === 'critical' ? paint('CRITICAL', '1;31', c)
+      : f.severity === 'warning' ? paint('warning ', '33', c)
+      : paint('info    ', '36', c);
+    const loc = f.where || (f.line === 0 ? `${f.file} (file-level)` : `${f.file}:${f.line}`);
+    process.stderr.write(`  ${tag} ${paint(loc, '36', c)}  [${f.ruleId}]\n            ${f.message}\n`);
+  }
+  process.stderr.write('\n');
+}
+
+function cmdScan(argv) {
+  const o = { mode: 'staged', paths: [], strict: false, quiet: false };
   for (const a of argv) {
     if (a === '--staged') o.mode = 'staged';
     else if (a === '--all' || a === '--ci') o.mode = 'all';
     else if (a === '--strict') o.strict = true;
     else if (a === '--quiet') o.quiet = true;
-    else if (a === '--no-color') o.color = false;
-    else if (a === '-h' || a === '--help') o.help = true;
-    else if (a === '-v' || a === '--version') o.version = true;
-    else if (a.startsWith('-')) { o.unknown = a; }
+    else if (a === '--no-color') { /* handled globally */ }
+    else if (a.startsWith('-')) { process.stderr.write(`polin-guard: unknown option ${a}\n`); return 2; }
     else { o.paths.push(a); o.mode = 'paths'; }
   }
-  return o;
-}
+  const c = useColor(argv);
 
-function paint(s, code, enabled) {
-  const ESC = String.fromCharCode(27);
-  return enabled ? ESC + "[" + code + "m" + s + ESC + "[0m" : s;
-}
-
-function main() {
-  const o = parseArgs(process.argv.slice(2));
-  const c = o.color && process.stdout.isTTY;
+  let res;
+  try { res = run({ mode: o.mode, paths: o.paths, strict: o.strict }); }
+  catch (e) { process.stderr.write(`polin-guard: ${e.message}\n`); return 2; }
 
-  if (o.help) { process.stdout.write(HELP + '\n'); return 0; }
-  if (o.version) {
-    try { process.stdout.write(require('../package.json').version + '\n'); } catch { process.stdout.write('0.0.0\n'); }
+  if (res.findings.length === 0) {
+    if (!o.quiet) process.stdout.write(paint('✓ polin-guard: no injection indicators found', '32', c) +
+      ` (${res.filesScanned} file${res.filesScanned === 1 ? '' : 's'} scanned)\n`);
     return 0;
   }
-  if (o.unknown) { process.stderr.write(`polin-guard: unknown option ${o.unknown}\n`); return 2; }
+  printFindings('polin-guard: potential code injection detected', res.findings, res.blocking, c);
+  if (res.blocking) {
+    process.stderr.write(
+      'Commit blocked. If this is a genuine attack, do NOT commit — investigate the file.\n' +
+      'Verified false positive? Use a "// polinguard-allow-line" comment or .polinguardrc.json.\n' +
+      '(Bypass for one commit: git commit --no-verify.)\n');
+    return 1;
+  }
+  process.stderr.write('Warnings only — not blocking. Use --strict to block on warnings.\n');
+  return 0;
+}
 
+function cmdAudit(argv) {
+  const strict = argv.includes('--strict');
+  const quiet = argv.includes('--quiet');
+  const c = useColor(argv);
   let res;
-  try {
-    res = run({ mode: o.mode, paths: o.paths, strict: o.strict });
-  } catch (e) {
-    process.stderr.write(`polin-guard: ${e.message}\n`);
-    return 2;
-  }
+  try { res = auditInstall(process.cwd()); }
+  catch (e) { process.stderr.write(`polin-guard: ${e.message}\n`); return 2; }
 
+  const blocking = strict ? (res.critical.length + res.warnings.length) > 0 : res.critical.length > 0;
   if (res.findings.length === 0) {
-    if (!o.quiet) {
-      process.stdout.write(paint('✓ polin-guard: no injection indicators found', '32', c) +
-        ` (${res.filesScanned} file${res.filesScanned === 1 ? '' : 's'} scanned)\n`);
-    }
+    if (!quiet) process.stdout.write(paint('✓ polin-guard: no supply-chain risks found', '32', c) + '\n');
     return 0;
   }
+  printFindings('polin-guard: supply-chain risks detected', res.findings, blocking, c);
+  process.stderr.write(`${res.critical.length} critical, ${res.warnings.length} warning(s). ` +
+    `Run \`polin-guard harden --fix\` to block install scripts.\n`);
+  return blocking ? 1 : 0;
+}
 
-  const header = res.blocking
-    ? paint('✖ polin-guard: potential code injection detected', '1;31', c)
-    : paint('⚠ polin-guard: review-worthy findings', '33', c);
-  process.stderr.write(`\n${header}\n\n`);
+function cmdHarden(argv) {
+  const fix = argv.includes('--fix');
+  const c = useColor(argv);
+  let r;
+  try { r = harden(process.cwd(), { fix }); }
+  catch (e) { process.stderr.write(`polin-guard: ${e.message}\n`); return 2; }
 
-  // Group findings by file.
-  const byFile = new Map();
-  for (const f of res.findings) {
-    if (!byFile.has(f.file)) byFile.set(f.file, []);
-    byFile.get(f.file).push(f);
-  }
-  for (const [file, items] of byFile) {
-    process.stderr.write(paint(file, '36', c) + '\n');
-    for (const it of items) {
-      const tag = it.severity === 'critical'
-        ? paint('CRITICAL', '1;31', c)
-        : paint('warning ', '33', c);
-      const loc = it.line === 0 ? `${file} (file-level)` : `${file}:${it.line}`;
-      process.stderr.write(`  ${tag} ${loc}  [${it.ruleId}]\n            ${it.message}\n`);
-    }
-    process.stderr.write('\n');
-  }
+  if (r.hasIgnore) process.stdout.write(paint('✓ ignore-scripts is already enabled', '32', c) + ` (${r.npmrc})\n`);
+  else if (r.applied) process.stdout.write(paint('✓ enabled ignore-scripts=true', '32', c) + ` in ${r.npmrc}\n`);
+  else process.stdout.write(paint('⚠ ignore-scripts is NOT enabled', '33', c) + ` — run \`polin-guard harden --fix\` to set it.\n`);
 
-  if (res.blocking) {
-    process.stderr.write(
-      'Commit blocked. If this is a genuine attack, do NOT commit — investigate the file.\n' +
-      'If this is a verified false positive, acknowledge the line with a\n' +
-      `"// polinguard-allow-line" comment, an "polinguard-allow-next-line" comment above it,\n` +
-      'or adjust .polinguardrc.json. (Bypass for one commit: git commit --no-verify.)\n'
-    );
-    return 1;
-  }
-  process.stderr.write('Warnings only — not blocking. Use --strict to block on warnings.\n');
+  process.stdout.write('\nRecommendations:\n');
+  for (const rec of r.recommendations) process.stdout.write(`  • ${rec}\n`);
   return 0;
 }
 
+function main() {
+  const argv = process.argv.slice(2);
+  if (argv.includes('-h') || argv.includes('--help')) { process.stdout.write(HELP + '\n'); return 0; }
+  if (argv.includes('-v') || argv.includes('--version')) {
+    try { process.stdout.write(require('../package.json').version + '\n'); } catch { process.stdout.write('0.0.0\n'); }
+    return 0;
+  }
+  const sub = argv[0];
+  if (sub === 'install-audit' || sub === 'audit') return cmdAudit(argv.slice(1));
+  if (sub === 'harden') return cmdHarden(argv.slice(1));
+  if (sub === 'scan') return cmdScan(argv.slice(1));
+  return cmdScan(argv); // default: scan
+}
+
 process.exit(main());

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "polin-guard",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Block obfuscated build/commit-time code-injection payloads (hidden long-line JS stagers) before they enter your repo. Zero dependencies. Works as a pre-commit hook, in CI, or standalone.",
   "bin": {
     "polin-guard": "bin/cli.js"

package/src/supplychain.js

@@ -0,0 +1,235 @@
+'use strict';
+
+/**
+ * Supply-chain layer for polin-guard.
+ *
+ * The scanner (scan.js) catches a payload that is already in your tree. This
+ * module attacks the *root cause*: a malicious dependency that executes code at
+ * `npm install` / build time. It reads manifests and lockfiles WITHOUT installing
+ * anything, and flags the vectors that actually deliver these attacks:
+ *
+ *   - lifecycle install scripts (pre/post-install, prepare, …) — how install-time
+ *     code runs at all — and especially scripts that pipe the network to a shell
+ *   - dependencies pulled from non-registry sources (git/http/tarball/file)
+ *   - packages resolved from a non-default registry (registry hijack)
+ *   - transitive packages that declare an install/build script (the real surface)
+ *   - typosquatted / homoglyph package names
+ *
+ * `harden()` flips on the defenses (ignore-scripts) so install scripts can't run.
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const LIFECYCLE = [
+  'preinstall', 'install', 'postinstall',
+  'preuninstall', 'postuninstall',
+  'prepare', 'prepublish', 'prepublishOnly', 'prepack', 'postpack',
+];
+
+// Commands inside a script that strongly indicate malicious install-time code.
+const SUSPICIOUS_SCRIPT = new RegExp(
+  [
+    '(?:curl|wget)\\s+[^|&;]*\\|\\s*(?:sh|bash|node|python)', // curl … | sh
+    '\\bnode\\s+(?:-e|--eval)\\b', // node -e "…"
+    '\\bbash\\s+-c\\b',
+    'base64\\s+(?:-d|--decode|-D)',
+    '\\beval\\b',
+    '\\b(?:powershell|iwr|Invoke-WebRequest|certutil)\\b',
+    '\\bchild_process\\b',
+    'https?:\\/\\/\\d{1,3}(?:\\.\\d{1,3}){3}', // raw IP URL
+    '\\b(?:atob|fromCharCode)\\b',
+    '\\/dev\\/tcp\\/',
+  ].join('|'),
+  'i'
+);
+
+// A small set of very popular packages, for typosquat distance checks.
+const POPULAR = [
+  'react', 'react-dom', 'lodash', 'express', 'chalk', 'axios', 'commander',
+  'webpack', 'vue', 'next', 'nuxt', 'vite', 'eslint', 'prettier', 'typescript',
+  'tailwindcss', 'dotenv', 'jest', 'babel', 'rollup', 'moment', 'dayjs',
+  'request', 'debug', 'colors', 'cross-env', 'node-fetch', 'uuid',
+];
+
+const DEFAULT_REGISTRY_HOSTS = new Set(['registry.npmjs.org']);
+
+function levenshtein(a, b) {
+  const m = a.length, n = b.length;
+  const d = Array.from({ length: m + 1 }, (_, i) => [i, ...Array(n).fill(0)]);
+  for (let j = 0; j <= n; j++) d[0][j] = j;
+  for (let i = 1; i <= m; i++) {
+    for (let j = 1; j <= n; j++) {
+      const cost = a[i - 1] === b[j - 1] ? 0 : 1;
+      d[i][j] = Math.min(d[i - 1][j] + 1, d[i][j - 1] + 1, d[i - 1][j - 1] + cost);
+    }
+  }
+  return d[m][n];
+}
+
+function readJson(p) {
+  try { return JSON.parse(fs.readFileSync(p, 'utf8')); } catch { return null; }
+}
+
+function allowedRegistryHosts(cwd) {
+  const hosts = new Set(DEFAULT_REGISTRY_HOSTS);
+  for (const p of [path.join(cwd, '.npmrc'), path.join(require('os').homedir(), '.npmrc')]) {
+    try {
+      const txt = fs.readFileSync(p, 'utf8');
+      const m = txt.match(/^\s*registry\s*=\s*(\S+)/m);
+      if (m) { try { hosts.add(new URL(m[1]).host); } catch { /* ignore */ } }
+    } catch { /* no .npmrc */ }
+  }
+  return hosts;
+}
+
+function hostOf(url) {
+  try { return new URL(url.replace(/^git\+/, '')).host; } catch { return null; }
+}
+
+function isNonRegistrySpec(spec) {
+  return /^(?:git\+|git:|github:|gitlab:|bitbucket:|https?:|file:|link:|portal:)/.test(spec) ||
+    /^[\w.-]+\/[\w.-]+(?:#.*)?$/.test(spec); // github user/repo shorthand
+}
+
+/** Audit package.json scripts + dependency sources. */
+function auditManifest(cwd, findings) {
+  const pkgPath = path.join(cwd, 'package.json');
+  const pkg = readJson(pkgPath);
+  if (!pkg) { findings.push({ severity: 'info', ruleId: 'no-manifest', where: 'package.json', message: 'No readable package.json found.' }); return null; }
+
+  const scripts = pkg.scripts || {};
+  for (const [name, body] of Object.entries(scripts)) {
+    const isLifecycle = LIFECYCLE.includes(name);
+    if (SUSPICIOUS_SCRIPT.test(String(body))) {
+      findings.push({ severity: 'critical', ruleId: 'malicious-script', where: `package.json scripts.${name}`,
+        message: `Script "${name}" runs a suspicious command (network-to-shell / eval / encoded): ${String(body).slice(0, 120)}` });
+    } else if (isLifecycle) {
+      findings.push({ severity: 'warning', ruleId: 'install-script', where: `package.json scripts.${name}`,
+        message: `This package defines a lifecycle install script "${name}" — it will run on install.` });
+    }
+  }
+
+  for (const field of ['dependencies', 'devDependencies', 'optionalDependencies']) {
+    const deps = pkg[field] || {};
+    for (const [name, spec] of Object.entries(deps)) {
+      if (typeof spec === 'string' && isNonRegistrySpec(spec)) {
+        findings.push({ severity: 'warning', ruleId: 'non-registry-source', where: `package.json ${field}.${name}`,
+          message: `Dependency "${name}" is installed from a non-registry source: ${spec}` });
+      }
+      // typosquat / homoglyph
+      if (/[^\x00-\x7f]/.test(name)) {
+        findings.push({ severity: 'critical', ruleId: 'homoglyph-name', where: `package.json ${field}.${name}`,
+          message: `Dependency name "${name}" contains non-ASCII characters (possible homoglyph squat).` });
+      } else {
+        const base = name.replace(/^@[^/]+\//, '');
+        for (const pop of POPULAR) {
+          if (base !== pop && Math.abs(base.length - pop.length) <= 1 && levenshtein(base, pop) === 1) {
+            findings.push({ severity: 'critical', ruleId: 'typosquat', where: `package.json ${field}.${name}`,
+              message: `Dependency "${name}" is one character away from popular package "${pop}" (possible typosquat).` });
+            break;
+          }
+        }
+      }
+    }
+  }
+  return pkg;
+}
+
+/** Audit lockfiles for non-registry resolutions and install-script packages. */
+function auditLockfiles(cwd, findings) {
+  const allowed = allowedRegistryHosts(cwd);
+  let installScriptPkgs = 0;
+
+  // npm: package-lock.json (v2/v3)
+  const lock = readJson(path.join(cwd, 'package-lock.json'));
+  if (lock && lock.packages) {
+    for (const [loc, info] of Object.entries(lock.packages)) {
+      if (!loc) continue;
+      if (info.hasInstallScript) installScriptPkgs++;
+      const resolved = info.resolved;
+      if (resolved && /^https?:/.test(resolved)) {
+        const h = hostOf(resolved);
+        if (h && !allowed.has(h)) {
+          findings.push({ severity: 'critical', ruleId: 'foreign-registry', where: `package-lock.json ${loc}`,
+            message: `Package resolved from a non-default registry/host "${h}": ${resolved}` });
+        }
+      } else if (resolved && /^git\+|^git:/.test(resolved)) {
+        findings.push({ severity: 'warning', ruleId: 'git-source', where: `package-lock.json ${loc}`,
+          message: `Package installed from a git source: ${resolved}` });
+      }
+    }
+  }
+
+  // pnpm: pnpm-lock.yaml (line scan — no YAML dependency)
+  try {
+    const txt = fs.readFileSync(path.join(cwd, 'pnpm-lock.yaml'), 'utf8');
+    const lines = txt.split(/\r?\n/);
+    for (let i = 0; i < lines.length; i++) {
+      const l = lines[i];
+      if (/^\s*requiresBuild:\s*true/.test(l)) installScriptPkgs++;
+      const tb = l.match(/tarball:\s*(\S+)/);
+      if (tb) {
+        const h = hostOf(tb[1]);
+        if (h && !allowed.has(h)) {
+          findings.push({ severity: 'critical', ruleId: 'foreign-registry', where: 'pnpm-lock.yaml',
+            message: `Package tarball from a non-default host "${h}": ${tb[1]}` });
+        }
+      }
+      if (/resolution:\s*\{[^}]*\b(repo|commit)\b/.test(l)) {
+        findings.push({ severity: 'warning', ruleId: 'git-source', where: 'pnpm-lock.yaml',
+          message: `Package resolved from a git source: ${l.trim().slice(0, 100)}` });
+      }
+    }
+  } catch { /* no pnpm-lock */ }
+
+  // yarn: yarn.lock
+  try {
+    const txt = fs.readFileSync(path.join(cwd, 'yarn.lock'), 'utf8');
+    for (const m of txt.matchAll(/resolved\s+"([^"]+)"/g)) {
+      const h = hostOf(m[1]);
+      if (h && /^https?:/.test(m[1]) && !allowed.has(h)) {
+        findings.push({ severity: 'critical', ruleId: 'foreign-registry', where: 'yarn.lock',
+          message: `Package resolved from a non-default host "${h}": ${m[1]}` });
+      }
+    }
+  } catch { /* no yarn.lock */ }
+
+  if (installScriptPkgs > 0) {
+    findings.push({ severity: 'info', ruleId: 'install-script-count', where: 'lockfile',
+      message: `${installScriptPkgs} installed package(s) declare an install/build script. Run \`polin-guard harden\` to block them with ignore-scripts.` });
+  }
+}
+
+/** Run the full supply-chain audit. */
+function auditInstall(cwd) {
+  const findings = [];
+  auditManifest(cwd, findings);
+  auditLockfiles(cwd, findings);
+  const critical = findings.filter((f) => f.severity === 'critical');
+  const warnings = findings.filter((f) => f.severity === 'warning');
+  return { findings, critical, warnings, blocking: critical.length > 0 };
+}
+
+/** Check (and optionally apply) install-time hardening for this project. */
+function harden(cwd, { fix = false } = {}) {
+  const npmrc = path.join(cwd, '.npmrc');
+  let current = '';
+  try { current = fs.readFileSync(npmrc, 'utf8'); } catch { /* none */ }
+  const hasIgnore = /^\s*ignore-scripts\s*=\s*true\s*$/m.test(current);
+
+  const result = { hasIgnore, applied: false, npmrc, recommendations: [] };
+  if (!hasIgnore) {
+    result.recommendations.push('Set `ignore-scripts=true` in .npmrc to stop dependency install scripts from executing.');
+    if (fix) {
+      const next = (current.replace(/\s*$/, '') + '\nignore-scripts=true\n').replace(/^\n/, '');
+      fs.writeFileSync(npmrc, next);
+      result.applied = true;
+    }
+  }
+  result.recommendations.push('Install with a frozen lockfile: `npm ci` / `pnpm install --frozen-lockfile`.');
+  result.recommendations.push('Pin the registry and review lockfile diffs in code review.');
+  return result;
+}
+
+module.exports = { auditInstall, harden, levenshtein, isNonRegistrySpec, SUSPICIOUS_SCRIPT, LIFECYCLE };