polin-guard 0.1.0 → 0.3.0

package/README.md

@@ -1,94 +1,169 @@
-# polin-guard
+<h1 align="center">🛡️ polin-guard</h1>
+
+<p align="center">
+  <strong>Stop obfuscated malware from being committed to your repo — automatically, on every commit.</strong>
+</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/polin-guard"><img alt="npm version" src="https://img.shields.io/npm/v/polin-guard?color=cb3837&logo=npm"></a>
+  <a href="https://www.npmjs.com/package/polin-guard"><img alt="npm downloads" src="https://img.shields.io/npm/dm/polin-guard?color=cb3837&logo=npm"></a>
+  <a href="https://github.com/Valentin-Shyaka/polin-guard/blob/main/LICENSE"><img alt="license" src="https://img.shields.io/npm/l/polin-guard?color=blue"></a>
+  <img alt="dependencies" src="https://img.shields.io/badge/dependencies-0-brightgreen">
+  <img alt="node" src="https://img.shields.io/node/v/polin-guard">
+</p>
+
+<p align="center">
+  <code>npm install --save-dev polin-guard</code>
+</p>
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/Valentin-Shyaka/polin-guard/main/assets/demo.svg" alt="polin-guard blocking a commit that contains an obfuscated injected payload" width="760">
+</p>
+
+---
+
+## The problem it solves
+
+Modern supply-chain attacks hide a malicious payload on a **single, space-padded
+line** inside an ordinary-looking config or entry file — `tailwind.config.js`,
+`ecosystem.config.js`, `.eslintrc.js`, `postcss.config.js`, `src/index.ts`, etc.
+The line is hundreds of spaces wide, so the payload scrolls **off-screen** in your
+editor and sails through code review:
+
+```js
+plugins: [tailwindcssAnimate];
+};                                          global['!']='…';var d=String.fromCharCode(127);…require;…Function(…)(…)
+//        ^ legitimate code                 ^ hundreds of spaces hide this →→→  obfuscated payload
+```
 
-**Block obfuscated build/commit-time code-injection payloads before they ever enter your repo.**
+When the project is built, that line runs with **full Node.js access** — reading
+your environment variables, `.env`, SSH keys, and tokens, and pulling a second
+stage. Because it sits in a file that's `require`d during `dev`/`build`/`test`, it
+executes silently and automatically.
 
-`polin-guard` is a tiny, **zero-dependency** scanner that catches the family of
-malicious JavaScript "stagers" that hide a payload on a single, space-padded line
-inside an otherwise normal config or entry file — e.g. `tailwind.config.js`,
-`ecosystem.config.js`, `.eslintrc.js`, `postcss.config.js`, or `src/index.ts`.
+**polin-guard catches it before it can ever be committed.**
 
-These payloads typically:
+> Built after a real incident in which this exact payload was committed across
+> multiple repositories and reached production branches.
+
+## How it detects (beyond signatures)
+
+polin-guard doesn't just match known payload strings — those are trivially
+renamed. It detects the **necessary conditions** of the attack and combines
+independent signals into a weighted **risk score**. To stay hidden *and* execute
+at build time, a payload is forced to do several of these at once:
+
+| Signal | What it catches | Weight |
+|--------|-----------------|-------:|
+| `concealment` | code hidden after a long mid-line whitespace gap (the off-screen trick) | 80 |
+| `signature` | known-family markers (`global['!']`, `global[_$_…]`, re-exposed `require`, `fromCharCode(127)`) | 60 |
+| `escape-density` | ≥25 `\xNN`/`\uNNNN` escapes on a line (obfuscated blob) | 50 |
+| `exec-sink` | dynamic execution: `Function()` / `eval` | 40 |
+| `long-token` | unbroken ≥120-char token (encoded blob) | 35 |
+| `ctor-chain` | `constructor.constructor` reach to `Function` | 35 |
+| `oversized-line` | line > 1000 chars (+30 more if it carries exec/require tokens) | 25 |
+| `entropy` | long, high-entropy line | 25 |
+| `indirect-require` · `dyn-timer` · `vm-module` | `require(<var>)`, `setTimeout("…")`, `require('vm')` | 25 |
+| `net-exec-combo` | network **+** code-exec/file-write together (runtime-fetched payload) | 30 |
+| `network` · `capability` | `fetch`/`http(s)`, or `process.env`/`fs`/`child_process` | 15 / 10 |
+| `autoloaded-context` | the above inside an auto-loaded config/entry file | +20 |
+
+A **file-level pass** also aggregates across lines, so a payload **split across
+many lines** or **fetched at runtime** still trips the score.
+
+**Block at score ≥ 70, warn at ≥ 35** (configurable). Because the signals are
+independent, evading one (rename, split, runtime-fetch, drop the padding) still
+trips the others — so evasion becomes self-defeating: visible in review, inert,
+readable, or capability-less. Lockfiles, minified bundles, source maps, and
+`node_modules` are skipped to keep false positives near zero.
+
+> **Evasion-tested.** The suite proves that a **renamed** (signature-free),
+> **split-across-lines**, and **runtime-fetched** payload are all still blocked,
+> while legitimate long-data lines and ordinary dynamic `require()` are not.
+
+## Quick start
 
