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

package/dist/security-runtime/src/checks/code/opengrep-container.mjs

@@ -0,0 +1,85 @@
+import crypto from 'node:crypto';
+import path from 'node:path';
+import { packageRoot } from '../../core/paths.mjs';
+
+const RUNNER = path.join(packageRoot, 'src', 'checks', 'code', 'opengrep-runner.mjs');
+const SELECTED_RUNNER = path.join(packageRoot, 'src', 'checks', 'code', 'selected-opengrep-runner.mjs');
+const lastJson = (stdout) => {
+  for (const line of String(stdout).split('\n').reverse()) {
+    if (!line.startsWith('{')) continue;
+    try { return JSON.parse(line); } catch { /* keep looking */ }
+  }
+  return null;
+};
+
+export async function runOpengrepContainer(ctx, { args, opengrep, rulesArchive, rulesRoot, vsgRulesDir, timeoutMs }) {
+  const runner = ctx.registry?.get('yara-runner');
+  if (!runner?.image) return { status: 'not_run', reason: 'The pinned Linux runner image is not in the tool registry.' };
+  const docker = await ctx.runProcess({ command: 'docker', args: ['version', '--format', '{{.Server.Version}}'], timeoutMs: 20_000 });
+  if (docker.status !== 'ran' || docker.exitCode !== 0) return { status: 'not_run', reason: 'Docker is not available, so the verified Linux Opengrep runner cannot start.' };
+  const name = `vsg-opengrep-${process.pid}-${crypto.randomBytes(4).toString('hex')}`;
+  const dockerArgs = [
+    'run', '--pull', 'never', '--rm', '--init', '-i', '--name', name, '--network', 'none', '--read-only', '--tmpfs', '/tmp:rw,exec,size=2g', '--memory', '4g', '--cap-drop', 'ALL', '--security-opt', 'no-new-privileges',
+    '-v', `${RUNNER}:/vsg/src/checks/code/opengrep-runner.mjs:ro`,
+    '-v', `${path.join(packageRoot, 'src', 'core')}:/vsg/src/core:ro`,
+    '-v', `${vsgRulesDir}:/vsg/rules:ro`,
+    '-v', `${opengrep.path}:/vsg/in/opengrep:ro`,
+    '-v', `${rulesArchive.path}:/vsg/in/rules.tar.gz:ro`,
+    '-v', `${ctx.repo}:/scan:ro`,
+    '-w', '/scan', runner.image, 'node', '/vsg/src/checks/code/opengrep-runner.mjs',
+    '--opengrep', '/vsg/in/opengrep', '--rules', '/vsg/in/rules.tar.gz', '--root', '/scan', '--work', '/tmp/vsg-opengrep',
+  ];
+  const input = JSON.stringify({
+    args, timeoutMs, opengrepSha256: opengrep.sha256,
+    rulesSha256: rulesArchive.sha256, rulesManifest: rulesArchive.files, rulesRoot,
+  });
+  const result = await ctx.runProcess({ command: 'docker', args: dockerArgs, input, timeoutMs: timeoutMs + 120_000, maxOutputBytes: 80 * 1024 * 1024 });
+  if (result.status !== 'ran') {
+    await ctx.runProcess({ command: 'docker', args: ['rm', '-f', name], timeoutMs: 30_000 });
+    return { status: 'not_run', reason: `Linux Opengrep runner ${result.reason}` };
+  }
+  if (result.exitCode !== 0 || result.truncated) {
+    await ctx.runProcess({ command: 'docker', args: ['rm', '-f', name], timeoutMs: 30_000 });
+    const detail = result.truncated ? 'produced truncated output' : `exited with code ${result.exitCode}`;
+    return { status: 'not_run', reason: `Linux Opengrep runner ${detail}.` };
+  }
+  const output = lastJson(result.stdout);
+  if (!output) return { status: 'not_run', reason: `Linux Opengrep runner produced no result (exit ${result.exitCode}).` };
+  if (!output.ok) return { status: 'not_run', reason: `Linux Opengrep runner failed: ${output.error}` };
+  return output.result;
+}
+
+/** Runs the fixed commercial selection from a disposable Linux volume without consulting restricted rule registries. */
+export async function runSelectedOpengrepContainer(ctx, { args, opengrep, source, sourceFiles, ruleIdsSha256, vsgRulesDir, timeoutMs, volume }) {
+  const runner = ctx.registry?.get('yara-runner');
+  if (!runner?.image) return { status: 'not_run', reason: 'The pinned Linux runner image is not in the tool registry.' };
+  const name = `vsg-selected-opengrep-${process.pid}-${crypto.randomBytes(4).toString('hex')}`;
+  const dockerArgs = [
+    'run', '--pull', 'never', '--rm', '--init', '-i', '--name', name, '--network', 'none', '--read-only', '--tmpfs', '/tmp:rw,exec,size=2g', '--memory', '4g', '--cap-drop', 'ALL', '--security-opt', 'no-new-privileges',
+    '-v', `${SELECTED_RUNNER}:/vsg/src/checks/code/selected-opengrep-runner.mjs:ro`,
+    '-v', `${path.join(packageRoot, 'src', 'core')}:/vsg/src/core:ro`,
+    '-v', `${vsgRulesDir}:/vsg/rules:ro`,
+    '-v', `${opengrep.path}:/vsg/in/opengrep:ro`,
+    '-v', `${volume}:/vsg/selected-source:ro`,
+    '-v', `${ctx.repo}:/scan:ro`,
+    '-w', '/scan', runner.image, 'node', '/vsg/src/checks/code/selected-opengrep-runner.mjs',
+    '--opengrep', '/vsg/in/opengrep', '--source-root', '/vsg/selected-source/files', '--root', '/scan', '--work', '/tmp/vsg-selected-opengrep',
+  ];
+  const input = JSON.stringify({
+    args, timeoutMs, opengrepSha256: opengrep.sha256,
+    sourceManifestSha256: source.manifestSha256, sourceFiles, ruleIdsSha256,
+  });
+  const result = await ctx.runProcess({ command: 'docker', args: dockerArgs, input, timeoutMs: timeoutMs + 120_000, maxOutputBytes: 80 * 1024 * 1024 });
+  if (result.status !== 'ran') {
+    await ctx.runProcess({ command: 'docker', args: ['rm', '-f', name], timeoutMs: 30_000 });
+    return { status: 'not_run', reason: `Selected Linux Opengrep runner ${result.reason}` };
+  }
+  if (result.exitCode !== 0 || result.truncated) {
+    const detail = result.truncated ? 'produced truncated output' : `exited with code ${result.exitCode}`;
+    return { status: 'not_run', reason: `Selected Linux Opengrep runner ${detail}.` };
+  }
+  const output = lastJson(result.stdout);
+  if (!output) return { status: 'not_run', reason: `Selected Linux Opengrep runner produced no result (exit ${result.exitCode}).` };
+  if (!output.ok) return { status: 'not_run', reason: `Selected Linux Opengrep runner failed: ${output.error}` };
+  return output.result;
+}

