@clear-capabilities/agentic-security-scanner 0.74.0

package/src/posture/ruleset-version.js

@@ -0,0 +1,71 @@
+// Ruleset version stamp (Sentinel-parity audit P2-13).
+//
+// The engine's built-in rules (engine.js, sast/*.js) evolve every release.
+// A change that's net-positive on the benchmark may regress on a specific
+// customer's codebase. Operators need a way to PIN the rule set so an
+// upgrade doesn't silently shift their finding stream.
+//
+// Mechanism:
+//   1. Each release stamps a RULESET_VERSION string (e.g. "0.45.0-2026-05-18").
+//   2. Operators write the version they want to use into
+//      .agentic-security/ruleset-version.json:
+//        { "version": "0.43.0-...", "pinned": true }
+//   3. The engine reads this at scan time. When pinned to an OLDER version,
+//      it logs a notice saying which scanner build is installed but which
+//      ruleset version is being honored.
+//   4. The version stamp is included in last-scan.json so /security-trend
+//      can attribute finding deltas to ruleset changes vs. code changes.
+//
+// LIMITATION: today, "pinning" is informational — it records intent but
+// doesn't actually run a different rule set. A future release will ship a
+// versioned ruleset-pack mechanism so old versions can be re-activated.
+// This module is the foothold for that work.
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { SCANNER_VERSION } from './version.js';
+
+// Tied to scanner/package.json via posture/version.js — they cannot diverge
+// (premortem 3R1.3).
+export const CURRENT_RULESET_VERSION = SCANNER_VERSION;
+
+const FILE = '.agentic-security/ruleset-version.json';
+
+export function readPinned(scanRoot) {
+  const fp = path.join(scanRoot || process.cwd(), FILE);
+  if (!fs.existsSync(fp)) return null;
+  try { return JSON.parse(fs.readFileSync(fp, 'utf8')); }
+  catch { return null; }
+}
+
+// Resolve the effective ruleset version: env override > pinned file > current.
+export function effectiveVersion(scanRoot) {
+  if (process.env.AGENTIC_SECURITY_RULESET_VERSION) {
+    return { version: process.env.AGENTIC_SECURITY_RULESET_VERSION, source: 'env' };
+  }
+  const pinned = readPinned(scanRoot);
+  if (pinned && pinned.version) {
+    return { version: pinned.version, pinned: !!pinned.pinned, source: 'file' };
+  }
+  return { version: CURRENT_RULESET_VERSION, source: 'default' };
+}
+
+// Annotate a scan result with the ruleset version stamp.
+export function stampScan(scanRoot, scan) {
+  if (!scan || typeof scan !== 'object') return scan;
+  const v = effectiveVersion(scanRoot);
+  scan._rulesetVersion = v.version;
+  scan._rulesetVersionSource = v.source;
+  if (v.version !== CURRENT_RULESET_VERSION && v.source !== 'default') {
+    // The operator pinned an older/newer version than what's installed.
+    // We surface this so they know the scan result reflects an intent
+    // mismatch (today, the pinning is informational — we don't actually
+    // run different rules — but the trail of intent is recorded).
+    scan._rulesetVersionMismatch = {
+      installed: CURRENT_RULESET_VERSION,
+      pinned: v.version,
+      note: 'Today the pinning is informational; future releases will honor it by running the historical rule set.',
+    };
+  }
+  return scan;
+}

package/src/posture/sbom.js

