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

package/dist/security-runtime/src/core/pipeline.mjs

@@ -0,0 +1,196 @@
+// The shared run path: detect, select checks, run them, normalize, dedupe, accept, gate, write outputs atomically.
+import fs from 'node:fs';
+import path from 'node:path';
+import crypto from 'node:crypto';
+import { AsyncLocalStorage } from 'node:async_hooks';
+import { applyAcceptances, loadAcceptances, loadConfig, reviewItems } from './accept.mjs';
+import { resolveBase } from './base-ref.mjs';
+import { UsageError } from './errors.mjs';
+import { cachedGet, vfetch } from './fetch.mjs';
+import { dedupe, makeFinding, scrubText } from './findings.mjs';
+import { applyPolicy, countsOf, requiredFor, verdictFor } from './gate.mjs';
+import { resolveTool } from './installer.mjs';
+import { acquireLock } from './lock.mjs';
+import { packageRoot } from './paths.mjs';
+import { detect } from './detect.mjs';
+import { nestedSummary } from './nested.mjs';
+import { writeOutputs } from './report.mjs';
+import { runProcess } from './runner.mjs';
+import { reviewIdentity } from '../agent/ingest.mjs';
+import { execFileSync } from 'node:child_process';
+import { captureRuntimeProvenance } from '../lattice/provenance.mjs';
+import { assertStandaloneExecution } from '../lattice/execution.mjs';
+import { loadSelectedRuntime } from '../lattice/selected-runtime.mjs';
+
+// The running check's AbortController. Processes a check starts through ctx.runProcess / ctx.runTool are killed (whole tree) when it
+// aborts: on timeout, when the check ends, and when the pipeline finishes.
+const currentCheck = new AsyncLocalStorage();
+const MAX_CONCURRENT = 3;
+const DEFAULT_CHECK_TIMEOUT_SEC = 1800;
+const withTimeout = (promise, ms, label) => new Promise((resolve, reject) => {
+  const t = setTimeout(() => reject(new Error(`${label} timed out after ${Math.round(ms / 1000)}s`)), ms);
+  promise.then((v) => { clearTimeout(t); resolve(v); }, (e) => { clearTimeout(t); reject(e); });
+});
+
+async function pool(items, limit, fn) {
+  const queue = [...items];
+  await Promise.all(Array.from({ length: Math.min(limit, queue.length) }, async () => {
+    while (queue.length) await fn(queue.shift());
+  }));
+}
+
+export function vsgVersion() {
+  try { return JSON.parse(fs.readFileSync(path.join(packageRoot, 'package.json'), 'utf8')).version; } catch { return '0.0.0'; }
+}
+
+/** Captures the same content identity used by agent review, plus bounded Git state for publication evidence. */
+export function captureReviewContext(repo, runId, out) {
+  const identity = reviewIdentity(repo, runId, out);
+  let commitSha = null;
+  let dirty = true;
+  try {
+    const options = { encoding: 'utf8', timeout: 10_000, stdio: ['ignore', 'pipe', 'pipe'] };
+    const inside = execFileSync('git', ['-C', repo, 'rev-parse', '--is-inside-work-tree'], options).trim();
+    if (inside === 'true') {
+      const commit = execFileSync('git', ['-C', repo, 'rev-parse', 'HEAD'], options).trim();
+      commitSha = /^[0-9a-f]{40}$/.test(commit) ? commit : null;
+      dirty = execFileSync('git', ['-C', repo, 'status', '--porcelain=v1', '--untracked-files=all'], { ...options, maxBuffer: 16 * 1024 * 1024 }).trim().length > 0;
+    }
+  } catch { /* Non-Git inputs retain a null commit and dirty=true. */ }
+  return { ...identity, commitSha, dirty };
+}
+
+/**
+ * Runs one mode over a repository and writes the outputs. Returns { verdict, counts, outputs, ... }.
+ * opts: { mode, repo, out, checks, registry, flags: { base, compare }, now, progress }
+ */
+export async function runPipeline({ mode, repo, out, checks, registry = new Map(), flags = {}, now = () => new Date(), progress = () => {} }) {
+  assertStandaloneExecution({ allowQualification: true });
+  const selectedRuntime = loadSelectedRuntime({ runtimeRoot: packageRoot });
+  repo = path.resolve(repo);
+  if (!fs.existsSync(repo) || !fs.statSync(repo).isDirectory()) throw new UsageError(`"${repo}" is not a directory. Pass the repository path.`);
+  out = path.resolve(out ?? path.join(repo, '.vsg'));
+  let previous = null;
+  if (flags.compare) {
+    try { previous = JSON.parse(fs.readFileSync(flags.compare, 'utf8')); } catch (e) { throw new UsageError(`Cannot read --compare file "${flags.compare}": ${e.message}.`); }
+    if (!Array.isArray(previous?.findings)) throw new UsageError(`--compare file "${flags.compare}" is not a vsg findings.json.`);
+  }
+  const lock = acquireLock(out);
+  const controllers = new Set(); // one per running check
+  try {
+    const startedAt = now().toISOString();
+    const runId = crypto.randomUUID();
+    const sourceStart = captureReviewContext(repo, runId, out);
+    const runtimeStart = captureRuntimeProvenance({ runtimeRoot: packageRoot });
+    const log = [];
+    const note = (line) => log.push(`${new Date().toISOString()} ${line}`);
+    note(`vsg ${vsgVersion()} ${mode} ${repo}`);
+
+    const config = loadConfig(repo);
+    const acceptances = loadAcceptances(repo, { now: now().getTime() });
+    const detection = detect(repo);
+    note(`detected: ${detection.stacks.join(', ') || 'nothing specific'}; lockfiles: ${detection.lockfiles.length}`);
+    if (detection.nestedRepos.length) note(nestedSummary(detection.nestedRepos));
+    const base = resolveBase(repo, { flag: flags.base, config });
+    const baseRef = base.sha;
+    const review = flags.noReview ? [] : reviewItems(repo, baseRef, base.why); // a live run with no repository has nothing to compare
+
+    const { required, removed } = requiredFor(mode, detection, { config });
+    const selected = checks.filter((c) => c.modes.includes(mode));
+    const requiredSet = new Set([...required, ...selected.filter((c) => c.requiredIn.includes(mode) && !removed.some((r) => r.id === c.id)).map((c) => c.id)]);
+    const raw = {};
+    const coverage = [];
+    const rawFindings = [];
+
+    const ctx = {
+      repo, out, mode, detection, nestedRepos: detection.nestedRepos, config, registry, selectedRuntime, baseRef, flags, live: flags.live ?? null, runId, log: note, fetch: vfetch, cachedGet, makeFinding, vsgVersion: vsgVersion(),
+      /** This run's findings so far (normalized, deduped, policy applied). Only meaningful to checks that set `last`, which run after the others. */
+      priorFindings() {
+        const snapshot = structuredClone(dedupe(rawFindings));
+        applyAcceptances(snapshot, acceptances);
+        return applyPolicy(snapshot);
+      },
+      runProcess: (o) => runProcess({ log: note, signal: currentCheck.getStore()?.signal, ...o }),
+      /** Runs a pinned, installed registry tool. Returns the runner result, or not_run with a setup hint. */
+      async runTool(name, args, o = {}) {
+        const tool = registry.get(name);
+        if (!tool) return { status: 'not_run', reason: `Tool "${name}" is not in the registry.` };
+        const resolved = resolveTool(tool);
+        if (!resolved) return { status: 'not_run', reason: `${tool.name} is not installed. Run vsg setup.` };
+        return runProcess({ command: resolved.path, args, cwd: o.cwd ?? repo, timeoutMs: (o.timeoutSec ?? tool.timeoutSec ?? 600) * 1000, envNames: [...(tool.env ?? []), ...(o.envNames ?? [])], extraEnv: o.extraEnv, input: o.input, log: note, signal: currentCheck.getStore()?.signal });
+      },
+    };
+
+    const runCheck = async (check) => {
+      const started = Date.now();
+      const controller = new AbortController();
+      controllers.add(controller);
+      const entry = { id: check.id, status: 'not_run', reason: '', required: requiredSet.has(check.id), toolVersion: null, dataVersions: {}, durationMs: 0 };
+      try {
+        const verdict = await check.applies(ctx);
+        const applies = typeof verdict === 'object' && verdict !== null ? verdict.applies : verdict;
+        if (!applies) {
+          entry.status = 'not_applicable';
+          entry.reason = (typeof verdict === 'object' && verdict?.reason) || 'nothing to check in this repository';
+        } else {
+          // Optional checks become required when their input exists. This keeps a clean repository not_applicable while failing closed
+          // if an artifact was produced but its scanner cannot complete.
+          entry.required = entry.required || check.requiredIfApplied === true;
+          progress(`Running ${check.id}`);
+          const res = await withTimeout(Promise.resolve(currentCheck.run(controller, () => check.run(ctx))), (check.timeoutSec ?? DEFAULT_CHECK_TIMEOUT_SEC) * 1000, check.id);
+          if (!['ran', 'not_run', 'not_applicable'].includes(res?.status)) throw new Error('returned an invalid status');
+          entry.status = res.status;
+          entry.reason = res.reason ?? '';
+          entry.toolVersion = res.toolVersion ?? null;
+          entry.dataVersions = res.dataVersions ?? {};
+          if (res.status === 'ran') for (const f of res.findings ?? []) rawFindings.push(makeFinding(f, check.id));
+          if (res.evidence && typeof res.evidence === 'object') raw[check.id] = res.evidence;
+        }
+      } catch (e) {
+        entry.status = 'not_run';
+        entry.reason = scrubText(e.message);
+        // a check that failed halfway contributes no findings
+        for (let i = rawFindings.length - 1; i >= 0; i--) if (rawFindings[i].check === check.id) rawFindings.splice(i, 1);
+      }
+      controller.abort(); // a timed-out check's scanner processes must not outlive it
+      controllers.delete(controller);
+      entry.durationMs = Date.now() - started;
+      note(`check ${check.id}: ${entry.status}${entry.reason ? ` (${entry.reason})` : ''} in ${entry.durationMs}ms`);
+      coverage.push(entry);
+    };
+    // Explicit numeric phases provide the one ordering barrier needed by post-build artifact checks. There is no general dependency graph:
+    // checks in a phase remain concurrent, and checks without a phase keep the original phase-0 behavior.
+    const phaseOf = (c) => c.last ? Number.MAX_SAFE_INTEGER : (c.phase ?? 0);
+    const phases = [...new Set(selected.map(phaseOf))].sort((a, b) => a - b);
+    for (const phase of phases) await pool(selected.filter((c) => phaseOf(c) === phase), MAX_CONCURRENT, runCheck);
+
+    // a required check with no implementation is not_run: the gate fails closed
+    for (const id of requiredSet) {
+      if (!coverage.some((c) => c.id === id)) {
+        coverage.push({ id, status: 'not_run', reason: `Check "${id}" is not implemented in this build.`, required: true, toolVersion: null, dataVersions: {}, durationMs: 0 });
+      }
+    }
+    coverage.sort((a, b) => a.id.localeCompare(b.id));
+
+    const findings = dedupe(rawFindings);
+    applyAcceptances(findings, acceptances);
+    applyPolicy(findings);
+    if (previous) {
+      const known = new Set(previous.findings.map((f) => f.fingerprint));
+      for (const f of findings) f.isNew = !known.has(f.fingerprint);
+    }
+    const counts = countsOf(findings);
+    const verdict = verdictFor(findings, coverage);
+    const sourceEnd = captureReviewContext(repo, runId, out);
+    const runtimeEnd = captureRuntimeProvenance({ runtimeRoot: packageRoot });
+    const finishedAt = now().toISOString();
+    note(`verdict ${verdict}`);
+
+    const run = { mode, target: flags.target ?? repo, authorization: flags.authorization ?? null, vsgVersion: vsgVersion(), startedAt, finishedAt, verdict, counts, coverage, findings, detection, acceptances, review, removedChecks: removed, raw, log, sourceSnapshot: { schemaVersion: 1, start: sourceStart, end: sourceEnd }, runtimeSnapshot: { schemaVersion: 1, start: runtimeStart, end: runtimeEnd } };
+    const outputs = writeOutputs(out, run);
+    return { verdict, counts, coverage, findings, outputs, review };
+  } finally {
+    for (const c of controllers) c.abort();
+    lock.release();
+  }
+}

