hullproof 0.0.0-stage → 0.5.0

package/dist/commands/ci.js

@@ -0,0 +1,115 @@
+// hullproof ci: discover, scan, map, check and gate in one command, with no model and no container (hunt is the one option that
+// calls a model, and only in the Pro edition). It writes four files for the commit and exits 0, 1 or 2:
+//   findings.json   the findings record, schema 1.1.0
+//   report.md       the plain English report
+//   results.sarif   SARIF 2.1.0 for code scanning
+//   pr-comment.md   the summary for a pull request
+// The files are byte identical for the same commit, engine, kit and scanner versions. They go to <out>/<commit>/ and to the flat
+// folder --artifacts (default <out>/ci), so a CI job, an AI tool and a person all read the same paths.
+// Exit 0: nothing at or above --fail-on failed. Exit 1: something did. Exit 2: bad input, a refused run or a records problem.
+import { existsSync, mkdirSync, rmSync, writeFileSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { readHeadCommit } from '../discover/git.js';
+import { loadHuntEnv } from '../env.js';
+import { checkSarif } from '../ci/sarif-check.js';
+import { buildSarif, sarifJson } from '../ci/sarif.js';
+import { ciVerdict, FAIL_ON_LEVELS, prComment } from '../ci/comment.js';
+import { gateLines } from '../gate/gate.js';
+import { loadKit, resolveKitDir } from '../report/kit.js';
+import { renderReport } from '../report/report.js';
+import { stableJson } from '../util.js';
+import { huntCommand } from './hunt.js';
+import { HUNT_PRO } from './hunt-pro.js';
+import { prepare } from './report-gate.js';
+import { scan } from './scan.js';
+export const CI_FILES = ['findings.json', 'report.md', 'results.sarif', 'pr-comment.md'];
+export async function ciCommand(o) {
+    const log = o.log ?? ((s) => process.stderr.write(s + '\n'));
+    const print = o.print ?? ((s) => process.stdout.write(s + '\n'));
+    const repo = resolve(o.repo);
+    if (!FAIL_ON_LEVELS.includes(o.failOn)) {
+        log(`hullproof ci: --fail-on takes ${FAIL_ON_LEVELS.join(', ')}`);
+        return 2;
+    }
+    const kitDir = resolveKitDir(repo, o.kit);
+    if (!kitDir) {
+        log('hullproof ci: no kit found. Pass --kit <folder holding docs/hullproof/security-controls.json> or set HULLPROOF_KIT.');
+        return 2;
+    }
+    // The edition follows the kit unless it is named: a kit with Pro requirements runs the full set, the Free kit runs BLOCKER and CRITICAL.
+    const edition = o.edition ?? (loadKit(kitDir).controls.some((c) => c.edition === 'pro') ? 'pro' : 'free');
+    if (o.hunt) {
+        if (!HUNT_PRO) {
+            log('hullproof ci: --hunt calls a model and is part of the Pro edition. This edition runs the deterministic checks only.');
+            return 2;
+        }
+        if (edition !== 'pro') {
+            log('hullproof ci: --hunt needs the Pro edition requirements (the kit has none, or --edition free was given)');
+            return 2;
+        }
+    }
+    const code = await scan({
+        repo, out: o.out, kit: kitDir, edition, stage: o.stage, allowNetwork: o.allowNetwork, tools: o.tools, rulePack: o.rulePack, log,
+    });
+    if (code !== 0)
+        return 2;
+    if (o.hunt) {
+        // The key comes from the environment (a CI secret) or a .env.local file, never from a flag, and is never printed.
+        // No .env.local is read in CI: the repository under test is untrusted and must not name the provider address.
+        process.env.HULLPROOF_NO_ENV_FILE = '1';
+        const { env } = loadHuntEnv(repo);
+        if (!o.provider && !env.HULLPROOF_PROVIDER && !env.ANTHROPIC_API_KEY && !env.OPENAI_API_KEY && !env.GEMINI_API_KEY) {
+            log('hullproof ci: --hunt needs a provider key in the environment (a CI secret). None is set, so no model was called.');
+            return 2;
+        }
+        const h = await huntCommand({ repo, out: o.out, kit: kitDir, commit: null, provider: o.provider, model: o.model, runs: null, dryRun: false, resume: false, replay: false, log });
+        if (h !== 0)
+            return 2;
+    }
+    const r = await prepare({ repo, out: o.out, kit: kitDir, commit: null, owner: o.owner, date: o.date, log });
+    if (typeof r === 'string') {
+        log(`hullproof ci: ${r}`);
+        return 2;
+    }
+    if (r.gate.problems.length) {
+        for (const p of r.gate.problems)
+            log(`hullproof ci: ${p}`);
+        return 2;
+    }
+    const findings = r.s.findings;
+    const verdict = ciVerdict(findings, o.failOn);
+    // The SARIF result of a record with no evidence file points at a file that exists in every repository the engine can scan.
+    const anchor = existsSync(join(repo, 'package.json')) ? 'package.json' : existsSync(join(repo, 'README.md')) ? 'README.md' : '.gitignore';
+    const sarif = buildSarif(findings, r.kit, anchor);
+    const bad = checkSarif(sarif);
+    if (bad.length) {
+        for (const b of bad)
+            log(`hullproof ci: results.sarif: ${b}`);
+        return 2;
+    }
+    const ran = r.s.metas.filter((m) => m.status === 'ran').map((m) => m.tool);
+    const files = {
+        'findings.json': stableJson(findings),
+        'report.md': renderReport(r.s, r.kit, r.gate, r.merged),
+        'results.sarif': sarifJson(sarif),
+        'pr-comment.md': prComment({ findings, verdict, failOn: o.failOn, edition, scanners: ran }),
+    };
+    const commit = readHeadCommit(repo);
+    const base = resolve(o.out ?? join(repo, '.hullproof'));
+    const targets = [join(base, commit), resolve(o.artifacts ?? join(base, 'ci'))];
+    for (const t of targets) {
+        mkdirSync(t, { recursive: true });
+        for (const n of CI_FILES) {
+            rmSync(join(t, n), { force: true });
+            writeFileSync(join(t, n), files[n]);
+        }
+    }
+    print(`hullproof ci: commit ${commit.slice(0, 12)}, ${edition} edition, stage ${findings.report.stage}, fails on ${o.failOn === 'none' ? 'nothing' : o.failOn.toUpperCase() + ' and above'}`);
+    print(`hullproof ci: findings ${verdict.blocking.length + verdict.others.length}, blocking ${verdict.blocking.length}`);
+    for (const f of verdict.blocking.slice(0, 20))
+        print(`  ${f.severity} ${f.sec_ids.join(',')} ${f.evidence[0] ? `${f.evidence[0].file}:${f.evidence[0].line}` : '-'} ${f.title}`);
+    print(`hullproof ci: release gate for this commit (informational in CI): ${gateLines(r.gate).at(-1)}`);
+    print(`hullproof ci: wrote ${CI_FILES.join(', ')} to ${targets[1]}`);
+    print(`hullproof ci: ${verdict.blocked ? 'FAILED, a blocking finding is open' : 'PASSED'}`);
+    return verdict.blocked ? 1 : 0;
+}

package/dist/commands/git.js

@@ -0,0 +1,58 @@
+// Git safety and state. Before any git command (ours or a scanner's), the repository's git configuration is checked
+// with the same three counts as the kit's scan.sh, and the scan is refused when a git command could run code from it.
+import { spawnSync } from 'node:child_process';
+import { existsSync, readFileSync, statSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+export function gitSafety(repo) {
+    const dotGit = join(repo, '.git');
+    if (!existsSync(dotGit))
+        return { ok: false, message: `${repo} is not a git repository`, credentialUrl: false };
+    let conf;
+    let extra = null;
+    if (statSync(dotGit).isDirectory()) {
+        conf = join(dotGit, 'config');
+        // config.worktree (set by newer checkouts, for example actions/checkout) is read with the same three counts as config.
+        if (existsSync(join(dotGit, 'config.worktree')))
+            extra = join(dotGit, 'config.worktree');
+    }
+    else {
+        const m = /^gitdir:\s*(.+)$/m.exec(readFileSync(dotGit, 'utf8'));
+        if (!m)
+            return { ok: false, message: 'refused: GIT CONFIG: NOT CHECKED (cannot read the gitdir line)', credentialUrl: false };
+        conf = join(dirname(dirname(resolve(repo, m[1].trim()))), 'config');
+    }
+    if (!existsSync(conf))
+        return { ok: false, message: 'refused: GIT CONFIG: NOT CHECKED (no config file at the expected place)', credentialUrl: false };
+    const lines = [...readFileSync(conf, 'utf8').split('\n'), ...(extra ? readFileSync(extra, 'utf8').split('\n') : [])];
+    const c1 = lines.filter((l) => /^[ \t]*(fsmonitor|sshCommand|hooksPath|textconv|pager|editor)[ \t]*=/i.test(l)).length;
+    const c2 = lines.filter((l) => /^\[(diff|filter|credential)[ "]|^\[(diff|filter|credential)\]/i.test(l)).length;
+    const c3 = lines.filter((l) => /:\/\/[^/ ]*@/.test(l)).length;
+    if (c1 > 0 || c2 > 0) {
+        return { ok: false, message: `refused: a git command could run code from this folder (code running keys ${c1}, driver and credential sections ${c2}). Remove the entries or scan a fresh clone.`, credentialUrl: c3 > 0 };
+    }
+    return { ok: true, message: `git config counts: code running keys 0, driver and credential sections 0, remote URLs with credentials ${c3}`, credentialUrl: c3 > 0 };
+}
+// git with the user and system configuration switched off, as scan.sh runs it. Call only after gitSafety passed.
+// HULLPROOF_TRUST_REPO_OWNER=1 is set by the container entry point of the GitHub Action, where the checkout belongs to another user
+// than the one running the engine and git would otherwise refuse it as a dubious ownership folder. It switches that one git check off
+// through a command line style setting, which git honours while the user configuration stays off. The repository's own
+// configuration is still checked by gitSafety above.
+export const TRUST_REPO_OWNER = { GIT_CONFIG_COUNT: '1', GIT_CONFIG_KEY_0: 'safe.directory', GIT_CONFIG_VALUE_0: '*' };
+export const GIT_ENV = {
+    GIT_CONFIG_GLOBAL: '/dev/null', GIT_CONFIG_SYSTEM: '/dev/null', GIT_OPTIONAL_LOCKS: '0', GIT_TERMINAL_PROMPT: '0',
+    ...(process.env.HULLPROOF_TRUST_REPO_OWNER === '1' ? TRUST_REPO_OWNER : {}),
+};
+function git(repo, args) {
+    const r = spawnSync('git', ['-C', repo, ...args], { encoding: 'utf8', env: { ...process.env, ...GIT_ENV } });
+    return r.status === 0 ? r.stdout : null;
+}
+// The commit, its tree and whether tracked files differ from it. Untracked files are left out, so engine output written
+// inside the repository does not change the answer between runs.
+export function gitState(repo) {
+    const commit = git(repo, ['rev-parse', 'HEAD'])?.trim();
+    const tree = git(repo, ['rev-parse', 'HEAD^{tree}'])?.trim();
+    const status = git(repo, ['status', '--porcelain', '--untracked-files=no']);
+    if (!commit || !tree || status === null || !/^[0-9a-f]{40}$/.test(commit) || !/^[0-9a-f]{40}$/.test(tree))
+        return null;
+    return { commit, tree, clean: status.trim() === '' };
+}

package/dist/commands/hooks.js

@@ -0,0 +1,30 @@
+// hullproof hooks install | uninstall | run. `run` is what the git hook calls (src/hooks/run.ts).
+import { installHooks } from '../hooks/install.js';
+import { runHook } from '../hooks/run.js';
+export async function hooksCommand(o) {
+    const log = o.log ?? ((s) => process.stderr.write(s + '\n'));
+    if (o.action === 'install' || o.action === 'uninstall') {
+        if (o.mode && !['git', 'husky', 'pre-commit'].includes(o.mode)) {
+            log('hullproof hooks: --mode is git, husky or pre-commit');
+            return 2;
+        }
+        const r = installHooks({ repo: o.repo, mode: o.mode, dryRun: o.dryRun, uninstall: o.action === 'uninstall' });
+        for (const l of r.lines)
+            log(l);
+        return r.code;
+    }
+    if (o.action === 'run') {
+        try {
+            const r = await runHook({ repo: o.repo, kit: o.kit, semgrep: !o.noSemgrep && process.env.HULLPROOF_HOOK_SEMGREP !== '0' });
+            for (const l of r.lines)
+                log(l);
+            return r.code === 1 ? 1 : r.code === 2 ? 0 : r.code;
+        }
+        catch (e) {
+            log(`hullproof: the pre-commit check could not run (${e.message}). The commit was not blocked.`);
+            return process.env.HULLPROOF_HOOK_STRICT === '1' ? 1 : 0;
+        }
+    }
+    log('hullproof hooks: use install, uninstall or run');
+    return 2;
+}

package/dist/commands/hunt-pro.js

@@ -0,0 +1 @@
+export const HUNT_PRO = null;

package/dist/commands/hunt.js

@@ -0,0 +1,86 @@
+// hullproof hunt. --replay (open) reruns the confirmation from the saved answers in <out>/<commit>/hunt/ and writes result.json.
+// The other modes call a model through the hunt step that only the Pro edition has (src/commands/hunt-pro.ts).
+import { resolve } from 'node:path';
+import { makeContext } from '../checks/context.js';
+import { getMap } from '../checks/map/shared.js';
+import { confirmHunt } from '../confirm/confirm.js';
+import { huntDir, readAnswers, readPlan, readSynthesis, writeResult, writeSynthesis } from '../confirm/store.js';
+import { summary } from '../confirm/summary.js';
+import { reguard } from '../confirm/synthesis.js';
+import { discover } from '../discover/discover.js';
+import { readHeadCommit } from '../discover/git.js';
+import { loadHuntEnv } from '../env.js';
+import { resolveKitDir } from '../report/kit.js';
+import { outDirFor } from './scan.js';
+import { HUNT_PRO } from './hunt-pro.js';
+export const DEFAULT_RUNS = 3;
+export async function huntCommand(o) {
+    const log = o.log ?? ((s) => process.stderr.write(s + '\n'));
+    const repo = resolve(o.repo);
+    const commit = o.commit ?? readHeadCommit(repo);
+    if (!commit) {
+        log(`hullproof hunt: no commit found in ${repo}; pass --commit`);
+        return 2;
+    }
+    if (o.replay && (o.dryRun || o.resume || o.provider || o.model || o.runs !== null)) {
+        log('hullproof hunt: --replay takes no other hunt option');
+        return 2;
+    }
+    if (o.dryRun && o.resume) {
+        log('hullproof hunt: --dry-run and --resume cannot be used together');
+        return 2;
+    }
+    const scanDir = outDirFor(repo, o.out, commit);
+    const hd = huntDir(scanDir);
+    let map;
+    let ctx;
+    try {
+        ctx = makeContext(repo, discover(repo));
+        map = getMap(ctx);
+    }
+    catch (e) {
+        log(`hullproof hunt: ${e.message}`);
+        return 2;
+    }
+    if (o.replay) {
+        let answers;
+        let plan;
+        try {
+            answers = readAnswers(hd);
+            plan = readPlan(hd);
+        }
+        catch (e) {
+            log(`hullproof hunt: ${e.message}`);
+            return 2;
+        }
+        if (!answers.length && !plan) {
+            log(`hullproof hunt: no saved hunt outputs in ${hd}`);
+            return 2;
+        }
+        const result = confirmHunt({ repo, map, answers, plan, commit });
+        writeResult(hd, result);
+        const syn = readSynthesis(hd);
+        if (syn)
+            writeSynthesis(hd, reguard(result, syn));
+        for (const l of summary(result))
+            log(l);
+        log(`hullproof hunt: replay wrote ${hd}/result.json`);
+        return 0;
+    }
+    if (!HUNT_PRO) {
+        log('hullproof hunt: the step that calls a model is not part of this edition. Use --replay to confirm saved outputs.');
+        return 2;
+    }
+    const runs = o.runs ?? DEFAULT_RUNS;
+    if (!Number.isInteger(runs) || runs < 1) {
+        log('hullproof hunt: --runs needs a whole number of 1 or more');
+        return 2;
+    }
+    const kitDir = resolveKitDir(repo, o.kit);
+    if (!kitDir) {
+        log('hullproof hunt: no kit found. Pass --kit or set HULLPROOF_KIT.');
+        return 2;
+    }
+    const { env } = loadHuntEnv(repo);
+    return HUNT_PRO.run({ repo, scanDir, huntDir: hd, commit, map, ctx, kitDir, provider: o.provider, model: o.model, runs, dryRun: o.dryRun, resume: o.resume, env, log });
+}

package/dist/commands/map.js

@@ -0,0 +1,33 @@
+// hullproof map: discovery, then the code map. Needs no kit and no scanner. Writes <out>/codemap.json (default: .hullproof
+// inside the repository), or prints it with --out -.
+import { mkdirSync, writeFileSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { makeContext } from '../checks/context.js';
+import { getMap } from '../checks/map/shared.js';
+import { discover } from '../discover/discover.js';
+import { stableJson } from '../util.js';
+export function mapCommand(repoArg, outArg, out, err) {
+    let json;
+    let summary;
+    try {
+        const repo = resolve(repoArg);
+        const ctx = makeContext(repo, discover(repo));
+        const map = getMap(ctx);
+        json = stableJson(map);
+        const notMapped = map.coverage.filter((c) => c.status !== 'mapped');
+        summary = `hullproof map: ${map.counts.entry_points} entry points${notMapped.length ? `; map incomplete for ${notMapped.map((c) => c.language).join(', ')}` : ''}`;
+    }
+    catch (e) {
+        err(`hullproof map: ${e.message}\n`);
+        return 2;
+    }
+    if (outArg === '-') {
+        out(json);
+        return 0;
+    }
+    const dir = resolve(outArg ?? join(repoArg, '.hullproof'));
+    mkdirSync(dir, { recursive: true });
+    writeFileSync(join(dir, 'codemap.json'), json);
+    out(`${summary}\nhullproof map: wrote ${join(dir, 'codemap.json')}\n`);
+    return 0;
+}

package/dist/commands/mcp.js

@@ -0,0 +1,17 @@
+// hullproof mcp: the MCP server over stdio. Read tools always; run_scan only with --allow-run.
+import { existsSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { HullproofTools } from '../mcp/tools.js';
+import { serve } from '../mcp/server.js';
+export async function mcpCommand(o) {
+    const log = o.log ?? ((s) => process.stderr.write(s + '\n'));
+    const repo = resolve(o.repo);
+    if (!existsSync(repo)) {
+        log(`hullproof mcp: ${repo} does not exist`);
+        return 2;
+    }
+    const tools = new HullproofTools({ repo, kit: o.kit, edition: o.edition, allowRun: o.allowRun, log });
+    log(`hullproof mcp: serving ${repo} on stdio (run_scan ${o.allowRun ? 'on' : 'off'})`);
+    await serve(process.stdin, process.stdout, tools);
+    return 0;
+}

package/dist/commands/pack.js

@@ -0,0 +1,48 @@
+// hullproof pack: validate the stack packs (packs/<id>), list them, or print the coverage table made from their recorded results.
+import { existsSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { coverageMarkdown, coverageRows, legendMarkdown } from '../packs/coverage.js';
+import { LEVEL_NAMES } from '../packs/manifest.js';
+import { defaultEnv, listPacks, PACKS_DIR, validatePack } from '../packs/validate.js';
+export function packCommand(o) {
+    const { out, err } = o;
+    if (!['validate', 'list', 'table'].includes(o.action)) {
+        err(`hullproof pack: use validate, list or table (got "${o.action}").\n`);
+        return 2;
+    }
+    const root = o.root ? resolve(o.root) : undefined;
+    if (root && !existsSync(root)) {
+        err(`hullproof pack: --root ${root} does not exist.\n`);
+        return 2;
+    }
+    const env = defaultEnv(root);
+    const folders = o.targets.length ? o.targets.map((t) => resolve(t)) : listPacks(root ? resolve(root, 'packs') : PACKS_DIR);
+    for (const f of folders)
+        if (!existsSync(f)) {
+            err(`hullproof pack: ${f} does not exist.\n`);
+            return 2;
+        }
+    const checked = folders.map((f) => validatePack(f, env));
+    if (o.action === 'table') {
+        out(`${legendMarkdown()}\n\n${coverageMarkdown(coverageRows(checked))}\n`);
+        return checked.some((c) => c.issues.length) ? 1 : 0;
+    }
+    if (o.action === 'list') {
+        for (const c of checked)
+            out(`${c.manifest?.id ?? c.dir}\t${c.manifest ? `${c.manifest.level} ${LEVEL_NAMES[c.manifest.level]}` : 'unreadable'}\t${c.manifest?.name ?? ''}\n`);
+        return 0;
+    }
+    let failed = 0;
+    for (const c of checked) {
+        if (!c.issues.length) {
+            out(`ok    ${c.manifest.id} ${c.manifest.level}${c.skipped.length ? ` (${c.skipped.length} Pro or internal part(s) not checked in this edition)` : ''}\n`);
+            continue;
+        }
+        failed++;
+        out(`FAIL  ${c.manifest?.id ?? c.dir}\n`);
+        for (const i of c.issues)
+            out(`      ${i.code}: ${i.message}\n`);
+    }
+    out(`hullproof pack validate: ${checked.length - failed} of ${checked.length} packs pass\n`);
+    return failed ? 1 : 0;
+}

package/dist/commands/prove-pro.js

@@ -0,0 +1 @@
+export const PROVE_PRO = null;

package/dist/commands/prove.js

@@ -0,0 +1,173 @@
+// hullproof prove. Runs test specs against a local copy of the app in a sandbox and keeps the transcripts as evidence. The safety
+// rules are enforced here before anything starts: an explicit flag, the owner's typed confirmation, no target address of any kind,
+// and (inside the runner) no secrets, no network, no host mounts. --replay rebuilds the result from saved transcripts with no
+// sandbox. --gen (Pro) writes specs from hunt leads. --self-test runs the escape attempts on this machine's container runtime.
+import { readFileSync } from 'node:fs';
+import { createInterface } from 'node:readline/promises';
+import { basename, join, resolve } from 'node:path';
+import { makeContext } from '../checks/context.js';
+import { getMap } from '../checks/map/shared.js';
+import { discover } from '../discover/discover.js';
+import { readHeadCommit } from '../discover/git.js';
+import { loadHuntEnv } from '../env.js';
+import { ContainerRunner, CliRuntime } from '../prove/container.js';
+import { runEscapeProbes, selfTestApp } from '../prove/probes.js';
+import { deriveRecipe } from '../prove/recipe.js';
+import { replayProve, runProve } from '../prove/run.js';
+import { DEFAULT_LIMITS } from '../prove/runner.js';
+import { checkConfirmation, CONFIRM_PHRASE } from '../prove/safety.js';
+import { validateSpec } from '../prove/spec.js';
+import { proveDir, writeSpec } from '../prove/store.js';
+import { huntDir, readResult } from '../confirm/store.js';
+import { outDirFor } from './scan.js';
+import { PROVE_PRO } from './prove-pro.js';
+export function summaryLines(r) {
+    const c = r.counts;
+    const lines = [`hullproof prove: ${c.proven} proven (3 of 3 runs), ${c.not_proven} not proven, ${c.invalid} invalid, ${c.unstable} unstable, ${c.error} error, ${c.not_provable} not provable here, ${c.dropped} spec file(s) dropped`];
+    if (r.not_provable)
+        lines.push(`hullproof prove: not provable here (${r.not_provable.code}): ${r.not_provable.reason}`);
+    for (const s of r.specs)
+        if (s.outcome !== 'proven' && s.outcome !== 'not_provable')
+            lines.push(`hullproof prove: ${s.spec_id}: ${s.outcome}: ${s.reason}`);
+    if (r.left_behind)
+        lines.push(`hullproof prove: WARNING: ${r.left_behind} container, image or network item(s) were left behind`);
+    return lines;
+}
+export async function proveCommand(o, deps = {}) {
+    const log = o.log ?? ((s) => process.stderr.write(s + '\n'));
+    if (o.target !== null) {
+        log('hullproof prove: refused. prove runs a local copy of the app in a sandbox and accepts no address. It never sends a request to a staging, production or any other URL.');
+        return 2;
+    }
+    const repo = resolve(o.repo);
+    const commit = o.commit ?? readHeadCommit(repo);
+    if (!commit) {
+        log(`hullproof prove: no commit found in ${repo}; pass --commit`);
+        return 2;
+    }
+    const dir = proveDir(outDirFor(repo, o.out, commit));
+    if (o.replay) {
+        if (o.gen || o.selfTest || o.specs.length || o.allowRun || o.confirm !== null || o.provider || o.model) {
+            log('hullproof prove: --replay takes no other option except --out and --commit');
+            return 2;
+        }
+        const r = replayProve(dir);
+        if (typeof r === 'string') {
+            log(`hullproof prove: ${r}`);
+            return 2;
+        }
+        for (const l of summaryLines(r))
+            log(l);
+        log(`hullproof prove: replay wrote ${join(dir, 'result.json')}`);
+        return 0;
+    }
+    // Specs the owner or a person wrote are validated and copied into the prove folder. A bad file is a bad input, named with its reasons.
+    for (const f of o.specs) {
+        let raw;
+        try {
+            raw = JSON.parse(readFileSync(resolve(f), 'utf8'));
+        }
+        catch (e) {
+            log(`hullproof prove: cannot read spec ${f}: ${e.message}`);
+            return 2;
+        }
+        const v = validateSpec(raw);
+        if (!v.ok) {
+            log(`hullproof prove: spec ${basename(f)} is invalid: ${v.errors.join('; ')}`);
+            return 2;
+        }
+        writeSpec(dir, v.spec);
+    }
+    let stack;
+    let map;
+    try {
+        stack = discover(repo);
+        map = getMap(makeContext(repo, stack));
+    }
+    catch (e) {
+        log(`hullproof prove: ${e.message}`);
+        return 2;
+    }
+    if (o.gen) {
+        if (!PROVE_PRO) {
+            log('hullproof prove: spec generation from leads is a Pro feature and is not part of this edition. Write specs by hand (see docs/INTERFACES.md) and pass them with --spec.');
+            return 2;
+        }
+        const hunt = readResult(huntDir(outDirFor(repo, o.out, commit)));
+        if (!hunt) {
+            log('hullproof prove: --gen needs the result of a hunt for this commit. Run hullproof hunt first.');
+            return 2;
+        }
+        const rec = deriveRecipe(repo, stack, map);
+        const { env } = loadHuntEnv(repo);
+        const code = await PROVE_PRO.generate({ repo, proveDir: dir, hunt, map, recipe: rec.ok ? rec.recipe : null, provider: o.provider, model: o.model, env, log });
+        if (code !== 0 || !o.allowRun)
+            return code;
+    }
+    if (!o.allowRun && !o.selfTest) {
+        log('hullproof prove: nothing to do. Use --allow-run to run specs, --replay to rebuild the result from saved transcripts, or --gen (Pro) to write specs from leads.');
+        return 2;
+    }
+    // Safety rule 1: the flag and the typed phrase, every run. Asked here, before a runtime is even looked for.
+    let typed = o.confirm;
+    if (typed === null && (deps.interactive ?? process.stdin.isTTY)) {
+        const ask = deps.ask ?? (async (q) => { const rl = createInterface({ input: process.stdin, output: process.stderr }); try {
+            return await rl.question(q);
+        }
+        finally {
+            rl.close();
+        } });
+        log('hullproof prove will build and start a copy of this app in a container, with no secrets, no network and no access to your files. Only the owner of the app may approve that.');
+        typed = await ask(`Type exactly "${CONFIRM_PHRASE}" to continue: `);
+    }
+    const c = checkConfirmation(o.allowRun || o.selfTest, typed);
+    if (!c.ok) {
+        log(`hullproof prove: ${c.reason}`);
+        return 2;
+    }
+    const bin = o.runtime ?? process.env.HULLPROOF_CONTAINER_BIN ?? 'docker';
+    if (!/^[a-z][a-z0-9._-]{0,30}$/.test(bin)) {
+        log('hullproof prove: --runtime names a container command such as docker or podman');
+        return 2;
+    }
+    const runner = deps.runner ?? new ContainerRunner(new CliRuntime(bin));
+    const av = await runner.available();
+    if (!av.ok) {
+        log(`hullproof prove: ${av.reason}`);
+        return 2;
+    }
+    if (o.selfTest)
+        return selfTest(runner, log);
+    if (o.allowInstallScripts)
+        log('hullproof prove: WARNING: --allow-install-scripts is on. Install scripts of every dependency run inside the build container, which can reach the package registry. They run with no secrets and no host mounts, but they are third party code. Use it only for an app you trust.');
+    const result = await runProve({ repo, proveDir: dir, commit, stack, map, runner, limits: DEFAULT_LIMITS, allowInstallScripts: o.allowInstallScripts, log });
+    for (const l of summaryLines(result))
+        log(l);
+    log(`hullproof prove: wrote ${join(dir, 'result.json')}`);
+    return result.left_behind > 0 || result.counts.error > 0 ? 1 : 0;
+}
+async function selfTest(runner, log) {
+    const app = selfTestApp();
+    try {
+        const p = await runner.prepare({ recipe: app.recipe, copyDir: app.dir, sourceDir: app.dir, limits: DEFAULT_LIMITS });
+        if (!p.ok) {
+            log(`hullproof prove: self test could not prepare the sandbox: ${p.reason}`);
+            return 1;
+        }
+        const s = await p.prepared.start();
+        if (!s.ok) {
+            log(`hullproof prove: self test could not start the sandbox: ${s.reason}`);
+            await p.prepared.dispose();
+            return 1;
+        }
+        const results = await runEscapeProbes(s.instance, app.marker);
+        for (const r of results)
+            log(`hullproof prove: self test: ${r.ok ? 'contained' : 'NOT CONTAINED'}: ${r.name} (${r.detail})`);
+        const left = (await s.instance.stop()).left_behind.length + (await p.prepared.dispose()).left_behind.length;
+        log(`hullproof prove: self test: ${left === 0 ? 'nothing left behind' : `${left} item(s) left behind`}`);
+        return results.every((r) => r.ok) && left === 0 ? 0 : 1;
+    }
+    finally {
+        app.cleanup();
+    }
+}

package/dist/commands/report-gate.js

@@ -0,0 +1,92 @@
+// hullproof report and hullproof gate. Both read the scan folder of the current commit (or --commit) and the kit.
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { readHeadCommit } from '../discover/git.js';
+import { evaluateGate, gateLines, loadKitGate } from '../gate/gate.js';
+import { loadKit, resolveKitDir } from '../report/kit.js';
+import { loadScan } from '../report/load.js';
+import { renderReport } from '../report/report.js';
+import { mergeHunt } from '../confirm/merge.js';
+import { KIT_LOCAL, outDirFor } from './scan.js';
+// The kit folder for report and gate: --kit, then HULLPROOF_KIT, then the kit the scan recorded in kit.local.json when
+// that folder still holds a controls file, then the usual search (the repository, then the development kit).
+export function kitForRead(repo, scanDir, flag) {
+    if (flag || process.env.HULLPROOF_KIT)
+        return resolveKitDir(repo, flag);
+    const p = join(scanDir, KIT_LOCAL);
+    if (existsSync(p)) {
+        try {
+            const rec = JSON.parse(readFileSync(p, 'utf8'));
+            if (rec.kit_dir && existsSync(join(rec.kit_dir, 'docs/hullproof/security-controls.json')))
+                return rec.kit_dir;
+        }
+        catch { /* an unreadable record falls through to the usual search */ }
+    }
+    return resolveKitDir(repo, null);
+}
+const today = () => new Date().toISOString().slice(0, 10);
+export async function prepare(o) {
+    const repo = resolve(o.repo);
+    const commit = o.commit ?? readHeadCommit(repo);
+    if (!commit)
+        return `no commit found in ${repo}; pass --commit`;
+    const dir = outDirFor(repo, o.out, commit);
+    let s;
+    try {
+        s = loadScan(dir);
+    }
+    catch (e) {
+        return e.message;
+    }
+    const kitDir = kitForRead(repo, dir, o.kit);
+    if (!kitDir)
+        return 'no kit found. Pass --kit or set HULLPROOF_KIT.';
+    const kit = loadKit(kitDir);
+    if (kit.controlsSha256 !== s.info.kit.controls_sha256)
+        return 'the kit controls file differs from the one the scan used. Run hullproof scan again.';
+    let owner = null;
+    if (o.owner) {
+        try {
+            owner = JSON.parse(readFileSync(resolve(o.owner), 'utf8'));
+        }
+        catch (e) {
+            return `cannot read the owner file: ${e.message}`;
+        }
+    }
+    if (o.date && !/^\d{4}-\d{2}-\d{2}$/.test(o.date))
+        return '--date needs YYYY-MM-DD';
+    // Confirmed hunt findings and findings proven by a test, and only those, join the rows and the findings record. Leads, unproven specs
+    // and runs that were not provable here are never read here.
+    const merged = s.hunt.result || s.prove?.result ? mergeHunt(s, kit, s.hunt.result, s.prove?.result ?? null) : null;
+    if (merged)
+        s = { ...s, results: merged.results, findings: merged.findings, findingsText: merged.findingsText };
+    const gate = evaluateGate({
+        kitGate: await loadKitGate(kitDir), controls: kit.controls, scope: { edition: s.info.edition, stage: s.info.stage, stageSource: s.info.stage_source },
+        rows: s.results, findingsText: s.findingsText, metas: s.metas, owner, repo, commit, today: o.date ?? today(),
+    });
+    return { s, kit, gate, repo, merged };
+}
+export async function report(o) {
+    const log = o.log ?? ((x) => process.stderr.write(x + '\n'));
+    const r = await prepare(o);
+    if (typeof r === 'string') {
+        log(`hullproof report: ${r}`);
+        return 2;
+    }
+    const path = join(r.s.dir, 'report.md');
+    writeFileSync(path, renderReport(r.s, r.kit, r.gate, r.merged));
+    log(`hullproof report: wrote ${path}`);
+    return 0;
+}
+export async function gate(o) {
+    const log = o.log ?? ((x) => process.stderr.write(x + '\n'));
+    const r = await prepare(o);
+    if (typeof r === 'string') {
+        log(`hullproof gate: ${r}`);
+        return 2;
+    }
+    for (const l of r.gate.problems)
+        log(`hullproof gate: ${l}`);
+    process.stdout.write(gateLines(r.gate).join('\n') + '\n');
+    return r.gate.exit;
+}