@bongos/core 1.18.18 → 1.19.2

package/modules/security/artifact-scan/fetch.js

@@ -0,0 +1,330 @@
+// modules/security/artifact-scan/fetch.js — the hardened fetch.
+//
+// `git clone` is not an inert download: by default it runs filters and hooks,
+// reads the user's config, follows submodules into other protocols, materializes
+// symlinks anywhere, and prompts for credentials. Each setting below closes one
+// of those doors and is annotated at its use site. Nothing beyond git itself is
+// ever executed. Async by design — see defaultRun.
+
+'use strict';
+
+const dns = require('node:dns');
+const fsp = require('node:fs/promises');
+const path = require('node:path');
+const { spawn } = require('node:child_process');
+
+const { CAPS } = require('./quarantine');
+const { buildManifest, CapExceeded } = require('./manifest');
+
+const MAX_CAPTURE_BYTES = 1 * 1024 * 1024;
+// git's stderr can name internal hosts and paths; only a short excerpt travels,
+// and only in a finding's detail, never in a message a caller might echo.
+const STDERR_EXCERPT = 300;
+
+// Literal addresses git must never be pointed at. Without this the scanner is an
+// SSRF gadget: an attacker-chosen URL makes OUR process fetch cloud metadata, or
+// probe internal hosts via the difference between an error and a timeout.
+function blockedAddress(hostname) {
+  const h = String(hostname).toLowerCase().replace(/^\[|\]$/g, '');
+  if (h === '') return 'an empty host';
+  if (h === 'localhost' || h.endsWith('.localhost')) return 'loopback';
+  if (h === '::1' || h === '::') return 'IPv6 loopback/unspecified';
+  if (/^f[cd][0-9a-f]{2}:/.test(h)) return 'an IPv6 unique-local address';
+  if (/^fe80:/.test(h)) return 'an IPv6 link-local address';
+
+  // WHATWG URL canonicalizes ::ffff:127.0.0.1 to ::ffff:7f00:1, so the hex form
+  // must decode too — checking only the dotted spelling is itself a bypass.
+  let v4 = h;
+  const dotted = h.match(/^::ffff:(\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3})$/);
+  const hex = h.match(/^::ffff:([0-9a-f]{1,4}):([0-9a-f]{1,4})$/);
+  if (dotted) v4 = dotted[1];
+  else if (hex) {
+    const [hi, lo] = [parseInt(hex[1], 16), parseInt(hex[2], 16)];
+    v4 = `${hi >> 8}.${hi & 0xff}.${lo >> 8}.${lo & 0xff}`;
+  }
+
+  const m = v4.match(/^(\d{1,3})\.(\d{1,3})\.(\d{1,3})\.(\d{1,3})$/);
+  if (!m) return null;
+  const [a, b] = [Number(m[1]), Number(m[2])];
+  if (a === 127) return 'loopback';
+  if (a === 0) return 'the unspecified range';
+  if (a === 10) return 'a private (RFC 1918) address';
+  if (a === 172 && b >= 16 && b <= 31) return 'a private (RFC 1918) address';
+  if (a === 192 && b === 168) return 'a private (RFC 1918) address';
+  if (a === 169 && b === 254) return 'the link-local range (cloud metadata lives at 169.254.169.254)';
+  if (a === 100 && b >= 64 && b <= 127) return 'the carrier-grade NAT range';
+  if (a >= 224) return 'a multicast/reserved address';
+  return null;
+}
+
+// https only: ssh:// executes a remote command, file:// and ext:: reach local
+// paths, git:// is unauthenticated. A URL is refused, never rewritten — quietly
+// "fixing" an attacker's URL into one we like is its own vulnerability.
+function validateTargetUrl(raw) {
+  const value = String(raw ?? '').trim();
+  if (!value) return { ok: false, refusal: 'No URL given.' };
+  let u;
+  try { u = new URL(value); } catch { return { ok: false, refusal: `Not a URL: ${value}` }; }
+
+  if (u.protocol !== 'https:') return { ok: false, refusal: `Only https:// targets are scannable — got "${u.protocol}".` };
+  if (u.username || u.password) return { ok: false, refusal: 'Refusing a URL with embedded credentials.' };
+  const blocked = blockedAddress(u.hostname);
+  if (blocked) return { ok: false, refusal: `Refusing to point the scanner at ${blocked} (${u.hostname}).` };
+  return { ok: true, url: u.toString(), host: u.hostname };
+}
+
+function defaultResolveHost(hostname) {
+  return dns.promises.lookup(hostname, { all: true }).then((rs) => rs.map((r) => r.address));
+}
+
+// Resolve the name ourselves and refuse if ANY answer is private. A literal-only
+// check is trivially bypassed by pointing a domain's A record at 169.254.169.254.
+//
+// RESIDUAL LIMIT, stated rather than papered over: git re-resolves when it
+// connects, so a name that answers publicly here and privately microseconds
+// later (true DNS rebinding) still gets through. Closing that needs address
+// pinning git does not expose. This removes the trivial attack, not the race.
+async function assertHostResolvesPublic(hostname, resolveHost) {
+  let addresses;
+  try {
+    addresses = await resolveHost(hostname);
+  } catch (err) {
+    throw abort('host_unresolvable', `Could not resolve "${hostname}" — refusing to fetch.`, { hostname });
+  }
+  for (const addr of addresses) {
+    const blocked = blockedAddress(addr);
+    if (blocked) {
+      throw abort('host_resolves_private', `"${hostname}" resolves to ${blocked} (${addr}) — refusing to fetch.`, { hostname, addr });
+    }
+  }
+  return addresses;
+}
+
+// The `-c key=value` pairs applied to every git invocation. This list IS the
+// security control, not boilerplate.
+function hardeningConfig(q) {
+  return [
+    'core.symlinks=false',            // a symlink becomes inert text, not a live pointer at ~/.aws
+    `core.hooksPath=${q.hooksDir}`,   // must be a real EMPTY dir — /dev/null is not a directory on Windows
+    'protocol.file.allow=never',      // blocks file:// submodule/url-rewrite escapes
+    'protocol.ext.allow=never',       // blocks ext:: command execution
+    'transfer.fsckObjects=true',
+    'fetch.fsckObjects=true',
+    'credential.helper=',             // never offer a stored credential to a third-party host
+    'core.askPass=',
+    'filter.lfs.smudge=',             // an LFS smudge filter is a process git runs on checkout
+    'filter.lfs.process=',
+    'filter.lfs.required=false',
+    'advice.detachedHead=false',
+  ].flatMap((kv) => ['-c', kv]);
+}
+
+// Only what git needs. The builder's ambient env — API tokens, DB passwords,
+// cloud credentials — is deliberately not forwarded to a process talking to a
+// server chosen by the person we are investigating. Proxy vars ARE forwarded, a
+// deliberate call: without them a builder behind a corporate proxy cannot scan.
+const ENV_PASSTHROUGH = [
+  'PATH', 'Path', 'PATHEXT',
+  'HOME', 'USERPROFILE', 'HOMEDRIVE', 'HOMEPATH',
+  'SystemRoot', 'SYSTEMROOT', 'ComSpec', 'COMSPEC', 'windir',
+  'TEMP', 'TMP', 'TMPDIR',
+  'LANG', 'LC_ALL',
+  'SSL_CERT_FILE', 'SSL_CERT_DIR', 'GIT_SSL_CAINFO',
+  'HTTP_PROXY', 'HTTPS_PROXY', 'NO_PROXY', 'http_proxy', 'https_proxy', 'no_proxy',
+];
+
+// Deduped case-insensitively: Windows' process.env is case-insensitive, so
+// reading both 'PATH' and 'Path' yields the same value under two keys, and the
+// duplicate makes CreateProcess fail to resolve git at all (spawn ENOENT).
+function hardenedEnv(q) {
+  const env = Object.create(null);
+  const seen = new Set();
+  for (const key of ENV_PASSTHROUGH) {
+    const lower = key.toLowerCase();
+    if (seen.has(lower) || process.env[key] === undefined) continue;
+    seen.add(lower);
+    env[key] = process.env[key];
+  }
+  return Object.assign(env, {
+    GIT_TERMINAL_PROMPT: '0',
+    GIT_ASKPASS: '',
+    SSH_ASKPASS: '',
+    GIT_CONFIG_NOSYSTEM: '1',
+    GIT_CONFIG_GLOBAL: q.gitConfigFile,
+    GIT_CONFIG_SYSTEM: q.gitConfigFile,
+    GIT_LFS_SKIP_SMUDGE: '1',
+    GCM_INTERACTIVE: 'never',
+  });
+}
+
+// Async spawn, never spawnSync: a 120s block would stall the event loop for any
+// caller that ever runs inside a request. argv is an array (no shell), so a URL
+// containing shell metacharacters is data, never a command. Output is bounded.
+function defaultRun(args, { cwd, env, timeoutMs }) {
+  return new Promise((resolve) => {
+    let child;
+    try {
+      child = spawn('git', args, { cwd, env, windowsHide: true });
+    } catch (err) {
+      return resolve({ status: null, stdout: '', stderr: '', timedOut: false, truncated: false, error: String(err.message) });
+    }
+    let stdout = '';
+    let stderr = '';
+    let timedOut = false;
+    // Capture is bounded, but a caller that PARSES stdout must be able to tell
+    // a complete answer from a clipped one — silently dropping the tail of
+    // `ls-files` hid gitlinks, and an unnoticed missing submodule is exactly
+    // the "unreviewed reads as clean" failure the floor exists to prevent.
+    let truncated = false;
+    const timer = setTimeout(() => { timedOut = true; child.kill('SIGKILL'); }, timeoutMs);
+    child.stdout.on('data', (d) => {
+      if (stdout.length < MAX_CAPTURE_BYTES) stdout += d;
+      else truncated = true;
+    });
+    child.stderr.on('data', (d) => { if (stderr.length < MAX_CAPTURE_BYTES) stderr += d; });
+    child.on('error', (err) => {
+      clearTimeout(timer);
+      resolve({ status: null, stdout, stderr, timedOut, truncated, error: String(err.message) });
+    });
+    child.on('close', (status) => {
+      clearTimeout(timer);
+      resolve({ status, stdout, stderr, timedOut, truncated, error: null });
+    });
+  });
+}
+
+// "<mode> <sha> <stage>\t<path>". Read BEFORE .git is deleted — the index is the
+// only remaining witness that a file was really a symlink (120000) or a
+// submodule (160000) once core.symlinks=false has flattened it.
+function parseLsFiles(stdout) {
+  const modes = [];
+  for (const line of String(stdout).split('\n')) {
+    if (!line.trim()) continue;
+    const tab = line.indexOf('\t');
+    if (tab === -1) continue;
+    modes.push({ mode: line.slice(0, line.indexOf(' ')), path: line.slice(tab + 1) });
+  }
+  return modes;
+}
+
+function finding(code, severity, message, detail) {
+  return { code, severity, message, detail: detail ?? null };
+}
+
+// Every throw out of fetchArtifact carries evidence, so a scan that died is
+// recordable as "aborted, here is why" rather than as silence.
+function abort(code, message, detail) {
+  const err = new Error(message);
+  err.code = code;
+  err.finding = finding(code, 'high', message, detail);
+  return err;
+}
+
+// Fetch one artifact into an existing quarantine.
+// Returns { url, host, addresses, sha, pristineDir, manifest, gitModes, findings }.
+async function fetchArtifact(rawUrl, {
+  quarantine,
+  timeoutMs = CAPS.cloneTimeoutMs,
+  maxFiles = CAPS.maxFiles,
+  maxBytes = CAPS.maxBytes,
+  run = defaultRun,
+  resolveHost = defaultResolveHost,
+} = {}) {
+  if (!quarantine || !quarantine.pristineDir) {
+    throw new Error('fetchArtifact requires a quarantine from createQuarantine().');
+  }
+  const valid = validateTargetUrl(rawUrl);
+  if (!valid.ok) throw abort('url_refused', valid.refusal, null);
+
+  const q = quarantine;
+  const env = hardenedEnv(q);
+  const cfg = hardeningConfig(q);
+  const findings = [];
+
+  const addresses = await assertHostResolvesPublic(valid.host, resolveHost);
+
+  const clone = await run(
+    [...cfg, 'clone', '--depth', '1', '--single-branch', '--no-tags', '--no-recurse-submodules', '--quiet', '--', valid.url, q.pristineDir],
+    { cwd: q.root, env, timeoutMs }
+  );
+
+  if (clone.timedOut) {
+    throw abort('clone_timeout', `Clone exceeded the ${timeoutMs}ms cap and was killed.`, { timeoutMs, url: valid.url });
+  }
+  if (clone.status !== 0) {
+    throw abort('clone_failed', `Clone failed (exit ${clone.status}).`, {
+      status: clone.status,
+      stderr_excerpt: String(clone.stderr || clone.error || '').trim().slice(0, STDERR_EXCERPT),
+    });
+  }
+
+  const rev = await run([...cfg, 'rev-parse', 'HEAD'], { cwd: q.pristineDir, env, timeoutMs });
+  if (rev.status !== 0) {
+    throw abort('head_unresolved', 'Could not resolve HEAD.', { stderr_excerpt: String(rev.stderr || '').trim().slice(0, STDERR_EXCERPT) });
+  }
+  const sha = rev.stdout.trim();
+
+  // The index is the ONLY witness that a path was really a symlink (120000) or
+  // a submodule (160000) once core.symlinks=false has flattened it, and a
+  // gitlink leaves an empty directory the manifest walk records nothing for.
+  // So when this read is incomplete the artifact's true shape is UNKNOWN —
+  // that must be a finding, never an empty list. Both fail-opens below were
+  // found by verifying the fix that folds these findings into the floor: the
+  // fold is worthless if the evidence was never produced.
+  const ls = await run([...cfg, 'ls-files', '-s'], { cwd: q.pristineDir, env, timeoutMs });
+  const gitModes = ls.status === 0 ? parseLsFiles(ls.stdout) : [];
+  if (ls.status !== 0 || ls.timedOut) {
+    findings.push(finding('git_index_unread', 'high',
+      'Could not read the git index — whether this artifact carries submodules or symlinks is UNKNOWN, not "none".',
+      { status: ls.status, timedOut: !!ls.timedOut, unscannable: true }));
+  } else if (ls.truncated) {
+    findings.push(finding('git_index_truncated', 'high',
+      'The git index listing was too large to read in full — any submodule or symlink past the cut is UNSEEN, so this artifact\'s shape is only partly known.',
+      { captured_bytes: ls.stdout.length, entries_parsed: gitModes.length, unscannable: true }));
+  }
+
+  for (const m of gitModes) {
+    if (m.mode === '120000') {
+      findings.push(finding('symlink_in_artifact', 'medium', `Symlink "${m.path}" — materialized as inert text, its target was never opened.`, m));
+    } else if (m.mode === '160000') {
+      // unscannable: a gitlink materializes as an EMPTY directory, so the
+      // manifest walk records no entry for it and the floor has nothing to
+      // skip — without this flag the reducer's coverage cap cannot see that
+      // real third-party code went unreviewed (review finding).
+      findings.push(finding('submodule_not_fetched', 'medium', `Submodule at "${m.path}" was NOT fetched and is therefore unreviewed.`, { ...m, unscannable: true }));
+    }
+  }
+
+  // The SHA and modes are captured, so a bare content tree makes the manifest
+  // mean exactly "the files this artifact would install".
+  await fsp.rm(path.join(q.pristineDir, '.git'), { recursive: true, force: true });
+
+  let manifest;
+  try {
+    manifest = await buildManifest(q.pristineDir, { maxFiles, maxBytes });
+  } catch (err) {
+    if (err instanceof CapExceeded) {
+      throw abort(err.code, `${err.message} Scan aborted — a partial read cannot produce an honest verdict.`, err.detail);
+    }
+    throw err;
+  }
+
+  if (manifest.symlinkCount > 0) {
+    findings.push(finding('real_symlink_present', 'high', `${manifest.symlinkCount} real symlink(s) survived core.symlinks=false; targets were not followed.`, null));
+  }
+  if (manifest.otherCount > 0) {
+    findings.push(finding('unreadable_node', 'medium', `${manifest.otherCount} non-regular file(s) were recorded but not read.`, null));
+  }
+
+  return { url: valid.url, host: valid.host, addresses, sha, pristineDir: q.pristineDir, manifest, gitModes, findings };
+}
+
+module.exports = {
+  fetchArtifact,
+  validateTargetUrl,
+  blockedAddress,
+  assertHostResolvesPublic,
+  hardeningConfig,
+  hardenedEnv,
+  parseLsFiles,
+};

