@clear-capabilities/agentic-security-scanner 0.79.0 → 0.84.1

package/src/posture/exploit-bundle.js

@@ -0,0 +1,210 @@
+// AI-native exploit PoC + regression test + remediation diff bundle —
+// Recommendation #6 of the world-class roadmap.
+//
+// For each high-confidence finding, emit a 4-piece bundle:
+//   1. PoC script    — a working curl / Python / Node command that
+//                      triggers the finding against the live app
+//   2. Regression test — a framework-idiomatic test (Jest / pytest /
+//                        JUnit) that exercises the vulnerable path
+//                        and asserts on the broken behavior
+//   3. Remediation     — the patched source code
+//   4. Diff            — git-applyable patch of #3 against the working tree
+//
+// All four artifacts ship together so the developer's path from
+// "scanner shows me a finding" to "PR landed with fix + test" is single-click.
+//
+// The four pieces are *deterministic* per family — we DON'T rely on
+// the LLM to generate them at scan time. Instead we use a per-family
+// template catalog that produces concrete artifacts from the finding's
+// IR context (file, line, source variable, sink expression, etc.).
+//
+// LLM validation (already wired in scanner/src/llm-validator/) can run
+// AFTER bundle emission to confirm the PoC is plausible — but bundle
+// generation itself is deterministic so --deterministic SARIF stays
+// reproducible run-over-run.
+
+const TEMPLATES = {
+  'sql-injection': {
+    pocCurl: (f) => `# PoC: SQL Injection at ${f.file}:${f.line}
+# The vulnerable code concatenates user input into a SQL query.
+# Sending an injected payload extracts the database.users table:
+curl -X GET '${f._inRoute?.path || '/UPDATE_ME'}?${(f._sourceParam || 'id')}=1%27%20UNION%20SELECT%20username,password%20FROM%20users--' \\
+  -H 'Accept: application/json'
+# Expected vulnerable behavior: response includes usernames + password hashes
+# Expected fixed behavior: response is a 4xx error or returns no rows`,
+    regressionTestJest: (f) => `// Regression test for ${f.cwe} at ${f.file}:${f.line}
+import request from 'supertest';
+import app from '../app';
+describe('${f.vuln}', () => {
+  it('rejects SQL injection payloads', async () => {
+    const payload = "1' UNION SELECT username,password FROM users--";
+    const res = await request(app).get('${f._inRoute?.path || '/UPDATE_ME'}').query({ id: payload });
+    expect(res.status).toBeGreaterThanOrEqual(400);
+    expect(JSON.stringify(res.body)).not.toMatch(/password|username/i);
+  });
+});`,
+    regressionTestPytest: (f) => `# Regression test for ${f.cwe} at ${f.file}:${f.line}
+import pytest
+from app import app as flask_app
+
+@pytest.fixture
+def client():
+    return flask_app.test_client()
+
+def test_sql_injection_rejected(client):
+    payload = "1' UNION SELECT username,password FROM users--"
+    resp = client.get("${f._inRoute?.path || '/UPDATE_ME'}", query_string={'id': payload})
+    assert resp.status_code >= 400, "Vulnerable endpoint returned 2xx for SQL injection payload"
+    body = resp.get_data(as_text=True)
+    assert 'password' not in body.lower(), "Response leaked password column"`,
+    remediationSummary: () =>
+      'Parameterize the SQL query: use ? placeholders (or named parameters) + a bind-value call instead of concatenating user input. The driver escapes parameter values; concatenation does not.',
+  },
+
+  'xss': {
+    pocCurl: (f) => `# PoC: Reflected XSS at ${f.file}:${f.line}
+curl -X GET '${f._inRoute?.path || '/UPDATE_ME'}?${(f._sourceParam || 'name')}=%3Cscript%3Ealert(1)%3C%2Fscript%3E'
+# Expected vulnerable behavior: response body contains the literal <script>alert(1)</script>
+# Expected fixed behavior: response body contains the HTML-encoded form &lt;script&gt;…`,
+    regressionTestJest: (f) => `import request from 'supertest';
+import app from '../app';
+describe('${f.vuln}', () => {
+  it('HTML-encodes user input', async () => {
+    const res = await request(app).get('${f._inRoute?.path || '/UPDATE_ME'}').query({ name: '<script>alert(1)</script>' });
+    expect(res.text).not.toContain('<script>alert(1)</script>');
+    expect(res.text).toMatch(/&lt;script&gt;|&amp;lt;|encoded/i);
+  });
+});`,
+    regressionTestPytest: (f) => `import pytest
+from app import app as flask_app
+
+@pytest.fixture
+def client():
+    return flask_app.test_client()
+
+def test_xss_encoded(client):
+    resp = client.get("${f._inRoute?.path || '/UPDATE_ME'}", query_string={'name': '<script>alert(1)</script>'})
+    body = resp.get_data(as_text=True)
+    assert '<script>alert(1)</script>' not in body, "XSS payload reflected unencoded"`,
+    remediationSummary: () =>
+      `Encode user input via the framework's built-in escaper (Razor @x, Django escape, Jinja autoescape, React JSX). Replace any explicit "raw"/"unsafe" output methods with their encoded equivalent.`,
+  },
+
+  'command-injection': {
+    pocCurl: (f) => `# PoC: Command Injection at ${f.file}:${f.line}
+curl -X POST '${f._inRoute?.path || '/UPDATE_ME'}' \\
+  -H 'Content-Type: application/json' \\
+  -d '{"${f._sourceParam || 'name'}": "; sleep 5; #"}'
+# Expected vulnerable behavior: response time > 5 seconds (sleep ran via shell)
+# Expected fixed behavior: response time normal, "sleep" appears as literal arg`,
+    regressionTestJest: (f) => `import request from 'supertest';
+import app from '../app';
+describe('${f.vuln}', () => {
+  it('does not invoke shell metacharacters', async () => {
+    const t0 = Date.now();
+    await request(app).post('${f._inRoute?.path || '/UPDATE_ME'}').send({ name: '; sleep 5; #' });
+    const elapsed = Date.now() - t0;
+    expect(elapsed).toBeLessThan(2000);
+  });
+});`,
+    remediationSummary: () =>
+      `Replace the system()/exec()/shell-out call with the argv form: pass the program path as a constant and arguments as a separate list/array. The shell parser is bypassed, and metacharacters are treated as literal args.`,
+  },
+
+  'path-traversal': {
+    pocCurl: (f) => `# PoC: Path Traversal at ${f.file}:${f.line}
+curl -X GET '${f._inRoute?.path || '/UPDATE_ME'}?${(f._sourceParam || 'file')}=../../../etc/passwd'
+# Expected vulnerable behavior: response contains "root:" / passwd file format
+# Expected fixed behavior: response is a 4xx or "file not found"`,
+    regressionTestJest: (f) => `import request from 'supertest';
+import app from '../app';
+describe('${f.vuln}', () => {
+  it('rejects path traversal sequences', async () => {
+    const res = await request(app).get('${f._inRoute?.path || '/UPDATE_ME'}').query({ file: '../../../etc/passwd' });
+    expect(res.status).toBeGreaterThanOrEqual(400);
+    expect(res.text).not.toMatch(/^root:/m);
+  });
+});`,
+    remediationSummary: () =>
+      `Canonicalize the resolved path via Path.GetFullPath / realpath, verify it starts with the allowed base directory, and reject mismatches. The bare Path.Combine / os.path.join does NOT prevent ../ escapes.`,
+  },
+
+  'open-redirect': {
+    pocCurl: (f) => `# PoC: Open Redirect at ${f.file}:${f.line}
+curl -I '${f._inRoute?.path || '/UPDATE_ME'}?${(f._sourceParam || 'url')}=//evil.example.com/phish'
+# Expected vulnerable behavior: 302 Location: //evil.example.com/phish (attacker host)
+# Expected fixed behavior: 4xx or redirect to same-origin only`,
+    regressionTestJest: (f) => `import request from 'supertest';
+import app from '../app';
+describe('${f.vuln}', () => {
+  it('rejects off-origin redirect targets', async () => {
+    const res = await request(app).get('${f._inRoute?.path || '/UPDATE_ME'}').query({ url: '//evil.example.com/phish' });
+    if (res.status === 302 || res.status === 301) {
+      expect(res.headers.location).not.toContain('evil.example.com');
+    }
+  });
+});`,
+    remediationSummary: () =>
+      `Use Url.IsLocalUrl(url) (ASP.NET Core) / matching an allow-list of paths/hosts. Pass-through redirects to user-controlled URLs are the basis for OAuth pivot phishing.`,
+  },
+};
+
+/**
+ * Generate the 4-piece bundle for a finding. Returns:
+ *   { family, pocs: { curl, ... }, tests: { jest, pytest, junit },
+ *     remediation: { summary, diff }, exploitable: true|false|unknown }
+ *
+ * When the family has no template, returns a "stub" bundle with the
+ * available context so a downstream LLM can fill in the gaps.
+ */
+export function generateBundle(finding, opts = {}) {
+  const family = finding.family || 'unknown';
+  const tmpl = TEMPLATES[family];
+  if (!tmpl) {
+    return {
+      family, exploitable: 'unknown',
+      pocs: { curl: null }, tests: { jest: null, pytest: null },
+      remediation: { summary: 'no template for this family yet — manual review required' },
+      stub: true,
+    };
+  }
+  const bundle = {
+    family,
+    cwe: finding.cwe,
+    sink: { file: finding.file, line: finding.line },
+    pocs: {
+      curl: tmpl.pocCurl ? tmpl.pocCurl(finding) : null,
+    },
+    tests: {
+      jest:   tmpl.regressionTestJest   ? tmpl.regressionTestJest(finding)   : null,
+      pytest: tmpl.regressionTestPytest ? tmpl.regressionTestPytest(finding) : null,
+    },
+    remediation: {
+      summary: tmpl.remediationSummary ? tmpl.remediationSummary(finding) : finding.remediation || null,
+      // Diff generation is best done by the existing security-fixer subagent
+      // (it has full IR/file context). We emit only the summary here.
+      diff: null,
+    },
+    exploitable: 'pending-validation',
+  };
+  return bundle;
+}
+
+/**
+ * Bulk-emit bundles for an array of findings. Returns a Map<finding.id, bundle>.
+ * Caps at maxBundles for memory; sorted by severity DESC + compositeRisk DESC.
+ */
+export function generateBundles(findings, opts = {}) {
+  if (!Array.isArray(findings)) return new Map();
+  const max = opts.maxBundles || 50;
+  const sev = { critical: 0, high: 1, medium: 2, low: 3, info: 4 };
+  const sorted = [...findings]
+    .filter(f => f.severity === 'critical' || f.severity === 'high')
+    .sort((a, b) => (sev[a.severity] - sev[b.severity]) || ((b.compositeRisk || 0) - (a.compositeRisk || 0)))
+    .slice(0, max);
+  const out = new Map();
+  for (const f of sorted) out.set(f.id || `${f.file}:${f.line}:${f.vuln}`, generateBundle(f, opts));
+  return out;
+}
+
+export const _internals = { TEMPLATES };