-- decode strings at runtime with a character-shuffle cipher,
-- re-expose Node's `require`/`module` as globals, and
-- execute a second stage through a `Function()` constructor —
+```bash
+npm install --save-dev polin-guard
+```
 
-…all of which runs **automatically at build/dev/CI time** with full Node.js
-access to your environment variables, SSH keys, and tokens. Because the malicious
-code sits hundreds of spaces to the right of legitimate code, it is trivially
-missed in review. `polin-guard` makes it impossible to miss.
+Scan right now:
 
-> Built after a real incident in which this exact payload was committed across
-> multiple repositories. The detection rules are tuned for **high precision** —
-> a `CRITICAL` finding should be safe to block a commit on.
+```bash
+npx polin-guard --all      # scan every tracked file in the repo
+```
 
-## What it detects
+### Block it on every commit (husky)
 
-| Rule | Severity | What it catches |
-|------|----------|-----------------|
-| `global-bang-key` | critical | `global['!']=…` stager marker |
-| `global-underscore-handle` | critical | `global[_$_…]=…` obfuscated handle |
-| `require-reexposed` | critical | `…]=require; … typeof module` capability escalation |
-| `char-shuffle-cipher` | critical | `String.fromCharCode(127)` cipher delimiter |
-| `escape-density` | critical | a line with ≥25 `\xNN`/`\uNNNN` escapes (obfuscated blob) |
-| `iife-constructor` | critical | immediately-invoked `Function()` on a long line |
-| `oversized-line` | critical* | a source line > 1000 chars **with** exec/require tokens (the concealment trick) |
-| `oversized-line` | warning | a long line with no exec tokens (review) |
-| `eval` / `atob` / `child_process` | warning | weaker indicators |
+```bash
+npm install --save-dev polin-guard husky
+npx husky init
+echo 'npx --no-install polin-guard --staged' > .husky/pre-commit
+```
 
-\* A long line **without** exec tokens is only a warning, to keep false positives near zero.
+That's it. The hook runs on **every commit and every `git commit --amend`**, and
+scans the exact content being committed. A malicious payload makes the commit fail.
 
-Lockfiles, minified bundles, source maps, and `node_modules` are excluded automatically.
+### Add the CI backstop (recommended)
 
-## Install
+A local hook can be skipped (`git commit --no-verify`) or sidestepped by a
+force-push from a compromised machine. Re-scan on the server, where it can't be
+skipped — copy [`examples/github-action.yml`](examples/github-action.yml) to
+`.github/workflows/polin-guard.yml`.
 
-```bash
-npm install --save-dev polin-guard
-```
+### No Node? Use the standalone script
 
-Or run it without installing:
+Drop [`scan-injection.sh`](scan-injection.sh) into your repo (works with the
+[pre-commit framework](examples/pre-commit-config.yaml) too):
 
 ```bash
-npx polin-guard --all
+./scan-injection.sh --staged
 ```
 
-No Node? Use the standalone script — copy `scan-injection.sh` into your repo.
-
 ## Usage
 
-```bash
-polin-guard --staged    # scan staged content (use in pre-commit; also covers `git commit --amend`)
-polin-guard --all       # scan every tracked file
-polin-guard --ci        # same as --all, for CI
-polin-guard path/to/file.js ...   # scan specific files (no git required)
-polin-guard --strict    # treat warnings as blocking too
+```text
+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
+  -h, --help   ·   -v, --version
+
+Exit 0 = clean · 1 = blocking finding · 2 = usage error
 ```
 
-Exit code `1` means a blocking finding was detected.
+## Supply-chain audit (root-cause defense)
 
-### As a pre-commit hook (husky)
+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
-npm install --save-dev polin-guard husky
-npx husky init
-# add the scan to the hook (runs on commit AND amend):
-echo 'npx --no-install polin-guard --staged' > .husky/pre-commit
+npx polin-guard install-audit
 ```
 
-A ready-made hook is included at `.husky/pre-commit` in this package.
-
-### As a pre-commit hook (pre-commit.com framework)
+It flags, by reading `package.json` and your lockfile:
 
-See `examples/pre-commit-config.yaml`. It calls the standalone `scan-injection.sh`,
-so it needs no Node.
+- 🔴 **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
 
