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

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

@@ -0,0 +1,131 @@
+// Gate (REQ-005): blocking policy and required checks as data tables, verdict semantics.
+import { SEVERITIES } from './findings.mjs';
+
+const atLeast = (f, min) => SEVERITIES.indexOf(f.severity) <= SEVERITIES.indexOf(min);
+const strong = (f) => f.confidence === 'high' || f.confidence === 'confirmed';
+
+/**
+ * Default blocking policy (build spec Data Contract). One row per finding category; blocks(f) returns a reason or null.
+ * Checks express policy inputs through severity and confidence: e.g. a vsg rule marked blocking emits confidence "confirmed";
+ * a secret only in history that is validated inactive is emitted below High; a reproduced agent finding is "confirmed".
+ */
+export const BLOCKING_POLICY = [
+  // Medium and below (low-signal generic matches, public-by-design info) are reported, never blocking (REQ-037).
+  { category: 'secret', blocks: (f) => (atLeast(f, 'high') ? 'Secret in the working tree, build output or served JavaScript' : null) },
+  { category: 'secret-history', blocks: (f) => (atLeast(f, 'high') ? 'Secret in git history (High)' : null) },
+  { category: 'malicious-package', blocks: () => 'Known malicious package' },
+  {
+    category: 'dependency-vuln',
+    blocks: (f) => (f.exploited.kev ? 'Vulnerability listed in CISA KEV'
+      : f.severity === 'critical' ? 'Critical dependency vulnerability'
+        : f.severity === 'high' && f.fix ? 'High dependency vulnerability with a fixed version' : null),
+  },
+  { category: 'dependency-change', blocks: (f) => (atLeast(f, 'high') ? 'Suspicious dependency change' : null) },
+  { category: 'code', blocks: (f) => (atLeast(f, 'high') && strong(f) ? 'Blocking code rule (error level, high confidence)' : null) },
+  { category: 'supabase', blocks: (f) => (atLeast(f, 'high') ? 'Supabase exposure' : null) },
+  { category: 'workflow', blocks: (f) => (atLeast(f, 'high') && strong(f) ? 'CI workflow risk (High severity, high confidence)' : null) },
+  { category: 'agent-surface', blocks: (f) => (atLeast(f, 'high') ? 'Critical or High agent-surface finding' : null) },
+  // Critical: any AV engine, a YARA rule scored 70 or more, or two YARA rules on one file. Medium: a lone low-score YARA heuristic (REQ-037).
+  { category: 'malware', blocks: (f) => (atLeast(f, 'high') ? 'Malware detection' : null) },
+  { category: 'replay', blocks: () => 'Cross-account replay succeeded' },
+  { category: 'live', blocks: (f) => (atLeast(f, 'high') ? 'High-impact live-site exposure' : null) },
+  { category: 'iac', blocks: (f) => (atLeast(f, 'high') ? 'High container or infrastructure misconfiguration' : null) },
+  { category: 'release', blocks: (f) => (atLeast(f, 'high') ? 'Release build, typecheck or test failure' : null) },
+  {
+    category: 'agent-finding',
+    blocks: (f) => (f.severity === 'critical' && f.confidence !== 'confirmed' ? 'Unreproduced Critical agent finding: needs confirmation'
+      : atLeast(f, 'high') && f.confidence === 'confirmed' ? 'Reproduced High or Critical agent finding' : null),
+  },
+  // posture, license, config and other categories never block by default
+];
+
+/**
+ * Required checks per mode. `when` is a detection or config condition ('always' if omitted); '@mode' includes another mode's set.
+ * Check ids are the contract between this table and src/checks/<id>/.
+ */
+export const REQUIRED_CHECKS = {
+  scan: [
+    { id: 'deps-vuln' }, { id: 'secrets-tree' }, { id: 'code' }, { id: 'agent-surface' },
+    { id: 'workflows', when: 'workflows' }, { id: 'dep-change', when: 'lockfiles' },
+  ],
+  deep: [
+    '@scan', { id: 'secrets-history' }, { id: 'malware' }, { id: 'licenses' },
+    { id: 'supabase-static', when: 'supabase' }, { id: 'agent-review' },
+  ],
+  url: [{ id: 'live-basic' }, { id: 'live-js-secrets' }],
+  release: ['@deep', '@url', { id: 'project-scripts' }, { id: 'sbom' }],
+};
+
+const CONDITIONS = {
+  always: () => true,
+  workflows: (d) => d.workflows.length > 0,
+  lockfiles: (d) => d.lockfiles.length > 0,
+  supabase: (d) => d.supabase,
+  accounts: (_d, x) => !!x.hasAccounts,
+};
+
+function expand(mode, detection, extra, seen = new Set()) {
+  if (seen.has(mode)) return [];
+  seen.add(mode);
+  const ids = [];
+  for (const row of REQUIRED_CHECKS[mode] ?? []) {
+    if (typeof row === 'string') ids.push(...expand(row.slice(1), detection, extra, seen));
+    else if (CONDITIONS[row.when ?? 'always'](detection, extra)) ids.push(row.id);
+  }
+  return ids;
+}
+
+/** Returns { required: [id], removed: [{ id, reason }] } after applying vsg.config.json requiredChecks.remove. */
+export function requiredFor(mode, detection, { config, hasAccounts = false } = {}) {
+  const ids = [...new Set(expand(mode, detection, { hasAccounts }))];
+  const removeList = config?.requiredChecks?.remove ?? [];
+  const removed = removeList.filter((r) => ids.includes(r.check)).map((r) => ({ id: r.check, reason: r.reason }));
+  const gone = new Set(removed.map((r) => r.id));
+  return { required: ids.filter((id) => !gone.has(id)), removed };
+}
+
+/** Sets blocking and blockReason from the policy. Accepted findings never block. */
+export function applyPolicy(findings, policy = BLOCKING_POLICY) {
+  for (const f of findings) {
+    const row = policy.find((p) => p.category === f.category);
+    const reason = f.status === 'accepted' ? null : row?.blocks(f) ?? null;
+    f.blocking = !!reason;
+    f.blockReason = reason ?? '';
+  }
+  return findings;
+}
+
+export function countsOf(findings) {
+  const counts = Object.fromEntries(SEVERITIES.map((s) => [s, 0]));
+  let blocking = 0;
+  let accepted = 0;
+  for (const f of findings) {
+    counts[f.severity]++;
+    if (f.blocking) blocking++;
+    if (f.status === 'accepted') accepted++;
+  }
+  return { ...counts, total: findings.length, blocking, accepted };
+}
+
+/**
+ * BLOCKED if any finding blocks; otherwise INCOMPLETE if a required check did not run (not_run or missing);
+ * otherwise PASS. A required check that is not_applicable is satisfied. PASS is never returned with a required check not run.
+ */
+export function verdictFor(findings, coverage) {
+  if (findings.some((f) => f.blocking)) return 'BLOCKED';
+  if (coverage.some((c) => c.required && c.status === 'not_run')) return 'INCOMPLETE';
+  return 'PASS';
+}
+
+export const EXIT_CODES = { PASS: 0, BLOCKED: 1, INCOMPLETE: 2 };
+
+/** First output line: the result in words. */
+export function headline(verdict, counts, coverage) {
+  const missing = coverage.filter((c) => c.required && c.status === 'not_run').length;
+  const plural = (n, w) => `${n} ${w}${n === 1 ? '' : 's'}`;
+  if (verdict === 'BLOCKED') {
+    return `BLOCKED: ${plural(counts.blocking, 'must-fix finding')}${missing ? ` and ${plural(missing, 'required check')} did not run` : ''}`;
+  }
+  if (verdict === 'INCOMPLETE') return `INCOMPLETE: ${plural(missing, 'required check')} did not run`;
+  return 'PASS: no must-fix findings and every required check ran';
+}

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