package/dist/security-runtime/src/checks/code/opengrep-runner.mjs

@@ -0,0 +1,86 @@
+// Linux-only Opengrep runner. On Windows the host mounts verified compressed
+// rules and the pinned Linux binary read-only; all extraction stays in /tmp.
+import { spawnSync } from 'node:child_process';
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+import { extractArchive, listTarGz, safeJoin } from '../../core/archive.mjs';
+
+const sha256 = (bytes) => crypto.createHash('sha256').update(bytes).digest('hex');
+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 treeManifest = (root) => {
+  const files = {};
+  const walk = (dir, rel = '') => {
+    for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+      const file = path.join(dir, entry.name);
+      const child = rel ? `${rel}/${entry.name}` : entry.name;
+      if (entry.isDirectory()) walk(file, child);
+      else if (entry.isFile()) files[child] = sha256(fs.readFileSync(file));
+      else throw new Error(`rules contain unsupported entry ${child}`);
+    }
+  };
+  walk(root);
+  return Object.fromEntries(Object.entries(files).sort(([a], [b]) => a.localeCompare(b)));
+};
+
+export function extractVerifiedRules({ archivePath, expectedSha256, expectedManifest, rulesRoot, workDir }) {
+  const archive = fs.readFileSync(archivePath);
+  if (sha256(archive) !== expectedSha256) throw new Error('rules archive checksum mismatch inside Linux runner');
+  const archiveFiles = {};
+  for (const entry of listTarGz(archive)) {
+    if (!entry.dir) archiveFiles[entry.name.replaceAll('\\', '/')] = sha256(entry.data());
+  }
+  const normalized = Object.fromEntries(Object.entries(archiveFiles).sort(([a], [b]) => a.localeCompare(b)));
+  if (!sameManifest(normalized, expectedManifest)) throw new Error('rules archive manifest mismatch inside Linux runner');
+  const output = path.join(workDir, 'rules');
+  extractArchive(archive, 'tar.gz', output);
+  if (!sameManifest(treeManifest(output), expectedManifest)) throw new Error('extracted rules manifest mismatch inside Linux runner');
+  const root = safeJoin(output, rulesRoot);
+  if (!fs.statSync(root).isDirectory()) throw new Error('rules root is not a directory');
+  return root;
+}
+
+function arg(name) {
+  const i = process.argv.indexOf(`--${name}`);
+  return i > 0 ? process.argv[i + 1] : undefined;
+}
+
+function main() {
+  const work = arg('work') ?? '/tmp/vsg-opengrep';
+  try {
+    const input = JSON.parse(fs.readFileSync(0, 'utf8') || '{}');
+    fs.rmSync(work, { recursive: true, force: true });
+    fs.mkdirSync(work, { recursive: true });
+    extractVerifiedRules({
+      archivePath: arg('rules'),
+      expectedSha256: input.rulesSha256,
+      expectedManifest: input.rulesManifest,
+      rulesRoot: input.rulesRoot,
+      workDir: work,
+    });
+    const sourceBinary = fs.readFileSync(arg('opengrep'));
+    if (sha256(sourceBinary) !== input.opengrepSha256) throw new Error('Opengrep checksum mismatch inside Linux runner');
+    const opengrep = path.join(work, 'opengrep');
+    fs.writeFileSync(opengrep, sourceBinary, { mode: 0o755 });
+    const result = spawnSync(opengrep, input.args, {
+      cwd: arg('root'), encoding: 'utf8', maxBuffer: 64 * 1024 * 1024, timeout: input.timeoutMs,
+      env: { PATH: '/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin', HOME: '/tmp', LANG: 'C.UTF-8', LC_ALL: 'C.UTF-8', PYTHONUTF8: '1' },
+    });
+    const response = result.error
+      ? { ok: false, error: `Opengrep could not complete: ${result.error.message}` }
+      : { ok: true, result: { status: 'ran', exitCode: result.status ?? -1, stdout: result.stdout ?? '', stderr: result.stderr ?? '', truncated: false } };
+    fs.rmSync(work, { recursive: true, force: true });
+    process.stdout.write(`${JSON.stringify(response)}\n`);
+  } catch (error) {
+    fs.rmSync(work, { recursive: true, force: true });
+    process.stdout.write(`${JSON.stringify({ ok: false, error: error.message })}\n`);
+  }
+}
+
+import { fileURLToPath } from 'node:url';
+if (process.argv[1] && fileURLToPath(import.meta.url) === path.resolve(process.argv[1])) main();

