polin-guard 0.1.0 → 0.2.0

package/README.md

@@ -1,94 +1,141 @@
-# polin-guard
-
-**Block obfuscated build/commit-time code-injection payloads before they ever enter your repo.**
-
-`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`.
-
-These payloads typically:
+<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
+```
 
-- 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 —
+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.
 
-…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.
+**polin-guard catches it before it can ever be committed.**
 
 > 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.
-
-## What it detects
-
-| 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 |
-
-\* A long line **without** exec tokens is only a warning, to keep false positives near zero.
-
-Lockfiles, minified bundles, source maps, and `node_modules` are excluded automatically.
-
-## Install
+> 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
 
 ```bash
 npm install --save-dev polin-guard
 ```
 
-Or run it without installing:
+Scan right now:
 
 ```bash
-npx polin-guard --all
-```
-
-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
+npx polin-guard --all      # scan every tracked file in the repo
 ```
 
-Exit code `1` means a blocking finding was detected.
-
-### As a pre-commit hook (husky)
+### Block it on every commit (husky)
 
 ```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
 ```
 
-A ready-made hook is included at `.husky/pre-commit` in this package.
+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.
 
-### As a pre-commit hook (pre-commit.com framework)
+### Add the CI backstop (recommended)
 
-See `examples/pre-commit-config.yaml`. It calls the standalone `scan-injection.sh`,
-so it needs no Node.
+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`.
 
-### In CI (the bypass-proof backstop)
+### No Node? Use the standalone script
 
-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:
+Drop [`scan-injection.sh`](scan-injection.sh) into your repo (works with the
+[pre-commit framework](examples/pre-commit-config.yaml) too):
 
-Copy `examples/github-action.yml` to `.github/workflows/polin-guard.yml`.
+```bash
+./scan-injection.sh --staged
+```
+
+## Usage
+
+```text
+polin-guard [options] [paths...]
+
+  --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
+
+Exit 0 = clean · 1 = blocking finding · 2 = usage error
+```
 
 ## Configuration
 
@@ -103,55 +150,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

@@ -93,7 +93,8 @@ function main() {
       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`);
+      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');
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "polin-guard",
-  "version": "0.1.0",
+  "version": "0.2.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 };