@@ -0,0 +1,129 @@
+// 0.7.0 Feat-6: SBOM emitters — CycloneDX 1.6 (JSON) + SPDX 2.3 (JSON).
+//
+// Reuses scan.components (parseManifests output) and scan.supplyChain to attach
+// vulnerability metadata to each component. No outbound calls; pure transform.
+//
+// CycloneDX schema reference: https://cyclonedx.org/docs/1.6/json/
+// SPDX 2.3 schema reference:  https://spdx.github.io/spdx-spec/v2.3/
+
+import * as crypto from 'node:crypto';
+
+function _purl(c) {
+  if (c.purl) return c.purl;
+  const eco = c.ecosystem || 'generic';
+  const name = encodeURIComponent(c.name || '');
+  const ver = encodeURIComponent(c.version || '');
+  // pkg:npm/<name>@<version> — pkg URL spec
+  return `pkg:${eco === 'npm' ? 'npm' : eco === 'pypi' ? 'pypi' : eco === 'maven' ? 'maven' : eco === 'cargo' ? 'cargo' : eco === 'go' ? 'golang' : eco === 'rubygems' ? 'gem' : eco === 'composer' ? 'composer' : eco}/${name}@${ver}`;
+}
+
+function _bomRef(c) {
+  return `${c.ecosystem || 'pkg'}:${c.name}@${c.version}`;
+}
+
+export function toCycloneDX(scan, meta = {}) {
+  const components = scan.components || [];
+  const supplyChain = (scan.supplyChain || []).filter(s => s.type === 'vulnerable_dep');
+  const serialNumber = `urn:uuid:${crypto.randomUUID()}`;
+
+  const cdxComponents = components.map(c => ({
+    type: 'library',
+    'bom-ref': _bomRef(c),
+    name: c.name,
+    version: c.version,
+    purl: _purl(c),
+    ...(c.license ? { licenses: [{ license: { id: c.license } }] } : {}),
+    ...(c.scope ? { scope: c.scope === 'dev' ? 'optional' : 'required' } : {}),
+  }));
+
+  const vulnerabilities = supplyChain.map(s => ({
+    'bom-ref': `${_bomRef({ ecosystem: s.ecosystem, name: s.name, version: s.version })}#${s.osvId || s.advisory || crypto.randomUUID()}`,
+    id: s.osvId || (s.cveAliases || [])[0] || s.advisory,
+    source: { name: 'OSV.dev', url: `https://osv.dev/vulnerability/${s.osvId || ''}` },
+    references: (s.cveAliases || []).map(cve => ({ id: cve, source: { name: 'NVD' } })),
+    ratings: [
+      ...(s.severity ? [{ severity: s.severity, method: 'other' }] : []),
+      ...(s.cvssVector ? [{ vector: s.cvssVector, method: 'CVSSv3' }] : []),
+    ],
+    description: s.description || s.advisory || '',
+    affects: [{ ref: _bomRef({ ecosystem: s.ecosystem, name: s.name, version: s.version }) }],
+    properties: [
+      ...(s.epssScore != null ? [{ name: 'epss:score', value: String(s.epssScore) }] : []),
+      ...(s.epssPercentile != null ? [{ name: 'epss:percentile', value: String(s.epssPercentile) }] : []),
+      ...(s.functionReachable ? [{ name: 'agentic-security:functionReachable', value: s.functionReachable }] : []),
+    ],
+  }));
+
+  return {
+    bomFormat: 'CycloneDX',
+    specVersion: '1.6',
+    serialNumber,
+    version: 1,
+    metadata: {
+      timestamp: meta.startedAt || new Date().toISOString(),
+      tools: [{ vendor: 'Clear Capabilities', name: 'agentic-security', version: '0.7.0' }],
+      component: { type: 'application', name: 'scan-target', version: '1.0.0' },
+    },
+    components: cdxComponents,
+    ...(vulnerabilities.length ? { vulnerabilities } : {}),
+  };
+}
+
+export function toSPDX(scan, meta = {}) {
+  const components = scan.components || [];
+  const supplyChain = (scan.supplyChain || []).filter(s => s.type === 'vulnerable_dep');
+  const docNamespace = `https://agentic-security.local/spdx/${crypto.randomUUID()}`;
+  const ts = meta.startedAt || new Date().toISOString();
+
+  const packages = components.map((c, i) => ({
+    SPDXID: `SPDXRef-Package-${i}`,
+    name: c.name,
+    versionInfo: c.version,
+    downloadLocation: 'NOASSERTION',
+    filesAnalyzed: false,
+    licenseConcluded: c.license || 'NOASSERTION',
+    licenseDeclared: c.license || 'NOASSERTION',
+    copyrightText: 'NOASSERTION',
+    externalRefs: [{
+      referenceCategory: 'PACKAGE-MANAGER',
+      referenceType: 'purl',
+      referenceLocator: _purl(c),
+    }],
+  }));
+
+  // SPDX expresses CVEs as external refs on the package, not separate elements
+  const cveByName = {};
+  for (const s of supplyChain) {
+    const k = `${s.ecosystem}:${s.name}@${s.version}`;
+    (cveByName[k] = cveByName[k] || []).push(...(s.cveAliases || (s.osvId ? [s.osvId] : [])));
+  }
+  for (let i = 0; i < components.length; i++) {
+    const c = components[i];
+    const k = `${c.ecosystem}:${c.name}@${c.version}`;
+    if (cveByName[k] && cveByName[k].length) {
+      packages[i].externalRefs.push(...cveByName[k].map(cve => ({
+        referenceCategory: 'SECURITY',
+        referenceType: 'cve',
+        referenceLocator: cve,
+      })));
+    }
+  }
+
+  return {
+    spdxVersion: 'SPDX-2.3',
+    dataLicense: 'CC0-1.0',
+    SPDXID: 'SPDXRef-DOCUMENT',
+    name: 'agentic-security-sbom',
+    documentNamespace: docNamespace,
+    creationInfo: {
+      created: ts,
+      creators: ['Tool: agentic-security-0.7.0'],
+    },
+    packages,
+    relationships: packages.map(p => ({
+      spdxElementId: 'SPDXRef-DOCUMENT',
+      relatedSpdxElement: p.SPDXID,
+      relationshipType: 'DESCRIBES',
+    })),
+  };
+}