package/dist/security-runtime/src/core/registry.mjs

@@ -0,0 +1,81 @@
+// Tool registry: one JSON file per pinned tool in tools/registry/. Declared as data, validated on load.
+import fs from 'node:fs';
+import path from 'node:path';
+import { UsageError } from './errors.mjs';
+import { defaultRegistryDir } from './paths.mjs';
+
+const HEX64 = /^[0-9a-f]{64}$/;
+const IMAGE = /^[a-z0-9][a-z0-9._\/-]*(:[\w.-]+)?@sha256:[0-9a-f]{64}$/;
+const LOCAL_HOSTS = new Set(['localhost', '127.0.0.1', '[::1]']);
+
+function httpsUrl(value) {
+  try {
+    const u = new URL(value);
+    return u.protocol === 'https:' || (u.protocol === 'http:' && LOCAL_HOSTS.has(u.hostname));
+  } catch {
+    return false;
+  }
+}
+
+function safeRelative(p) {
+  if (typeof p !== 'string' || !p || path.isAbsolute(p) || /^[A-Za-z]:/.test(p) || p.includes('\0')) return false;
+  return !p.replace(/\\/g, '/').split('/').includes('..');
+}
+
+export function validateTool(t) {
+  const errors = [];
+  const need = (cond, msg) => { if (!cond) errors.push(msg); };
+  if (!t || typeof t !== 'object') return ['not a JSON object'];
+  need(typeof t.name === 'string' && /^[a-z0-9][a-z0-9-]*$/.test(t.name), 'name must be lowercase letters, digits and dashes');
+  need(typeof t.version === 'string' && t.version.length > 0, 'version is required');
+  need(typeof t.license === 'string' && t.license.length > 0, 'license is required');
+  need(httpsUrl(t.homepage), 'homepage must be an https URL');
+  need(httpsUrl(t.releaseUrl), 'releaseUrl must be an https URL');
+  need(t.checksumsUrl === undefined || httpsUrl(t.checksumsUrl), 'checksumsUrl must be an https URL');
+  need(t.timeoutSec === undefined || (Number.isFinite(t.timeoutSec) && t.timeoutSec > 0), 'timeoutSec must be a positive number');
+  need(t.env === undefined || (Array.isArray(t.env) && t.env.every((n) => typeof n === 'string')), 'env must be an array of variable names');
+  need(!!t.platforms !== !!t.image, 'exactly one of platforms or image is required');
+  need(t.containerPlatform === undefined || (typeof t.containerPlatform === 'string' && !!t.platforms?.[t.containerPlatform]), 'containerPlatform must name one of the platforms');
+  if (t.image !== undefined) need(typeof t.image === 'string' && IMAGE.test(t.image), 'image must be <name>@sha256:<64 hex>');
+  if (t.platforms !== undefined) {
+    need(t.platforms && typeof t.platforms === 'object' && Object.keys(t.platforms).length > 0, 'platforms must not be empty');
+    for (const [key, p] of Object.entries(t.platforms ?? {})) {
+      need(/^[a-z0-9]+-[a-z0-9]+$/.test(key), `platform key "${key}" must look like win32-x64`);
+      need(httpsUrl(p?.url), `${key}: url must be an https URL`);
+      need(HEX64.test(p?.sha256 ?? ''), `${key}: sha256 must be 64 lowercase hex characters`);
+      need(['none', 'zip', 'tar.gz'].includes(p?.archive), `${key}: archive must be none, zip or tar.gz`);
+      need(safeRelative(p?.bin), `${key}: bin must be a relative path without ..`);
+    }
+  }
+  if (t.verify !== undefined) {
+    need(Array.isArray(t.verify?.args) && t.verify.args.every((a) => typeof a === 'string'), 'verify.args must be an array of strings');
+    need(typeof t.verify?.expect === 'string', 'verify.expect must be a string');
+  }
+  return errors;
+}
+
+/** Loads and validates every registry file. Throws UsageError listing all problems (configuration error). */
+export function loadRegistry(dir = defaultRegistryDir) {
+  const tools = new Map();
+  const problems = [];
+  let files = [];
+  try {
+    // <tool>-exclusions.json files are data for a check (for example the YARA Forge exclusion list), not tools
+    files = fs.readdirSync(dir).filter((f) => f.endsWith('.json') && !f.endsWith('-exclusions.json')).sort();
+  } catch { /* no registry directory: empty registry */ }
+  for (const file of files) {
+    let data;
+    try {
+      data = JSON.parse(fs.readFileSync(path.join(dir, file), 'utf8'));
+    } catch (e) {
+      problems.push(`${file}: invalid JSON (${e.message})`);
+      continue;
+    }
+    const errors = validateTool(data);
+    if (data?.name && file !== `${data.name}.json`) errors.push(`file name must be ${data.name}.json`);
+    if (errors.length) problems.push(`${file}: ${errors.join('; ')}`);
+    else tools.set(data.name, data);
+  }
+  if (problems.length) throw new UsageError(`Invalid tool registry: ${problems.join(' | ')}. Fix the registry file.`);
+  return tools;
+}