package/dist/security-runtime/src/checks/code/selected-opengrep-runner.mjs

@@ -0,0 +1,112 @@
+// Linux-only selected SAST runner. The 161 reviewed files and two license files are fetched into a
+// disposable Docker volume from fixed upstream URLs, verified again, and staged into tmpfs.
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { safeJoin } from '../../core/archive.mjs';
+
+const sha256 = (bytes) => crypto.createHash('sha256').update(bytes).digest('hex');
+const same = (a, b) => a.length === b.length && a.every((value, index) => value === b[index]);
+
+function arg(name) {
+  const index = process.argv.indexOf(`--${name}`);
+  return index > 0 ? process.argv[index + 1] : undefined;
+}
+
+export function stageSelectedSource({ sourceRoot, files, expectedManifestSha256, expectedRuleIdsSha256, target }) {
+  if (!Array.isArray(files) || files.length !== 163) throw new Error('Selected SAST source manifest must contain exactly 163 files.');
+  if (sha256(JSON.stringify(files)) !== expectedManifestSha256) throw new Error('Selected SAST source manifest identity changed inside Linux runner.');
+  const expected = new Map();
+  for (const item of files) {
+    if (!item || typeof item.path !== 'string' || !item.path || item.path.includes('\\') || item.path.split('/').some((part) => !part || part === '.' || part === '..')
+      || !/^https:\/\//.test(item.url ?? '') || !/^[0-9a-f]{64}$/.test(item.sha256 ?? '') || !Number.isSafeInteger(item.bytes) || item.bytes < 0 || expected.has(item.path.toLowerCase())) {
+      throw new Error('Selected SAST source manifest contains an invalid or duplicate path.');
+    }
+    expected.set(item.path.toLowerCase(), item);
+  }
+  const observed = [];
+  const walkSource = (dir, rel = '') => {
+    for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+      const childRel = rel ? `${rel}/${entry.name}` : entry.name;
+      const child = path.join(dir, entry.name);
+      const stat = fs.lstatSync(child);
+      if (stat.isSymbolicLink()) throw new Error(`Selected SAST source contains linked path ${childRel}.`);
+      if (entry.isDirectory()) walkSource(child, childRel);
+      else if (entry.isFile()) observed.push(childRel);
+      else throw new Error(`Selected SAST source contains unsupported path ${childRel}.`);
+    }
+  };
+  walkSource(sourceRoot);
+  observed.sort();
+  const expectedPaths = files.map((item) => item.path).sort();
+  if (!same(observed, expectedPaths)) throw new Error('Selected SAST source volume differs from the fixed manifest.');
+  const ruleIds = [];
+  for (const item of files) {
+    const source = safeJoin(sourceRoot, item.path);
+    const sourceStat = fs.lstatSync(source);
+    if (!sourceStat.isFile() || sourceStat.isSymbolicLink()) throw new Error(`Selected SAST source path is not a regular file: ${item.path}.`);
+    const bytes = fs.readFileSync(source);
+    if (bytes.byteLength !== item.bytes || sha256(bytes) !== item.sha256) throw new Error(`Selected SAST source path changed: ${item.path}.`);
+    const destination = safeJoin(target, item.path);
+    fs.mkdirSync(path.dirname(destination), { recursive: true });
+    fs.writeFileSync(destination, bytes, { mode: 0o644 });
+    if (/\.ya?ml$/i.test(item.path)) {
+      for (const found of bytes.toString('utf8').matchAll(/^\s*(?:-\s*)?id:\s*['"]?([^'"\s#]+)['"]?\s*(?:#.*)?$/gm)) ruleIds.push(found[1]);
+    }
+  }
+  ruleIds.sort();
+  if (ruleIds.length !== 161 || new Set(ruleIds).size !== 161 || sha256(JSON.stringify(ruleIds)) !== expectedRuleIdsSha256) {
+    throw new Error('Selected SAST rule identities do not match the fixed 161-rule catalog.');
+  }
+  const written = [];
+  const walk = (dir, rel = '') => {
+    for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+      const childRel = rel ? `${rel}/${entry.name}` : entry.name;
+      const child = path.join(dir, entry.name);
+      if (entry.isDirectory()) walk(child, childRel);
+      else if (entry.isFile()) written.push(childRel);
+      else throw new Error(`Selected SAST source produced unsupported path ${childRel}.`);
+    }
+  };
+  walk(target);
+  written.sort();
+  if (!same(written, expectedPaths)) throw new Error('Selected SAST extracted tree differs from the fixed manifest.');
+  return { ruleIds };
+}
+
+function main() {
+  const work = arg('work') ?? '/tmp/vsg-selected-opengrep';
+  try {
+    const input = JSON.parse(fs.readFileSync(0, 'utf8') || '{}');
+    fs.rmSync(work, { recursive: true, force: true });
+    fs.mkdirSync(work, { recursive: true });
+    const sourceRoot = path.join(work, 'source');
+    stageSelectedSource({
+      sourceRoot: arg('source-root'),
+      files: input.sourceFiles,
+      expectedManifestSha256: input.sourceManifestSha256,
+      expectedRuleIdsSha256: input.ruleIdsSha256,
+      target: sourceRoot,
+    });
+    const binary = fs.readFileSync(arg('opengrep'));
+    if (sha256(binary) !== input.opengrepSha256) throw new Error('Opengrep checksum mismatch inside selected runner.');
+    const opengrep = path.join(work, 'opengrep');
+    fs.writeFileSync(opengrep, binary, { mode: 0o755 });
+    const result = spawnSync(opengrep, input.args, {
+      cwd: arg('root'), encoding: 'utf8', maxBuffer: 64 * 1024 * 1024, timeout: input.timeoutMs,
+      env: { PATH: '/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin', HOME: '/tmp', LANG: 'C.UTF-8', LC_ALL: 'C.UTF-8', PYTHONUTF8: '1' },
+    });
+    const response = result.error
+      ? { ok: false, error: `Selected Opengrep could not complete: ${result.error.message}` }
+      : { ok: true, result: { status: 'ran', exitCode: result.status ?? -1, stdout: result.stdout ?? '', stderr: result.stderr ?? '', truncated: false } };
+    fs.rmSync(work, { recursive: true, force: true });
+    process.stdout.write(`${JSON.stringify(response)}\n`);
+  } catch (error) {
+    fs.rmSync(work, { recursive: true, force: true });
+    process.stdout.write(`${JSON.stringify({ ok: false, error: error.message })}\n`);
+  }
+}
+
+import { fileURLToPath } from 'node:url';
+if (process.argv[1] && fileURLToPath(import.meta.url) === path.resolve(process.argv[1])) main();

package/dist/security-runtime/src/checks/dep-change/guarddog.mjs

@@ -0,0 +1,142 @@
+// GuardDog (Datadog) malicious-package scan of changed packages, run in a throwaway container pinned by digest (REQ-010).
+// Only called with names and versions that already passed validation, so nothing here can be read as a container flag.
+import { randomBytes } from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+import { sha256 } from '../../core/findings.mjs';
+import { vsgHome } from '../../core/paths.mjs';
+
+const GUARDDOG_TIMEOUT_MS = 120_000;
+export const CONCURRENCY = 6;
+export const MAX_GUARDDOG = 25;
+/**
+ * Wall-clock budget for all GuardDog scans of one run. A working copy once spent 256 s here (25 scans of 5 to 45 s each, three of them
+ * running into the 120 s timeout). No new scan starts after the budget; the ones still running get a short grace period. Packages that were
+ * not scanned are counted and reported, never silently dropped.
+ */
+export const BUDGET_MS = 60_000;
+const GRACE_MS = 15_000;
+export const CACHE_TTL_MS = 14 * 24 * 3600_000;
+const HARDEN = ['--cap-drop', 'ALL', '--security-opt', 'no-new-privileges', '--memory', '2g', '--pids-limit', '512'];
+
+/** { available, reason } : Docker engine reachable. */
+export async function dockerAvailable(ctx) {
+  const r = await ctx.runProcess({ command: 'docker', args: ['version', '--format', '{{.Server.Version}}'], timeoutMs: 20_000 });
+  if (r.status !== 'ran') return { available: false, reason: `Docker is not available: ${r.reason}` };
+  if (r.exitCode !== 0 || !r.stdout.trim()) return { available: false, reason: 'Docker is installed but its engine is not running' };
+  return { available: true, reason: '' };
+}
+
+/** Makes sure the pinned image exists locally (pulling it by digest if needed). Returns null or a reason string. */
+async function ensureImage(ctx, image) {
+  const have = await ctx.runProcess({ command: 'docker', args: ['image', 'inspect', '--format', '{{.Id}}', image], timeoutMs: 30_000 });
+  if (have.status === 'ran' && have.exitCode === 0) return null;
+  const pull = await ctx.runProcess({ command: 'docker', args: ['pull', '--quiet', image], timeoutMs: 600_000 });
+  return pull.status === 'ran' && pull.exitCode === 0 ? null : `could not pull ${image}: ${pull.reason ?? pull.stderr.trim().split(/\r?\n/).pop()}`;
+}
+
+/** Interprets GuardDog JSON. malicious means GuardDog's own risk engine rated the package high_risk. Capability rules are informational and ignored. */
+export function interpretGuardDog(json) {
+  const label = json?.risk_score?.label ?? 'unknown';
+  const hit = (v) => v !== null && v !== undefined && !(Array.isArray(v) && v.length === 0) && !(typeof v === 'object' && !Array.isArray(v) && Object.keys(v).length === 0) && v !== '';
+  const rules = Object.entries(json?.results ?? {})
+    .filter(([rule, v]) => !rule.startsWith('capability-') && hit(v))
+    .map(([rule, v]) => {
+      const first = Array.isArray(v) ? v[0] : v;
+      const where = typeof first === 'object' && first ? first.location ?? '' : '';
+      const message = typeof first === 'object' && first ? first.message ?? '' : String(first);
+      return { rule, where, message };
+    });
+  return { label, malicious: label === 'high_risk', rules, errors: Object.keys(json?.errors ?? {}) };
+}
+
+/**
+ * Disk cache of finished scans. A published package version never changes and the image is pinned by digest, so a clean or flagged
+ * result stays valid until the image changes; the TTL only bounds how long a result is trusted. Only successful scans are cached.
+ * ctx.guarddogCacheDir: a directory, or null/false to switch the cache off (tests); unset means <vsg home>/cache/guarddog.
+ */
+const cacheDir = (ctx) => (ctx.guarddogCacheDir === undefined ? path.join(vsgHome(), 'cache', 'guarddog') : ctx.guarddogCacheDir || null);
+const cacheFile = (dir, image, p) => path.join(dir, `${sha256(`${image}\0${p.ecosystem}\0${p.name}\0${p.version}`).slice(0, 32)}.json`);
+
+export function readCache(ctx, image, p, now = Date.now()) {
+  const dir = cacheDir(ctx);
+  if (!dir) return null;
+  try {
+    const e = JSON.parse(fs.readFileSync(cacheFile(dir, image, p), 'utf8'));
+    if (e.image === image && e.name === p.name && e.version === p.version && e.ecosystem === p.ecosystem && now - e.at < CACHE_TTL_MS && e.result?.label) return { ok: true, sandbox: e.sandbox, result: e.result, cached: true };
+  } catch { /* no usable entry */ }
+  return null;
+}
+
+function writeCache(ctx, image, p, scan, now = Date.now()) {
+  const dir = cacheDir(ctx);
+  if (!dir || !scan.ok) return;
+  try {
+    fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+    const file = cacheFile(dir, image, p);
+    const tmp = `${file}.${process.pid}.tmp`;
+    fs.writeFileSync(tmp, JSON.stringify({ image, ecosystem: p.ecosystem, name: p.name, version: p.version, at: now, sandbox: scan.sandbox, result: scan.result }), { mode: 0o600 });
+    fs.renameSync(tmp, file);
+  } catch { /* a cache that cannot be written only costs time */ }
+}
+
+async function scanOne(ctx, image, p, name, timeoutMs = GUARDDOG_TIMEOUT_MS) {
+  const args = ['run', '--rm', '--name', name, ...HARDEN, image, p.ecosystem === 'PyPI' ? 'pypi' : 'npm', 'scan', p.name, '--version', p.version, '--output-format', 'json'];
+  let r = await ctx.runProcess({ command: 'docker', args, timeoutMs });
+  let sandbox = 'on';
+  // GuardDog refuses to run when it cannot start its own sandbox; the container is already isolated, so retry once without it.
+  if (r.status === 'ran' && r.exitCode !== 0 && /sandbox/i.test(`${r.stdout}${r.stderr}`)) {
+    sandbox = 'off (container only)';
+    r = await ctx.runProcess({ command: 'docker', args: [...args, '--no-sandbox'], timeoutMs });
+  }
+  if (r.status !== 'ran') {
+    await ctx.runProcess({ command: 'docker', args: ['rm', '-f', name], timeoutMs: 30_000 }); // timeout killed the client, not the container
+    return { ok: false, reason: r.reason };
+  }
+  if (r.exitCode !== 0) return { ok: false, reason: `GuardDog exited with code ${r.exitCode}: ${r.stderr.trim().split(/\r?\n/).pop() ?? ''}` };
+  const start = r.stdout.indexOf('{');
+  let result;
+  try { result = interpretGuardDog(JSON.parse(r.stdout.slice(start))); } catch { return { ok: false, reason: 'GuardDog did not return valid JSON' }; }
+  // GuardDog exits 0 with an "errors" entry when it could not fetch or analyze the package; that is not a clean result.
+  if (result.label === 'unknown' && result.errors.length) return { ok: false, reason: `GuardDog reported ${result.errors.join(', ')} (for example the package was removed from the registry)` };
+  return { ok: true, sandbox, result };
+}
+
+/**
+ * Runs GuardDog on up to MAX_GUARDDOG packages, within BUDGET_MS (ctx.guarddogBudgetMs overrides it). Cached results are used first and cost nothing.
+ * Returns { ran, reason, results: [{ package, ok, result|reason, cached? }], skipped (over the package cap), budgetSkipped (not started in time), cached, budgetMs }.
+ * `ran` is false when GuardDog was skipped entirely (the check itself still ran).
+ */
+export async function runGuardDog(ctx, packages) {
+  const tool = ctx.registry?.get('guarddog');
+  if (!tool?.image) return { ran: false, reason: 'GuardDog skipped: it is not in the tool registry', results: [] };
+  const docker = await dockerAvailable(ctx);
+  if (!docker.available) return { ran: false, reason: `GuardDog skipped: ${docker.reason}`, results: [] };
+  const pullProblem = await ensureImage(ctx, tool.image);
+  if (pullProblem) return { ran: false, reason: `GuardDog skipped: ${pullProblem}`, results: [] };
+  const budgetMs = ctx.guarddogBudgetMs ?? BUDGET_MS;
+  const started = Date.now();
+  const deadline = started + budgetMs;
+  const chosen = packages.slice(0, MAX_GUARDDOG);
+  const results = [];
+  const queue = [];
+  for (const p of chosen) {
+    const hit = readCache(ctx, tool.image, p);
+    if (hit) results.push({ package: `${p.name}@${p.version}`, ecosystem: p.ecosystem, ...hit });
+    else queue.push(p);
+  }
+  const cached = results.length;
+  await Promise.all(Array.from({ length: Math.min(CONCURRENCY, queue.length) }, async () => {
+    while (queue.length && Date.now() < deadline) {
+      const p = queue.shift();
+      const name = `vsg-guarddog-${randomBytes(6).toString('hex')}`;
+      const timeoutMs = Math.min(GUARDDOG_TIMEOUT_MS, Math.max(10_000, deadline - Date.now() + GRACE_MS));
+      const scan = await scanOne(ctx, tool.image, p, name, timeoutMs);
+      writeCache(ctx, tool.image, p, scan);
+      results.push({ package: `${p.name}@${p.version}`, ecosystem: p.ecosystem, ...scan });
+    }
+  }));
+  results.sort((a, b) => a.package.localeCompare(b.package));
+  const skipped = packages.length - chosen.length;
+  return { ran: true, reason: '', image: tool.image, version: tool.version, results, skipped, budgetSkipped: queue.length, cached, budgetMs, durationMs: Date.now() - started };
+}