nubos-pilot 1.2.0 → 1.2.1

package/lib/security/patterns.cjs

@@ -0,0 +1,119 @@
+'use strict';
+
+const BUILTIN_PATTERNS = Object.freeze([
+  {
+    rule_name: 'eval_call',
+    category: 'dynamic-exec',
+    severity: 'risk',
+    regex: '\\beval\\s*\\(',
+    reminder: 'Dynamic code execution via eval(). Avoid evaluating runtime strings; parse data explicitly.',
+  },
+  {
+    rule_name: 'new_function',
+    category: 'dynamic-exec',
+    severity: 'risk',
+    regex: 'new\\s+Function\\s*\\(',
+    reminder: 'new Function() evaluates strings as code. Replace with explicit logic or a safe parser.',
+  },
+  {
+    rule_name: 'node_child_process_exec',
+    category: 'dynamic-exec',
+    severity: 'risk',
+    regex: 'child_process\\.(exec|execSync)\\s*\\(',
+    reminder: 'Shell exec of a string is injection-prone. Prefer execFile/spawn with an argv array.',
+  },
+  {
+    rule_name: 'python_os_system',
+    category: 'dynamic-exec',
+    severity: 'risk',
+    regex: '\\bos\\.system\\s*\\(',
+    reminder: 'os.system runs a shell command string. Use subprocess.run([...]) with a list, shell=False.',
+  },
+  {
+    rule_name: 'python_subprocess_shell',
+    category: 'dynamic-exec',
+    severity: 'risk',
+    regex: 'subprocess\\.(call|run|Popen|check_output)\\s*\\([^)]*shell\\s*=\\s*True',
+    reminder: 'subprocess with shell=True is injection-prone. Pass an argument list and shell=False.',
+  },
+  {
+    rule_name: 'python_pickle_load',
+    category: 'unsafe-deserialization',
+    severity: 'risk',
+    regex: '\\bpickle\\.loads?\\s*\\(',
+    reminder: 'pickle deserialization executes arbitrary code on untrusted input. Use json or a safe format.',
+  },
+  {
+    rule_name: 'yaml_unsafe_load',
+    category: 'unsafe-deserialization',
+    severity: 'risk',
+    regex: 'yaml\\.load\\s*\\((?![^)]*Safe)',
+    reminder: 'yaml.load without SafeLoader can instantiate arbitrary objects. Use yaml.safe_load.',
+  },
+  {
+    rule_name: 'php_unserialize',
+    category: 'unsafe-deserialization',
+    severity: 'risk',
+    regex: '\\bunserialize\\s*\\(',
+    reminder: 'unserialize() on untrusted input enables object injection. Use json_decode for data.',
+  },
+  {
+    rule_name: 'react_dangerously_set_inner_html',
+    category: 'dom-injection',
+    severity: 'risk',
+    substrings: ['dangerouslySetInnerHTML'],
+    reminder: 'dangerouslySetInnerHTML can introduce XSS. Sanitize input or render as text.',
+  },
+  {
+    rule_name: 'dom_inner_html_assignment',
+    category: 'dom-injection',
+    severity: 'risk',
+    regex: '\\.innerHTML\\s*=',
+    reminder: 'Assigning to .innerHTML with untrusted data is an XSS vector. Use textContent or sanitize.',
+  },
+  {
+    rule_name: 'dom_document_write',
+    category: 'dom-injection',
+    severity: 'risk',
+    regex: 'document\\.write\\s*\\(',
+    reminder: 'document.write with dynamic input enables XSS. Build DOM nodes explicitly instead.',
+  },
+  {
+    rule_name: 'github_workflow_edit',
+    category: 'workflow-file',
+    severity: 'warn',
+    path_only: true,
+    paths: ['**/.github/workflows/**'],
+    reminder: 'Workflow files can grant repository-level permissions. Review trigger and permission scope.',
+  },
+  {
+    rule_name: 'private_key_block',
+    category: 'hardcoded-secret',
+    severity: 'risk',
+    regex: '-----BEGIN (?:RSA |EC |OPENSSH |DSA |PGP )?PRIVATE KEY-----',
+    reminder: 'Hardcoded private key material. Load keys from a secret manager, never from source.',
+  },
+  {
+    rule_name: 'aws_access_key_id',
+    category: 'hardcoded-secret',
+    severity: 'risk',
+    regex: '\\b(?:AKIA|ASIA)[0-9A-Z]{16}\\b',
+    reminder: 'Hardcoded AWS access key id. Move credentials to the secret manager / environment.',
+  },
+  {
+    rule_name: 'stripe_live_secret',
+    category: 'hardcoded-secret',
+    severity: 'risk',
+    substrings: ['sk_live_'],
+    reminder: 'Hardcoded live Stripe secret key prefix. Load credentials from the secret manager.',
+  },
+  {
+    rule_name: 'generic_secret_assignment',
+    category: 'hardcoded-secret',
+    severity: 'warn',
+    regex: '(?:password|passwd|secret|api[_-]?key|access[_-]?token|auth[_-]?token)\\s*[:=]\\s*[\'"][^\'"\\s]{8,}[\'"]',
+    reminder: 'Looks like a hardcoded credential. Load it from configuration / a secret manager instead.',
+  },
+]);
+
+module.exports = { BUILTIN_PATTERNS };