package/src/posture/schema-aware-bridge.js

@@ -0,0 +1,207 @@
+// Schema-aware cross-language bridges (P4.1).
+//
+// The existing cross-lang bridges (`cross-lang-openapi.js`, `cross-lang-grpc.js`,
+// `cross-lang-graphql.js`) work by NAME-MATCHING: they pair a JS client's
+// `fetch('/api/users/:id')` with a Python `@app.get('/api/users/<id>')`.
+// That misses real attack paths whenever:
+//   - the client and server disagree on the path shape (`:id` vs `<id>` vs `{id}`)
+//   - a field is named differently on each side (clientside `user.email`
+//     posted as JSON; serverside reads `data['emailAddress']`)
+//   - the schema permits extra fields the server silently uses
+//
+// SCHEMA-AWARE bridging uses the actual schema document (OpenAPI / proto /
+// SDL) as the ground truth and propagates taint via STRUCTURAL FIELD
+// IDENTITY rather than name string-equality:
+//
+//   client posts `{ email, password }` to /signup
+//     ↓ (schema says /signup accepts { emailAddress: string, password: string })
+//     ↓ rename client.email → schema.emailAddress
+//   server reads request.body.emailAddress
+//     ↓ inherits client-side taint via schema.emailAddress
+//   server passes emailAddress into raw_sql query
+//     ↓ cross-language SQL-i chain
+//
+// This module builds the SCHEMA FIELD GRAPH for an OpenAPI / proto / SDL
+// document and exposes a `matchEndpoint(schemaDoc, clientCall)` that
+// returns the canonical endpoint shape (path-template + body-schema +
+// param-schema) — usable by the existing bridges as an upgrade-in-place.
+
+/**
+ * Normalize an OpenAPI 3.x path template to a canonical shape.
+ *   `/users/{id}/posts/{postId}` → `/users/:_/posts/:_`
+ *   `/users/<id>`               → `/users/:_`
+ *   `/users/:id`                → `/users/:_`
+ */
+export function canonicalizePath(p) {
+  if (typeof p !== 'string') return '';
+  return p
+    .replace(/\{[^}]+\}/g, ':_')
+    .replace(/<[^>]+>/g, ':_')
+    .replace(/:[A-Za-z0-9_]+/g, ':_')
+    .replace(/\/+$/g, '')
+    .toLowerCase();
+}
+
+/** OpenAPI 3.x → flat list of endpoints with normalized shapes. */
+export function indexOpenApi(doc) {
+  if (!doc || typeof doc !== 'object') return [];
+  const paths = doc.paths || {};
+  const out = [];
+  for (const [rawPath, ops] of Object.entries(paths)) {
+    if (!ops || typeof ops !== 'object') continue;
+    for (const [method, def] of Object.entries(ops)) {
+      if (!/^(get|post|put|patch|delete|head|options)$/i.test(method)) continue;
+      if (!def || typeof def !== 'object') continue;
+      const bodySchema = resolveBodySchema(def, doc);
+      const paramFields = (def.parameters || [])
+        .filter(p => p && (p.in === 'query' || p.in === 'path' || p.in === 'header' || p.in === 'cookie'))
+        .map(p => ({ name: p.name, in: p.in, schema: p.schema || null }));
+      out.push({
+        method: method.toUpperCase(),
+        pathRaw: rawPath,
+        pathCanon: canonicalizePath(rawPath),
+        operationId: def.operationId || null,
+        bodyFields: flattenSchemaFields(bodySchema, doc),
+        paramFields,
+      });
+    }
+  }
+  return out;
+}
+
+function resolveBodySchema(def, doc) {
+  const rb = def.requestBody;
+  if (!rb) return null;
+  const content = rb.content || {};
+  // Prefer application/json.
+  const json = content['application/json'] || content['application/x-www-form-urlencoded'] || Object.values(content)[0];
+  if (!json) return null;
+  return resolveRef(json.schema, doc);
+}
+
+function resolveRef(node, doc) {
+  if (!node) return null;
+  if (node.$ref) {
+    const m = /^#\/components\/schemas\/([^/]+)$/.exec(node.$ref);
+    if (m) return doc?.components?.schemas?.[m[1]] || null;
+  }
+  return node;
+}
+
+/** Walk a JSON schema and return a flat list of `{ path, type }` field descriptors. */
+export function flattenSchemaFields(schema, doc, prefix = '') {
+  if (!schema) return [];
+  const resolved = resolveRef(schema, doc);
+  if (!resolved) return [];
+  if (resolved.type === 'object' && resolved.properties) {
+    const out = [];
+    for (const [name, prop] of Object.entries(resolved.properties)) {
+      const next = prefix ? `${prefix}.${name}` : name;
+      const childResolved = resolveRef(prop, doc);
+      if (childResolved && (childResolved.type === 'object' || childResolved.properties)) {
+        out.push(...flattenSchemaFields(childResolved, doc, next));
+      } else {
+        out.push({ path: next, type: childResolved?.type || 'unknown' });
+      }
+    }
+    return out;
+  }
+  if (resolved.type === 'array' && resolved.items) {
+    return flattenSchemaFields(resolved.items, doc, prefix ? `${prefix}[*]` : '[*]');
+  }
+  return prefix ? [{ path: prefix, type: resolved.type || 'unknown' }] : [];
+}
+
+/**
+ * Match a client-side call site `{ method, path, bodyKeys, queryKeys }`
+ * against the schema's endpoints. Returns the matched endpoint (or null)
+ * + a field-renaming map { clientKey: serverField } when synonyms are
+ * detected.
+ *
+ * Synonym rules (case-insensitive):
+ *   email ↔ emailAddress ↔ mail
+ *   pwd ↔ password
+ *   id ↔ userId ↔ uid
+ *   token ↔ accessToken ↔ authToken
+ */
+const SYNONYMS = [
+  ['email', 'emailaddress', 'mail', 'email_address'],
+  ['pwd',   'password',     'pass', 'passwd'],
+  ['id',    'userid',       'uid',  'user_id'],
+  ['token', 'accesstoken',  'authtoken', 'access_token'],
+  ['name',  'fullname',     'displayname', 'full_name'],
+];
+const SYN_INDEX = new Map();
+for (const grp of SYNONYMS) for (const w of grp) SYN_INDEX.set(w, grp);
+
+function _norm(s) { return String(s || '').toLowerCase().replace(/[_-]/g, ''); }
+function _areSynonyms(a, b) {
+  const na = _norm(a), nb = _norm(b);
+  if (na === nb) return true;
+  const ga = SYN_INDEX.get(na);
+  if (!ga) return false;
+  return ga.includes(nb);
+}
+
+export function matchEndpoint(schemaIndex, clientCall) {
+  if (!Array.isArray(schemaIndex) || !clientCall) return null;
+  const methodU = (clientCall.method || 'GET').toUpperCase();
+  const pathC   = canonicalizePath(clientCall.path || '');
+  // Exact (method, path canonical) match first.
+  let best = null;
+  for (const ep of schemaIndex) {
+    if (ep.method !== methodU) continue;
+    if (ep.pathCanon !== pathC) continue;
+    best = ep; break;
+  }
+  if (!best) return null;
+  // Build the rename map between client-side body keys and server-side fields.
+  const rename = {};
+  const clientKeys = Array.isArray(clientCall.bodyKeys) ? clientCall.bodyKeys : [];
+  const serverFields = best.bodyFields.map(f => f.path);
+  for (const ck of clientKeys) {
+    if (serverFields.includes(ck)) { rename[ck] = ck; continue; }
+    const hit = serverFields.find(sf => _areSynonyms(ck, sf));
+    if (hit) rename[ck] = hit;
+  }
+  return { endpoint: best, rename };
+}
+
+/**
+ * gRPC proto → endpoint index. Accepts the AST shape produced by a generic
+ * proto3 parser (just the field tuples we care about: service + rpc + msg).
+ */
+export function indexProto(protoAst) {
+  if (!protoAst || !Array.isArray(protoAst.services)) return [];
+  const messages = new Map();
+  for (const m of (protoAst.messages || [])) messages.set(m.name, m.fields || []);
+  const out = [];
+  for (const svc of protoAst.services) {
+    for (const rpc of (svc.rpcs || [])) {
+      out.push({
+        service: svc.name,
+        method:  rpc.name,
+        requestType:  rpc.requestType,
+        responseType: rpc.responseType,
+        requestFields:  messages.get(rpc.requestType)  || [],
+        responseFields: messages.get(rpc.responseType) || [],
+      });
+    }
+  }
+  return out;
+}
+
+/**
+ * GraphQL SDL → operation index.
+ */
+export function indexGraphQL(sdlAst) {
+  if (!sdlAst || !Array.isArray(sdlAst.types)) return [];
+  const types = new Map();
+  for (const t of sdlAst.types) types.set(t.name, t.fields || []);
+  const query  = types.get('Query') || [];
+  const mutation = types.get('Mutation') || [];
+  const out = [];
+  for (const f of query)    out.push({ op: 'Query',    name: f.name, args: f.args || [], returns: f.returns });
+  for (const f of mutation) out.push({ op: 'Mutation', name: f.name, args: f.args || [], returns: f.returns });
+  return out;
+}