@@ -0,0 +1,255 @@
+// Verified installer: download, check SHA-256 BEFORE extracting, extract to a staging directory, then move into the tools cache.
+// Never touches PATH or system settings.
+import fs from 'node:fs';
+import path from 'node:path';
+import { extractArchive, listTarGz, listZip, safeJoin } from './archive.mjs';
+import { InstallError } from './errors.mjs';
+import { vfetch } from './fetch.mjs';
+import { sha256 } from './findings.mjs';
+import { platformKey, toolsDir } from './paths.mjs';
+import { runProcess } from './runner.mjs';
+
+const MARKER = '.vsg-installed.json';
+const MARKER_VERSION = 2;
+const ARCHIVE = '.vsg-verified-archive';
+const ARCHIVE_MARKER = '.vsg-archive-only.json';
+export const installDir = (tool, platform) => {
+  const hostPlatform = platformFor(tool);
+  return platform && platform !== hostPlatform
+    ? path.join(toolsDir(), '_platforms', platform, tool.name, tool.version)
+    : path.join(toolsDir(), tool.name, tool.version);
+};
+
+/** Hash every file in an installed tree. The marker itself is excluded. */
+function contentManifest(root) {
+  const files = {};
+  const walk = (dir, rel = '') => {
+    for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+      const child = path.join(dir, entry.name);
+      const childRel = rel ? path.join(rel, entry.name) : entry.name;
+      if (childRel === MARKER || childRel === ARCHIVE) continue;
+      if (entry.isDirectory()) walk(child, childRel);
+      else if (entry.isFile()) files[childRel.split(path.sep).join('/')] = sha256(fs.readFileSync(child));
+      else throw new Error(`installed tool contains unsupported entry "${childRel}"`);
+    }
+  };
+  walk(root);
+  return Object.fromEntries(Object.entries(files).sort(([a], [b]) => a.localeCompare(b)));
+}
+
+const sameManifest = (a, b) => {
+  const ak = Object.keys(a).sort();
+  const bk = Object.keys(b).sort();
+  return ak.length === bk.length && ak.every((k, i) => k === bk[i] && a[k] === b[k]);
+};
+
+const archiveManifest = (buf, kind) => {
+  const entries = kind === 'zip' ? listZip(buf) : kind === 'tar.gz' ? listTarGz(buf) : null;
+  if (!entries) throw new Error(`unsupported archive type "${kind}"`);
+  const files = {};
+  for (const entry of entries) {
+    if (entry.dir) continue;
+    let name;
+    try {
+      const root = path.resolve('__vsg_archive_manifest_root__');
+      const absolute = safeJoin(root, entry.name);
+      name = path.relative(root, absolute).split(path.sep).join('/');
+      if (!name) throw new Error('empty path');
+    } catch {
+      throw new Error(`unsafe archive entry "${entry.name}"`);
+    }
+    if (name === MARKER || name === ARCHIVE) throw new Error(`unsafe archive entry "${entry.name}"`);
+    if (files[name] !== undefined) throw new Error(`duplicate archive entry "${name}"`);
+    files[name] = sha256(entry.data());
+  }
+  return Object.fromEntries(Object.entries(files).sort(([a], [b]) => a.localeCompare(b)));
+};
+
+/**
+ * The platform whose build is installed for a tool on this host: the host's own, else the tool's containerPlatform
+ * (a build that runs in a Linux container, for example YARA-X on Windows, where the native binary is not used).
+ */
+export function platformFor(tool) {
+  const host = platformKey();
+  return tool.platforms?.[host] ? host : (tool.containerPlatform ?? host);
+}
+
+/** Returns { path, dir, platform } for an installed tool on this host, or null. */
+export function resolveTool(tool, platform = platformFor(tool)) {
+  const entry = tool.platforms?.[platform];
+  if (!entry) return null;
+  const dir = installDir(tool, platform);
+  try {
+    const marker = JSON.parse(fs.readFileSync(path.join(dir, MARKER), 'utf8'));
+    const bin = safeJoin(dir, entry.bin);
+    if (marker.schemaVersion !== MARKER_VERSION || marker.name !== tool.name || marker.version !== tool.version || marker.archiveSha256 !== entry.sha256 || !marker.files) return null;
+    if (marker.platform && marker.platform !== platform) return null;
+    if (platform !== platformFor(tool) && marker.platform !== platform) return null;
+    const expected = entry.archive === 'none'
+      ? { [entry.bin.replace(/\\/g, '/')]: entry.sha256 }
+      : (() => {
+        const archive = fs.readFileSync(path.join(dir, ARCHIVE));
+        if (sha256(archive) !== entry.sha256) throw new Error('verified archive changed');
+        return archiveManifest(archive, entry.archive);
+      })();
+    if (!sameManifest(marker.files, expected) || !sameManifest(marker.files, contentManifest(dir))) return null;
+    if (!Object.prototype.hasOwnProperty.call(marker.files, entry.bin.replace(/\\/g, '/')) || !fs.lstatSync(bin).isFile()) return null;
+    return { path: bin, dir, platform };
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Returns a checksum-bound compressed archive and its complete file manifest.
+ * This intentionally does not trust or require extracted files: Windows can
+ * keep a rules package compressed and let a pinned Linux runner extract it.
+ */
+export function resolveVerifiedArchive(tool, platform = platformFor(tool)) {
+  const entry = tool.platforms?.[platform];
+  if (!entry || entry.archive === 'none') return null;
+  const dir = installDir(tool, platform);
+  try {
+    const archive = path.join(dir, ARCHIVE);
+    const bytes = fs.readFileSync(archive);
+    if (sha256(bytes) !== entry.sha256) return null;
+    const archiveOnly = fs.existsSync(path.join(dir, ARCHIVE_MARKER));
+    const markerPath = archiveOnly ? path.join(dir, ARCHIVE_MARKER) : path.join(dir, MARKER);
+    const marker = JSON.parse(fs.readFileSync(markerPath, 'utf8'));
+    if (marker.schemaVersion !== (archiveOnly ? 1 : MARKER_VERSION) || marker.name !== tool.name || marker.version !== tool.version || marker.archiveSha256 !== entry.sha256 || !marker.files) return null;
+    if (marker.platform && marker.platform !== platform) return null;
+    if (platform !== platformFor(tool) && marker.platform !== platform) return null;
+    const expected = archiveManifest(bytes, entry.archive);
+    if (!sameManifest(marker.files, expected)) return null;
+    return { path: archive, dir, platform, archive: entry.archive, sha256: entry.sha256, files: expected };
+  } catch {
+    return null;
+  }
+}
+
+/** Runs the registry's verify command and checks its output. Returns { ok, output }. */
+export async function verifyTool(tool, resolved) {
+  if (!resolved) return { ok: false, output: 'installation contents are missing or changed; run vsg setup --repair' };
+  if (!tool.verify) return { ok: true, output: '' };
+  // a build for another platform (a container build on this host) cannot run here: it is verified by its checksum only
+  if (resolved.platform && resolved.platform !== platformKey()) return { ok: true, output: 'checksum verified; runs in a container on this host' };
+  const r = await runProcess({ command: resolved.path, args: tool.verify.args, timeoutMs: 30_000 });
+  const output = `${r.stdout}\n${r.stderr}`.trim();
+  return { ok: r.status === 'ran' && output.includes(tool.verify.expect), output: output.split('\n')[0] ?? '' };
+}
+
+/**
+ * Installs one binary-distributed tool. Returns { status: 'installed'|'already', path }.
+ * Throws InstallError on a missing platform build, checksum mismatch, unsafe archive or failed verification.
+ */
+export async function installTool(tool, { force = false, log = () => {}, fetchOpts = {}, platform } = {}) {
+  const key = platform ?? platformFor(tool);
+  const entry = tool.platforms?.[key];
+  if (!entry) throw new InstallError(`${tool.name} has no build for ${key}. Add one to its registry file.`);
+  if (!force) {
+    const existing = resolveTool(tool, key);
+    if (existing) return { status: 'already', path: existing.path };
+    const markerPath = path.join(installDir(tool, key), MARKER);
+    if (fs.existsSync(markerPath)) throw new InstallError(`${tool.name} has a legacy or unverified installation. Run vsg setup --repair to replace it.`);
+  }
+  const host = new URL(entry.url).hostname;
+  log(`Downloading ${tool.name} ${tool.version} from ${host}`);
+  const res = await vfetch(entry.url, { timeoutMs: 600_000, allowHosts: [host], ...fetchOpts });
+  if (!res.ok) throw new InstallError(`Download of ${tool.name} failed with HTTP ${res.status}. Retry later.`);
+  const actual = sha256(res.body);
+  if (actual !== entry.sha256) {
+    throw new InstallError(`Checksum mismatch for ${tool.name} ${tool.version}: expected ${entry.sha256}, got ${actual}. The download was refused and nothing was extracted.`);
+  }
+  const dir = installDir(tool, key);
+  const staging = `${dir}.partial-${process.pid}`;
+  const aside = `${dir}.old-${process.pid}`; // the previous install waits here until the new one is in place and verified
+  fs.rmSync(staging, { recursive: true, force: true });
+  fs.rmSync(aside, { recursive: true, force: true });
+  let movedAside = false;
+  const restoreOld = () => {
+    if (!movedAside) return;
+    fs.rmSync(dir, { recursive: true, force: true });
+    fs.renameSync(aside, dir);
+    movedAside = false;
+  };
+  try {
+    if (entry.archive === 'none') {
+      const bin = safeJoin(staging, entry.bin);
+      fs.mkdirSync(path.dirname(bin), { recursive: true });
+      fs.writeFileSync(bin, res.body);
+    } else {
+      extractArchive(res.body, entry.archive, staging);
+    }
+    const bin = safeJoin(staging, entry.bin);
+    if (!fs.existsSync(bin)) throw new InstallError(`${tool.name}: expected binary "${entry.bin}" was not found in the download.`);
+    if (process.platform !== 'win32' && key.startsWith(process.platform)) fs.chmodSync(bin, 0o755);
+    if (entry.archive !== 'none') fs.writeFileSync(path.join(staging, ARCHIVE), res.body);
+    const files = contentManifest(staging);
+    fs.writeFileSync(path.join(staging, MARKER), JSON.stringify({ schemaVersion: MARKER_VERSION, name: tool.name, version: tool.version, platform: key, archiveSha256: entry.sha256, sha256: entry.sha256, files, installedAt: new Date().toISOString() }));
+    fs.mkdirSync(path.dirname(dir), { recursive: true });
+    if (fs.existsSync(dir)) { fs.renameSync(dir, aside); movedAside = true; }
+    fs.renameSync(staging, dir);
+  } catch (e) {
+    fs.rmSync(staging, { recursive: true, force: true });
+    try { restoreOld(); } catch { /* the old install stays in ${dir}.old-<pid> */ }
+    throw e;
+  }
+  const resolved = resolveTool(tool, key);
+  if (!resolved) {
+    const hadOld = movedAside;
+    if (hadOld) restoreOld();
+    else fs.rmSync(dir, { recursive: true, force: true });
+    throw new InstallError(`${tool.name} was installed but its extracted contents did not match the verified archive. Run vsg setup --repair.`);
+  }
+  const check = await verifyTool(tool, resolved);
+  if (!check.ok) {
+    const hadOld = movedAside;
+    if (hadOld) restoreOld();
+    else fs.rmSync(dir, { recursive: true, force: true });
+    throw new InstallError(`${tool.name} was installed but its version check failed (wanted "${tool.verify.expect}", got "${check.output}"). It was removed${hadOld ? ' and the previous install was restored' : ''}.`);
+  }
+  fs.rmSync(aside, { recursive: true, force: true });
+  return { status: 'installed', path: resolved.path };
+}
+
+/** Downloads and verifies an archive without extracting it onto the host. */
+export async function installVerifiedArchive(tool, { force = false, log = () => {}, fetchOpts = {}, platform } = {}) {
+  const key = platform ?? platformFor(tool);
+  const entry = tool.platforms?.[key];
+  if (!entry || entry.archive === 'none') throw new InstallError(`${tool.name} has no archive for ${key}.`);
+  if (!force) {
+    const existing = resolveVerifiedArchive(tool, key);
+    if (existing) return { status: 'already', path: existing.path };
+  }
+  const host = new URL(entry.url).hostname;
+  log(`Downloading ${tool.name} ${tool.version} from ${host}`);
+  const res = await vfetch(entry.url, { timeoutMs: 600_000, allowHosts: [host], ...fetchOpts });
+  if (!res.ok) throw new InstallError(`Download of ${tool.name} failed with HTTP ${res.status}. Retry later.`);
+  const actual = sha256(res.body);
+  if (actual !== entry.sha256) throw new InstallError(`Checksum mismatch for ${tool.name} ${tool.version}: expected ${entry.sha256}, got ${actual}. The download was refused and nothing was stored.`);
+  const files = archiveManifest(res.body, entry.archive);
+  const dir = installDir(tool, key);
+  const staging = `${dir}.partial-${process.pid}`;
+  const aside = `${dir}.old-${process.pid}`;
+  fs.rmSync(staging, { recursive: true, force: true });
+  fs.rmSync(aside, { recursive: true, force: true });
+  let movedAside = false;
+  try {
+    fs.mkdirSync(staging, { recursive: true });
+    fs.writeFileSync(path.join(staging, ARCHIVE), res.body);
+    fs.writeFileSync(path.join(staging, ARCHIVE_MARKER), JSON.stringify({ schemaVersion: 1, name: tool.name, version: tool.version, platform: key, archiveSha256: entry.sha256, files, installedAt: new Date().toISOString() }));
+    fs.mkdirSync(path.dirname(dir), { recursive: true });
+    if (fs.existsSync(dir)) { fs.renameSync(dir, aside); movedAside = true; }
+    fs.renameSync(staging, dir);
+    if (!resolveVerifiedArchive(tool, key)) throw new InstallError(`${tool.name} archive failed its post-install integrity check.`);
+    fs.rmSync(aside, { recursive: true, force: true });
+    return { status: 'installed', path: path.join(dir, ARCHIVE) };
+  } catch (e) {
+    fs.rmSync(staging, { recursive: true, force: true });
+    if (movedAside) {
+      fs.rmSync(dir, { recursive: true, force: true });
+      fs.renameSync(aside, dir);
+    }
+    throw e;
+  }
+}

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

@@ -0,0 +1,38 @@
+// Output-directory lock. A second concurrent run on the same directory exits 3.
+import fs from 'node:fs';
+import path from 'node:path';
+import { LockError } from './errors.mjs';
+
+const STALE_MS = 6 * 60 * 60 * 1000;
+
+const alive = (pid) => {
+  try { process.kill(pid, 0); return true; } catch (e) { return e.code === 'EPERM'; }
+};
+
+/** Creates the output directory (self-ignored by a .gitignore containing *), takes the lock, returns { release }. */
+export function acquireLock(outDir) {
+  fs.mkdirSync(outDir, { recursive: true });
+  const ignore = path.join(outDir, '.gitignore');
+  if (!fs.existsSync(ignore)) fs.writeFileSync(ignore, '*\n');
+  const lock = path.join(outDir, '.lock');
+  for (let attempt = 0; attempt < 2; attempt++) {
+    try {
+      fs.mkdirSync(lock);
+      fs.writeFileSync(path.join(lock, 'pid'), String(process.pid));
+      return { release: () => fs.rmSync(lock, { recursive: true, force: true }) };
+    } catch (e) {
+      if (e.code !== 'EEXIST') throw e;
+      let pid = NaN;
+      let age = 0;
+      try {
+        pid = Number(fs.readFileSync(path.join(lock, 'pid'), 'utf8'));
+        age = Date.now() - fs.statSync(lock).mtimeMs;
+      } catch { /* unreadable lock: treat as stale */ }
+      if (Number.isFinite(pid) && pid > 0 && alive(pid) && age < STALE_MS) {
+        throw new LockError(`Another vsg run holds the lock on ${outDir} (pid ${pid}). Wait for it to finish, or delete ${lock} if it crashed.`);
+      }
+      fs.rmSync(lock, { recursive: true, force: true }); // stale: owner is gone
+    }
+  }
+  throw new LockError(`Could not take the lock on ${outDir}. Delete ${lock} and retry.`);
+}

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

@@ -0,0 +1,107 @@
+// Nested repositories: coding agents leave full checkouts (git worktrees, clones) inside a working copy, usually gitignored.
+// Scanners that deliberately ignore .gitignore would read each copy and report every finding once per copy, so those directories are
+// skipped everywhere and reported once. A directory below the scan root counts as a nested repository when it holds a `.git` entry
+// (a directory, or a file that points at a worktree's git directory) and the outer repository tracks nothing inside it.
+// Tracked content is always scanned: a `.git` file planted inside a tracked folder cannot hide that folder.
+import { spawnSync } from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
+
+const SKIP_DIRS = new Set(['node_modules', '.git', '.vsg', '.next', '.expo', '.venv', 'venv', '__pycache__', '.turbo', '.cache', 'coverage', 'dist', 'build', '.pnpm-store']);
+const MAX_DEPTH = 10;
+// Coding agents keep their checkouts in folders such as .claude/worktrees and .codex-worktrees. A checkout whose .git entry was removed
+// (a half-cleaned worktree) is still a full copy of the project, so every untracked folder inside such a hidden container counts as nested too.
+const isContainer = (rel) => {
+  const parts = rel.split('/');
+  const last = parts.at(-1);
+  return /^\..*worktrees$/i.test(last) || (/^worktrees$/i.test(last) && (parts.at(-2) ?? '').startsWith('.'));
+};
+const GIT = ['-c', 'core.fsmonitor=false', '--no-optional-locks'];
+
+/** Tracked layout of the outer repository, relative to root: { dirs (every directory holding tracked files), gitlinks (submodules) }, or null when git cannot say. */
+function trackedIndex(root) {
+  const r = spawnSync('git', [...GIT, 'ls-files', '-s', '-z'], { cwd: root, encoding: 'utf8', maxBuffer: 256 * 1024 * 1024, windowsHide: true });
+  if (r.error || r.status !== 0) return null;
+  const dirs = new Set();
+  const gitlinks = new Set();
+  for (const entry of r.stdout.split('\0')) {
+    const m = /^(\d+) \S+ \d\t(.+)$/.exec(entry);
+    if (!m) continue;
+    const p = m[2];
+    if (m[1] === '160000') { gitlinks.add(p); continue; }
+    for (let i = p.indexOf('/'); i > 0; i = p.indexOf('/', i + 1)) dirs.add(p.slice(0, i));
+  }
+  return { dirs, gitlinks };
+}
+
+/** True when root sits inside a git work tree (its own .git or a parent's). */
+const insideGit = (root) => spawnSync('git', [...GIT, 'rev-parse', '--is-inside-work-tree'], { cwd: root, encoding: 'utf8', windowsHide: true }).stdout?.trim() === 'true';
+
+/**
+ * Nested repositories below `root`: [{ path (relative, posix), kind: 'repo' | 'submodule' }], sorted.
+ * Does not enter node_modules and similar, and stops descending at a nested repository.
+ * If the outer repository exists but git cannot list it, nothing is skipped: scanning too much is safe, hiding code is not.
+ */
+export function findNestedRepos(root) {
+  root = path.resolve(root);
+  const found = [];
+  let index; // undefined: not asked yet; null: no outer repository; false: git failed
+  const outer = () => {
+    if (index !== undefined) return index;
+    return (index = insideGit(root) ? (trackedIndex(root) ?? false) : null);
+  };
+  let failed = false;
+  const walk = (dir, rel, depth, inContainer = false) => {
+    if (depth > MAX_DEPTH || failed) return;
+    let entries;
+    try { entries = fs.readdirSync(dir, { withFileTypes: true }); } catch { return; }
+    if (rel && (inContainer || entries.some((e) => e.name === '.git'))) {
+      const ix = outer();
+      if (ix === false) { failed = true; return; }
+      if (ix === null || !ix.dirs.has(rel)) {
+        found.push({ path: rel, kind: ix?.gitlinks.has(rel) ? 'submodule' : 'repo' });
+        return;
+      }
+      // the outer repository tracks files here: not a nested repository, keep looking inside
+    }
+    for (const e of entries) {
+      if (e.isSymbolicLink() || !e.isDirectory() || SKIP_DIRS.has(e.name)) continue;
+      walk(path.join(dir, e.name), rel ? `${rel}/${e.name}` : e.name, depth + 1, isContainer(rel));
+    }
+  };
+  walk(root, '', 0);
+  return failed ? [] : found.sort((a, b) => a.path.localeCompare(b.path));
+}
+
+/**
+ * Which of `rels` (root-relative directories) git ignores while the repository tracks nothing in them. check-ignore never reports tracked
+ * files, but a directory holding a force-added file is still reported as ignored, so tracked directories are removed here.
+ * Returns [] when git cannot say (nothing is then skipped).
+ */
+export function ignoredUntracked(root, rels) {
+  if (!rels.length) return [];
+  const r = spawnSync('git', [...GIT, 'check-ignore', '-z', '--stdin'], { cwd: root, input: rels.join('\0'), encoding: 'utf8', maxBuffer: 64 * 1024 * 1024, windowsHide: true });
+  if (r.error || (r.status !== 0 && r.status !== 1)) return [];
+  const ignored = r.stdout.split('\0').filter(Boolean);
+  if (!ignored.length) return [];
+  const ix = trackedIndex(root);
+  return ix ? ignored.filter((p) => !ix.dirs.has(p) && !ix.gitlinks.has(p)) : [];
+}
+
+/**
+ * Trailing `git ls-files` arguments that keep git out of nested checkouts. Without them `ls-files --others` lists every file of every
+ * untracked worktree (2.3 million entries, 105 s, on a working copy with 100 of them); with them it takes under a second.
+ */
+export const excludeNested = (nested) => (nested?.length ? ['--', '.', ...nested.map((n) => `:(exclude,literal)${n.path}`)] : []);
+
+/** One line for report.md and coverage evidence, or '' when nothing was skipped. */
+export function nestedSummary(nested) {
+  if (!nested?.length) return '';
+  const first = nested.slice(0, 10).map((n) => (n.kind === 'submodule' ? `${n.path} (submodule, scan it separately)` : n.path));
+  return `Skipped ${nested.length} nested git ${nested.length === 1 ? 'repository or worktree' : 'repositories or worktrees'} (not part of this repository): ${first.join(', ')}${nested.length > 10 ? `, and ${nested.length - 10} more` : ''}.`;
+}
+
+// listFiles() is called by many checks with only a path; detect() primes this so they all skip the same directories.
+const primed = new Map();
+export const primeNested = (root, nested) => primed.set(path.resolve(root), nested);
+export const primedNested = (root) => primed.get(path.resolve(root));

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

@@ -0,0 +1,20 @@
+import os from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+export const packageRoot = fileURLToPath(new URL('../..', import.meta.url));
+export const defaultRegistryDir = path.join(packageRoot, 'tools', 'registry');
+export const defaultChecksDir = path.join(packageRoot, 'src', 'checks');
+export const platformKey = () => `${process.platform}-${process.arch}`;
+
+export function vsgHome() {
+  return process.env.VSG_HOME || path.join(os.homedir(), '.vsg');
+}
+
+export function toolsDir() {
+  if (process.env.VSG_TOOLS_DIR) return process.env.VSG_TOOLS_DIR;
+  if (process.platform === 'win32') {
+    return path.join(process.env.LOCALAPPDATA || path.join(os.homedir(), 'AppData', 'Local'), 'vsg', 'tools');
+  }
+  return path.join(process.env.XDG_CACHE_HOME || path.join(os.homedir(), '.cache'), 'vsg', 'tools');
+}