package/lib/security/review.cjs

@@ -0,0 +1,220 @@
+'use strict';
+
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+const crypto = require('node:crypto');
+
+const git = require('../git.cjs');
+const ledger = require('./ledger.cjs');
+
+const REVIEWER_AGENT = 'np-security-reviewer';
+const MAX_DIFF_BYTES = 96 * 1024;
+const MAX_UNTRACKED_BYTES = 16 * 1024;
+const SHA_RE = /^[0-9a-fA-F]{7,40}$/;
+
+function _safeRef(ref) {
+  return typeof ref === 'string' && SHA_RE.test(ref) ? ref : 'HEAD';
+}
+
+function _lines(stdout) {
+  return String(stdout || '').split(/\r?\n/).filter(Boolean);
+}
+
+function isRepo(cwd) {
+  const r = git.runGit(['rev-parse', '--is-inside-work-tree'], { cwd });
+  return r.ok && String(r.stdout).trim() === 'true';
+}
+
+function headSha(cwd) {
+  const r = git.runGit(['rev-parse', 'HEAD'], { cwd });
+  return r.ok ? String(r.stdout).trim() : null;
+}
+
+function computeStopDiff(cwd, baseline, maxFiles) {
+  const ref = _safeRef(baseline && baseline.head);
+  const cap = Number.isFinite(maxFiles) ? maxFiles : 30;
+
+  const tracked = git.runGit(['--no-pager', 'diff', '--name-only', '--end-of-options', ref], { cwd });
+  const untracked = git.runGit(['ls-files', '--others', '--exclude-standard'], { cwd });
+  const files = [..._lines(tracked.stdout), ..._lines(untracked.stdout)];
+  const uniqueFiles = [...new Set(files)].slice(0, cap);
+  const truncatedFiles = files.length > cap;
+
+  let diffText = '';
+  const trackedDiff = git.runGit(['--no-pager', 'diff', '--no-color', '--end-of-options', ref], { cwd });
+  if (trackedDiff.ok) diffText += String(trackedDiff.stdout || '').slice(0, MAX_DIFF_BYTES);
+
+  let untrackedBudget = MAX_UNTRACKED_BYTES;
+  for (const f of _lines(untracked.stdout)) {
+    if (untrackedBudget <= 0) break;
+    let body = '';
+    try { body = fs.readFileSync(path.join(cwd, f), 'utf-8'); } catch { continue; }
+    const chunk = '\n--- new file: ' + f + ' ---\n' + body.slice(0, untrackedBudget);
+    diffText += chunk;
+    untrackedBudget -= chunk.length;
+  }
+
+  return { ref, files: uniqueFiles, truncatedFiles, diffText };
+}
+
+function computeCommitDiff(cwd, maxFiles) {
+  const cap = Number.isFinite(maxFiles) ? maxFiles : 30;
+  const names = git.runGit(['diff-tree', '--no-commit-id', '--name-only', '-r', 'HEAD'], { cwd });
+  const files = [..._lines(names.stdout)].slice(0, cap);
+  const show = git.runGit(['--no-pager', 'show', '--no-color', 'HEAD'], { cwd });
+  const diffText = show.ok ? String(show.stdout || '').slice(0, MAX_DIFF_BYTES) : '';
+  return { ref: 'HEAD', files, truncatedFiles: _lines(names.stdout).length > cap, diffText };
+}
+
+function _readGuidance(guidancePath) {
+  if (!guidancePath) return '';
+  try { return fs.readFileSync(guidancePath, 'utf-8').slice(0, 8 * 1024); }
+  catch { return ''; }
+}
+
+function buildReviewerPrompt(opts) {
+  const o = opts || {};
+  const mode = o.mode === 'commit' ? 'commit' : 'stop';
+  const guidance = _readGuidance(o.guidancePath);
+  const surrounding = mode === 'commit'
+    ? 'This is a pre-existing commit review. Read surrounding code (callers, sanitizers, related files) with your Read/Grep tools before deciding whether a finding is real, to keep false positives low.'
+    : 'Review only what this turn changed. Start from the diff; do not assume issues outside it.';
+
+  const parts = [];
+  parts.push('<security_scan mode="' + mode + '">');
+  parts.push('You are running in SESSION/DIFF mode (Modus B), not milestone mode.');
+  parts.push(surrounding);
+  parts.push('');
+  parts.push('Changed files (' + o.files.length + (o.truncatedFiles ? '+, truncated' : '') + '):');
+  parts.push(o.files.map((f) => '- ' + f).join('\n'));
+  if (guidance) {
+    parts.push('');
+    parts.push('Project security guidance (ADDITIVE — augments built-in checks, never disables them):');
+    parts.push(guidance);
+  }
+  parts.push('');
+  parts.push('Diff under review:');
+  parts.push('```diff');
+  parts.push(o.diffText);
+  parts.push('```');
+  parts.push('');
+  parts.push('Output ONLY a single JSON object (no prose, no markdown fence) of the form:');
+  parts.push('{"status":"clean|risks-found","findings":[{"category":"...","severity":"high|medium|low","file":"path","line":<int|null>,"title":"...","evidence":"...","mitigation_hint":"..."}]}');
+  parts.push('Report ONLY concrete Risk findings. Omit Pass/no-risk entries. If nothing, return {"status":"clean","findings":[]}.');
+  parts.push('</security_scan>');
+  return parts.join('\n');
+}
+
+function parseReviewerOutput(raw) {
+  if (!raw || typeof raw !== 'string') return { findings: [], status: 'unknown', parse_ok: false };
+  let resultText = raw;
+  try {
+    const outer = JSON.parse(raw);
+    if (outer && typeof outer === 'object' && typeof outer.result === 'string') resultText = outer.result;
+  } catch { /* raw may already be the agent text */ }
+
+  let envelope = _tryParseJson(resultText);
+  if (!envelope) envelope = _tryParseJson(_stripFence(resultText));
+  if (!envelope || typeof envelope !== 'object' || !Array.isArray(envelope.findings)) {
+    return { findings: [], status: 'unknown', parse_ok: false };
+  }
+  const findings = envelope.findings
+    .filter((f) => f && typeof f === 'object')
+    .map((f) => ({
+      category: f.category || null,
+      severity: _normSeverity(f.severity),
+      file: f.file || null,
+      line: Number.isFinite(f.line) ? f.line : null,
+      title: f.title || null,
+      mitigation_hint: f.mitigation_hint || null,
+    }));
+  return { findings, status: envelope.status || 'unknown', parse_ok: true };
+}
+
+function _normSeverity(s) {
+  const v = String(s || '').toLowerCase();
+  if (v === 'high' || v === 'critical') return 'risk';
+  if (v === 'risk' || v === 'fail') return 'risk';
+  if (v === 'medium' || v === 'low' || v === 'warn' || v === 'nit') return 'warn';
+  return 'risk';
+}
+
+function _tryParseJson(s) {
+  try { return JSON.parse(s); } catch { return null; }
+}
+
+function _stripFence(s) {
+  const m = String(s).match(/```(?:json)?\s*([\s\S]*?)```/);
+  return m ? m[1] : s;
+}
+
+function _defaultSpawn(promptText, opts) {
+  const spawnHeadless = require('../../bin/np-tools/spawn-headless.cjs');
+  const tmp = os.tmpdir();
+  const tag = process.pid + '-' + crypto.randomBytes(4).toString('hex');
+  const promptPath = path.join(tmp, 'np-sec-prompt-' + tag + '.txt');
+  const outputPath = path.join(tmp, 'np-sec-out-' + tag + '.json');
+  fs.writeFileSync(promptPath, promptText, 'utf-8');
+  const captured = [];
+  try {
+    spawnHeadless.run(
+      ['--agent', REVIEWER_AGENT, '--prompt-path', promptPath, '--output-path', outputPath,
+        '--timeout-ms', String(opts.timeoutMs)],
+      { cwd: opts.cwd, stdout: { write: (s) => captured.push(s) } },
+    );
+    return fs.readFileSync(outputPath, 'utf-8');
+  } finally {
+    try { fs.unlinkSync(promptPath); } catch {}
+    try { fs.unlinkSync(outputPath); } catch {}
+  }
+}
+
+function runReview(opts) {
+  const o = opts || {};
+  const cwd = o.cwd || process.cwd();
+  const sid = o.sid;
+  const mode = o.mode === 'commit' ? 'commit' : 'stop';
+  const config = o.config || {};
+  const spawn = typeof o.spawnImpl === 'function' ? o.spawnImpl : _defaultSpawn;
+
+  if (!isRepo(cwd)) return { ran: false, reason: 'not-a-repo' };
+
+  const begin = ledger.tryBeginReview(sid, { staleMs: (config.review_timeout_ms || 180000) + 60000 });
+  if (!begin.began) return { ran: false, reason: begin.reason };
+
+  try {
+    const maxFiles = Number.isFinite(config.max_files_per_review) ? config.max_files_per_review : 30;
+    const diff = mode === 'commit'
+      ? computeCommitDiff(cwd, maxFiles)
+      : computeStopDiff(cwd, ledger.readLedger(sid).baseline, maxFiles);
+
+    if (!diff.files.length || !String(diff.diffText).trim()) {
+      return { ran: true, mode, findings_added: 0, reason: 'empty-diff' };
+    }
+
+    const promptText = buildReviewerPrompt({
+      mode, files: diff.files, truncatedFiles: diff.truncatedFiles,
+      diffText: diff.diffText, guidancePath: config.guidance_path,
+    });
+
+    const raw = spawn(promptText, { cwd, timeoutMs: config.review_timeout_ms || 180000 });
+    const parsed = parseReviewerOutput(raw);
+    const risks = parsed.findings.filter((f) => f.severity === 'risk');
+    const merged = ledger.addReviewFindings(sid, risks, mode);
+    return { ran: true, mode, parse_ok: parsed.parse_ok, findings_total: parsed.findings.length, findings_added: merged.added };
+  } finally {
+    ledger.endReview(sid);
+  }
+}
+
+module.exports = {
+  REVIEWER_AGENT,
+  isRepo,
+  headSha,
+  computeStopDiff,
+  computeCommitDiff,
+  buildReviewerPrompt,
+  parseReviewerOutput,
+  runReview,
+};