package/src/posture/security-trend.js

@@ -0,0 +1,87 @@
+// Security regression scorecard — trend tracking across scans.
+//
+// Reads .agentic-security/scan-history.json (appended to by the post-edit hook
+// and runScan) and returns a delta summary: findings added, findings fixed,
+// net change, and which files regressed.
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+
+const HISTORY_FILE = '.agentic-security/scan-history.json';
+const MAX_HISTORY = 30; // rolling window
+
+function _readHistory(scanRoot) {
+  const histPath = scanRoot ? path.join(scanRoot, HISTORY_FILE) : HISTORY_FILE;
+  try {
+    return JSON.parse(fs.readFileSync(histPath, 'utf8'));
+  } catch {
+    return [];
+  }
+}
+
+function _writeHistory(scanRoot, history) {
+  const histPath = scanRoot ? path.join(scanRoot, HISTORY_FILE) : HISTORY_FILE;
+  try {
+    fs.mkdirSync(path.dirname(histPath), { recursive: true });
+    fs.writeFileSync(histPath, JSON.stringify(history.slice(-MAX_HISTORY), null, 2));
+  } catch {}
+}
+
+function _snapshotFromScan(scan, label) {
+  const findings = scan.findings || [];
+  return {
+    timestamp: new Date().toISOString(),
+    label: label || 'scan',
+    total: findings.length,
+    critical: findings.filter(f => f.severity === 'critical').length,
+    high: findings.filter(f => f.severity === 'high').length,
+    medium: findings.filter(f => f.severity === 'medium').length,
+    low: findings.filter(f => f.severity === 'low').length,
+    kev: findings.filter(f => f.kev).length,
+    ids: new Set(findings.map(f => f.id).filter(Boolean)),
+  };
+}
+
+function appendScanSnapshot(scan, scanRoot, label) {
+  const history = _readHistory(scanRoot);
+  const snap = _snapshotFromScan(scan, label);
+  // Don't store the full id Set in JSON — store sorted array
+  const entry = { ...snap, ids: [...snap.ids].sort() };
+  history.push(entry);
+  _writeHistory(scanRoot, history);
+}
+
+function computeTrend(scanRoot) {
+  const history = _readHistory(scanRoot);
+  if (history.length < 2) {
+    return { hasTrend: false, snapshots: history, message: 'Need at least 2 scans to show a trend.' };
+  }
+
+  const prev = history[history.length - 2];
+  const curr = history[history.length - 1];
+
+  const prevIds = new Set(prev.ids || []);
+  const currIds = new Set(curr.ids || []);
+
+  const introduced = [...currIds].filter(id => !prevIds.has(id));
+  const fixed = [...prevIds].filter(id => !currIds.has(id));
+
+  const delta = curr.total - prev.total;
+  const critDelta = curr.critical - prev.critical;
+
+  return {
+    hasTrend: true,
+    snapshots: history,
+    prev: { timestamp: prev.timestamp, total: prev.total, critical: prev.critical, high: prev.high },
+    curr: { timestamp: curr.timestamp, total: curr.total, critical: curr.critical, high: curr.high },
+    introduced: introduced.length,
+    fixed: fixed.length,
+    delta,
+    critDelta,
+    improving: delta <= 0 && critDelta <= 0,
+    introducedIds: introduced.slice(0, 10),
+    fixedCount: fixed.length,
+  };
+}
+
+export { appendScanSnapshot, computeTrend };