-### In CI (the bypass-proof backstop)
+Then **shut the door** so dependency scripts can't execute at all:
 
-A local hook can be skipped with `git commit --no-verify` or sidestepped by a
-force-push from a compromised machine. Add the server-side scan so history is
-always re-checked:
+```bash
+npx polin-guard harden --fix     # writes ignore-scripts=true to .npmrc
+```
 
-Copy `examples/github-action.yml` to `.github/workflows/polin-guard.yml`.
+Run `install-audit` in CI too — see [`examples/github-action.yml`](examples/github-action.yml).
 
 ## Configuration
 
@@ -103,55 +178,45 @@ Optional `.polinguardrc.json` in your repo root:
 }
 ```
 
-### Acknowledging a verified false positive
+**Acknowledging a verified false positive** (e.g. a legitimate inline blob):
 
-If a line is genuinely legitimate (a real minified-in-source blob, say):
-
-- put `// polinguard-allow-line` on the same line, **or**
-- put `// polinguard-allow-next-line` on the line above it, **or**
+- add `// polinguard-allow-line` on the same line, **or**
+- add `// polinguard-allow-next-line` on the line above it, **or**
 - raise `maxLineLength` / exclude the path in `.polinguardrc.json`.
 
-Never use `git commit --no-verify` to push past a finding you haven't understood.
-
-## Audit an existing repo / whole org
+> Never use `git commit --no-verify` to push past a finding you don't understand.
 
-One-off scan of a checked-out repo:
+## Audit an existing repo or whole org
 
 ```bash
+# one repo
 npx polin-guard --all
-# or, without Node:
-git grep -nI '.\{1000,\}'   # flag any suspiciously long line
-```
-
-Scan every branch of every repo in a GitHub org:
 
-```bash
+# every branch of every repo in a GitHub org
 for r in $(gh repo list YOUR_ORG --limit 200 --json name --jq '.[].name'); do
-  git clone --quiet "https://github.com/YOUR_ORG/$r.git" "/tmp/scan/$r" || continue
+  git clone -q "https://github.com/YOUR_ORG/$r.git" "/tmp/scan/$r" || continue
   ( cd "/tmp/scan/$r"
     for b in $(git branch -r | grep -v HEAD | sed 's# *origin/##'); do
-      git checkout -q "$b" 2>/dev/null || continue
-      npx --yes polin-guard --all || echo "FOUND in $r @ $b"
+      git checkout -q "$b" 2>/dev/null && { npx --yes polin-guard --all || echo "FOUND in $r @ $b"; }
     done )
 done
 ```
 
 ## How it works
 
-Pure Node, no dependencies (so the security tool itself adds no supply-chain risk).
-For each candidate file it reads the staged blob (`git show :file`) or the working
-copy, then analyzes every line for the signatures and concealment patterns above.
-It exits non-zero on any `critical` finding so a hook or CI step fails the build.
-
-## Development
+Pure Node, **zero dependencies** (so the security tool adds no supply-chain risk
+of its own). For each candidate file it reads the staged blob (`git show :file`)
+or the working copy, analyzes every line against the rules above, and exits
+non-zero on any `critical` finding so your hook or CI step fails.
 
-```bash
-npm test   # runs the zero-dependency test suite (clean + inert-malicious fixtures)
-```
+## Links
 
-The `test/fixtures/malicious.config.js` fixture contains the detection *signatures*
-but performs no real decode/exec — it exists only to prove the detector fires.
+- 📦 **npm:** https://www.npmjs.com/package/polin-guard
+- 🐙 **GitHub:** https://github.com/Valentin-Shyaka/polin-guard
+- 🐛 **Issues:** https://github.com/Valentin-Shyaka/polin-guard/issues
+- 🔒 **Security policy:** [SECURITY.md](SECURITY.md)
+- 🤝 **Contributing:** [CONTRIBUTING.md](CONTRIBUTING.md)
 
 ## License
 