package/src/posture/federated-learning.js

@@ -0,0 +1,172 @@
+// Federated learning across opt-in customers — Recommendation #7 of the
+// world-class+2 plan.
+//
+// Extends scanner/src/posture/triage-learning.js with a privacy-preserving
+// cross-customer aggregation layer. Each opt-in customer's triage
+// decisions contribute a noisy gradient (ε-differential privacy) to a
+// central coordinator. The aggregated global prior gets blended with
+// each local prior so all customers benefit from each other's calibration
+// without sharing source code or findings.
+//
+// Privacy model:
+//   - We only submit (family, sink-method, tp_delta, fp_delta) — never
+//     the finding text, file path, or any identifier
+//   - Counts are perturbed with Laplace noise at scale 1/ε (default ε=1.0)
+//   - Receipts of every transmission written to
+//     .agentic-security/federated-receipts.jsonl for audit
+//   - Opt-in via AGENTIC_SECURITY_FEDERATED=1; off-by-default
+//
+// Threat model:
+//   - Attacker controls the coordinator → cannot recover an individual
+//     customer's triage history because of DP noise
+//   - Attacker controls one customer → can attempt poisoning, but each
+//     customer's contribution is capped via SUBMISSION_CAP_PER_DAY
+//   - Network observer → all traffic is HTTPS; payloads are aggregated
+//     counts not individual events
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import * as crypto from 'node:crypto';
+import { statePath, safeWriteState } from './state-dir.js';
+import { loadCalibration } from './triage-learning.js';
+
+const RECEIPTS_FILE = 'federated-receipts.jsonl';
+const LAST_PUSH_FILE = 'federated-last-push.json';
+const DEFAULT_EPSILON = 1.0;
+const SUBMISSION_CAP_PER_DAY = 10;
+const DEFAULT_PUSH_INTERVAL_HOURS = 24;
+
+/**
+ * Sample from Laplace(0, b) where b = 1/ε. Used to add DP noise to count
+ * deltas before submission.
+ */
+function laplaceNoise(epsilon) {
+  if (epsilon <= 0) return 0;
+  const u = Math.random() - 0.5;
+  const b = 1 / epsilon;
+  return -b * Math.sign(u) * Math.log(1 - 2 * Math.abs(u));
+}
+
+function _receiptsPath(scanRoot) { return statePath(scanRoot, RECEIPTS_FILE); }
+function _lastPushPath(scanRoot) { return statePath(scanRoot, LAST_PUSH_FILE); }
+
+function _appendReceipt(scanRoot, receipt) {
+  const fp = _receiptsPath(scanRoot);
+  try { fs.appendFileSync(fp, JSON.stringify(receipt) + '\n'); } catch {}
+}
+
+function _readLastPush(scanRoot) {
+  const fp = _lastPushPath(scanRoot);
+  if (!fs.existsSync(fp)) return null;
+  try { return JSON.parse(fs.readFileSync(fp, 'utf8')); } catch { return null; }
+}
+
+function _writeLastPush(scanRoot, payload) {
+  const fp = _lastPushPath(scanRoot);
+  safeWriteState(fp, JSON.stringify(payload, null, 2));
+}
+
+/**
+ * Compute the privatized gradient against a baseline calibration. The
+ * gradient is the per-bucket count delta since the last push, with
+ * Laplace noise added. The baseline is `lastPush.snapshot`; current
+ * counts come from the local triage-learning store.
+ */
+export function computePrivatizedGradient(currentCalibration, baseline, opts = {}) {
+  const epsilon = opts.epsilon ?? DEFAULT_EPSILON;
+  const grad = { global: {}, perProject: null }; // perProject NEVER shared
+  const baseGlobal = baseline?.snapshot?.global || {};
+  for (const [bucket, cur] of Object.entries(currentCalibration.global || {})) {
+    const prev = baseGlobal[bucket] || { tp: 0, fp: 0 };
+    const tpDelta = (cur.tp || 0) - (prev.tp || 0);
+    const fpDelta = (cur.fp || 0) - (prev.fp || 0);
+    if (tpDelta === 0 && fpDelta === 0) continue;
+    grad.global[bucket] = {
+      tp: Math.max(0, Math.round(tpDelta + laplaceNoise(epsilon))),
+      fp: Math.max(0, Math.round(fpDelta + laplaceNoise(epsilon))),
+    };
+  }
+  return grad;
+}
+
+/**
+ * Push the privatized gradient to the central coordinator. Coordinator
+ * endpoint defaults to a known address; can be overridden by
+ * AGENTIC_SECURITY_FEDERATED_ENDPOINT. Records a receipt on success or
+ * failure.
+ */
+export async function pushGradient(scanRoot, gradient, opts = {}) {
+  if (process.env.AGENTIC_SECURITY_FEDERATED !== '1') {
+    return { ok: false, reason: 'opt-in-not-enabled' };
+  }
+  const last = _readLastPush(scanRoot) || { count: 0, day: '' };
+  const today = new Date().toISOString().slice(0, 10);
+  if (last.day === today && last.count >= SUBMISSION_CAP_PER_DAY) {
+    return { ok: false, reason: 'daily-cap-reached', cap: SUBMISSION_CAP_PER_DAY };
+  }
+  const endpoint = opts.endpoint || process.env.AGENTIC_SECURITY_FEDERATED_ENDPOINT;
+  if (!endpoint) return { ok: false, reason: 'no-endpoint-configured' };
+  const payload = {
+    schema: 'agentic-security/federated-grad/v1',
+    epsilon: opts.epsilon ?? DEFAULT_EPSILON,
+    bucketCount: Object.keys(gradient.global || {}).length,
+    gradient: gradient.global || {},
+    ts: new Date().toISOString(),
+    submissionId: crypto.randomBytes(8).toString('hex'),
+  };
+  try {
+    const res = await fetch(endpoint, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json', 'User-Agent': 'agentic-security/0.1' },
+      body: JSON.stringify(payload),
+    });
+    const ok = res.ok;
+    const status = res.status;
+    _appendReceipt(scanRoot, { ts: payload.ts, submissionId: payload.submissionId, ok, status, bucketCount: payload.bucketCount });
+    _writeLastPush(scanRoot, {
+      count: (last.day === today ? last.count : 0) + 1, day: today,
+      snapshot: { global: Object.fromEntries(Object.entries(loadCalibration(scanRoot).global || {})) },
+    });
+    return { ok, status, submissionId: payload.submissionId };
+  } catch (e) {
+    _appendReceipt(scanRoot, { ts: payload.ts, submissionId: payload.submissionId, ok: false, error: String(e && e.message || e) });
+    return { ok: false, reason: 'network-error', error: String(e && e.message || e) };
+  }
+}
+
+/**
+ * Pull the aggregated global prior from the coordinator. The coordinator
+ * returns an aggregated calibration after combining all opt-in customer
+ * gradients.
+ */
+export async function pullAggregatedPrior(scanRoot, opts = {}) {
+  if (process.env.AGENTIC_SECURITY_FEDERATED !== '1') return null;
+  const endpoint = (opts.endpoint || process.env.AGENTIC_SECURITY_FEDERATED_ENDPOINT || '').replace(/\/$/, '');
+  if (!endpoint) return null;
+  try {
+    const res = await fetch(`${endpoint}/aggregate`, {
+      headers: { 'User-Agent': 'agentic-security/0.1' },
+    });
+    if (!res.ok) return null;
+    const prior = await res.json();
+    _appendReceipt(scanRoot, { ts: new Date().toISOString(), kind: 'pull', ok: true });
+    return prior;
+  } catch { return null; }
+}
+
+/**
+ * Run the periodic federated learning cycle: compute privatized
+ * gradient against last push baseline, submit, fetch aggregated prior.
+ */
+export async function federatedCycle(scanRoot, opts = {}) {
+  const calibration = loadCalibration(scanRoot);
+  const last = _readLastPush(scanRoot);
+  const gradient = computePrivatizedGradient(calibration, last || {}, opts);
+  const pushResult = await pushGradient(scanRoot, gradient, opts);
+  const pullResult = await pullAggregatedPrior(scanRoot, opts);
+  return { gradient, pushResult, aggregatedPrior: pullResult };
+}
+
+export const _internals = {
+  laplaceNoise, DEFAULT_EPSILON, SUBMISSION_CAP_PER_DAY, DEFAULT_PUSH_INTERVAL_HOURS,
+};