package/lib/security/review.test.cjs

@@ -0,0 +1,143 @@
+'use strict';
+
+const { test } = require('node:test');
+const assert = require('node:assert/strict');
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+const { execFileSync } = require('node:child_process');
+
+const review = require('./review.cjs');
+const ledger = require('./ledger.cjs');
+
+function git(cwd, args) {
+  execFileSync('git', args, { cwd, stdio: 'pipe' });
+}
+
+function tempRepo() {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'np-sec-repo-'));
+  git(dir, ['init', '-q']);
+  git(dir, ['config', 'user.email', 't@t.test']);
+  git(dir, ['config', 'user.name', 'Test']);
+  fs.writeFileSync(path.join(dir, 'app.js'), 'function ok(){ return 1; }\n');
+  git(dir, ['add', '-A']);
+  git(dir, ['commit', '-q', '-m', 'init']);
+  return dir;
+}
+function headOf(dir) {
+  return execFileSync('git', ['rev-parse', 'HEAD'], { cwd: dir, encoding: 'utf-8' }).trim();
+}
+
+let _c = 0;
+function freshSid() { _c += 1; return 'rev-test-' + process.pid + '-' + _c; }
+function cleanup(sid) { ledger.removeLedger(sid); try { fs.unlinkSync(ledger.ledgerPath(sid) + '.lock'); } catch {} }
+
+test('REV-1 computeStopDiff captures tracked + untracked changes since baseline', () => {
+  const dir = tempRepo();
+  try {
+    const base = headOf(dir);
+    fs.appendFileSync(path.join(dir, 'app.js'), 'const x = eval(input);\n');
+    fs.writeFileSync(path.join(dir, 'new.js'), 'el.innerHTML = data;\n');
+    const diff = review.computeStopDiff(dir, { head: base }, 30);
+    assert.ok(diff.files.includes('app.js'));
+    assert.ok(diff.files.includes('new.js'));
+    assert.ok(diff.diffText.includes('eval(input)'));
+    assert.ok(diff.diffText.includes('new file: new.js'));
+  } finally { fs.rmSync(dir, { recursive: true, force: true }); }
+});
+
+test('REV-2 computeStopDiff caps file count', () => {
+  const dir = tempRepo();
+  try {
+    const base = headOf(dir);
+    for (let i = 0; i < 10; i++) fs.writeFileSync(path.join(dir, 'f' + i + '.js'), 'x\n');
+    const diff = review.computeStopDiff(dir, { head: base }, 3);
+    assert.equal(diff.files.length, 3);
+    assert.equal(diff.truncatedFiles, true);
+  } finally { fs.rmSync(dir, { recursive: true, force: true }); }
+});
+
+test('REV-3 computeCommitDiff reads the HEAD commit', () => {
+  const dir = tempRepo();
+  try {
+    fs.appendFileSync(path.join(dir, 'app.js'), 'const y = 2;\n');
+    git(dir, ['add', '-A']);
+    git(dir, ['commit', '-q', '-m', 'change']);
+    const diff = review.computeCommitDiff(dir, 30);
+    assert.ok(diff.files.includes('app.js'));
+    assert.ok(diff.diffText.includes('const y = 2'));
+  } finally { fs.rmSync(dir, { recursive: true, force: true }); }
+});
+
+test('REV-4 buildReviewerPrompt includes guidance additively and the schema instruction', () => {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'np-sec-g-'));
+  const gp = path.join(dir, 'guidance.md');
+  fs.writeFileSync(gp, 'Never log customer_id.');
+  try {
+    const prompt = review.buildReviewerPrompt({
+      mode: 'stop', files: ['a.js'], truncatedFiles: false, diffText: '+ eval(x)', guidancePath: gp,
+    });
+    assert.ok(prompt.includes('Modus B') || prompt.includes('SESSION/DIFF'));
+    assert.ok(prompt.includes('Never log customer_id.'));
+    assert.ok(prompt.includes('ADDITIVE'));
+    assert.ok(prompt.includes('"status":"clean|risks-found"'));
+  } finally { fs.rmSync(dir, { recursive: true, force: true }); }
+});
+
+test('REV-5 parseReviewerOutput handles claude -p envelope, fences, and junk', () => {
+  const envelope = JSON.stringify({ result: '{"status":"risks-found","findings":[{"category":"injection","severity":"high","file":"a.js","line":3,"title":"SQLi","mitigation_hint":"parameterize"}]}' });
+  const a = review.parseReviewerOutput(envelope);
+  assert.equal(a.parse_ok, true);
+  assert.equal(a.findings.length, 1);
+  assert.equal(a.findings[0].severity, 'risk');
+
+  const fenced = JSON.stringify({ result: '```json\n{"status":"clean","findings":[]}\n```' });
+  const b = review.parseReviewerOutput(fenced);
+  assert.equal(b.parse_ok, true);
+  assert.equal(b.findings.length, 0);
+
+  const junk = review.parseReviewerOutput('not json at all');
+  assert.equal(junk.parse_ok, false);
+});
+
+test('REV-6 runReview guard blocks a concurrent review (no double spawn)', () => {
+  const dir = tempRepo();
+  const sid = freshSid();
+  try {
+    ledger.setBaseline(sid, { head: headOf(dir) });
+    fs.appendFileSync(path.join(dir, 'app.js'), 'const z = eval(q);\n');
+    ledger.tryBeginReview(sid, {});  // simulate an in-flight review
+    let spawnCalls = 0;
+    const r = review.runReview({ cwd: dir, sid, mode: 'stop', config: {}, spawnImpl: () => { spawnCalls++; return '{}'; } });
+    assert.equal(r.ran, false);
+    assert.equal(r.reason, 'in-flight');
+    assert.equal(spawnCalls, 0);
+  } finally { ledger.endReview(sid); cleanup(sid); fs.rmSync(dir, { recursive: true, force: true }); }
+});
+
+test('REV-7 runReview spawns, parses, and merges risk findings into the ledger', () => {
+  const dir = tempRepo();
+  const sid = freshSid();
+  try {
+    ledger.setBaseline(sid, { head: headOf(dir) });
+    fs.appendFileSync(path.join(dir, 'app.js'), 'const z = eval(q);\n');
+    const stub = () => JSON.stringify({ result: '{"status":"risks-found","findings":[{"category":"dynamic-exec","severity":"high","file":"app.js","line":2,"title":"eval"}]}' });
+    const r = review.runReview({ cwd: dir, sid, mode: 'stop', config: {}, spawnImpl: stub });
+    assert.equal(r.ran, true);
+    assert.equal(r.findings_added, 1);
+    const taken = ledger.takeUnsurfacedRisks(sid, {});
+    assert.equal(taken.findings.length, 1);
+  } finally { cleanup(sid); fs.rmSync(dir, { recursive: true, force: true }); }
+});
+
+test('REV-8 runReview on an empty diff does not spawn', () => {
+  const dir = tempRepo();
+  const sid = freshSid();
+  try {
+    ledger.setBaseline(sid, { head: headOf(dir) });
+    let spawnCalls = 0;
+    const r = review.runReview({ cwd: dir, sid, mode: 'stop', config: {}, spawnImpl: () => { spawnCalls++; return '{}'; } });
+    assert.equal(r.findings_added, 0);
+    assert.equal(spawnCalls, 0);
+  } finally { cleanup(sid); fs.rmSync(dir, { recursive: true, force: true }); }
+});

