polin-guard 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Valentin Shyaka
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,157 @@
+# 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:
+
+- 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 —
+
+…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.
+
+> 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
+
+```bash
+npm install --save-dev polin-guard
+```
+
+Or run it without installing:
+
+```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
+```
+
+Exit code `1` means a blocking finding was detected.
+
+### As a pre-commit hook (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.
+
+### As a pre-commit hook (pre-commit.com framework)
+
+See `examples/pre-commit-config.yaml`. It calls the standalone `scan-injection.sh`,
+so it needs no Node.
+
+### In CI (the bypass-proof backstop)
+
+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:
+
+Copy `examples/github-action.yml` to `.github/workflows/polin-guard.yml`.
+
+## Configuration
+
+Optional `.polinguardrc.json` in your repo root:
+
+```json
+{
+  "maxLineLength": 1000,
+  "maxEscapes": 25,
+  "excludeDirs": ["node_modules", "dist", "build", "vendor"],
+  "includeExtensions": [".js", ".cjs", ".mjs", ".jsx", ".ts", ".tsx", ".vue", ".json", ".bat", ".cmd", ".ps1", ".sh"]
+}
+```
+
+### Acknowledging a verified false positive
+
+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**
+- 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
+
+One-off scan of a checked-out repo:
+
+```bash
+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
+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
+  ( 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"
+    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
+
+```bash
+npm test   # runs the zero-dependency test suite (clean + inert-malicious fixtures)
+```
+
+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.
+
+## License
+
+MIT

package/bin/cli.js

@@ -0,0 +1,114 @@
+#!/usr/bin/env node
+'use strict';
+
+const { run } = require('../src/scan');
+
+const HELP = `polin-guard — block obfuscated code-injection payloads before they are committed
+
+Usage:
+  polin-guard [options] [paths...]
+
+Modes:
+  --staged        Scan files staged for commit (default; use in pre-commit hooks).
+  --all           Scan all git-tracked files.
+  --ci            Alias for --all (use in CI).
+  [paths...]      Scan specific files/globs (no git required).
+
+Options:
+  --strict        Treat warnings as blocking (exit non-zero on warnings too).
+  --quiet         Only print on findings.
+  --no-color      Disable ANSI colors.
+  -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
+
+Docs & allowlisting: see README. Add a config via .polinguardrc.json.`;
+
+function parseArgs(argv) {
+  const o = { mode: 'staged', paths: [], strict: false, quiet: false, color: true };
+  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 { o.paths.push(a); o.mode = 'paths'; }
+  }
+  return o;
+}
+
+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;
+
+  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'); }
+    return 0;
+  }
+  if (o.unknown) { process.stderr.write(`polin-guard: unknown option ${o.unknown}\n`); return 2; }
+
+  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 (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;
+  }
+
+  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`);
+
+  // 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 (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');
+  return 0;
+}
+
+process.exit(main());

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "polin-guard",
+  "version": "0.1.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"
+  },
+  "main": "src/scan.js",
+  "type": "commonjs",
+  "files": [
+    "bin/",
+    "src/",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "test": "node test/run.js",
+    "scan": "node bin/cli.js --all",
+    "scan:staged": "node bin/cli.js --staged"
+  },
+  "keywords": [
+    "security",
+    "supply-chain",
+    "malware",
+    "pre-commit",
+    "husky",
+    "git-hook",
+    "obfuscation",
+    "static-analysis",
+    "injection",
+    "stager"
+  ],
+  "engines": {
+    "node": ">=14"
+  },
+  "license": "MIT",
+  "dependencies": {},
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Valentin-Shyaka/polin-guard.git"
+  }
+}

package/src/patterns.js

@@ -0,0 +1,92 @@
+'use strict';
+
+/**
+ * Detection rules for polin-guard.
+ *
+ * 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.
+ *
+ * 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.
+ */
+
+// 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.
+  excludeDirs: [
+    'node_modules', '.git', 'dist', 'build', 'out', 'coverage',
+    '.next', '.nuxt', '.output', '.turbo', '.cache', 'vendor', '__snapshots__',
+  ],
+  excludeFilePatterns: [
+    /\.min\.(js|css|mjs|cjs)$/i,
+    /\.map$/i,
+    /(^|\/)(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/;
+
+// 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.",
+  },
+];
+
+module.exports = {
+  DEFAULTS,
+  SIGNATURES,
+  IIFE_CONSTRUCTOR,
+  EXEC_TOKENS,
+  SOFT_INDICATORS,
+};

package/src/scan.js

@@ -0,0 +1,190 @@
+'use strict';
+
+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 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) {
+    const p = path.join(cwd, name);
+    try {
+      if (fs.existsSync(p)) {
+        const user = JSON.parse(fs.readFileSync(p, 'utf8'));
+        return { ...DEFAULTS, ...user };
+      }
+    } catch (e) {
+      process.stderr.write(`polin-guard: ignoring invalid ${name}: ${e.message}\n`);
+    }
+  }
+  return { ...DEFAULTS };
+}
+
+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);
+}
+
+/** 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
+  }
+}
+
+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;
+}
+
+function countEscapes(line) {
+  const m = line.match(/\\x[0-9a-fA-F]{2}|\\u[0-9a-fA-F]{4}/g);
+  return m ? m.length : 0;
+}
+
+/** Analyze a single line. Returns array of findings for that line. */
+function analyzeLine(line, cfg) {
+  const out = [];
+
+  // 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 });
+    }
+  }
+
+  // 2) Dense escape-sequence blob -> obfuscated payload.
+  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.`,
+    });
+  }
+
+  // 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.',
+    });
+  }
+
+  // 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.'),
+    });
+  }
+
+  // 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 });
+    }
+  }
+
+  return out;
+}
+
+/** Scan one file's content (string). */
+function scanContent(file, content, cfg) {
+  const findings = [];
+  const lines = content.split(/\r?\n/);
+  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 });
+    }
+  }
+  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;
+
+  if (mode === 'paths') {
+    files = opts.paths || [];
+    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; }
+    };
+  } else {
+    // staged (default): scan the exact content that will be committed.
+    files = getStagedFiles(cwd);
+    readFile = (f) => readStaged(f, cwd);
+  }
+
+  const scanned = [];
+  const findings = [];
+  for (const file of files) {
+    if (isExcluded(file, cfg)) continue;
+    const content = readFile(file);
+    if (content == null) continue;
+    scanned.push(file);
+    findings.push(...scanContent(file, content, cfg));
+  }
+
+  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 };