@m2-ai/lattice-cli 0.0.0-stage → 0.8.7

package/dist/security-runtime/src/checks/code/index.mjs

@@ -0,0 +1,617 @@
+// code (REQ-013): Opengrep with a pinned general ruleset (semgrep-rules, fetched into the tools cache, never committed)
+// plus the vsg stack rules in rules/. Reads source only; never runs the scanned project's code.
+import fs from 'node:fs';
+import path from 'node:path';
+import { listFiles } from '../../core/detect.mjs';
+import { resolveTool, resolveVerifiedArchive } from '../../core/installer.mjs';
+import { packageRoot, toolsDir } from '../../core/paths.mjs';
+import { normalizeSarif } from '../../core/sarif.mjs';
+import { callsUnconditionally, discoverAuthHelpers, MAX_DEPTH as MAX_AUTH_DEPTH, parseDeclarations, parseImports, regexNames, resolveModule, rpcPrimitive, stripComments, stripLiterals, writeRulesWithHelpers } from './auth-helpers.mjs';
+import { scanTargetsWithIgnored } from '../_lib/targets.mjs';
+import { runOpengrepContainer, runSelectedOpengrepContainer } from './opengrep-container.mjs';
+import { assertStandaloneExecution } from '../../lattice/execution.mjs';
+import { withTransientDockerSource } from '../../lattice/source-acquirer.mjs';
+
+export const id = 'code';
+export const title = 'Insecure code and stack rules (Opengrep)';
+export const modes = ['scan', 'deep', 'release'];
+export const requiredIn = ['scan', 'deep', 'release'];
+export const timeoutSec = 900;
+
+export const VSG_RULES_DIR = path.join(packageRoot, 'rules');
+
+/**
+ * Rule directories taken from the pinned semgrep-rules package (paths relative to the package root).
+ * Security directories only. Left out on purpose: best-practice, correctness, performance and portability packs
+ * (style, not exploitability), generic/secrets (Betterleaks owns secrets), GitHub Actions rules (zizmor owns workflows),
+ * and stacks Richard does not ship. Changing the pin means re-checking this list against the new package.
+ */
+export const RULE_DIRS = [
+  'javascript/lang/security', 'javascript/browser/security', 'javascript/express/security',
+  'javascript/jsonwebtoken', 'javascript/jose', 'javascript/jwt-simple', 'javascript/node-crypto', 'javascript/passport-jwt',
+  'javascript/serialize-javascript', 'javascript/shelljs', 'javascript/vm2', 'javascript/sequelize',
+  'typescript/lang/security', 'typescript/react/security', 'typescript/nestjs',
+  'python/lang/security', 'python/requests/security', 'python/flask/security', 'python/django/security', 'python/fastapi',
+  'python/jinja2', 'python/jwt', 'python/cryptography', 'python/sqlalchemy/security', 'python/pymongo', 'python/docker', 'python/boto3', 'python/sh',
+  'dockerfile/security', 'yaml/docker-compose/security',
+];
+
+// Directories that are not the product's own code. Test fixtures are excluded so planted examples never become findings.
+export const EXCLUDES = ['node_modules', '.next', 'dist', 'build', '.vsg', '.venv', 'venv', '.git', '__pycache__', '.pnpm-store', 'fixtures', '__fixtures__'];
+
+const SOURCE = /\.(?:[cm]?[jt]sx?|py)$|(?:^|\/)(?:Dockerfile(?:\..+)?|[^/]+\.dockerfile|(?:docker-)?compose(?:[.-][^/]+)?\.ya?ml)$/i;
+
+/**
+ * Hostile-input guard for YAML. Opengrep's --timeout and --max-memory do not bound the YAML parser: a few-hundred-byte alias-expansion
+ * file ("billion laughs", for example Juice Shop test/files/yamlBomb.yml) makes it run until the whole check times out (verified on 1.30.0:
+ * with --timeout 15 and with --max-memory 1000 it still ran past 100 s). Restricting YAML to compose files would not help (a bomb can be named
+ * docker-compose.yml) and Opengrep's --exclude globs misbehave on Windows (the runtime expands "*.yml" against the working directory),
+ * so every YAML file is screened here by a cheap expansion estimate and an offender is excluded by its exact path and reported as degraded.
+ */
+export const YAML_EXPANSION_LIMIT = 100_000;
+const YAML_FILE = /\.ya?ml$/i;
+const ALIAS = /(?:^|[\s[{,:-])\*[^\s,\]}]+/g;
+const ANCHOR = /(?:^|[\s[{,:-])&([^\s,\]}]+)/g;
+const MAX_SCREEN_BYTES = 1_000_000; // Opengrep ignores bigger files itself (--max-target-bytes default)
+
+/** Estimated node count after alias expansion, line by line. Over-estimates are fine; a bomb grows exponentially so it cannot hide. */
+export function yamlExpansionEstimate(text) {
+  const anchors = new Map(); // anchor name -> estimated size
+  const open = []; // anchors whose block is still open: { name, indent }
+  let total = 0;
+  for (const raw of text.split(/\r?\n/)) {
+    const line = raw.replace(/\s#.*$/, '');
+    if (!line.trim() || line.trim().startsWith('#')) continue;
+    const indent = line.length - line.trimStart().length;
+    while (open.length && indent <= open.at(-1).indent) open.pop();
+    let cost = 1;
+    for (const m of line.matchAll(ALIAS)) cost += anchors.get(m[0].replace(/^[^*]*\*/, '')) ?? 1;
+    total += cost;
+    for (const o of open) anchors.set(o.name, anchors.get(o.name) + cost);
+    for (const m of line.matchAll(ANCHOR)) { anchors.set(m[1], cost); open.push({ name: m[1], indent }); }
+    if (total > YAML_EXPANSION_LIMIT * 1000) return Infinity;
+  }
+  return total;
+}
+
+/** YAML files (relative posix paths) whose alias expansion is too large to hand to Opengrep. Honors the same directory exclusions as the scan. */
+export function screenYaml(repo, nested = []) {
+  const skipped = [];
+  const skipNested = new Set(nested.map((n) => n.path));
+  const walk = (dir, rel) => {
+    let entries;
+    try { entries = fs.readdirSync(dir, { withFileTypes: true }); } catch { return; }
+    for (const e of entries) {
+      if (e.isSymbolicLink()) continue;
+      const r = rel ? `${rel}/${e.name}` : e.name;
+      if (e.isDirectory()) { if (!EXCLUDES.includes(e.name) && !skipNested.has(r)) walk(path.join(dir, e.name), r); continue; }
+      if (!e.isFile() || !YAML_FILE.test(e.name)) continue;
+      try {
+        const full = path.join(dir, e.name);
+        if (fs.statSync(full).size > MAX_SCREEN_BYTES) continue;
+        const text = fs.readFileSync(full, 'utf8');
+        if (!text.includes('*')) continue;
+        const est = yamlExpansionEstimate(text);
+        if (est > YAML_EXPANSION_LIMIT) skipped.push({ file: r, estimate: est });
+      } catch { /* unreadable: Opengrep reports it itself */ }
+    }
+  };
+  walk(repo, '');
+  return skipped;
+}
+
+export function applies(ctx) {
+  const files = listFiles(ctx.repo);
+  return files.some((f) => SOURCE.test(f))
+    ? true
+    : { applies: false, reason: 'no JavaScript, TypeScript, Python or Docker files were found' };
+}
+
+/**
+ * Reads the vsg rules. SARIF carries no custom metadata, so blocking, fix and OWASP labels come from the rule files.
+ * Returns Map<ruleId, { blocking, fix, owasp }>.
+ */
+export function loadVsgRules(dir = VSG_RULES_DIR) {
+  const rules = new Map();
+  let files = [];
+  try { files = fs.readdirSync(dir).filter((f) => /\.ya?ml$/.test(f)).sort(); } catch { return rules; }
+  for (const file of files) {
+    const text = fs.readFileSync(path.join(dir, file), 'utf8');
+    const starts = [...text.matchAll(/^\s*- id:\s*(\S+)\s*$/gm)];
+    starts.forEach((m, i) => {
+      const block = text.slice(m.index, starts[i + 1]?.index ?? text.length);
+      const meta = (key) => new RegExp(`^\\s*${key}:\\s*(.+?)\\s*$`, 'm').exec(block)?.[1]?.replace(/^["']|["']$/g, '');
+      rules.set(m[1], {
+        blocking: meta('vsg-blocking') === 'true',
+        fix: meta('vsg-fix') ?? '',
+        title: meta('vsg-title'),
+        severity: meta('vsg-severity'),
+        owasp: meta('owasp')?.replace(/\s+-\s+/, ' '),
+      });
+    });
+  }
+  return rules;
+}
+
+/** Opengrep rewrites rule ids to dotted config paths; this returns the stable id (vsg-... or the registry rule id). */
+export function cleanRuleId(raw, selectedRuleIds = []) {
+  const s = String(raw);
+  const vsg = /(?:^|\.)(vsg-[a-z0-9-]+)$/.exec(s);
+  if (vsg) return vsg[1];
+  const selected = selectedRuleIds.filter((ruleId) => s === ruleId || s.endsWith(`.${ruleId}`));
+  if (selected.length === 1) return selected[0];
+  return s.replace(/^.*?semgrep-rules-[0-9a-f]{40}\./, '');
+}
+
+const firstSentence = (text) => {
+  const t = String(text ?? '').replace(/\s+/g, ' ').trim();
+  const end = t.search(/[.!?](\s|$)/);
+  const s = end > 0 ? t.slice(0, end + 1) : t;
+  return s.length > 140 ? `${s.slice(0, 137)}...` : s;
+};
+
+const CONFIDENCE_TAG = /^(HIGH|MEDIUM|LOW) CONFIDENCE$/i;
+
+/**
+ * Maps Opengrep SARIF to raw findings through the core normalizer.
+ * vsg rules marked blocking become High with "confirmed" confidence (the gate blocks them) and other vsg rules stay below High;
+ * registry rules keep their level, and only ERROR with HIGH confidence reaches the gate's blocking threshold.
+ */
+export function mapSarif(sarif, { repo, vsgRules = loadVsgRules(), selectedRuleIds = [] } = {}) {
+  const clone = structuredClone(sarif);
+  const tagsOf = new Map();
+  const messageOf = new Map();
+  for (const run of clone.runs ?? []) {
+    for (const rule of run.tool?.driver?.rules ?? []) {
+      const tags = rule.properties?.tags ?? [];
+      rule.id = cleanRuleId(rule.id, selectedRuleIds);
+      // SARIF precision from Opengrep says "very-high" for every rule, so confidence comes from the rule's own CONFIDENCE tag.
+      const conf = tags.map((t) => CONFIDENCE_TAG.exec(t)?.[1]?.toLowerCase()).find(Boolean) ?? 'medium';
+      rule.properties = { ...rule.properties, precision: conf };
+      const text = rule.fullDescription?.text ?? rule.help?.text ?? '';
+      rule.shortDescription = { text: firstSentence(text) || rule.id };
+      tagsOf.set(rule.id, tags);
+      messageOf.set(rule.id, text);
+    }
+    for (const result of run.results ?? []) {
+      result.ruleId = cleanRuleId(result.ruleId, selectedRuleIds);
+      delete result.ruleIndex;
+    }
+  }
+  const mapped = normalizeSarif(clone, { tool: 'opengrep', category: 'code', repo }).map((f) => {
+    const vsg = vsgRules.get(f.ruleId);
+    const out = { ...f };
+    if (vsg) {
+      // A non-blocking vsg rule is capped below High unless the rule file says vsg-severity: high (it still cannot block: its confidence stays below high).
+      out.severity = vsg.blocking ? 'high' : vsg.severity === 'high' ? 'high' : (f.severity === 'high' || f.severity === 'critical' ? 'medium' : f.severity);
+      out.confidence = vsg.blocking ? 'confirmed' : (f.confidence === 'high' ? 'medium' : f.confidence);
+      out.fix = vsg.fix;
+      if (vsg.title) out.title = vsg.title;
+      out.owasp = vsg.owasp ? [vsg.owasp] : [];
+    } else {
+      out.fix = `Review the flagged code and apply the safer pattern described in the finding. Rule: ${f.ruleId}.`;
+    }
+    if (!out.title || out.title.length < 4) out.title = f.ruleId;
+    return out;
+  });
+  return dedupeWrites(dropRegistryDuplicates(mapped, vsgRules), repo);
+}
+
+/**
+ * A registry rule that flags the same line and the same weakness (CWE) as a vsg rule is the same issue: the vsg finding carries the
+ * stack-specific fix, so the registry copy is dropped. It is kept when it would block and the vsg finding would not.
+ */
+function dropRegistryDuplicates(findings, vsgRules) {
+  const vsg = findings.filter((f) => vsgRules.has(f.ruleId));
+  return findings.filter((f) => {
+    if (vsgRules.has(f.ruleId)) return true;
+    const twin = vsg.find((v) => v.location.file === f.location.file && v.location.line === f.location.line && v.cwe.some((c) => f.cwe.includes(c)));
+    if (!twin) return true;
+    const blocksAlone = f.severity === 'high' && f.confidence === 'high';
+    return blocksAlone && twin.confidence !== 'confirmed';
+  });
+}
+
+/** The "writes without checking the caller" rules match every write call; a handler or action is the unit a person fixes. */
+export const WRITE_RULES = new Set(['vsg-nextjs-route-write-no-auth', 'vsg-nextjs-action-write-no-auth', 'vsg-nextjs-inline-action-write-no-auth']);
+// A function begins at a line that declares one: `function f(`, or `const f = async (...) =>` / `const f = function`.
+const FUNCTION_START = /^\s*(?:export\s+)?(?:default\s+)?(?:async\s+)?function\b|^\s*(?:export\s+)?(?:const|let|var)\s+[\w$]+\s*(?::[^=]+)?=\s*(?:async\s*)?(?:function\b|\([^)]*\)\s*(?::[^=]+?)?\s*=>|[\w$]+\s*=>)/;
+
+/**
+ * One finding per handler or action: of the write-rule findings in the same function, keeps the first write and says how many more there are.
+ * The enclosing function is the nearest declaration line above the write, found by reading the file as text. A file that cannot be read keeps its findings as they are.
+ */
+export function dedupeWrites(findings, repo) {
+  if (!repo) return findings;
+  const starts = new Map(); // file -> sorted line numbers where a function declaration begins
+  const startsOf = (file) => {
+    if (!starts.has(file)) {
+      let lines = [];
+      try { lines = fs.readFileSync(path.join(repo, file), 'utf8').split(/\r?\n/); } catch { /* unreadable: keep findings */ }
+      starts.set(file, lines.length ? lines.flatMap((l, i) => (FUNCTION_START.test(l) ? [i + 1] : [])) : null);
+    }
+    return starts.get(file);
+  };
+  const groups = new Map(); // `${rule}|${file}|${handlerStart}` -> findings
+  const out = [];
+  for (const f of findings) {
+    const file = f.location?.file;
+    const line = f.location?.line;
+    const s = WRITE_RULES.has(f.ruleId) && file && line ? startsOf(file) : null;
+    if (!s) { out.push(f); continue; }
+    const start = s.filter((n) => n <= line).at(-1) ?? 0;
+    const key = `${f.ruleId}|${file}|${start}`;
+    if (!groups.has(key)) { groups.set(key, []); out.push(groups.get(key)); }
+    groups.get(key).push(f);
+  }
+  return out.map((g) => {
+    if (!Array.isArray(g)) return g;
+    g.sort((a, b) => a.location.line - b.location.line);
+    const [first, ...rest] = g;
+    if (!rest.length) return first;
+    return { ...first, description: `${first.description} This handler makes ${g.length} write calls in all, first at line ${first.location.line} (others at lines ${rest.map((r) => r.location.line).join(', ')}); fixing the check at the top fixes all of them.` };
+  });
+}
+
+/**
+ * Names in one file that reach an auth primitive within MAX_DEPTH calls through functions of the same file, exported or not.
+ */
+function localAuthDetails(text, authRpcs = []) {
+  const rpcRe = rpcPrimitive(authRpcs);
+  const decls = parseDeclarations(text, { extraPrimitives: rpcRe ? [rpcRe] : [] });
+  const dist = new Map([...decls.values()].filter((d) => d.primitive).map((d) => [d.name, 1]));
+  const failsClosed = new Set([...decls.values()].filter((d) => d.failsClosed).map((d) => d.name));
+  for (let pass = 0; pass < MAX_AUTH_DEPTH; pass++) {
+    let changed = false;
+    for (const d of decls.values()) {
+      for (const c of d.calls) {
+        if (dist.has(c) && dist.get(c) < MAX_AUTH_DEPTH && !(dist.get(d.name) <= dist.get(c) + 1)) { dist.set(d.name, dist.get(c) + 1); changed = true; }
+        if (failsClosed.has(c) && callsUnconditionally(d.body, c)) {
+          if (!failsClosed.has(d.name)) { failsClosed.add(d.name); changed = true; }
+        }
+      }
+    }
+    if (!changed) break;
+  }
+  return new Map([...dist.keys()].filter((n) => /^[A-Za-z_$][\w$]*$/.test(n)).map((n) => {
+    const declaration = decls.get(n);
+    return [n, { failsClosed: failsClosed.has(n), returnsAuthValue: declaration?.returnsAuthValue === true, denialKeys: declaration?.denialKeys ?? new Set() }];
+  }));
+}
+
+export function localAuthNames(text, authRpcs = []) { return new Set(localAuthDetails(text, authRpcs).keys()); }
+
+/**
+ * Automatic discovery is definition-aware: a custom guard only excuses a write when the file
+ * actually calls a local helper or imports the discovered helper from its defining module. The
+ * shipped `authHelpers` configuration remains an explicit policy and is handled in the rules.
+ */
+function importedAuthDetails(repo, file, text, helpers) {
+  if (!helpers.length) return new Map();
+  const localDeclarations = parseDeclarations(text);
+  const imports = parseImports(text);
+  const out = new Map();
+  for (const [local, binding] of imports) {
+    if (localDeclarations.has(local)) continue; // a local declaration shadows the import
+    const target = resolveModule(repo, file, binding.source);
+    if (!target) continue;
+    const helper = helpers.find((h) => h.file === target && (h.name === binding.imported || (h.exports ?? []).includes(binding.imported) || (binding.imported === 'default' && (h.exports ?? []).includes('default'))));
+    if (helper) out.set(local, { failsClosed: helper.failsClosed === true, returnsAuthValue: helper.returnsAuthValue === true, denialKeys: new Set(helper.denialKeys ?? []) });
+  }
+  return out;
+}
+
+const escapedName = (name) => name.replace(/\$/g, '\\$');
+
+function resultBindings(statement, helper) {
+  const name = escapedName(helper);
+  const m = new RegExp(`^\\s*(?:const|let|var)\\s+(\\{[^}]+\\}|[A-Za-z_$][\\w$]*)(?:\\s*:[^=]+)?\\s*=\\s*(?:await\\s+)?${name}\\s*\\(\\s*\\)\\s*;?\\s*$`).exec(stripLiterals(stripComments(statement)));
+  if (!m) return [];
+  if (!m[1].startsWith('{')) return [{ key: m[1], local: m[1] }];
+  return m[1].slice(1, -1).split(',').map((part) => part.trim()).filter(Boolean).map((part) => {
+    const pair = part.split(/\s*:\s*/);
+    const key = pair[0].replace(/\?$/, '').trim();
+    const local = (pair[1] ?? key).trim();
+    return /^[A-Za-z_$][\w$]*$/.test(key) && /^[A-Za-z_$][\w$]*$/.test(local) ? { key, local } : null;
+  }).filter(Boolean);
+}
+
+function callerEnforcesResult(lines, fromIndex, toIndex, bindings, helper) {
+  if (!bindings.length) return false;
+  const after = stripLiterals(stripComments(lines.slice(fromIndex + 1, toIndex).join('\n')));
+  if (/\bcatch\b|=>|\bfunction\b/.test(after)) return false;
+  let depth = 0;
+  const flags = stripLiterals(stripComments(lines.join('\n'))).split(/\r?\n/).map((code) => {
+    const atTop = depth === 1;
+    depth += (code.match(/{/g) ?? []).length - (code.match(/}/g) ?? []).length;
+    return { code, atTop };
+  });
+  if (!flags[fromIndex]?.atTop) return false;
+  let guardIndex = fromIndex + 1;
+  while (guardIndex < toIndex && !flags[guardIndex].code.trim()) guardIndex++;
+  if (guardIndex >= toIndex || !flags[guardIndex].atTop) return false;
+  const guardLine = flags[guardIndex].code;
+  for (const { key, local } of bindings) {
+    const variable = escapedName(local);
+    const deniedName = helper.denialKeys?.has(key) === true;
+    const authValue = helper.returnsAuthValue === true && /^(?:user|session|claims|context|identity|access|result|auth)$/i.test(key);
+    const negated = authValue && new RegExp(`^\\s*if\\s*\\(\\s*!\\s*${variable}(?:\\.(?:allowed|authorized|authenticated|user|session))?\\s*\\)\\s*(?:\\{\\s*)?(?:return|throw)\\b`);
+    const successFlag = /^(?:allowed|authorized|authenticated)$/i.test(key);
+    const positive = deniedName && new RegExp(`^\\s*if\\s*\\(\\s*${successFlag ? '!' : ''}${variable}\\s*\\)\\s*(?:\\{\\s*)?(?:return|throw)\\b`);
+    if ((negated && negated.test(guardLine)) || (positive && positive.test(guardLine))) return true;
+  }
+  return false;
+}
+
+/**
+ * Drops write-without-auth findings whose handler calls a file-local auth wrapper before the write (see localAuthNames).
+ * Returns { findings, dropped: [{ file, line, helper }] }. A file that cannot be read keeps its findings.
+ */
+export function dropLocalAuthWrites(findings, repo, authRpcs = [], discoveredHelpers = []) {
+  const cache = new Map();
+  const load = (file) => {
+    if (!cache.has(file)) {
+      try {
+        const text = fs.readFileSync(path.join(repo, file), 'utf8');
+        const lines = text.split(/\r?\n/);
+        const helpers = localAuthDetails(text, authRpcs);
+        for (const [name, detail] of importedAuthDetails(repo, file, text, discoveredHelpers)) helpers.set(name, detail);
+        cache.set(file, { lines, starts: lines.flatMap((line, index) => FUNCTION_START.test(line) ? [index + 1] : []), helpers });
+      } catch { cache.set(file, null); }
+    }
+    return cache.get(file);
+  };
+  const dropped = [];
+  const kept = findings.filter((finding) => {
+    const file = finding.location?.file;
+    const line = finding.location?.line;
+    const info = WRITE_RULES.has(finding.ruleId) && file && line ? load(file) : null;
+    if (!info || !info.helpers.size) return true;
+    const start = info.starts.filter((number) => number <= line).at(-1) ?? 1;
+    const lines = info.lines.slice(start - 1, line - 1);
+    let depth = 0;
+    const flags = stripLiterals(stripComments(lines.join('\n'))).split(/\r?\n/).map((code) => {
+      const atTop = depth === 1;
+      depth += (code.match(/{/g) ?? []).length - (code.match(/}/g) ?? []).length;
+      return { code, atTop };
+    });
+    if (!/\{\s*$/.test(flags[0]?.code ?? '')) return true;
+    const calls = [];
+    for (const name of info.helpers.keys()) {
+      const re = new RegExp(`(?<![\\w$.])${escapedName(name)}\\s*\\(`);
+      for (let index = 1; index < flags.length; index++) if (re.test(flags[index].code)) calls.push({ name, index });
+    }
+    calls.sort((left, right) => left.index - right.index);
+    const first = calls[0];
+    if (!first || !flags[first.index].atTop) return true;
+    const { name: helper, index: callAt } = first;
+    const detail = info.helpers.get(helper);
+    const callCode = flags[callAt].code;
+    const call = new RegExp(`^\\s*(?:(?:(?:await|return\\s+await)\\s+|return\\s+)|(?:const|let|var)\\s+(?:\\{[^}]+\\}|[A-Za-z_$][\\w$]*)(?:\\s*:[^=]+)?\\s*=\\s*await\\s+)${escapedName(helper)}\\s*\\(\\s*\\)\\s*;?\\s*$`);
+    const prefix = flags.slice(1, callAt).map((entry) => entry.code).join('\n');
+    if (!call.test(callCode) || /\b(?:if|else|switch|for|while|try|catch|return|throw)\b|=>/.test(prefix)) return true;
+    const beforeWrite = stripLiterals(stripComments(lines.join('\n')));
+    const caught = /\b(?:try|catch)\b/.test(beforeWrite);
+    const binding = resultBindings(lines[callAt], helper);
+    const enforced = detail.failsClosed && !caught || callerEnforcesResult(lines, callAt, lines.length, binding, detail);
+    if (!enforced) return true;
+    dropped.push({ file, line, helper });
+    return false;
+  });
+  return { findings: kept, dropped };
+}
+
+/**
+ * Opengrep's parser (tree-sitter) rejects some valid TypeScript and JavaScript: `new?: string` in a type, `typeof fn<T>` (an instantiation
+ * expression) and `import("pkg").Type` in a type position, and some files for reasons that could not be narrowed (a script with two regex
+ * literals containing `<`). The file is then skipped apart from a warning, so every such file is named here: the report lists them under
+ * "Not fully tested" because the code rules may have missed findings in them (Opengrep recovers part of some of these files, none of the rest). Verified on 1.30.0: forcing a language or another file extension does not help.
+ * Returns { files: [relative posix path], other: [note] }.
+ */
+export function splitScanNotes(notes) {
+  const files = [];
+  const other = [];
+  for (const n of notes) {
+    const m = /^Syntax error at line (.+?):\d+:?\s*$/.exec(n);
+    if (m) files.push(m[1].replace(/\\/g, '/').replace(/^\.\//, ''));
+    else other.push(n);
+  }
+  return { files: [...new Set(files)].sort(), other };
+}
+
+function sarifNotes(sarif) {
+  const notes = [];
+  for (const run of sarif?.runs ?? []) {
+    for (const inv of run.invocations ?? []) {
+      if (inv.executionSuccessful === false) notes.push('Opengrep reported an unsuccessful execution.');
+      for (const n of inv.toolExecutionNotifications ?? []) {
+        if (n.level === 'error' || n.level === 'warning') notes.push(String(n.message?.text ?? n.descriptor?.id ?? 'a scan error').split('\n')[0].slice(0, 200));
+      }
+    }
+  }
+  return notes;
+}
+
+/**
+ * Docker normally receives relative artifact paths because its working directory is /scan.
+ * Normalize an absolute mount path too, so findings, parser diagnostics and auth-helper
+ * post-processing always use paths relative to the Windows repository.
+ */
+export function normalizeContainerSarifPaths(sarif, mount = '/scan') {
+  const prefix = `${mount.replace(/\/$/, '')}/`;
+  const filePrefix = `file://${prefix}`;
+  const relative = (value) => {
+    if (typeof value !== 'string') return value;
+    if (value.startsWith(filePrefix)) return value.slice(filePrefix.length);
+    if (value.startsWith(prefix)) return value.slice(prefix.length);
+    return value;
+  };
+  const inText = (value) => typeof value === 'string'
+    ? value.replaceAll(filePrefix, '').replaceAll(prefix, '')
+    : value;
+  for (const run of sarif?.runs ?? []) {
+    for (const result of run.results ?? []) {
+      for (const location of result.locations ?? []) {
+        const artifact = location?.physicalLocation?.artifactLocation;
+        if (artifact?.uri) artifact.uri = relative(artifact.uri);
+      }
+    }
+    for (const invocation of run.invocations ?? []) {
+      for (const note of invocation.toolExecutionNotifications ?? []) {
+        if (note?.message?.text) note.message.text = inText(note.message.text);
+      }
+    }
+  }
+  return sarif;
+}
+
+/**
+ * Opengrep on Windows expands %NAME% in its arguments the way cmd.exe does. A folder named literally "%SystemDrive%" (a script that
+ * created it from an unexpanded variable) became the target "C:", and the scan walked the whole drive until the 15 minute timeout
+ * (verified on 1.30.0, Windows 10). Doubling every percent sign keeps the literal name; verified that "%%" reaches Opengrep as "%",
+ * and that a name with an undefined variable such as "x%FOO%y.py" is unchanged either way.
+ */
+export const literalArg = (arg, platform = process.platform) => (platform === 'win32' ? String(arg).replace(/%/g, '%%') : String(arg));
+
+/** Opengrep arguments (verified against `opengrep scan --help` for 1.30.0). Run with the repository as the working directory. */
+export function scanArgs(root, skipFiles = [], rulesDir = VSG_RULES_DIR, nested = [], targets = ['.'], platform = process.platform, ruleDirs = RULE_DIRS) {
+  const lit = (a) => literalArg(a, platform);
+  const join = platform === 'win32' ? path.win32.join : path.posix.join;
+  return [
+    'scan', '--sarif', '--quiet', '--disable-version-check',
+    // --disable-nosem: a "nosem" comment in the scanned repository must not silence a finding; only vsg.accept.json (approved by Richard) can.
+    '--disable-nosem',
+    // --no-git-ignore: scan files even when .gitignore hides them (for example a worktree under an ignored path), so a clean result is never silent.
+    '--no-git-ignore',
+    // --x-ignore-semgrepignore-files: a .semgrepignore in the scanned repository can hide directories silently. This flag is marked internal
+    // in --help; if a future Opengrep drops it the scan fails loudly (not_run), never silently.
+    '--x-ignore-semgrepignore-files',
+    '--timeout', '15',
+    ...EXCLUDES.flatMap((e) => ['--exclude', e]),
+    // exact paths only (never globs, see screenYaml)
+    ...skipFiles.flatMap((f) => ['--exclude', lit(f)]),
+    // nested repositories and worktrees: other checkouts, not this repository. Verified on 1.30.0: a leading slash anchors the exact path
+    // (the same path without it also matched; either way there is no glob, so Windows has nothing to expand).
+    ...nested.flatMap((n) => ['--exclude', lit(`/${n.path}`)]),
+    '-c', rulesDir,
+    ...ruleDirs.flatMap((d) => ['-c', join(root, d)]),
+    ...targets.map(lit),
+  ];
+}
+
+export async function run(ctx) {
+  assertStandaloneExecution({ allowQualification: true });
+  const artifactMode = ctx.selectedRuntime?.kind === 'lattice-artifact';
+  const selected = artifactMode ? ctx.selectedRuntime.selectedRuntime?.sast : null;
+  if (artifactMode && !selected) return { status: 'not_run', reason: 'The selected SAST runtime contract is missing; restricted fallback is refused.' };
+  const rulesTool = artifactMode ? null : ctx.registry?.get('semgrep-rules');
+  const containerMode = artifactMode || (process.platform === 'win32' && typeof ctx.runProcess === 'function');
+  const resolved = !containerMode && rulesTool ? resolveTool(rulesTool) : null;
+  const archive = containerMode && rulesTool ? resolveVerifiedArchive(rulesTool) : null;
+  if (!artifactMode && !resolved && !archive) return { status: 'not_run', reason: 'The semgrep-rules ruleset is not installed. Run vsg setup.' };
+  const root = artifactMode
+    ? '/tmp/vsg-selected-opengrep/source'
+    : containerMode
+    ? path.posix.join('/tmp/vsg-opengrep/rules', path.posix.dirname(rulesTool.platforms['win32-x64'].bin.replaceAll('\\', '/')))
+    : path.dirname(resolved.path);
+  const missing = artifactMode
+    ? []
+    : containerMode
+    ? RULE_DIRS.filter((d) => !Object.keys(archive.files).some((file) => file.startsWith(`${path.posix.dirname(rulesTool.platforms['win32-x64'].bin.replaceAll('\\', '/'))}/${d}/`)))
+    : RULE_DIRS.filter((d) => !fs.existsSync(path.join(root, d)));
+  if (missing.length) return { status: 'not_run', reason: `The pinned ruleset is missing expected rule directories (${missing.slice(0, 3).join(', ')}). Re-run vsg setup --repair or update RULE_DIRS for the new pin.` };
+
+  const hostile = screenYaml(ctx.repo, ctx.nestedRepos);
+  // Explicit authHelpers are added to a generated copy of the rules. Automatically discovered
+  // helpers stay out of the global rule regex: a name can be exported by unrelated modules, and a
+  // regex cannot tell which definition a call resolves to. They are checked after SARIF against
+  // the actual local/imported definition instead.
+  const found = discoverAuthHelpers(ctx.repo, { excludes: EXCLUDES });
+  const configured = ctx.config?.authHelpers ?? [];
+  const extra = regexNames(configured);
+  let rulesDir = VSG_RULES_DIR;
+  let tempRules = null;
+  if (extra.length) {
+    fs.mkdirSync(toolsDir(), { recursive: true });
+    tempRules = fs.mkdtempSync(path.join(toolsDir(), 'rules-'));
+    writeRulesWithHelpers(VSG_RULES_DIR, tempRules, extra);
+    rulesDir = tempRules;
+  }
+  // A working copy that holds agent worktrees also tends to hold ignored build output and browser profiles (a 4.6 GB .next-e2e took Opengrep
+  // past its time limit on its own). Git never ignores tracked files, so these directories hold only untracked, uncommitted files. They are
+  // skipped only in that situation (nested checkouts found), and counted in the reason so the coverage never claims them.
+  const nestedPaths = (ctx.nestedRepos ?? []).map((n) => n.path);
+  const { targets, ignoredDirs, prunedDirs } = scanTargetsWithIgnored(ctx.repo, nestedPaths, EXCLUDES, nestedPaths.length > 0);
+  let res;
+  try {
+    if (artifactMode) {
+      const opengrepTool = ctx.registry?.get('opengrep');
+      const linux = opengrepTool ? resolveTool(opengrepTool, 'linux-x64') : null;
+      const runner = ctx.registry?.get('yara-runner');
+      if (!linux || !runner?.image) return { status: 'not_run', reason: 'The verified Linux Opengrep binary or runner image is unavailable. Run vsg setup --repair.' };
+      try {
+        res = await withTransientDockerSource(ctx, { image: runner.image, source: selected.source, label: 'sast' }, ({ volume }) => runSelectedOpengrepContainer(ctx, {
+          args: scanArgs(root, hostile.map((h) => h.file), '/vsg/rules', ctx.nestedRepos, targets, 'linux', selected.rulesRoots),
+          opengrep: { ...linux, sha256: opengrepTool.platforms['linux-x64'].sha256 },
+          source: selected.source,
+          sourceFiles: selected.sourceFiles,
+          ruleIdsSha256: selected.ruleIdsSha256,
+          vsgRulesDir: rulesDir,
+          timeoutMs: (opengrepTool.timeoutSec ?? timeoutSec) * 1000,
+          volume,
+        }));
+      } catch (error) {
+        return { status: 'not_run', reason: `Selected SAST ${error.message}` };
+      }
+    } else if (containerMode) {
+      const opengrepTool = ctx.registry?.get('opengrep');
+      const linux = opengrepTool ? resolveTool(opengrepTool, 'linux-x64') : null;
+      if (!linux) return { status: 'not_run', reason: 'The verified Linux Opengrep binary is not installed. Run vsg setup --repair.' };
+      res = await runOpengrepContainer(ctx, {
+        args: scanArgs(root, hostile.map((h) => h.file), '/vsg/rules', ctx.nestedRepos, targets, 'linux'),
+        opengrep: { ...linux, sha256: opengrepTool.platforms['linux-x64'].sha256 },
+        rulesArchive: archive,
+        rulesRoot: path.posix.dirname(rulesTool.platforms['win32-x64'].bin.replaceAll('\\', '/')),
+        vsgRulesDir: rulesDir,
+        timeoutMs: (opengrepTool.timeoutSec ?? timeoutSec) * 1000,
+      });
+    } else {
+      res = await ctx.runTool('opengrep', scanArgs(root, hostile.map((h) => h.file), rulesDir, ctx.nestedRepos, targets));
+    }
+  } finally {
+    if (tempRules) fs.rmSync(tempRules, { recursive: true, force: true });
+  }
+  if (res.status !== 'ran') return { status: 'not_run', reason: res.reason };
+  if (res.truncated) return { status: 'not_run', reason: 'Opengrep output was too large to read completely.' };
+  if (res.exitCode !== 0) {
+    const tail = res.stderr.trim().split(/\r?\n/).slice(-3).join(' | ');
+    return { status: 'not_run', reason: `Opengrep failed with exit code ${res.exitCode}${tail ? `: ${tail}` : ''}.` };
+  }
+  let sarif;
+  try { sarif = JSON.parse(res.stdout); } catch { return { status: 'not_run', reason: 'Opengrep did not return valid SARIF.' }; }
+  if (containerMode) normalizeContainerSarifPaths(sarif);
+
+  const local = dropLocalAuthWrites(mapSarif(sarif, { repo: ctx.repo, selectedRuleIds: selected?.selectedRuleIds ?? [] }), ctx.repo, found.authRpcs, found.helpers);
+  const findings = local.findings;
+  const { files: unparsed, other: notes } = splitScanNotes(sarifNotes(sarif));
+  const reasons = [
+    ...(hostile.length ? [`skipped ${hostile.length} YAML file(s) whose alias expansion is too large to parse safely (for example ${hostile[0].file})`] : []),
+    ...(ignoredDirs.length ? [`skipped ${ignoredDirs.length} ignored, untracked director${ignoredDirs.length === 1 ? 'y' : 'ies'} because nested worktrees were present (for example ${ignoredDirs.slice(0, 3).join(', ')})`] : []),
+    ...(found.capped ? [`auth-helper discovery indexed only the first ${found.indexedFiles} of ${found.candidateFiles} source files, so a wrapper defined later may not be recognized`] : []),
+    ...(unparsed.length ? [`Opengrep could not parse ${unparsed.length} file(s), so the code rules may have missed findings in them (a parser limitation, not a finding): ${unparsed.slice(0, 20).join(', ')}${unparsed.length > 20 ? `, and ${unparsed.length - 20} more` : ''}`] : []),
+    ...(notes.length ? [`Opengrep reported ${notes.length} scan problem(s), for example: ${notes[0]}`] : []),
+  ];
+  return {
+    status: 'ran',
+    reason: reasons.length ? `degraded: ${reasons.join('; ')}` : '',
+    findings,
+    toolVersion: ctx.registry?.get('opengrep')?.version ?? null,
+    dataVersions: artifactMode
+      ? { 'selected-sast': selected.source.manifestSha256.slice(0, 12), 'selected-sast-rules': String(selected.selectedRuleIds.length), 'vsg-rules': String(loadVsgRules().size) }
+      : { 'semgrep-rules': rulesTool.version.slice(0, 12), 'vsg-rules': String(loadVsgRules().size) },
+    evidence: { opengrepExitCode: res.exitCode, results: findings.length, ruleDirectories: RULE_DIRS.length, scanProblems: notes.slice(0, 20), unparsedFiles: unparsed.slice(0, 200), skippedIgnoredDirs: ignoredDirs.slice(0, 100), skippedDependencyDirs: prunedDirs.slice(0, 100), droppedLocalAuthWrites: local.dropped.slice(0, 100), skippedYaml: hostile.slice(0, 50).map((h) => ({ file: h.file, estimatedNodes: Number.isFinite(h.estimate) ? h.estimate : 'unbounded' })), durationMs: res.durationMs,
+      authHelpers: { discovered: found.helpers.slice(0, 200), configured, authRpcs: found.authRpcs.slice(0, 200), indexedFiles: found.indexedFiles, candidateFiles: found.candidateFiles, capped: found.capped } },
+  };
+}
+
+export default { id, title, modes, requiredIn, timeoutSec, applies, run };