package/dist/security-runtime/src/core/report.mjs

@@ -0,0 +1,128 @@
+// Output writer (REQ-006): report.md, findings.json, results.sarif, coverage.json, run.log, raw/.
+// Files are staged inside the output directory and moved into place at the end, so a failed run never leaves half-written outputs.
+import fs from 'node:fs';
+import path from 'node:path';
+import { headline } from './gate.mjs';
+import { scrubText, scrubUrl } from './findings.mjs';
+import { nestedSummary } from './nested.mjs';
+import { toSarif } from './sarif.mjs';
+
+const SEV = { critical: 'Critical', high: 'High', medium: 'Medium', low: 'Low', info: 'Info' };
+const OUTPUTS = ['report.md', 'findings.json', 'results.sarif', 'coverage.json', 'run.log', 'raw'];
+
+function retainedSnapshot(outDir, key) {
+  try {
+    const findings = JSON.parse(fs.readFileSync(path.join(outDir, 'findings.json'), 'utf8'))[key];
+    const coverage = JSON.parse(fs.readFileSync(path.join(outDir, 'coverage.json'), 'utf8'))[key];
+    return findings && JSON.stringify(findings) === JSON.stringify(coverage) ? findings : null;
+  } catch { return null; }
+}
+
+function findingBlock(f, n, withReason) {
+  const where = f.location.file ? `${f.location.file}${f.location.line ? `:${f.location.line}` : ''}`
+    : f.location.url ?? (f.location.package ? `${f.location.package}${f.location.version ? `@${f.location.version}` : ''}` : '');
+  const lines = [`${n}. **${SEV[f.severity]}**: ${f.title} (${f.id})`];
+  if (where) lines.push(`   - Where: ${where}`);
+  if (withReason && f.blockReason) lines.push(`   - Why it blocks: ${f.blockReason}`);
+  if (f.description) lines.push(`   - What: ${f.description}`);
+  if (f.exploited.kev) lines.push('   - Known to be exploited (CISA KEV).');
+  if (f.exploited.epss != null) lines.push(`   - EPSS score: ${f.exploited.epss}`);
+  if (f.evidence) lines.push(`   - Evidence: ${f.evidence.replace(/\s+/g, ' ').slice(0, 300)}`);
+  if (f.fix) lines.push(`   - Fix: ${f.fix}`);
+  lines.push(`   - Found by: ${f.sources.map((s) => (s.ruleId ? `${s.tool} (${s.ruleId})` : s.tool)).join(', ')}`);
+  if (f.isNew === true) lines.push('   - New since the comparison run.');
+  return lines.join('\n');
+}
+
+export function renderReport(run) {
+  const { verdict, counts, coverage, findings, mode, target, review, acceptances } = run;
+  const shownTarget = /^https?:\/\//i.test(String(target)) ? scrubUrl(target) : String(target);
+  const out = [`# ${headline(verdict, counts, coverage)}`, '', `Mode: ${mode}. Target: ${shownTarget}. Finished: ${run.finishedAt}.`, ...(run.authorization ? [`Authorized by: ${scrubText(run.authorization)}`] : []), ...(run.detection.nestedRepos?.length ? ['', nestedSummary(run.detection.nestedRepos)] : []), ''];
+
+  out.push('## Must fix', '');
+  const must = findings.filter((f) => f.blocking);
+  out.push(...(must.length ? must.map((f, i) => findingBlock(f, i + 1, true) + '\n') : ['Nothing blocks this release.', '']));
+
+  out.push('## Not tested', '');
+  const notRun = coverage.filter((c) => c.status === 'not_run');
+  const notApplicable = coverage.filter((c) => c.status === 'not_applicable');
+  if (!notRun.length && !notApplicable.length) out.push('Every selected check ran.', '');
+  notRun.forEach((c, i) => out.push(`${i + 1}. ${c.id}: did not run${c.required ? ' (required, so the verdict cannot be PASS)' : ''}. ${c.reason}`));
+  if (notRun.length) out.push('');
+  if (notApplicable.length) out.push(`Not applicable to this repository: ${notApplicable.map((c) => `${c.id}${c.reason ? ` (${c.reason})` : ''}`).join(', ')}.`, '');
+
+  // A check that ran but could not cover everything (files its tool could not parse, stale data, skipped directories) names what it missed.
+  const partial = coverage.filter((c) => c.status === 'ran' && /^degraded:/.test(c.reason ?? ''));
+  if (partial.length) {
+    out.push('## Not fully tested', '');
+    partial.forEach((c, i) => out.push(`${i + 1}. ${c.id}: ran, but ${String(c.reason).replace(/^degraded:\s*/, 'with reduced coverage: ')}`));
+    out.push('');
+  }
+
+  out.push('## Other findings', '');
+  const others = findings.filter((f) => !f.blocking);
+  if (!others.length) out.push('None.', '');
+  const cats = [...new Set(others.map((f) => f.category))].sort();
+  for (const cat of cats) {
+    out.push(`### ${cat}`, '');
+    others.filter((f) => f.category === cat).forEach((f, i) => out.push(findingBlock(f, i + 1, false) + '\n'));
+  }
+
+  out.push('## Acceptances and review items', '');
+  const accLines = [
+    ...findings.filter((f) => f.status === 'accepted').map((f) => `Accepted: ${f.title} (${f.id}).`),
+    ...findings.filter((f) => f.status === 'expired-acceptance').map((f) => `Acceptance expired, finding is open again: ${f.title} (${f.id}).`),
+    ...acceptances.invalid.map((a) => `Ignored invalid acceptance (${a.problem}); it suppresses nothing.`),
+    ...(run.removedChecks ?? []).map((r) => `Required check "${r.id}" was removed by vsg.config.json: ${r.reason}`),
+    ...review.map((r) => `For human review: ${r}`),
+  ];
+  out.push(...(accLines.length ? accLines.map((l, i) => `${i + 1}. ${l}`) : ['None.']), '');
+
+  out.push('## Tools and data versions', '');
+  out.push(`vsg ${run.vsgVersion}.`);
+  for (const c of coverage) {
+    const bits = [c.status, `${c.durationMs} ms`];
+    if (c.toolVersion) bits.push(`tool ${c.toolVersion}`);
+    if (c.dataVersions && Object.keys(c.dataVersions).length) bits.push(`data ${JSON.stringify(c.dataVersions)}`);
+    out.push(`- ${c.id}: ${bits.join(', ')}`);
+  }
+  if (run.detection.stacks.length) out.push(`- Detected: ${run.detection.stacks.join(', ')}`);
+  return `${out.join('\n')}\n`;
+}
+
+/** Writes all outputs. `raw` maps check id to { filename: text }. Returns the output paths. */
+export function writeOutputs(outDir, run) {
+  const sourceSnapshot = run.sourceSnapshot ?? retainedSnapshot(outDir, 'sourceSnapshot');
+  const runtimeSnapshot = run.runtimeSnapshot ?? retainedSnapshot(outDir, 'runtimeSnapshot');
+  const staging = path.join(outDir, `.staging-${process.pid}`);
+  fs.rmSync(staging, { recursive: true, force: true });
+  fs.mkdirSync(path.join(staging, 'raw'), { recursive: true });
+  const json = (x) => `${JSON.stringify(x, null, 2)}\n`;
+  const findingsDoc = {
+    schemaVersion: 1, vsgVersion: run.vsgVersion, mode: run.mode, target: /^https?:\/\//i.test(String(run.target)) ? scrubUrl(run.target) : run.target, authorization: run.authorization ? scrubText(run.authorization) : null, startedAt: run.startedAt, finishedAt: run.finishedAt,
+    verdict: run.verdict, counts: run.counts, checks: run.coverage, findings: run.findings,
+    acceptances: { valid: run.acceptances.valid.length, invalid: run.acceptances.invalid.length }, review: run.review,
+    ...(sourceSnapshot ? { sourceSnapshot } : {}), ...(runtimeSnapshot ? { runtimeSnapshot } : {}),
+  };
+  fs.writeFileSync(path.join(staging, 'findings.json'), json(findingsDoc));
+  fs.writeFileSync(path.join(staging, 'results.sarif'), json(toSarif(run.findings, { vsgVersion: run.vsgVersion })));
+  fs.writeFileSync(path.join(staging, 'coverage.json'), json({ schemaVersion: 1, mode: run.mode, detection: run.detection, skippedNestedRepos: run.detection.nestedRepos?.length ? { count: run.detection.nestedRepos.length, summary: nestedSummary(run.detection.nestedRepos), repos: run.detection.nestedRepos } : null, checks: run.coverage, ...(sourceSnapshot ? { sourceSnapshot } : {}), ...(runtimeSnapshot ? { runtimeSnapshot } : {}) }));
+  fs.writeFileSync(path.join(staging, 'report.md'), renderReport(run));
+  fs.writeFileSync(path.join(staging, 'run.log'), `${run.log.map((l) => scrubText(l)).join('\n')}\n`);
+  for (const [checkId, files] of Object.entries(run.raw)) {
+    for (const [name, content] of Object.entries(files)) {
+      const dir = path.join(staging, 'raw', path.basename(checkId));
+      fs.mkdirSync(dir, { recursive: true });
+      fs.writeFileSync(path.join(dir, path.basename(name)), scrubText(Buffer.isBuffer(content) ? content.toString('utf8') : typeof content === 'string' ? content : JSON.stringify(content, null, 2)));
+    }
+  }
+  for (const name of OUTPUTS) {
+    fs.rmSync(path.join(outDir, name), { recursive: true, force: true });
+    fs.renameSync(path.join(staging, name), path.join(outDir, name));
+  }
+  fs.rmSync(staging, { recursive: true, force: true });
+  return {
+    dir: outDir, report: path.join(outDir, 'report.md'), findings: path.join(outDir, 'findings.json'), sarif: path.join(outDir, 'results.sarif'),
+    coverage: path.join(outDir, 'coverage.json'), log: path.join(outDir, 'run.log'), raw: path.join(outDir, 'raw'),
+  };
+}