package/lib/security/scan.cjs

@@ -0,0 +1,180 @@
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const { BUILTIN_PATTERNS } = require('./patterns.cjs');
+
+const MAX_CUSTOM_RULES = 50;
+const MAX_REMINDER_BYTES = 1024;
+const NESTED_QUANTIFIER_RE = /\([^)]*[+*][^)]*\)\s*[+*]/;
+
+function _looksCatastrophic(src) {
+  return NESTED_QUANTIFIER_RE.test(src);
+}
+
+function _globToRegExp(glob) {
+  let re = '';
+  for (let i = 0; i < glob.length; i++) {
+    const c = glob[i];
+    if (c === '*') {
+      if (glob[i + 1] === '*') {
+        re += '.*';
+        i++;
+        if (glob[i + 1] === '/') i++;
+      } else {
+        re += '[^/]*';
+      }
+    } else if (c === '?') {
+      re += '[^/]';
+    } else if ('\\^$.|+()[]{}'.includes(c)) {
+      re += '\\' + c;
+    } else {
+      re += c;
+    }
+  }
+  return new RegExp('^' + re + '$');
+}
+
+function _pathMatchesAny(filePath, globs) {
+  if (!Array.isArray(globs) || globs.length === 0) return false;
+  const normalized = String(filePath).replace(/\\/g, '/');
+  for (const g of globs) {
+    if (typeof g !== 'string' || g.length === 0) continue;
+    try {
+      if (_globToRegExp(g).test(normalized)) return true;
+    } catch { /* skip malformed glob */ }
+  }
+  return false;
+}
+
+function _compileRule(rule, source) {
+  if (!rule || typeof rule !== 'object') return null;
+  const ruleName = typeof rule.rule_name === 'string' ? rule.rule_name.trim() : '';
+  if (!ruleName) return { skipped: 'missing-rule_name' };
+
+  let reminder = typeof rule.reminder === 'string' ? rule.reminder : '';
+  if (Buffer.byteLength(reminder, 'utf-8') > MAX_REMINDER_BYTES) {
+    reminder = Buffer.from(reminder, 'utf-8').slice(0, MAX_REMINDER_BYTES).toString('utf-8');
+  }
+
+  const paths = Array.isArray(rule.paths) ? rule.paths : null;
+  const excludePaths = Array.isArray(rule.exclude_paths) ? rule.exclude_paths : null;
+
+  const compiled = {
+    rule_name: ruleName,
+    category: typeof rule.category === 'string' && rule.category ? rule.category : 'custom',
+    severity: typeof rule.severity === 'string' && rule.severity ? rule.severity : 'warn',
+    reminder,
+    source,
+    paths,
+    exclude_paths: excludePaths,
+    path_only: rule.path_only === true,
+  };
+
+  if (compiled.path_only) {
+    if (!paths) return { skipped: 'path_only-without-paths' };
+    return compiled;
+  }
+
+  if (typeof rule.regex === 'string' && rule.regex.length > 0) {
+    if (_looksCatastrophic(rule.regex)) return { skipped: 'catastrophic-regex' };
+    try { compiled.regex = new RegExp(rule.regex); }
+    catch { return { skipped: 'invalid-regex' }; }
+    return compiled;
+  }
+
+  if (Array.isArray(rule.substrings) && rule.substrings.length > 0) {
+    compiled.substrings = rule.substrings.filter((s) => typeof s === 'string' && s.length > 0);
+    if (compiled.substrings.length === 0) return { skipped: 'empty-substrings' };
+    return compiled;
+  }
+
+  return { skipped: 'no-matcher' };
+}
+
+function loadCustomRules(customRulesPath) {
+  if (!customRulesPath) return { rules: [], skipped: [] };
+  let raw;
+  try { raw = fs.readFileSync(customRulesPath, 'utf-8'); }
+  catch { return { rules: [], skipped: [{ reason: 'unreadable', file: path.basename(String(customRulesPath)) }] }; }
+  let parsed;
+  try { parsed = JSON.parse(raw); }
+  catch { return { rules: [], skipped: [{ reason: 'invalid-json', file: path.basename(String(customRulesPath)) }] }; }
+  const list = Array.isArray(parsed) ? parsed : (parsed && Array.isArray(parsed.patterns) ? parsed.patterns : null);
+  if (!list) return { rules: [], skipped: [{ reason: 'no-patterns-array', file: path.basename(String(customRulesPath)) }] };
+
+  const rules = [];
+  const skipped = [];
+  for (const entry of list.slice(0, MAX_CUSTOM_RULES)) {
+    const c = _compileRule(entry, 'custom');
+    if (c && c.skipped) { skipped.push({ reason: c.skipped, rule_name: entry && entry.rule_name }); continue; }
+    if (c) rules.push(c);
+  }
+  if (list.length > MAX_CUSTOM_RULES) {
+    skipped.push({ reason: 'rule-cap-exceeded', dropped: list.length - MAX_CUSTOM_RULES });
+  }
+  return { rules, skipped };
+}
+
+let _builtinCompiled = null;
+function _builtins() {
+  if (_builtinCompiled) return _builtinCompiled;
+  _builtinCompiled = BUILTIN_PATTERNS.map((r) => _compileRule(r, 'builtin')).filter((c) => c && !c.skipped);
+  return _builtinCompiled;
+}
+
+function _firstMatchLine(content, compiled) {
+  const lines = content.split(/\r?\n/);
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    if (compiled.regex) {
+      if (compiled.regex.test(line)) return i + 1;
+    } else if (compiled.substrings) {
+      for (const s of compiled.substrings) {
+        if (line.includes(s)) return i + 1;
+      }
+    }
+  }
+  return null;
+}
+
+function scanContent(opts) {
+  const o = opts || {};
+  const filePath = o.filePath || '';
+  const content = typeof o.content === 'string' ? o.content : '';
+  const custom = loadCustomRules(o.customRulesPath);
+  const rules = _builtins().concat(custom.rules);
+  const findings = [];
+
+  for (const rule of rules) {
+    if (rule.paths && !_pathMatchesAny(filePath, rule.paths)) continue;
+    if (rule.exclude_paths && _pathMatchesAny(filePath, rule.exclude_paths)) continue;
+
+    if (rule.path_only) {
+      findings.push({
+        rule_name: rule.rule_name, category: rule.category, severity: rule.severity,
+        file: filePath, line: 1, reminder: rule.reminder, source: rule.source,
+      });
+      continue;
+    }
+
+    const line = _firstMatchLine(content, rule);
+    if (line != null) {
+      findings.push({
+        rule_name: rule.rule_name, category: rule.category, severity: rule.severity,
+        file: filePath, line, reminder: rule.reminder, source: rule.source,
+      });
+    }
+  }
+
+  return { findings, custom_skipped: custom.skipped };
+}
+
+module.exports = {
+  scanContent,
+  loadCustomRules,
+  _globToRegExp,
+  _looksCatastrophic,
+  MAX_CUSTOM_RULES,
+};