package/modules/security/artifact-scan/floor.js

@@ -0,0 +1,319 @@
+// modules/security/artifact-scan/floor.js — the zero-LLM deterministic floor
+// (task 1002544, goal 1000055).
+//
+// The floor's whole purpose is that a successful prompt injection cannot erase
+// its own evidence: this report is computed by CODE and written to disk BEFORE
+// any model reads a byte of the artifact. A panel can add findings on top; the
+// reducer takes the MAXIMUM of this floor and everything downstream, so
+// nothing a model says can lower what the detectors already proved.
+//
+// The floor reads the PRISTINE copy, not the mirror. Code is immune to
+// persuasion, so the injection-safety argument for the mirror does not apply —
+// and the mirror is scrubbed, so codepoint evidence EXISTS only in pristine.
+// Reads follow the same confinement discipline as mirror.js: manifest-driven,
+// lexically checked before any fs call, realpath-verified inside the pen.
+//
+// Verdict arithmetic (monotone by construction):
+//   any critical finding  → 'dangerous'
+//   any finding at all    → 'caution'
+//   no findings           → 'clean'
+// A detector that crashes contributes a finding (never silence), so a broken
+// detector degrades the verdict toward caution rather than toward clean.
+
+'use strict';
+
+const fsp = require('node:fs/promises');
+const path = require('node:path');
+const { TextDecoder } = require('node:util');
+
+const { isInside } = require('./quarantine');
+const { MIRROR_CAPS } = require('./mirror');
+const { scrubUntrusted } = require('./fence-local');
+const { finding, isSensitivePath, SEVERITIES, excerpt } = require('./detectors/shared');
+
+const npmLifecycle = require('./detectors/npm-lifecycle');
+const hooks = require('./detectors/hooks');
+const mcp = require('./detectors/mcp');
+const permissions = require('./detectors/permissions');
+const credentials = require('./detectors/credentials');
+const network = require('./detectors/network');
+const injection = require('./detectors/injection');
+const dependencies = require('./detectors/dependencies');
+const configObfuscation = require('./detectors/config-obfuscation');
+const capabilities = require('./detectors/capabilities');
+
+const FLOOR_VERSION = '1.0.0';
+const REPORT_BASENAME = 'floor-report.json';
+
+// Bounds on the fetch-stage fold (see runFloor's extraFindings).
+const MAX_EXTRA_FINDINGS = 500;
+const CODE_MAX_CHARS = 64;
+
+// Shared with the reducer (task 1002545): the max() it takes is over this rank.
+const VERDICT_RANK = Object.freeze({ clean: 0, caution: 1, dangerous: 2 });
+
+const UTF8_STRICT = new TextDecoder('utf-8', { fatal: true });
+
+const DETECTORS = Object.freeze([
+  ['npm-lifecycle', npmLifecycle.detect],
+  ['claude-hooks', hooks.detect],
+  ['mcp-servers', mcp.detect],
+  ['permissions', permissions.detect],
+  ['credential-stores', credentials.detect],
+  ['network-sinks', network.detect],
+  ['injection-text', injection.detect],
+  ['dependencies', dependencies.detect],
+  ['config-obfuscation', configObfuscation.detect],
+]);
+
+// Per-chunk parallel-read width. Bounded so a huge artifact cannot exhaust
+// file descriptors; chunked (not a free-running pool) so files[]/skipped[]
+// keep deterministic manifest order.
+const READ_CONCURRENCY = 16;
+
+// Manifest-driven confined read of every renderable text file. Anything the
+// floor cannot honestly read (binary, oversize, escaping, unreadable) becomes
+// a skipped record — counted, never silently dropped — because "I did not read
+// it" must always be visible to the reducer's coverage cap.
+async function buildCorpus({ pristineDir, quarantineRoot, entries, caps = {}, realQuarantine: realQuarantineIn = null }) {
+  const maxFileBytes = caps.maxFileBytes ?? MIRROR_CAPS.maxFileBytes;
+  const realQuarantine = realQuarantineIn || await fsp.realpath(quarantineRoot);
+
+  // One entry → { file } | { skip }, so chunked parallel reads reassemble in
+  // manifest order below. The RAW rel is used for every filesystem operation;
+  // the STORED path is scrubbed at this chokepoint, because manifest paths are
+  // artifact-controlled and corpus records flow into the report (coverage,
+  // capability inventory) — the report must never become a carrier.
+  const readOne = async (entry) => {
+    const rel = entry.path;
+    const safeRel = scrubUntrusted(rel);
+    const skip = (reason, bytes) => ({ skip: { path: safeRel, reason, bytes: bytes || 0 } });
+    if (entry.kind !== 'file') return skip(entry.kind === 'symlink' ? 'symlink' : 'special', entry.size);
+    if (typeof rel !== 'string' || rel.length === 0 || path.isAbsolute(rel)
+      || !isInside(pristineDir, path.resolve(pristineDir, ...rel.split('/')))) {
+      return skip('path_escape', entry.size);
+    }
+    if (entry.size > maxFileBytes) return skip('oversize', entry.size);
+
+    const abs = path.resolve(pristineDir, ...rel.split('/'));
+    let buf;
+    try {
+      const real = await fsp.realpath(abs);
+      if (!isInside(realQuarantine, real)) return skip('path_escape', entry.size);
+      const st = await fsp.lstat(abs);
+      if (st.isSymbolicLink()) return skip('path_escape', entry.size);
+      // Read the verified resolved path — same TOCTOU close as mirror.js.
+      buf = await fsp.readFile(real);
+    } catch {
+      return skip('unreadable', entry.size);
+    }
+
+    try {
+      return { file: { path: safeRel, size: buf.length, text: UTF8_STRICT.decode(buf) } };
+    } catch {
+      return skip('non_utf8', buf.length);
+    }
+  };
+
+  const files = [];
+  const skipped = [];
+  for (let i = 0; i < entries.length; i += READ_CONCURRENCY) {
+    const chunk = await Promise.all(entries.slice(i, i + READ_CONCURRENCY).map(readOne));
+    for (const r of chunk) {
+      if (r.file) files.push(r.file);
+      else skipped.push(r.skip);
+    }
+  }
+  return { files, skipped };
+}
+
+function computeFloorVerdict(findings) {
+  if (findings.some((f) => f.severity === 'critical')) return 'dangerous';
+  return findings.length > 0 ? 'caution' : 'clean';
+}
+
+function countBySeverity(findings) {
+  const counts = { critical: 0, high: 0, medium: 0, low: 0 };
+  for (const f of findings) counts[f.severity] = (counts[f.severity] || 0) + 1;
+  return counts;
+}
+
+// The same-file join: a file that both names a credential store AND carries a
+// network sink. Labeled exactly "same-file co-occurrence" — the floor has no
+// dataflow analysis and must never imply one; co-location is opportunity, and
+// opportunity inside one file is the strongest static exfil signal we can
+// honestly claim.
+function coOccurrence(corpus) {
+  const creds = credentials.perFileHits(corpus);
+  const sinks = network.perFileHits(corpus);
+  const findings = [];
+  for (const [file, credHits] of creds) {
+    const sinkHits = sinks.get(file);
+    if (!sinkHits) continue;
+    // Only FILE-class credential hits (a concrete on-disk secret path) arm this
+    // critical. An env-var NAME next to a fetch() is the single most common
+    // shape in ordinary tooling, so it must not be the read half of a
+    // read-then-send accusation — it still stands as its own medium finding.
+    const fileCreds = credHits.filter((h) => h.klass === 'file');
+    if (fileCreds.length === 0) continue;
+    findings.push(finding('read_then_send_same_file', 'critical', file,
+      `Same-file co-occurrence: names ${fileCreds[0].label} (line ${fileCreds[0].line}) AND carries ${sinkHits[0].label} (line ${sinkHits[0].line}). Co-location, not proven dataflow.`,
+      {
+        credential_stores: fileCreds.map((h) => h.label),
+        network_sinks: sinkHits.map((h) => h.label),
+        claimed_as: 'same-file co-occurrence, not dataflow',
+      }));
+  }
+  return findings;
+}
+
+// Coverage findings: a skip is only honest if it cannot resolve to "clean". A
+// skipped SENSITIVE file (a config that changes what the harness/installer
+// does) becomes a finding; an artifact NONE of whose bytes were readable
+// becomes a finding. Both keep the floor's own verdict off 'clean' when
+// executable/config content went unreviewed — the header's promise that
+// unreviewed never reads as clean, enforced in the floor itself and not left to
+// the downstream reducer alone.
+function coverageFindings(corpus) {
+  const findings = [];
+  for (const s of corpus.skipped) {
+    if (isSensitivePath(s.path)) {
+      findings.push(finding('unreviewed_sensitive_file', 'high', s.path,
+        `A security-relevant file was skipped (${s.reason}) and never reviewed — the installer/harness can still read it.`,
+        { reason: s.reason, bytes: s.bytes || 0 }));
+    }
+  }
+  if (corpus.files.length === 0 && corpus.skipped.length > 0) {
+    findings.push(finding('nothing_readable', 'high', '(floor)',
+      `None of the artifact's ${corpus.skipped.length} file(s) were readable as text — the floor reviewed nothing.`,
+      { skipped: corpus.skipped.length }));
+  }
+  return findings;
+}
+
+// Run every detector crash-isolated: a detector that throws yields a finding,
+// never a hole in the report. `detectors` is injectable so the crash-isolation
+// contract is unit-testable with a deliberately-throwing detector.
+function runDetectors(corpus, detectors = DETECTORS) {
+  const findings = [];
+  const errors = [];
+  for (const [name, detect] of detectors) {
+    try {
+      findings.push(...detect(corpus));
+    } catch (err) {
+      errors.push({ detector: name, error: String(err && err.message ? err.message : err) });
+      findings.push(finding('detector_error', 'high', '(floor)',
+        `Detector "${name}" crashed — its surface is UNREVIEWED and counts against coverage, not toward clean.`,
+        { detector: name }));
+    }
+  }
+  return { findings, errors };
+}
+
+// Build + persist the floor report. Returns the report object; the file at
+// <quarantineRoot>/floor-report.json is on disk before this resolves — callers
+// (the skill) MUST await this before any model reads a byte.
+//
+// `extraFindings` carries code-computed evidence produced BEFORE the floor ran
+// — fetchArtifact's findings (unfetched submodules, surviving symlinks,
+// non-regular nodes). They belong in the persisted report for the same reason
+// every detector finding does: they are arithmetic, not opinion, and the
+// reducer takes its floor component from this report. Routing them only to a
+// chat summary let a repo whose submodule was never fetched reduce to CLEAN
+// (review finding) — an artifact with unreviewed code must never read as clean.
+async function runFloor({ pristineDir, quarantineRoot, entries, sha = null, contentHash = null, caps = {}, extraFindings = [] }) {
+  // Resolved once, shared by the corpus reads and the persist below. Allowed to
+  // throw: an unresolvable pen means no report can honestly land anywhere.
+  const realQuarantine = await fsp.realpath(quarantineRoot);
+  let corpus = { files: [], skipped: [] };
+  let corpusError = null;
+  try {
+    corpus = await buildCorpus({ pristineDir, quarantineRoot, entries, caps, realQuarantine });
+  } catch (err) {
+    corpusError = String(err && err.message ? err.message : err);
+  }
+
+  const { findings, errors } = runDetectors(corpus);
+  // Each post-detector step is crash-isolated too: the whole point of the floor
+  // is that a report ALWAYS lands, so a throw in co-occurrence, the coverage
+  // pass, or the capability inventory must degrade to a finding, never abort
+  // the persist. isolate() runs a step, appends its result, and on a throw
+  // records a detector_error (which contributes caution) instead of propagating.
+  const isolate = (name, fn) => {
+    try { return fn(); }
+    catch (err) {
+      errors.push({ detector: name, error: String(err && err.message ? err.message : err) });
+      findings.push(finding('detector_error', 'high', '(floor)',
+        `Step "${name}" crashed — its surface is UNREVIEWED and counts against coverage, not toward clean.`, { detector: name }));
+      return null;
+    }
+  };
+
+  findings.push(...(isolate('co-occurrence', () => coOccurrence(corpus)) || []));
+  findings.push(...(isolate('coverage', () => coverageFindings(corpus)) || []));
+  // Re-built through finding() so fetch-stage strings get the same scrub + cap
+  // every other finding gets — a caller's array is untrusted input here too.
+  // `code` does NOT pass through finding()'s chokepoint (it is a label, not a
+  // quoted string), so it is scrubbed + capped explicitly here; and the array
+  // is length-capped, because an unbounded fold would let one stage balloon
+  // the persisted report.
+  findings.push(...(isolate('fetch-stage', () => (Array.isArray(extraFindings) ? extraFindings : [])
+    .filter((f) => f && typeof f === 'object')
+    .slice(0, MAX_EXTRA_FINDINGS)
+    .map((f) => finding(
+      excerpt(String(f.code || 'fetch_finding'), CODE_MAX_CHARS),
+      SEVERITIES.includes(f.severity) ? f.severity : 'high',
+      String(f.file || '(fetch)'),
+      String(f.message || ''),
+      f.detail ?? null
+    ))) || []));
+  const capabilityInventory = isolate('capabilities', () => capabilities.inventory(corpus)) || [];
+  if (corpusError) {
+    findings.push(finding('corpus_error', 'high', '(floor)',
+      'The floor could not read the artifact tree at all — nothing here was reviewed.', { error: corpusError }));
+  }
+
+  const report = {
+    floor_version: FLOOR_VERSION,
+    detectors_run: DETECTORS.map(([name]) => name),
+    detector_errors: errors,
+    generated_at: new Date().toISOString(),
+    target: { sha, content_hash: contentHash },
+    findings,
+    counts: countBySeverity(findings),
+    floor_verdict: computeFloorVerdict(findings),
+    // Printed, never scored — the reader's power budget for the artifact.
+    capabilities: capabilityInventory,
+    coverage: {
+      files_read: corpus.files.length,
+      bytes_read: corpus.files.reduce((sum, f) => sum + f.size, 0),
+      files_skipped: corpus.skipped,
+      bytes_skipped: corpus.skipped.reduce((sum, s) => sum + (s.bytes || 0), 0),
+    },
+  };
+
+  // Atomic persist inside the pen: write-then-rename so a crash mid-write can
+  // never leave a half-valid report a later stage might trust. Persist is the
+  // one step that MUST be allowed to throw — a report we could not write to disk
+  // is not a report, and the caller needs to know the floor did not land.
+  const outPath = path.join(realQuarantine, REPORT_BASENAME);
+  const tmpPath = `${outPath}.tmp`;
+  await fsp.writeFile(tmpPath, JSON.stringify(report, null, 2), 'utf8');
+  await fsp.rename(tmpPath, outPath);
+
+  return { report, reportPath: outPath };
+}
+
+module.exports = {
+  FLOOR_VERSION,
+  REPORT_BASENAME,
+  VERDICT_RANK,
+  DETECTORS,
+  buildCorpus,
+  computeFloorVerdict,
+  countBySeverity,
+  coOccurrence,
+  coverageFindings,
+  runDetectors,
+  runFloor,
+};