package/dist/security-runtime/src/core/runner.mjs

@@ -0,0 +1,86 @@
+// Safe process execution: argument arrays only, environment allowlist, timeout with process-tree kill.
+import { spawn, spawnSync } from 'node:child_process';
+import { scrubText } from './findings.mjs';
+
+// Names every scanner may inherit. Anything else (tokens, cloud keys, proxies with credentials) must be named per tool.
+const BASE_ENV = new Set([
+  'PATH', 'PATHEXT', 'SYSTEMROOT', 'SYSTEMDRIVE', 'WINDIR', 'COMSPEC', 'TEMP', 'TMP', 'TMPDIR', 'HOME', 'HOMEDRIVE', 'HOMEPATH',
+  'USERPROFILE', 'APPDATA', 'LOCALAPPDATA', 'PROGRAMDATA', 'PROGRAMFILES', 'PROGRAMFILES(X86)', 'PROGRAMW6432',
+  'NUMBER_OF_PROCESSORS', 'PROCESSOR_ARCHITECTURE', 'OS', 'LANG', 'LC_ALL', 'TERM', 'TZ', 'NO_COLOR', 'CI',
+  'XDG_CACHE_HOME', 'XDG_CONFIG_HOME', 'XDG_DATA_HOME',
+]);
+
+export function buildEnv(envNames = [], extra = {}) {
+  const allowed = new Set([...BASE_ENV, ...envNames.map((n) => n.toUpperCase())]);
+  const env = {};
+  for (const [k, v] of Object.entries(process.env)) if (allowed.has(k.toUpperCase())) env[k] = v;
+  return { ...env, ...extra };
+}
+
+function killTree(child) {
+  if (!child.pid) return;
+  if (process.platform === 'win32') {
+    spawnSync('taskkill', ['/pid', String(child.pid), '/T', '/F'], { windowsHide: true, stdio: 'ignore' });
+  } else {
+    try { process.kill(-child.pid, 'SIGKILL'); } catch { try { child.kill('SIGKILL'); } catch { /* already gone */ } }
+  }
+}
+
+/**
+ * Runs a command. Resolves { status: 'ran'|'not_run', exitCode, stdout, stderr, durationMs, reason }.
+ * 'ran' means the process started and exited (the caller interprets exitCode). 'not_run' means it could not start, timed out, was
+ * cancelled through `signal` (an AbortSignal; the whole process tree is killed), or wrote more than maxOutputBytes (the tree is
+ * killed then too: an incomplete output is never read as a result).
+ */
+export function runProcess({ command, args = [], cwd, envNames = [], extraEnv = {}, timeoutMs = 600_000, maxOutputBytes = 32 * 1024 * 1024, input, log, signal }) {
+  return new Promise((resolve) => {
+    const started = Date.now();
+    const chunks = { out: [], err: [] };
+    let size = 0;
+    let truncated = false;
+    let timedOut = false;
+    let aborted = false;
+    let settled = false;
+    let child;
+    let timer; // declared before finish() can run: spawn() may throw synchronously (seen in sandboxed agent shells)
+    const onAbort = () => { aborted = true; if (child) killTree(child); };
+    const finish = (result) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      signal?.removeEventListener('abort', onAbort);
+      const durationMs = Date.now() - started;
+      const full = { stdout: Buffer.concat(chunks.out).toString('utf8'), stderr: Buffer.concat(chunks.err).toString('utf8'), durationMs, truncated, ...result };
+      log?.(`$ ${[command, ...args].map((a) => scrubText(a)).join(' ')} -> ${full.status}${full.exitCode !== undefined ? ` exit ${full.exitCode}` : ''}${full.reason ? ` (${full.reason})` : ''} in ${durationMs}ms`);
+      resolve(full);
+    };
+    if (signal?.aborted) { finish({ status: 'not_run', reason: 'cancelled before it started' }); return; }
+    try {
+      child = spawn(command, args, { cwd, env: buildEnv(envNames, extraEnv), shell: false, windowsHide: true, detached: process.platform !== 'win32', stdio: ['pipe', 'pipe', 'pipe'] });
+    } catch (e) {
+      finish({ status: 'not_run', reason: `could not start ${command}: ${e.message}` });
+      return;
+    }
+    signal?.addEventListener('abort', onAbort, { once: true });
+    timer = setTimeout(() => { timedOut = true; killTree(child); }, timeoutMs);
+    const collect = (key) => (d) => {
+      size += d.length;
+      if (size > maxOutputBytes) {
+        if (!truncated) { truncated = true; killTree(child); }
+        return;
+      }
+      chunks[key].push(d);
+    };
+    child.stdout.on('data', collect('out'));
+    child.stderr.on('data', collect('err'));
+    child.on('error', (e) => finish({ status: 'not_run', reason: `could not start ${command}: ${e.message}` }));
+    child.on('close', (code, signalName) => {
+      if (truncated) finish({ status: 'not_run', reason: `output exceeded ${Math.round((maxOutputBytes / 1048576) * 100) / 100} MB and the process was stopped` });
+      else if (aborted) finish({ status: 'not_run', reason: 'cancelled and stopped' });
+      else if (timedOut) finish({ status: 'not_run', reason: `timed out after ${timeoutMs / 1000}s and was stopped` });
+      else finish({ status: 'ran', exitCode: code ?? -1, signal: signalName });
+    });
+    child.stdin.on('error', () => {});
+    child.stdin.end(input);
+  });
+}