package/src/posture/semantic-clone.js

@@ -0,0 +1,114 @@
+// FR-SEM-8 — Semantic clone / equivalence detection.
+//
+// Cluster findings whose sink-side code "shape" is structurally equivalent
+// even when surface text differs (renamed variables, reordered statements,
+// reformatted whitespace). The shape is a normalized AST-token hash: strip
+// identifiers down to their kind (id/lit/op), collapse whitespace, drop
+// comments. Two functions that compute the same thing under different names
+// produce the same shape hash.
+//
+// Two uses:
+//   1. Dedupe near-identical findings across cloned code regions
+//      (annotate `cloneClusterId` so /fix can patch the canonical instance).
+//   2. Surface "you have 3 SQL escaper functions, 1 is broken" — emit an
+//      info finding when a clone cluster contains a mix of vulnerable and
+//      non-vulnerable members (the broken one is the outlier).
+//
+// This is intentionally a coarse approximation, not a full structural
+// equivalence proof. It catches the common case (copy-paste with renaming);
+// it does not catch true semantic equivalence under arbitrary refactoring.
+
+import * as crypto from 'node:crypto';
+
+const JS_TOKEN_RE = /(\/\/[^\n]*|\/\*[\s\S]*?\*\/|"(?:[^"\\]|\\.)*"|'(?:[^'\\]|\\.)*'|`(?:[^`\\]|\\.)*`|\b(?:if|else|for|while|switch|case|return|break|continue|throw|try|catch|finally|function|const|let|var|class|new|this|super|import|export|from|as|async|await|yield|of|in|typeof|instanceof|null|true|false|undefined)\b|\b[A-Za-z_$][\w$]*\b|0x[0-9a-fA-F]+|\d+(?:\.\d+)?|[(){}\[\];,.<>!?:+\-*\/=&|^~%]+|\s+)/g;
+
+const JS_KEYWORDS = new Set([
+  'if','else','for','while','switch','case','return','break','continue','throw',
+  'try','catch','finally','function','const','let','var','class','new','this','super',
+  'import','export','from','as','async','await','yield','of','in','typeof','instanceof',
+  'null','true','false','undefined',
+]);
+
+function tokenize(snippet) {
+  if (!snippet || typeof snippet !== 'string') return [];
+  const tokens = [];
+  for (const m of snippet.matchAll(JS_TOKEN_RE)) {
+    const t = m[0];
+    if (/^\s+$/.test(t)) continue;
+    if (/^\/[\/*]/.test(t)) continue;          // comment
+    if (/^["'`]/.test(t)) { tokens.push('LIT'); continue; }
+    if (/^0x[0-9a-fA-F]+$|^\d/.test(t)) { tokens.push('NUM'); continue; }
+    if (JS_KEYWORDS.has(t)) { tokens.push(`K:${t}`); continue; }
+    if (/^[A-Za-z_$]/.test(t)) { tokens.push('ID'); continue; }
+    tokens.push(t);
+  }
+  return tokens;
+}
+
+export function shapeHash(snippet, opts = {}) {
+  const tokens = tokenize(snippet);
+  if (tokens.length < (opts.minTokens ?? 8)) return null;
+  return crypto.createHash('sha256').update(tokens.join(' ')).digest('hex').slice(0, 16);
+}
+
+// Cluster findings by snippet shape. Returns the same array with two fields
+// added to each finding: cloneClusterId (16-hex or null), cloneClusterSize.
+export function annotateCloneClusters(findings) {
+  if (!Array.isArray(findings) || findings.length === 0) return findings;
+  const buckets = new Map();
+  for (const f of findings) {
+    if (!f || typeof f !== 'object') continue;
+    const snippet = f.snippet || f.sink?.snippet || f.source?.snippet || '';
+    const hash = shapeHash(snippet);
+    if (!hash) { f.cloneClusterId = null; f.cloneClusterSize = 1; continue; }
+    f.cloneClusterId = hash;
+    if (!buckets.has(hash)) buckets.set(hash, []);
+    buckets.get(hash).push(f);
+  }
+  for (const [, group] of buckets) {
+    for (const f of group) f.cloneClusterSize = group.length;
+  }
+  return findings;
+}
+
+// Surface "outlier in clone cluster" infos — when a cluster contains 2+
+// members and they disagree on severity, the high-sev member is likely the
+// broken implementation among siblings.
+export function findCloneOutliers(findings) {
+  if (!Array.isArray(findings)) return [];
+  const buckets = new Map();
+  for (const f of findings) {
+    if (!f || !f.cloneClusterId) continue;
+    if (!buckets.has(f.cloneClusterId)) buckets.set(f.cloneClusterId, []);
+    buckets.get(f.cloneClusterId).push(f);
+  }
+  const out = [];
+  const SEV = { critical: 0, high: 1, medium: 2, low: 3, info: 4 };
+  for (const [hash, group] of buckets) {
+    if (group.length < 3) continue;             // benchmark fixtures cluster as pairs constantly — require 3+
+    const sevs = new Set(group.map(g => g.severity));
+    if (sevs.size < 2) continue;                // homogeneous cluster, not an outlier
+    group.sort((a, b) => (SEV[a.severity] ?? 9) - (SEV[b.severity] ?? 9));
+    const worst = group[0];
+    const worstRank = SEV[worst.severity] ?? 9;
+    const bestRank = SEV[group[group.length - 1].severity] ?? 9;
+    // Require: worst is high+/critical AND spread ≥ 2 severity tiers. This
+    // narrows the rule to genuine "3 sanitizers, 1 is broken" cases and
+    // suppresses benchmark-shape clones that vary only by safe/unsafe label.
+    if (worstRank > 1) continue;                 // worst must be at least 'high'
+    if (bestRank - worstRank < 2) continue;     // need a real gap
+    out.push({
+      id: `clone-outlier:${hash}`,
+      file: worst.file,
+      line: worst.line || 0,
+      vuln: 'Structural clone outlier — one member of a cloned-code cluster is more severe than its siblings',
+      severity: 'info',
+      family: 'clone-outlier',
+      cloneClusterId: hash,
+      cloneClusterSize: group.length,
+      description: `${group.length} structurally-equivalent code regions detected; the one at ${worst.file}:${worst.line} carries ${worst.severity} severity vs. its siblings — likely the broken implementation among copy-pasted helpers.`,
+      remediation: 'Compare implementations across the cluster and either harmonize or remove the divergent member.',
+    });
+  }
+  return out;
+}