package/src/posture/findings-memory.js

@@ -0,0 +1,152 @@
+// Findings memory — natural-language Q&A over the institutional knowledge
+// the scanner has accumulated. Backs the MCP query_findings_memory tool.
+//
+// Sources searched, in this order:
+//
+//   1. .agentic-security/last-scan.json          current findings
+//   2. .agentic-security/triage-memory.jsonl     past wont-fix / FP decisions
+//   3. .agentic-security/scan-history/*.json     prior scans
+//   4. .agentic-security/AGENTS.md               continual-learning narrative
+//
+// Naive keyword matching for v1. Each match has a `score` (count of query
+// terms matched) and a `source` ('finding' | 'triage' | 'history' |
+// 'agents-md'). Returns top-10 by score.
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+
+const STATE = '.agentic-security';
+
+function _read(scanRoot, name) {
+  try { return fs.readFileSync(path.join(scanRoot, STATE, name), 'utf8'); } catch { return null; }
+}
+
+function _readJson(scanRoot, name) {
+  const raw = _read(scanRoot, name);
+  if (!raw) return null;
+  try { return JSON.parse(raw); } catch { return null; }
+}
+
+function _terms(query) {
+  return String(query || '').toLowerCase().split(/\s+/).filter(t => t.length >= 2);
+}
+
+function _score(haystack, terms) {
+  const lower = String(haystack || '').toLowerCase();
+  let s = 0;
+  for (const t of terms) if (lower.includes(t)) s++;
+  return s;
+}
+
+function _findingHaystack(f) {
+  return [f.vuln, f.family, f.file, f.severity, f.description, f.cwe, f.id]
+    .filter(Boolean).join(' | ');
+}
+
+function _truncate(s, n = 160) {
+  return String(s || '').replace(/\s+/g, ' ').slice(0, n);
+}
+
+/**
+ * Run a natural-language query over the scanner's accumulated memory.
+ */
+export function queryFindingsMemory(scanRoot, query) {
+  const terms = _terms(query);
+  if (!terms.length) return { results: [], count: 0 };
+
+  const results = [];
+
+  // 1. Current findings.
+  const scan = _readJson(scanRoot, 'last-scan.json');
+  if (scan && Array.isArray(scan.findings)) {
+    for (const f of scan.findings) {
+      const hay = _findingHaystack(f);
+      const score = _score(hay, terms);
+      if (!score) continue;
+      results.push({
+        source: 'finding',
+        score,
+        finding_id: f.id || null,
+        severity: f.severity,
+        family: f.family,
+        file: f.file,
+        line: f.line,
+        snippet: _truncate(f.vuln || f.description || f.family),
+      });
+    }
+  }
+
+  // 2. Triage memory (past decisions).
+  const triageRaw = _read(scanRoot, 'triage-memory.jsonl');
+  if (triageRaw) {
+    const lines = triageRaw.split('\n').filter(Boolean);
+    for (const ln of lines) {
+      let entry; try { entry = JSON.parse(ln); } catch { continue; }
+      const hay = [entry.decision, entry.reason, entry.family, entry.vuln, entry.file].join(' ');
+      const score = _score(hay, terms);
+      if (!score) continue;
+      results.push({
+        source: 'triage',
+        score,
+        decision: entry.decision,
+        at: entry.at,
+        family: entry.family,
+        snippet: _truncate(entry.reason || entry.vuln),
+        bucket: entry.bucket,
+      });
+    }
+  }
+
+  // 3. Scan history.
+  try {
+    const histDir = path.join(scanRoot, STATE, 'scan-history');
+    if (fs.existsSync(histDir)) {
+      const files = fs.readdirSync(histDir).filter(f => f.endsWith('.json')).slice(-10);
+      for (const f of files) {
+        try {
+          const hist = JSON.parse(fs.readFileSync(path.join(histDir, f), 'utf8'));
+          if (!Array.isArray(hist.findings)) continue;
+          for (const x of hist.findings.slice(0, 50)) {
+            const hay = _findingHaystack(x);
+            const score = _score(hay, terms);
+            if (!score) continue;
+            results.push({
+              source: 'history',
+              score,
+              from: f.replace(/\.json$/, ''),
+              severity: x.severity,
+              family: x.family,
+              file: x.file,
+              snippet: _truncate(x.vuln || x.description),
+            });
+          }
+        } catch {}
+      }
+    }
+  } catch {}
+
+  // 4. AGENTS.md narrative.
+  const agents = _read(scanRoot, 'AGENTS.md');
+  if (agents) {
+    const sections = agents.split(/^##\s+/m);
+    for (const sec of sections) {
+      const score = _score(sec, terms);
+      if (!score) continue;
+      const title = sec.split('\n')[0] || '';
+      results.push({
+        source: 'agents-md',
+        score,
+        title: _truncate(title, 80),
+        snippet: _truncate(sec.replace(title, ''), 200),
+      });
+    }
+  }
+
+  // Top-10 by score, ties broken by source priority (finding > triage >
+  // history > agents-md so live data wins).
+  const PRI = { finding: 4, triage: 3, history: 2, 'agents-md': 1 };
+  results.sort((a, b) => (b.score - a.score) || (PRI[b.source] - PRI[a.source]));
+  return { results: results.slice(0, 10), count: results.length };
+}
+
+export const _internals = { _terms, _score, _findingHaystack };

package/src/posture/fix-style-mirror.js

@@ -0,0 +1,118 @@
+// Fix style mirror — find existing fix patterns in the repo for the
+// security-fixer agent to mirror, so remediation matches house style
+// rather than producing canned generic replacements.
+//
+// Strategy: for a given finding (family + file), look at sibling files
+// in the same directory tree for instances of the canonical safe pattern
+// for that family (e.g. parameterized queries for sqli). Return up to 5
+// real examples the agent can reference.
+//
+// Cheap implementation — grep-style search via fs.readdirSync. No regex
+// engine deps. v1 covers the canonical fix patterns for the 8 most-
+// common families.
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+
+const SAFE_PATTERNS = {
+  'sqli':              ['\\.query\\([^,)]+,\\s*\\[', '\\.prepare\\(', '\\.execute\\([^,)]+,\\s*\\['],
+  'sql-injection':     ['\\.query\\([^,)]+,\\s*\\[', '\\.prepare\\(', '\\.execute\\([^,)]+,\\s*\\['],
+  'xss':               ['escapeHtml\\(', 'sanitize\\(', 'DOMPurify\\.', '\\bencodeHTML\\b'],
+  'command-injection': ['\\bexecFile\\(', '\\bspawn\\([^,)]+,\\s*\\['],
+  'path-traversal':    ['path\\.resolve\\(', 'path\\.normalize\\(', 'startsWith\\(.*path\\.sep'],
+  'ssrf':              ['allowlist\\.includes\\(', 'url\\.hostname'],
+  'crypto-weak-cipher':['createCipheriv\\(\\s*[\'"`]aes-256-gcm', 'createCipheriv\\(\\s*[\'"`]chacha20'],
+  'crypto-weak-hash':  ['createHash\\(\\s*[\'"`]sha-?256', 'createHash\\(\\s*[\'"`]sha-?512', 'createHash\\(\\s*[\'"`]blake'],
+  'hardcoded-secret':  ['process\\.env\\.[A-Z_]+', 'config\\.[a-z_]+'],
+};
+
+const SKIP_DIRS = new Set(['node_modules', '.git', '.bench-cache', 'dist', 'build', 'coverage', '.next']);
+const MAX_FILES = 200;
+const MAX_EXAMPLES = 5;
+const MAX_FILE_SIZE = 100_000;
+
+function _siblings(scanRoot, file, maxDepth = 3) {
+  if (!file) return [];
+  const abs = path.isAbsolute(file) ? file : path.join(scanRoot, file);
+  const baseDir = path.dirname(abs);
+  // Walk upward maxDepth levels and collect files of the same extension.
+  const ext = path.extname(abs);
+  if (!ext) return [];
+  const candidates = [];
+  let cur = baseDir;
+  for (let d = 0; d < maxDepth; d++) {
+    if (!fs.existsSync(cur)) break;
+    _walkUp(cur, ext, candidates);
+    const parent = path.dirname(cur);
+    if (parent === cur) break;
+    cur = parent;
+  }
+  return candidates.slice(0, MAX_FILES).filter(p => p !== abs);
+}
+
+function _walkUp(dir, ext, out) {
+  let entries;
+  try { entries = fs.readdirSync(dir, { withFileTypes: true }); } catch { return; }
+  for (const e of entries) {
+    const p = path.join(dir, e.name);
+    if (e.isDirectory()) {
+      if (SKIP_DIRS.has(e.name)) continue;
+      // Stop one level deep here; outer loop walks upward.
+      try {
+        const childEntries = fs.readdirSync(p, { withFileTypes: true });
+        for (const ce of childEntries) {
+          if (ce.isFile() && ce.name.endsWith(ext)) {
+            out.push(path.join(p, ce.name));
+            if (out.length >= MAX_FILES) return;
+          }
+        }
+      } catch {}
+      continue;
+    }
+    if (e.isFile() && e.name.endsWith(ext)) {
+      out.push(p);
+      if (out.length >= MAX_FILES) return;
+    }
+  }
+}
+
+/**
+ * Returns up to 5 style-mirror examples for a finding's family. Each
+ * example is `{ file, line, snippet }`. The agent can quote these as
+ * "here's how this codebase already does it."
+ */
+export function findStyleExamples(scanRoot, finding) {
+  if (!finding || !finding.family) return [];
+  const patterns = SAFE_PATTERNS[finding.family] ||
+                   SAFE_PATTERNS[String(finding.family).toLowerCase()] || null;
+  if (!patterns) return [];
+  const files = _siblings(scanRoot, finding.file || '');
+  const examples = [];
+  const patternRes = patterns.map(p => new RegExp(p));
+
+  for (const fp of files) {
+    if (examples.length >= MAX_EXAMPLES) break;
+    let content;
+    try {
+      const stat = fs.statSync(fp);
+      if (stat.size > MAX_FILE_SIZE) continue;
+      content = fs.readFileSync(fp, 'utf8');
+    } catch { continue; }
+    for (const re of patternRes) {
+      const m = re.exec(content);
+      if (!m) continue;
+      const line = content.slice(0, m.index).split('\n').length;
+      const lines = content.split('\n');
+      const snippet = lines.slice(Math.max(0, line - 2), Math.min(lines.length, line + 1)).join('\n').trim();
+      examples.push({
+        file: path.relative(scanRoot, fp),
+        line,
+        snippet: snippet.slice(0, 240),
+      });
+      break;
+    }
+  }
+  return examples;
+}
+
+export const _internals = { SAFE_PATTERNS, _siblings };