package/dist/security-runtime/src/core/sarif.mjs

@@ -0,0 +1,141 @@
+// SARIF 2.1.0 in (normalizer) and out (results.sarif), plus the CWE to OWASP Top 10:2025 map.
+import crypto from 'node:crypto';
+import { scrubText, redact } from './findings.mjs';
+
+const A = {
+  A01: 'A01:2025 Broken Access Control',
+  A02: 'A02:2025 Security Misconfiguration',
+  A03: 'A03:2025 Software Supply Chain Failures',
+  A04: 'A04:2025 Cryptographic Failures',
+  A05: 'A05:2025 Injection',
+  A06: 'A06:2025 Insecure Design',
+  A07: 'A07:2025 Authentication Failures',
+  A08: 'A08:2025 Software or Data Integrity Failures',
+  A09: 'A09:2025 Security Logging and Alerting Failures',
+  A10: 'A10:2025 Mishandling of Exceptional Conditions',
+};
+const GROUPS = {
+  A01: [22, 23, 36, 73, 200, 201, 219, 284, 285, 352, 359, 402, 425, 441, 497, 538, 540, 548, 552, 566, 601, 639, 668, 706, 862, 863, 918, 922, 1275],
+  A02: [2, 11, 13, 15, 16, 260, 315, 489, 547, 611, 614, 756, 776, 942, 1004, 1032, 1174],
+  A03: [829, 937, 1035, 1104, 1357, 1395],
+  A04: [261, 296, 310, 311, 312, 319, 321, 322, 323, 324, 325, 326, 327, 328, 329, 330, 331, 335, 336, 337, 338, 340, 347, 523, 757, 759, 760, 780, 818, 916],
+  A05: [20, 74, 75, 77, 78, 79, 80, 83, 87, 88, 89, 90, 91, 93, 94, 95, 96, 97, 98, 99, 113, 116, 138, 184, 470, 471, 564, 610, 643, 644, 652, 917, 943, 1236, 1336],
+  A06: [73, 183, 256, 266, 269, 311, 419, 430, 434, 444, 451, 463, 501, 522, 525, 539, 579, 598, 602, 642, 646, 653, 656, 657, 799, 807, 840, 841, 927, 1021, 1173],
+  A07: [255, 259, 287, 288, 290, 294, 295, 297, 300, 302, 304, 306, 307, 346, 384, 521, 613, 620, 640, 798, 940, 941, 1216],
+  A08: [345, 353, 426, 494, 502, 565, 784, 830, 915],
+  A09: [117, 223, 532, 778],
+  A10: [209, 215, 234, 248, 252, 274, 280, 369, 390, 391, 394, 396, 397, 431, 456, 476, 636, 703, 754, 755, 833],
+};
+// first group listed wins when a CWE appears in several groups
+export const CWE_TO_OWASP = {};
+for (const [group, cwes] of Object.entries(GROUPS)) for (const n of cwes) CWE_TO_OWASP[n] ??= A[group];
+
+export function owaspForCwes(cwes) {
+  const out = new Set();
+  for (const c of cwes) {
+    const n = Number(String(c).replace(/\D/g, ''));
+    if (CWE_TO_OWASP[n]) out.add(CWE_TO_OWASP[n]);
+  }
+  return [...out];
+}
+
+/** security-severity 9+ critical, 7+ high, 4+ medium, above 0 low; otherwise level error/warning/note -> high/medium/low. */
+export function severityFromSarif(result, rule) {
+  const raw = result?.properties?.['security-severity'] ?? rule?.properties?.['security-severity'];
+  const score = raw === undefined ? NaN : Number(raw);
+  if (Number.isFinite(score) && score > 0) return score >= 9 ? 'critical' : score >= 7 ? 'high' : score >= 4 ? 'medium' : 'low';
+  const level = result?.level ?? rule?.defaultConfiguration?.level ?? 'warning';
+  return { error: 'high', warning: 'medium', note: 'low' }[level] ?? 'info';
+}
+
+const PRECISION = { 'very-high': 'high', high: 'high', medium: 'medium', low: 'low' };
+
+function cwesOf(rule, result) {
+  const found = new Set();
+  const sources = [...(rule?.properties?.tags ?? []), ...(result?.properties?.tags ?? []), rule?.properties?.cwe, ...(rule?.relationships ?? []).map((r) => r?.target?.id)].flat();
+  for (const s of sources) {
+    const m = typeof s === 'string' ? /cwe[-/ _]?(\d+)/i.exec(s) : null;
+    if (m) found.add(`CWE-${m[1]}`);
+  }
+  return [...found];
+}
+
+function uriToPath(uri, repo) {
+  let p = String(uri ?? '');
+  if (p.startsWith('file:///')) p = p.slice(8);
+  else if (p.startsWith('file://')) p = p.slice(7);
+  try { p = decodeURIComponent(p); } catch { /* keep raw */ }
+  p = p.replace(/\\/g, '/');
+  if (repo) {
+    const root = repo.replace(/\\/g, '/').replace(/\/$/, '');
+    if (p.toLowerCase().startsWith(`${root.toLowerCase()}/`)) p = p.slice(root.length + 1);
+  }
+  return p.replace(/^\.\//, '');
+}
+
+/**
+ * Normalizes SARIF 2.1.0 to raw findings (input for makeFinding).
+ * opts: { tool, category, repo, secrets (redact snippets), fix, confidence }
+ */
+export function normalizeSarif(sarif, opts = {}) {
+  const out = [];
+  for (const run of sarif?.runs ?? []) {
+    const driver = run.tool?.driver ?? {};
+    const rules = driver.rules ?? [];
+    const byId = new Map(rules.map((r) => [r.id, r]));
+    for (const result of run.results ?? []) {
+      const rule = byId.get(result.ruleId) ?? rules[result.ruleIndex];
+      const ruleId = result.ruleId ?? rule?.id ?? 'unknown';
+      const phys = result.locations?.[0]?.physicalLocation;
+      const file = phys?.artifactLocation?.uri ? uriToPath(phys.artifactLocation.uri, opts.repo) : undefined;
+      const line = phys?.region?.startLine;
+      const snippet = phys?.region?.snippet?.text ?? phys?.contextRegion?.snippet?.text ?? '';
+      const evidence = snippet ? (opts.secrets ? redact(snippet.trim()) : scrubText(snippet.trim().slice(0, 500))) : '';
+      const cwe = cwesOf(rule, result);
+      out.push({
+        tool: opts.tool ?? driver.name,
+        ruleId,
+        key: `${ruleId}:${crypto.createHash('sha256').update(snippet.trim() || String(line ?? '')).digest('hex').slice(0, 12)}`,
+        category: opts.category ?? 'other',
+        severity: severityFromSarif(result, rule),
+        confidence: opts.confidence ?? PRECISION[rule?.properties?.precision] ?? 'medium',
+        title: rule?.shortDescription?.text ?? rule?.name ?? ruleId,
+        description: result.message?.text ?? rule?.fullDescription?.text ?? '',
+        location: { file, line },
+        evidence,
+        refs: [rule?.helpUri].filter(Boolean),
+        fix: opts.fix ?? '',
+        cwe,
+      });
+    }
+  }
+  return out;
+}
+
+const LEVEL = { critical: 'error', high: 'error', medium: 'warning', low: 'note', info: 'note' };
+const SCORE = { critical: 9.5, high: 8, medium: 5, low: 2 };
+
+/** Writes our findings as SARIF 2.1.0 (results.sarif). */
+export function toSarif(findings, { vsgVersion = '0.0.0' } = {}) {
+  const rules = new Map();
+  const results = findings.map((f) => {
+    const ruleId = `${f.check}/${f.sources[0]?.ruleId ?? f.id}`;
+    if (!rules.has(ruleId)) rules.set(ruleId, { id: ruleId, name: ruleId, shortDescription: { text: f.title } });
+    const result = {
+      ruleId,
+      level: LEVEL[f.severity],
+      message: { text: f.description ? `${f.title}: ${f.description}` : f.title },
+      partialFingerprints: { vsgFingerprint: f.fingerprint },
+      properties: { ...(SCORE[f.severity] ? { 'security-severity': String(SCORE[f.severity]) } : {}), severity: f.severity, blocking: f.blocking, status: f.status },
+    };
+    if (f.location.file) {
+      result.locations = [{ physicalLocation: { artifactLocation: { uri: f.location.file }, ...(f.location.line ? { region: { startLine: f.location.line } } : {}) } }];
+    }
+    return result;
+  });
+  return {
+    $schema: 'https://json.schemastore.org/sarif-2.1.0.json',
+    version: '2.1.0',
+    runs: [{ tool: { driver: { name: 'vsg', version: vsgVersion, rules: [...rules.values()] } }, results }],
+  };
+}