-MIT
+[MIT](LICENSE) © Valentin Shyaka

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,94 +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);
-      process.stderr.write(`  ${tag} ${file}:${it.line}  [${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.1.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/patterns.js

@@ -1,25 +1,40 @@
 'use strict';
 
 /**
- * Detection rules for polin-guard.
+ * Detection model for polin-guard (v0.2).
  *
- * These target the family of obfuscated build/commit-time JavaScript "stagers"
- * that hide a payload on a single, heavily space-padded line inside an otherwise
- * legitimate config or entry file (e.g. tailwind.config.js, ecosystem.config.js,
- * .eslintrc.js, postcss.config.js, src/index.ts). The payload typically:
- *   - decodes strings at runtime via a character-shuffle cipher,
- *   - re-exposes Node's `require`/`module` as globals, and
- *   - runs a second stage through a Function() constructor.
+ * v0.1 was signature-only and therefore evadable. v0.2 detects the *necessary
+ * conditions* of the attack class and combines independent signals into a
+ * weighted RISK SCORE. To stay hidden yet execute at build time, the payload is
+ * forced to do several things at once — and each is a detector here:
  *
- * The goal is HIGH precision: a "critical" finding should almost never be a
- * false positive, so it is safe to BLOCK a commit on it.
+ *   - HIDE visually        -> concealment (code after a long whitespace gap),
+ *                             long unbroken tokens, dense escapes, high entropy
+ *   - EXECUTE implicitly   -> dynamic exec sinks (Function/eval/indirect require/
+ *                             constructor.constructor/vm/string-timer) in
+ *                             auto-loaded config/entry files
+ *   - OBFUSCATE            -> entropy / escape / long-token signals (token-agnostic)
+ *   - REACH SECRETS        -> env/fs/child_process + network capability
+ *
+ * Defeating one detector by renaming/splitting/runtime-fetching still trips the
+ * others, so evasion becomes self-defeating (visible, inert, readable, or
+ * capability-less). The known-family signatures remain as fast, high-weight hits.
  */
 
-// Default thresholds (override via .polinguardrc.json).
 const DEFAULTS = {
-  maxLineLength: 1000, // a single source line longer than this is suspicious
-  maxEscapes: 25, // count of \xNN / \uNNNN escapes on one line => obfuscated blob
-  // Files / directories that legitimately contain long or generated lines.
+  // Scoring thresholds.
+  criticalScore: 70, // >= this blocks the commit
+  warningScore: 35, // >= this is reported (non-blocking unless --strict)
+
+  // Detector thresholds.
+  maxLineLength: 1000, // oversized source line
+  maxEscapes: 25, // \xNN / \uNNNN escapes on one line => obfuscated blob
+  maxTokenLength: 120, // unbroken non-whitespace run => encoded blob
+  minGapWhitespace: 80, // code hidden after this many mid-line spaces/tabs
+  entropyMinLen: 200, // only entropy-score lines at least this long
+  entropyThreshold: 4.3, // bits/char; obfuscated/encoded content runs high
+  fileEscapeTotal: 100, // total escapes across a file (catches split payloads)
+
   excludeDirs: [
     'node_modules', '.git', 'dist', 'build', 'out', 'coverage',
     '.next', '.nuxt', '.output', '.turbo', '.cache', 'vendor', '__snapshots__',
@@ -30,63 +45,53 @@ const DEFAULTS = {
     /(^|\/)(package-lock\.json|pnpm-lock\.yaml|yarn\.lock|bun\.lockb?)$/i,
     /\.snap$/i,
   ],
-  // Only these extensions are scanned. Covers JS/TS, Vue, configs, and the
-  // Windows batch / shell droppers seen alongside the JS stager.
   includeExtensions: [
     '.js', '.cjs', '.mjs', '.jsx', '.ts', '.tsx', '.vue',
     '.json', '.bat', '.cmd', '.ps1', '.sh',
   ],
 };
 
-// Near-unique signatures of the known stager. Each match is CRITICAL on its own.
-const SIGNATURES = [
-  {
-    id: 'global-bang-key',
-    re: /global\s*\[\s*['"`]!['"`]\s*\]/,
-    message: "Assigns to global['!'] — a known obfuscated-stager marker.",
-  },
-  {
-    id: 'global-underscore-handle',
-    re: /global\s*\[\s*_\$_/,
-    message: 'Assigns to global[_$_…] — obfuscated stager variable handle.',
-  },
-  {
-    id: 'require-reexposed',
-    re: /\]\s*=\s*require\s*;[\s\S]{0,60}typeof\s+module/,
-    message: 'Re-exposes require()/module as globals — capability-escalation pattern.',
-  },
-  {
-    id: 'char-shuffle-cipher',
-    // String.fromCharCode(127) used as a sentinel/delimiter in the shuffle cipher.
-    // Legitimate uses are virtually always inside excluded node_modules (e.g. websocket).
-    re: /String\.fromCharCode\(\s*127\s*\)/,
-    message: 'Uses fromCharCode(127) cipher delimiter — stager string-decoder pattern.',
-  },
-];
-
-// Immediately-invoked Function() / this[...] constructor: a second-stage exec sink.
-const IIFE_CONSTRUCTOR =
-  /(?:\bFunction\b|this\s*\[[^\]]+\]|global\s*\[[^\]]+\])\s*\([^)]*\)\s*\(/;
-
-// Tokens that turn an over-long line from "suspicious" into "critical".
-const EXEC_TOKENS =
-  /\b(require|eval|atob|unescape|child_process|execSync|spawnSync|Function)\b|process\s*\.\s*env|global\s*\[|String\.fromCharCode/;
+// Per-signal weights (points added to a line's / file's risk score).
+const WEIGHTS = {
+  signature: 60, // a known-family signature
+  concealment: 80, // code after a long mid-line whitespace gap (off-screen trick)
+  longToken: 35, // unbroken token >= maxTokenLength
+  escapeDense: 50, // >= maxEscapes on one line
+  entropy: 25, // long, high-entropy line
+  oversized: 25, // line longer than maxLineLength
+  oversizedExecBonus: 30, // ...and it also carries exec/require tokens
+  execSink: 40, // Function()/eval dynamic execution
+  indirectRequire: 25, // require(<non-literal>)
+  ctorChain: 35, // constructor.constructor / ['constructor']
+  dynTimer: 25, // setTimeout/Interval("string")
+  vmModule: 25, // require('vm')
+  network: 15, // fetch / http(s)/net/dns/tls
+  capability: 10, // process.env / fs / child_process
+  netExecCombo: 30, // network + exec/file-write on the same line
+  autoloadBonus: 20, // exec/capability/network inside an auto-loaded file
+};
 
-// Standalone weaker indicators (reported as warnings, never block on their own).
-const SOFT_INDICATORS = [
-  { id: 'eval-call', re: /\beval\s*\(/, message: 'Contains eval().' },
-  { id: 'atob-call', re: /\batob\s*\(/, message: 'Contains atob() (base64 decode).' },
-  {
-    id: 'child-process-in-config',
-    re: /require\(\s*['"`]child_process['"`]\s*\)/,
-    message: "Loads child_process.",
-  },
+// Known-family signatures (fast, high-confidence). Each adds WEIGHTS.signature.
+const SIGNATURES = [
+  { id: 'global-bang-key', re: /global\s*\[\s*['"`]!['"`]\s*\]/, message: "global['!'] stager marker" },
+  { id: 'global-underscore-handle', re: /global\s*\[\s*_\$_/, message: 'global[_$_…] obfuscated handle' },
+  { id: 'require-reexposed', re: /\]\s*=\s*require\s*;[\s\S]{0,60}typeof\s+module/, message: 'require/module re-exposed as globals' },
+  { id: 'char-shuffle-cipher', re: /String\.fromCharCode\(\s*127\s*\)/, message: 'fromCharCode(127) cipher delimiter' },
 ];
 
-module.exports = {
-  DEFAULTS,
-  SIGNATURES,
-  IIFE_CONSTRUCTOR,
-  EXEC_TOKENS,
-  SOFT_INDICATORS,
+// Behavioral / structural regexes (token-agnostic where possible).
+const RE = {
+  execSink: /\b(?:new\s+)?Function\s*\(|\beval\s*\(/,
+  indirectRequire: /\brequire\s*\(\s*(?!['"`)])/, // require( not immediately a string
+  ctorChain: /\bconstructor\b\s*(?:\.\s*constructor|\[\s*['"`]\s*constructor)|\[\s*['"`]constructor['"`]\s*\]/,
+  dynTimer: /\bset(?:Timeout|Interval)\s*\(\s*['"`]/,
+  vmModule: /\brequire\s*\(\s*['"`]vm['"`]\s*\)/,
+  network: /\bfetch\s*\(|\bXMLHttpRequest\b|require\s*\(\s*['"`](?:https?|net|dns|tls|dgram)['"`]\s*\)|\bhttps?\s*\.\s*(?:get|request)\b/,
+  capability: /\bprocess\s*\.\s*env\b|require\s*\(\s*['"`](?:fs|os|child_process)['"`]\s*\)|\bchild_process\b/,
+  fsWrite: /\b(?:writeFileSync|writeFile|appendFileSync|appendFile|createWriteStream)\b/,
+  childProc: /\bchild_process\b|\b(?:execSync|spawnSync|spawn|fork)\s*\(|\bexec\s*\(/,
+  // tokens that upgrade an oversized line to critical
+  execTokens: /\b(?:require|eval|atob|unescape|child_process|Function)\b|process\s*\.\s*env|global\s*\[|String\.fromCharCode/,
 };
+
+module.exports = { DEFAULTS, WEIGHTS, SIGNATURES, RE };

package/src/scan.js

@@ -3,27 +3,17 @@
 const fs = require('fs');
 const path = require('path');
 const { execFileSync } = require('child_process');
-const {
-  DEFAULTS,
-  SIGNATURES,
-  IIFE_CONSTRUCTOR,
-  EXEC_TOKENS,
-  SOFT_INDICATORS,
-} = require('./patterns');
+const { DEFAULTS, WEIGHTS, SIGNATURES, RE } = require('./patterns');
 
 const ALLOW_LINE_MARKER = 'polinguard-allow-next-line';
 const ALLOW_INLINE_MARKER = 'polinguard-allow-line';
 
 /** Load optional config file from the repo root or cwd. */
 function loadConfig(cwd) {
-  const candidates = ['.polinguardrc.json', '.polinguard.json'];
-  for (const name of candidates) {
+  for (const name of ['.polinguardrc.json', '.polinguard.json']) {
     const p = path.join(cwd, name);
     try {
-      if (fs.existsSync(p)) {
-        const user = JSON.parse(fs.readFileSync(p, 'utf8'));
-        return { ...DEFAULTS, ...user };
-      }
+      if (fs.existsSync(p)) return { ...DEFAULTS, ...JSON.parse(fs.readFileSync(p, 'utf8')) };
     } catch (e) {
       process.stderr.write(`polin-guard: ignoring invalid ${name}: ${e.message}\n`);
     }
@@ -34,34 +24,33 @@ function loadConfig(cwd) {
 function git(args, cwd) {
   return execFileSync('git', args, { cwd, encoding: 'utf8', maxBuffer: 1024 * 1024 * 64 });
 }
-
-/** Files staged for commit (added/copied/modified/renamed). */
 function getStagedFiles(cwd) {
-  const out = git(['diff', '--cached', '--name-only', '--diff-filter=ACMR'], cwd);
-  return out.split('\n').filter(Boolean);
+  return git(['diff', '--cached', '--name-only', '--diff-filter=ACMR'], cwd).split('\n').filter(Boolean);
 }
-
-/** All tracked files (for --all / --ci). */
 function getTrackedFiles(cwd) {
   return git(['ls-files'], cwd).split('\n').filter(Boolean);
 }
-
-/** Read the *staged* blob content (what will actually be committed). */
 function readStaged(file, cwd) {
-  try {
-    return git(['show', `:${file}`], cwd);
-  } catch (e) {
-    return null; // deleted or unreadable
-  }
+  try { return git(['show', `:${file}`], cwd); } catch { return null; }
 }
 
 function isExcluded(file, cfg) {
   const parts = file.split(/[\\/]/);
   if (parts.some((p) => cfg.excludeDirs.includes(p))) return true;
   if (cfg.excludeFilePatterns.some((re) => re.test(file))) return true;
-  const ext = path.extname(file).toLowerCase();
-  if (!cfg.includeExtensions.includes(ext)) return true;
-  return false;
+  return !cfg.includeExtensions.includes(path.extname(file).toLowerCase());
+}
+
+/** Files that a build/test tool loads automatically — exec here is high-risk. */
+function isAutoLoaded(file) {
+  const base = (file.split(/[\\/]/).pop() || '').toLowerCase();
+  return (
+    /\.config\.(js|cjs|mjs|ts)$/.test(base) ||
+    /^\.?eslintrc(\.(js|cjs|json|yml|yaml))?$/.test(base) ||
+    /^(index|main|server|app)\.(js|cjs|mjs|ts)$/.test(base) ||
+    /^\.(babelrc|prettierrc|stylelintrc)/.test(base) ||
+    base === 'ecosystem.config.js'
+  );
 }
 
 function countEscapes(line) {
@@ -69,103 +58,151 @@ function countEscapes(line) {
   return m ? m.length : 0;
 }
 
-/** Analyze a single line. Returns array of findings for that line. */
-function analyzeLine(line, cfg) {
-  const out = [];
+/** Shannon entropy (bits/char). Obfuscated/encoded blobs run high. */
+function entropy(s) {
+  if (!s.length) return 0;
+  const freq = Object.create(null);
+  for (const ch of s) freq[ch] = (freq[ch] || 0) + 1;
+  let h = 0;
+  for (const k in freq) { const p = freq[k] / s.length; h -= p * Math.log2(p); }
+  return h;
+}
 
-  // 1) Near-unique stager signatures -> always critical.
-  for (const sig of SIGNATURES) {
-    if (sig.re.test(line)) {
-      out.push({ ruleId: sig.id, severity: 'critical', message: sig.message });
-    }
+function longestToken(line) {
+  let max = 0;
+  for (const t of line.split(/\s+/)) if (t.length > max) max = t.length;
+  return max;
+}
+
+/**
+ * Score a single line. Returns { score, signals: [{id, weight, message}], flags }.
+ * `flags` exposes booleans the file-level pass aggregates.
+ */
+function analyzeLine(line, cfg, ctx = {}) {
+  const signals = [];
+  const add = (id, weight, message) => signals.push({ id, weight, message });
+
+  for (const sig of SIGNATURES) if (sig.re.test(line)) add(sig.id, WEIGHTS.signature, sig.message);
+
+  // Concealment: code after a long mid-line whitespace gap (off-screen trick).
+  const body = line.replace(/^[ \t]+/, '');
+  if (new RegExp(`\\S[ \\t]{${cfg.minGapWhitespace},}\\S`).test(body)) {
+    add('concealment', WEIGHTS.concealment, `code hidden after ${cfg.minGapWhitespace}+ spaces (off-screen concealment)`);
   }
 
-  // 2) Dense escape-sequence blob -> obfuscated payload.
+  const tok = longestToken(body);
+  if (tok >= cfg.maxTokenLength) add('long-token', WEIGHTS.longToken, `unbroken ${tok}-char token (encoded blob)`);
+
   const esc = countEscapes(line);
-  if (esc >= cfg.maxEscapes) {
-    out.push({
-      ruleId: 'escape-density',
-      severity: 'critical',
-      message: `High escape-sequence density (${esc} \\x/\\u escapes) — obfuscated blob.`,
-    });
-  }
+  if (esc >= cfg.maxEscapes) add('escape-density', WEIGHTS.escapeDense, `${esc} \\x/\\u escapes (obfuscated blob)`);
 
-  // 3) Immediately-invoked Function() constructor on a long line -> exec sink.
-  if (IIFE_CONSTRUCTOR.test(line) && line.length > 200) {
-    out.push({
-      ruleId: 'iife-constructor',
-      severity: 'critical',
-      message: 'Immediately-invoked Function()/dynamic constructor on a long line — second-stage exec sink.',
-    });
+  if (line.length >= cfg.entropyMinLen) {
+    const h = entropy(line);
+    if (h >= cfg.entropyThreshold) add('entropy', WEIGHTS.entropy, `high entropy ${h.toFixed(2)} over ${line.length} chars`);
   }
 
-  // 4) Oversized line: critical if it also carries exec/require tokens, else a warning.
   if (line.length > cfg.maxLineLength) {
-    const exec = EXEC_TOKENS.test(line);
-    out.push({
-      ruleId: 'oversized-line',
-      severity: exec ? 'critical' : 'warning',
-      message: `Line length ${line.length} exceeds limit (${cfg.maxLineLength})` +
-        (exec ? ' and contains exec/require tokens — classic hidden-payload concealment.' : ' — review for hidden content.'),
-    });
+    const exec = RE.execTokens.test(line);
+    add('oversized-line', WEIGHTS.oversized + (exec ? WEIGHTS.oversizedExecBonus : 0),
+      `line length ${line.length}${exec ? ' with exec/require tokens' : ''}`);
   }
 
-  // 5) Soft indicators (warnings only).
-  for (const ind of SOFT_INDICATORS) {
-    if (ind.re.test(line)) {
-      out.push({ ruleId: ind.id, severity: 'warning', message: ind.message });
-    }
+  const execSink = RE.execSink.test(line);
+  if (execSink) add('exec-sink', WEIGHTS.execSink, 'dynamic code-exec sink (Function/eval)');
+  if (RE.indirectRequire.test(line)) add('indirect-require', WEIGHTS.indirectRequire, 'require() with a non-literal argument');
+  if (RE.ctorChain.test(line)) add('ctor-chain', WEIGHTS.ctorChain, 'constructor.constructor access (reaches Function)');
+  if (RE.dynTimer.test(line)) add('dyn-timer', WEIGHTS.dynTimer, 'setTimeout/Interval with a string body');
+  if (RE.vmModule.test(line)) add('vm-module', WEIGHTS.vmModule, 'loads the vm module');
+
+  const net = RE.network.test(line);
+  if (net) add('network', WEIGHTS.network, 'network access');
+  const cap = RE.capability.test(line);
+  if (cap) add('capability', WEIGHTS.capability, 'env/fs/child_process capability');
+  const fsWrite = RE.fsWrite.test(line);
+  const child = RE.childProc.test(line);
+
+  if (net && (execSink || RE.indirectRequire.test(line) || fsWrite || child)) {
+    add('net-exec-combo', WEIGHTS.netExecCombo, 'network + code-exec/file-write on one line (runtime-fetched payload)');
   }
+  if (ctx.autoLoaded && (execSink || cap || net || child)) {
+    add('autoloaded-context', WEIGHTS.autoloadBonus, 'in an auto-loaded config/entry file');
+  }
+
+  const score = signals.reduce((a, s) => a + s.weight, 0);
+  return { score, signals, flags: { execSink, net, cap, fsWrite, child, esc, longTok: tok >= cfg.maxTokenLength } };
+}
 
-  return out;
+function severityFor(score, cfg) {
+  if (score >= cfg.criticalScore) return 'critical';
+  if (score >= cfg.warningScore) return 'warning';
+  return null;
 }
 
-/** Scan one file's content (string). */
+/** Scan one file's content (string) -> findings[]. */
 function scanContent(file, content, cfg) {
-  const findings = [];
+  const ctx = { autoLoaded: isAutoLoaded(file) };
   const lines = content.split(/\r?\n/);
+  const findings = [];
+
+  let fileEsc = 0, anyExec = false, anyNet = false, anyChild = false, anyFsWrite = false, anyLongTok = false;
+
   for (let i = 0; i < lines.length; i++) {
     const line = lines[i];
-    // Inline allow markers let a maintainer acknowledge a known-good long line.
     if (line.includes(ALLOW_INLINE_MARKER)) continue;
     if (i > 0 && lines[i - 1].includes(ALLOW_LINE_MARKER)) continue;
 
-    const lineFindings = analyzeLine(line, cfg);
-    for (const f of lineFindings) {
-      findings.push({ ...f, file, line: i + 1 });
+    const { score, signals, flags } = analyzeLine(line, cfg, ctx);
+    fileEsc += flags.esc;
+    anyExec = anyExec || flags.execSink;
+    anyNet = anyNet || flags.net;
+    anyChild = anyChild || flags.child;
+    anyFsWrite = anyFsWrite || flags.fsWrite;
+    anyLongTok = anyLongTok || flags.longTok;
+
+    const sev = severityFor(score, cfg);
+    if (sev) {
+      const top = signals.slice().sort((a, b) => b.weight - a.weight);
+      findings.push({
+        file, line: i + 1, score, severity: sev,
+        ruleId: top[0].id,
+        message: `risk ${score} [${top.map((s) => s.id).join(', ')}] — ${top[0].message}`,
+      });
     }
   }
+
+  // File-level pass: catches payloads split across many lines or fetched at runtime.
+  const region = [];
+  if (fileEsc >= cfg.fileEscapeTotal && (anyExec || anyChild)) {
+    region.push({ s: 80, m: `${fileEsc} escape sequences across the file + a dynamic-exec sink (split/obfuscated payload)` });
+  }
+  if (anyLongTok && (anyExec || anyChild)) {
+    region.push({ s: 55, m: 'long encoded token(s) + a dynamic-exec sink' });
+  }
+  if (anyNet && (anyExec || anyChild || anyFsWrite)) {
+    region.push({ s: 55 + (ctx.autoLoaded ? WEIGHTS.autoloadBonus : 0), m: 'network access + code-exec/file-write across the file (runtime-fetched payload)' });
+  }
+  if (region.length) {
+    const best = region.sort((a, b) => b.s - a.s)[0];
+    const sev = severityFor(best.s, cfg);
+    if (sev) findings.push({ file, line: 0, score: best.s, severity: sev, ruleId: 'file-region', message: `file-level risk ${best.s} — ${best.m}` });
+  }
+
   return findings;
 }
 
-/**
- * Run a scan.
- * @param {object} opts
- * @param {'staged'|'all'|'paths'} opts.mode
- * @param {string[]} [opts.paths] explicit paths when mode === 'paths'
- * @param {string} [opts.cwd]
- * @param {boolean} [opts.strict] treat warnings as blocking too
- */
 function run(opts = {}) {
   const cwd = opts.cwd || process.cwd();
   const cfg = loadConfig(cwd);
   const mode = opts.mode || 'staged';
 
-  let files = [];
-  let readFile;
-
+  let files, readFile;
   if (mode === 'paths') {
     files = opts.paths || [];
-    readFile = (f) => {
-      try { return fs.readFileSync(path.resolve(cwd, f), 'utf8'); } catch { return null; }
-    };
+    readFile = (f) => { try { return fs.readFileSync(path.resolve(cwd, f), 'utf8'); } catch { return null; } };
   } else if (mode === 'all') {
     files = getTrackedFiles(cwd);
-    readFile = (f) => {
-      try { return fs.readFileSync(path.resolve(cwd, f), 'utf8'); } catch { return null; }
-    };
+    readFile = (f) => { try { return fs.readFileSync(path.resolve(cwd, f), 'utf8'); } catch { return null; } };
   } else {
-    // staged (default): scan the exact content that will be committed.
     files = getStagedFiles(cwd);
     readFile = (f) => readStaged(f, cwd);
   }
@@ -183,8 +220,7 @@ function run(opts = {}) {
   const critical = findings.filter((f) => f.severity === 'critical');
   const warnings = findings.filter((f) => f.severity === 'warning');
   const blocking = opts.strict ? findings.length > 0 : critical.length > 0;
-
   return { filesScanned: scanned.length, findings, critical, warnings, blocking };
 }
 
-module.exports = { run, scanContent, analyzeLine, loadConfig };
+module.exports = { run, scanContent, analyzeLine, loadConfig, entropy, isAutoLoaded };

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 };