hullproof 0.0.0-stage → 0.5.0

package/dist/packs/manifest.js

@@ -0,0 +1,36 @@
+// The stack pack manifest (packs/<id>/pack.json) and the fixture result (packs/<id>/fixture-result.json): their types, the
+// depth levels, and the one function that says which level a recorded result supports. Format: docs/PACK-GUIDE.md.
+export const LEVELS = ['L0', 'L1', 'L2', 'L3', 'L4'];
+export const rank = (l) => LEVELS.indexOf(l);
+export const isLevel = (x) => typeof x === 'string' && LEVELS.includes(x);
+export const LEVEL_NAMES = { L0: 'Generic', L1: 'Detected', L2: 'Mapped', L3: 'Checked', L4: 'Provable' };
+// Thresholds a recorded result must reach. Written once, here, and quoted in the guide.
+export const L3_MIN_RECALL = 0.5; // share of planted flaws the pack's rules and checks must find, on a blind answer key
+export const REAL_APP_MIN_RECALL = 0.9; // share of a sample of real route registrations the map must hold, on every real app measured for the pack
+export const MIN_RUNS = 3; // identical runs needed to call the output stable
+const stable = (m) => m.stability.runs >= MIN_RUNS && m.stability.identical;
+const exact = (m) => !!m.mapped && m.mapped.expected >= 1 && m.mapped.matched === m.mapped.expected && m.mapped.extra === 0 && stable(m);
+// A real application is the hardest test of the extractor. A pack that fell short on one cannot claim L2, whatever the synthetic fixtures say.
+const realAppShort = (m) => m.kind === 'third_party' && !!m.mapped && (m.mapped.expected < 1 || m.mapped.matched / m.mapped.expected < REAL_APP_MIN_RECALL || !stable(m));
+const recallOk = (m) => !!m.flaws && m.blind_key && m.flaws.planted >= 1 && m.flaws.found / m.flaws.planted >= L3_MIN_RECALL && m.flaws.false_findings === 0 && stable(m);
+// The highest level the result supports for a scope (null: the whole pack). Levels build on each other, so a gap stops the climb.
+export function supportedLevel(r, scope = null) {
+    const found = new Set(r.detect.found);
+    if (!r.detect.expected.length || !r.detect.expected.every((x) => found.has(x)))
+        return 'L0';
+    if (!r.measurements.some(exact) || r.measurements.some(realAppShort))
+        return 'L1';
+    if (!r.measurements.some(recallOk))
+        return 'L2';
+    if (scope === null)
+        return 'L3';
+    const pr = r.proof.find((p) => p.scope === scope);
+    return pr && pr.planted >= 1 && pr.proven === pr.planted && pr.false_proofs_fixed === 0 && pr.runs >= MIN_RUNS && pr.identical ? 'L4' : 'L3';
+}
+// The measurements the coverage table shows: what the map holds comes from the best exact measurement, the flaws from the best flaw
+// measurement (one with a blind key and a pass first). They can be two different fixtures; the table says so.
+export const mappedFrom = (r) => r.measurements.find((m) => exact(m) && m.blind_key && m.mapped && m.kind !== 'third_party') ?? r.measurements.find((m) => exact(m) && m.kind !== 'third_party') ?? r.measurements.find((m) => exact(m)) ?? r.measurements.find((m) => m.mapped) ?? null;
+export const flawsFrom = (r) => r.measurements.find(recallOk) ?? r.measurements.find((m) => m.flaws) ?? null;
+// The level a manifest claims for the whole pack and for each scope, as [scope or null, level] pairs.
+export const claims = (m) => [[null, m.level], ...(m.scopes ?? []).map((s) => [s.where, s.level])];
+export const topLevel = (m) => claims(m).map((c) => c[1]).reduce((a, b) => (rank(b) > rank(a) ? b : a));

package/dist/packs/validate.js

@@ -0,0 +1,271 @@
+// hullproof pack validate: reads packs/<id>/pack.json and fixture-result.json and rejects a pack that is missing a part, lists a rule
+// without a test, has no fixture result, uses a bad level, or claims a level its recorded fixture result does not support.
+// Reads files only. Runs no scanner, no model and no network.
+import { existsSync, readFileSync, readdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { loadChecks } from '../checks/run.js';
+import { PRO_MAP_CHECKS } from '../checks/pro-map.js';
+import { DETECTORS_DIR } from '../discover/detectors.js';
+import { cmp } from '../util.js';
+import { claims, isLevel, LEVELS, rank, supportedLevel, topLevel } from './manifest.js';
+export const ENGINE_ROOT = fileURLToPath(new URL('../../', import.meta.url));
+export const PACKS_DIR = join(ENGINE_ROOT, 'packs');
+// What a part must have at each level. L0 needs nothing but the manifest and a fixture result; every pack needs the fixture result.
+const NEEDS = { detectors: 'L1', extractors: 'L2', auth_patterns: 'L2', checks: 'L3', mapping: 'L3', start_recipe: 'L4' };
+export function defaultEnv(root = ENGINE_ROOT) {
+    const detectorIds = new Set();
+    for (const n of readdirSync(DETECTORS_DIR).filter((f) => f.endsWith('.json'))) {
+        for (const e of JSON.parse(readFileSync(join(DETECTORS_DIR, n), 'utf8')).entries)
+            detectorIds.add(e.id);
+    }
+    return { root, detectorIds, checkIds: new Set(loadChecks().map((c) => c.id)), recipes: RECIPES, hasPro: PRO_MAP_CHECKS.length > 0 };
+}
+// Start recipes the proof sandbox builds (src/prove/recipe.ts). A pack at L4 names one of these.
+export const RECIPES = new Set(['node-express', 'python-flask']);
+const SEC_ID = /^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/;
+const DATE = /^\d{4}-\d{2}-\d{2}$/;
+export function readJson(file) {
+    try {
+        return JSON.parse(readFileSync(file, 'utf8'));
+    }
+    catch (e) {
+        return e.message;
+    }
+}
+// The Semgrep rule ids in a rule file, read without YAML parsing: lines of the form "  - id: name".
+export const ruleIds = (text) => [...text.matchAll(/^\s*-\s+id:\s*([A-Za-z0-9._-]+)\s*$/gm)].map((m) => m[1]);
+export function validatePack(folder, env) {
+    const id = folder.split('/').filter(Boolean).pop() ?? folder;
+    const issues = [];
+    const skipped = [];
+    const bad = (code, message) => { issues.push({ pack: id, code, message }); };
+    const out = (manifest, result) => ({ dir: folder, manifest, result, issues: issues.sort((a, b) => cmp(a.code, b.code) || cmp(a.message, b.message)), skipped });
+    const mf = join(folder, 'pack.json');
+    if (!existsSync(mf)) {
+        bad('manifest_missing', 'there is no pack.json');
+        return out(null, null);
+    }
+    const raw = readJson(mf);
+    if (typeof raw === 'string') {
+        bad('manifest_unreadable', `pack.json is not valid JSON: ${raw}`);
+        return out(null, null);
+    }
+    const m = raw;
+    // ---- identity and levels
+    if (m.schema !== 1)
+        bad('schema', 'schema must be 1');
+    if (typeof m.id !== 'string' || !SEC_ID.test(m.id))
+        bad('id', 'id must be lower case words joined with hyphens');
+    else if (m.id !== id)
+        bad('id', `id "${m.id}" does not match the folder name "${id}"`);
+    for (const k of ['name', 'summary'])
+        if (typeof m[k] !== 'string' || !m[k].trim())
+            bad('field', `${k} is missing`);
+    if (m.edition !== 'free' && m.edition !== 'pro')
+        bad('field', 'edition must be free or pro');
+    for (const k of ['languages', 'frameworks'])
+        if (!Array.isArray(m[k]) || m[k].length === 0 || m[k].some((x) => typeof x !== 'string'))
+            bad('field', `${k} must list at least one stack id`);
+    if (!isLevel(m.level))
+        bad('level', `level "${String(m.level)}" is not one of ${LEVELS.join(', ')}`);
+    for (const s of m.scopes ?? []) {
+        if (typeof s.where !== 'string' || !s.where.trim())
+            bad('level', 'a scope has no "where"');
+        else if (!isLevel(s.level))
+            bad('level', `scope "${s.where}" has level "${String(s.level)}", which is not one of ${LEVELS.join(', ')}`);
+        else if (isLevel(m.level) && rank(s.level) <= rank(m.level))
+            bad('level', `scope "${s.where}" is L${rank(s.level)}, which is not higher than the pack level; a scope exists only to reach a higher level`);
+    }
+    if (m.limits !== undefined && (!Array.isArray(m.limits) || m.limits.some((x) => typeof x !== 'string' || !x.trim())))
+        bad('field', 'limits must be a list of sentences');
+    const levelsOk = isLevel(m.level) && (m.scopes ?? []).every((s) => isLevel(s.level));
+    const parts = m.parts ?? {};
+    if (!m.parts || typeof m.parts !== 'object')
+        bad('parts_missing', 'parts is missing');
+    // ---- every part the declared level needs must be there
+    if (levelsOk) {
+        const top = topLevel(m);
+        for (const [part, at] of Object.entries(NEEDS)) {
+            const have = parts[part];
+            const present = Array.isArray(have) ? have.length > 0 : have !== undefined && have !== null;
+            if (rank(top) >= rank(at) && !present)
+                bad('part_missing', `the pack declares ${top}, which needs "${part}" (from ${at}), and the manifest has none`);
+        }
+    }
+    // ---- files named by a part must exist (a Pro part is skipped when the Pro folders are not in this tree)
+    const here = (rel) => existsSync(join(env.root, rel));
+    const fileRef = (part, r) => {
+        if (!r || typeof r.file !== 'string') {
+            bad('file', `${part}: an entry has no file`);
+            return;
+        }
+        if (here(r.file))
+            return;
+        if (r.pro && !env.hasPro) {
+            skipped.push(`${part}: ${r.file} (Pro, not in this edition)`);
+            return;
+        }
+        bad('file_missing', `${part}: ${r.file} does not exist`);
+    };
+    for (const part of ['extractors', 'auth_patterns', 'sources_sinks', 'mapping'])
+        for (const r of parts[part] ?? [])
+            fileRef(part, r);
+    for (const d of parts.detectors ?? [])
+        if (!env.detectorIds.has(d))
+            bad('detector_unknown', `detectors: "${d}" is not an id in detectors/*.json`);
+    for (const f of m.frameworks ?? [])
+        if (!env.detectorIds.has(f))
+            bad('detector_unknown', `frameworks: "${f}" is not an id in detectors/*.json`);
+    // ---- rules need tests: every rule id in the file has a "ruleid" line and an "ok" line in the test files
+    for (const r of parts.rules ?? []) {
+        if (!r || typeof r.file !== 'string') {
+            bad('file', 'rules: an entry has no file');
+            continue;
+        }
+        if (!here(r.file)) {
+            if (r.pro && !env.hasPro)
+                skipped.push(`rules: ${r.file} (Pro, not in this edition)`);
+            else
+                bad('file_missing', `rules: ${r.file} does not exist`);
+            continue;
+        }
+        if (!Array.isArray(r.tests) || r.tests.length === 0) {
+            bad('rule_without_test', `rules: ${r.file} has no test files`);
+            continue;
+        }
+        // An npm install carries the rules but not the test folder, so the rule tests cannot be read there.
+        if (!existsSync(join(env.root, 'test/fixtures'))) {
+            skipped.push(`rules: tests for ${r.file} (no fixture folder in this tree)`);
+            continue;
+        }
+        const missing = r.tests.filter((t) => !here(t));
+        for (const t of missing)
+            bad('file_missing', `rules: test file ${t} for ${r.file} does not exist`);
+        if (missing.length)
+            continue;
+        const testText = r.tests.map((t) => readFileSync(join(env.root, t), 'utf8')).join('\n');
+        for (const rid of ruleIds(readFileSync(join(env.root, r.file), 'utf8'))) {
+            if (!new RegExp(`ruleid: ${rid}\\b`).test(testText))
+                bad('rule_without_test', `rules: ${rid} in ${r.file} has no "ruleid: ${rid}" line in its test files`);
+            if (!new RegExp(`ok: ${rid}\\b`).test(testText))
+                bad('rule_without_test', `rules: ${rid} in ${r.file} has no "ok: ${rid}" line in its test files`);
+        }
+    }
+    // ---- checks must exist in this engine (a Pro check is skipped when the Pro folders are absent)
+    for (const c of parts.checks ?? []) {
+        if (!c || typeof c.id !== 'string') {
+            bad('check_unknown', 'checks: an entry has no id');
+            continue;
+        }
+        if (env.checkIds.has(c.id))
+            continue;
+        if (c.pro && !env.hasPro)
+            skipped.push(`checks: ${c.id} (Pro, not in this edition)`);
+        else
+            bad('check_unknown', `checks: ${c.id} is not a check this engine loads`);
+    }
+    // ---- start recipe
+    const rc = parts.start_recipe;
+    if (rc) {
+        if (!env.recipes.has(rc.recipe))
+            bad('recipe_unknown', `start_recipe: "${rc.recipe}" is not a recipe the proof sandbox builds (${[...env.recipes].sort(cmp).join(', ')})`);
+        fileRef('start_recipe', rc);
+    }
+    // ---- fixture and its recorded result
+    const fx = m.fixture;
+    let result = null;
+    if (!fx || typeof fx !== 'object')
+        bad('fixture_missing', 'fixture is missing');
+    else {
+        for (const k of ['dir', 'fixed_dir', 'result'])
+            if (typeof fx[k] !== 'string' || !fx[k])
+                bad('fixture_missing', `fixture.${k} is missing`);
+        if (!Array.isArray(fx.answer_keys) || fx.answer_keys.length === 0 || fx.answer_keys.some((k) => !['in_repo', 'outside_repo', 'independent'].includes(k)))
+            bad('fixture_missing', 'fixture.answer_keys must list in_repo, outside_repo or independent');
+        // Fixtures marked internal are in neither edition. Their folders are checked only in a tree that has the internal fixture area.
+        const internalArea = here('test/fixtures/packs');
+        for (const k of ['dir', 'fixed_dir'])
+            if (typeof fx[k] === 'string' && fx[k] && !here(fx[k])) {
+                if (fx.internal && !internalArea)
+                    skipped.push(`fixture.${k}: ${fx[k]} (internal fixture, not in this edition)`);
+                else if (fx.internal !== true && !existsSync(join(env.root, 'test/fixtures')))
+                    skipped.push(`fixture.${k}: ${fx[k]} (no fixture folder in this tree)`);
+                else
+                    bad('fixture_missing', `fixture.${k}: ${fx[k]} does not exist`);
+            }
+        const rf = typeof fx.result === 'string' ? join(env.root, fx.result) : '';
+        if (!rf || !existsSync(rf))
+            bad('fixture_result_missing', `there is no fixture result (${fx.result ?? 'no path'}); a pack with no recorded result on its fixture is not listed`);
+        else {
+            const r = readJson(rf);
+            if (typeof r === 'string')
+                bad('fixture_result_invalid', `${fx.result} is not valid JSON: ${r}`);
+            else {
+                const why = checkResult(r, m.id);
+                if (why.length)
+                    for (const w of why)
+                        bad('fixture_result_invalid', `${fx.result}: ${w}`);
+                else
+                    result = r;
+            }
+        }
+    }
+    // ---- the declared levels against what the result supports
+    if (levelsOk && result) {
+        for (const [scope, lv] of claims(m)) {
+            const sup = supportedLevel(result, scope);
+            if (rank(lv) > rank(sup))
+                bad('level_too_high', `${scope ? `scope "${scope}"` : 'the pack'} declares ${lv}, and the recorded fixture result supports ${sup}`);
+        }
+    }
+    return out(m, result);
+}
+function checkResult(r, id) {
+    const w = [];
+    if (r.schema !== 1)
+        w.push('schema must be 1');
+    if (r.pack !== id)
+        w.push(`pack is "${String(r.pack)}", not "${id}"`);
+    if (typeof r.measured !== 'string' || !DATE.test(r.measured))
+        w.push('measured must be a date, YYYY-MM-DD');
+    if (!r.detect || !Array.isArray(r.detect.expected) || !Array.isArray(r.detect.found))
+        w.push('detect.expected and detect.found are required');
+    if (!Array.isArray(r.measurements) || r.measurements.length === 0)
+        w.push('measurements is empty; a pack with no measurement on a fixture is not listed');
+    const nums = (o, keys, name) => { if (o && keys.some((k) => !Number.isInteger(o[k]) || o[k] < 0))
+        w.push(`${name} needs whole numbers for ${keys.join(', ')}`); };
+    for (const m of Array.isArray(r.measurements) ? r.measurements : []) {
+        const n = `measurement "${String(m?.name)}"`;
+        if (!m || typeof m.name !== 'string' || !['synthetic', 'demo', 'third_party'].includes(m.kind) || typeof m.blind_key !== 'boolean') {
+            w.push(`${n} needs name, kind and blind_key`);
+            continue;
+        }
+        if (typeof m.source !== 'string' || !m.source.trim())
+            w.push(`${n}: source says nothing about how the numbers were made`);
+        nums(m.mapped, ['expected', 'matched', 'extra'], `${n} mapped`);
+        if (m.mapped && (typeof m.mapped.what !== 'string' || !m.mapped.what))
+            w.push(`${n}: mapped.what is missing`);
+        nums(m.flaws, ['planted', 'found', 'false_findings'], `${n} flaws`);
+        if (!m.stability || !Number.isInteger(m.stability.runs) || typeof m.stability.identical !== 'boolean')
+            w.push(`${n}: stability.runs and stability.identical are required`);
+        if (m.mapped && m.mapped.matched > m.mapped.expected)
+            w.push(`${n}: matched is more than expected`);
+        if (m.flaws && m.flaws.found > m.flaws.planted)
+            w.push(`${n}: flaws.found is more than planted`);
+    }
+    if (!Array.isArray(r.proof))
+        w.push('proof must be a list (empty when no proof was run)');
+    else
+        for (const p of r.proof)
+            nums(p, ['planted', 'proven', 'runs', 'false_proofs_fixed'], 'proof');
+    return w;
+}
+export function listPacks(dir = PACKS_DIR) {
+    if (!existsSync(dir))
+        return [];
+    return readdirSync(dir, { withFileTypes: true }).filter((d) => d.isDirectory()).map((d) => join(dir, d.name)).sort(cmp);
+}
+export function validateAll(dir = PACKS_DIR, env = defaultEnv()) {
+    return listPacks(dir).map((p) => validatePack(p, env));
+}

package/dist/prove/container.js

@@ -0,0 +1,276 @@
+// The container backend. It speaks the docker command line, so Colima, Docker Desktop and Podman work through the same commands.
+// Safety rules 4 and 6 of the design are built into runArgs() and checked again by assertSafeRunArgs() before any container starts:
+// non root, read only root filesystem, no host mounts (the copy goes in at build time, nothing is mounted), no capabilities, no
+// privilege escalation, memory, cpu, process and time limits, and no network while tests run. The build phase may reach the package
+// registry (lockfile install, no install scripts). A Postgres store runs on an internal network that has no route out.
+import { spawn } from 'node:child_process';
+import { copyFileSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { randomBytes } from 'node:crypto';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { assertSandboxTarget } from './safety.js';
+const MAX_OUT = 4 * 1024 * 1024;
+export class CliRuntime {
+    bin;
+    constructor(bin = 'docker') { this.bin = bin; }
+    run(args, o = {}) {
+        return new Promise((resolve) => {
+            let out = '';
+            let err = '';
+            let timedOut = false;
+            let done = false;
+            const fin = (e) => { if (!done) {
+                done = true;
+                resolve(e);
+            } };
+            let child;
+            try {
+                child = spawn(this.bin, args, { stdio: ['pipe', 'pipe', 'pipe'] });
+            }
+            catch (e) {
+                return fin({ code: null, stdout: '', stderr: e.message, timedOut: false });
+            }
+            const timer = o.timeoutMs ? setTimeout(() => { timedOut = true; child.kill('SIGKILL'); }, o.timeoutMs) : null;
+            child.stdout.on('data', (d) => { if (out.length < MAX_OUT)
+                out += d.toString('utf8'); });
+            child.stderr.on('data', (d) => { if (err.length < MAX_OUT)
+                err += d.toString('utf8'); });
+            child.on('error', (e) => { if (timer)
+                clearTimeout(timer); fin({ code: null, stdout: out, stderr: e.code === 'ENOENT' ? `${this.bin}: command not found` : e.message, timedOut }); });
+            child.on('close', (code) => { if (timer)
+                clearTimeout(timer); fin({ code, stdout: out, stderr: err, timedOut }); });
+            child.stdin.on('error', () => undefined);
+            child.stdin.end(o.input ?? '');
+        });
+    }
+}
+export const LABEL = 'hullproof.prove';
+export const APP_USER = '10001:10001';
+export const EXEC_DIR = '/app/.hullproof-exec';
+const EXEC_FILES = ['spec.ts', 'executor.ts', 'exec-main.ts'];
+// The step executor runs inside the container as TypeScript, so its sources are always read from src/prove (shipped with the package),
+// also when the engine itself runs from dist/.
+const HERE = fileURLToPath(new URL('../../src/prove/', import.meta.url));
+const PG_IMAGE = 'postgres:16-alpine';
+const PG_USER = '70:70';
+const clip = (s, n = 600) => { const t = s.trim().replace(/\s+/g, ' '); return t.length <= n ? t : '…' + t.slice(t.length - n); };
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+// ---- commands, as pure functions so they can be tested without a runtime --------------------------------------------------------
+// A Python app runs in a Python image that also holds the node binary, because the step executor and the health probe are Node scripts
+// that run inside the sandbox. The binary is copied from the same image the Node recipe uses, at build time, so nothing else is fetched.
+export const NODE_IMAGE = 'node:22-slim';
+export function dockerfile(r) {
+    const py = r.stack === 'python-flask';
+    return [
+        ...(py ? [`FROM ${NODE_IMAGE} AS node`] : []),
+        `FROM ${r.base_image}`,
+        ...(py ? ['COPY --from=node /usr/local/bin/node /usr/local/bin/node', 'ENV PYTHONDONTWRITEBYTECODE=1 PYTHONUNBUFFERED=1 PIP_DISABLE_PIP_VERSION_CHECK=1 PIP_NO_CACHE_DIR=1 HOME=/tmp'] : []),
+        'WORKDIR /app', 'COPY . /app', ...(r.install ? [`RUN ${r.install.join(' ')}`] : []), `USER ${APP_USER}`, '',
+    ].join('\n');
+}
+export const buildArgs = (tag, runId, ctx) => ['build', '--label', `${LABEL}=${runId}`, '--tag', tag, '--file', join(ctx, 'Dockerfile.hullproof'), ctx];
+export function runArgs(a) {
+    const args = [
+        'run', '--detach', '--init', '--name', a.name, '--label', `${LABEL}=${a.runId}`,
+        '--network', a.network, '--read-only', '--user', a.user, '--cap-drop', 'ALL', '--security-opt', 'no-new-privileges',
+        '--pids-limit', String(a.limits.pids), '--memory', a.limits.memory, '--memory-swap', a.limits.memory, '--cpus', a.limits.cpus,
+        '--ulimit', 'nofile=1024:1024', '--ulimit', 'core=0',
+        ...a.tmpfs.flatMap((t) => ['--tmpfs', t]),
+        ...Object.entries(a.env).flatMap(([k, v]) => ['--env', `${k}=${v}`]),
+        a.image, ...a.cmd,
+    ];
+    assertSafeRunArgs(args.slice(0, args.length - 1 - a.cmd.length), a.network);
+    return args;
+}
+const FORBIDDEN = new Set(['--privileged', '-v', '--volume', '--volumes-from', '--mount', '-p', '--publish', '-P', '--publish-all', '--device', '--cap-add', '--pid', '--ipc', '--uts', '--userns', '--add-host', '--env-file', '--cgroupns', '--group-add', '--sysctl']);
+// Refuses anything that would weaken the sandbox. `head` is the argument list up to, and not including, the image name. The builder
+// calls this on its own output; tests call it on bad input.
+export function assertSafeRunArgs(head, allowedNetwork) {
+    const bad = [];
+    const val = (flag) => { const i = head.indexOf(flag); return i >= 0 ? head[i + 1] : undefined; };
+    for (const a of head)
+        if (FORBIDDEN.has(a) || /^--(?:privileged|volume|mount|publish|device|cap-add|pid|ipc|uts|userns|add-host|env-file)=/.test(a))
+            bad.push(a);
+    if (head.some((a) => /unconfined/.test(a)))
+        bad.push('unconfined security option');
+    if (!head.includes('--read-only'))
+        bad.push('missing --read-only');
+    if (val('--cap-drop') !== 'ALL')
+        bad.push('capabilities are not all dropped');
+    if (!head.some((a, i) => a === '--security-opt' && head[i + 1] === 'no-new-privileges'))
+        bad.push('missing no-new-privileges');
+    for (const f of ['--pids-limit', '--memory', '--cpus'])
+        if (!val(f))
+            bad.push(`missing ${f}`);
+    const user = val('--user');
+    if (!user || /^(?:0|root)(?::|$)/.test(user))
+        bad.push('the container would run as root');
+    const net = val('--network');
+    if (net !== 'none' && net !== allowedNetwork)
+        bad.push(`network ${net ?? 'default'} is not none or the internal network`);
+    if (net !== 'none' && !/^hp-prove-net-/.test(net ?? ''))
+        bad.push('a network other than none must be a hullproof internal network');
+    if (bad.length)
+        throw new Error(`unsafe container arguments refused: ${bad.join(', ')}`);
+}
+const healthScript = (port, path) => `fetch('http://127.0.0.1:${port}${path}',{signal:AbortSignal.timeout(2000)}).then(r=>process.exit(r.status<500?0:2),()=>process.exit(1))`;
+export class ContainerRunner {
+    name = 'container';
+    rt;
+    o;
+    constructor(rt, o = {}) { this.rt = rt; this.o = o; }
+    async available() {
+        const r = await this.rt.run(['info'], { timeoutMs: 20_000 });
+        if (r.code === 0)
+            return { ok: true };
+        const missing = /not found|ENOENT/.test(r.stderr);
+        return { ok: false, reason: missing ? `no container runtime: ${this.rt.bin} was not found. Install one, for example: brew install colima docker, then colima start.` : `the container runtime is not running (${clip(r.stderr, 160) || 'no answer'}). For Colima run: colima start.` };
+    }
+    async prepare(req) {
+        const runId = randomBytes(5).toString('hex');
+        const image = `hullproof-prove-${runId}`;
+        mkdirSync(join(req.copyDir, '.hullproof-exec'), { recursive: true });
+        for (const f of EXEC_FILES)
+            copyFileSync(join(HERE, f), join(req.copyDir, '.hullproof-exec', f));
+        writeFileSync(join(req.copyDir, 'Dockerfile.hullproof'), dockerfile(req.recipe));
+        const b = await this.rt.run(buildArgs(image, runId, req.copyDir), { timeoutMs: 600_000 });
+        if (b.code !== 0) {
+            await this.rt.run(['rmi', '-f', image]);
+            return { ok: false, code: 'build_failed', reason: `the image did not build${b.timedOut ? ' in time' : ''}: ${clip(b.stderr || b.stdout)}` };
+        }
+        return { ok: true, prepared: new ContainerPrepared(this.rt, runId, image, req, this.o.sleepMs ?? 500) };
+    }
+}
+class ContainerPrepared {
+    n = 0;
+    live = new Set();
+    rt;
+    runId;
+    image;
+    req;
+    pause;
+    constructor(rt, runId, image, req, pause) { this.rt = rt; this.runId = runId; this.image = image; this.req = req; this.pause = pause; }
+    async start() {
+        const { recipe, limits } = this.req;
+        const id = `${this.runId}-${++this.n}`;
+        const name = `hp-prove-${id}`;
+        const inst = new ContainerInstance(this.rt, name, recipe, limits);
+        this.live.add(inst);
+        const fail = async (code, reason) => { const logs = await this.rt.run(['logs', '--tail', '15', name]); await inst.stop(); this.live.delete(inst); return { ok: false, code, reason: `${reason}${logs.stdout + logs.stderr ? `. Last output: ${clip(logs.stdout + ' ' + logs.stderr, 400)}` : ''}` }; };
+        const data = (s) => s.replace(/\{DATA\}/g, '/data');
+        let network = 'none';
+        const env = {};
+        const tmpfs = ['/tmp:rw,noexec,nosuid,nodev,size=64m'];
+        if (recipe.data_store.kind === 'sqlite')
+            tmpfs.push(`/data:rw,noexec,nosuid,nodev,size=64m,uid=10001,gid=10001`);
+        if (recipe.data_store.kind === 'postgres') {
+            network = `hp-prove-net-${id}`;
+            const pg = `hp-prove-pg-${id}`;
+            const net = await this.rt.run(['network', 'create', '--internal', '--label', `${LABEL}=${this.runId}`, network]);
+            if (net.code !== 0) {
+                this.live.delete(inst);
+                return { ok: false, code: 'start_failed', reason: `the internal network could not be created: ${clip(net.stderr)}` };
+            }
+            inst.network = network;
+            inst.extra.push(pg);
+            const pgRun = await this.rt.run(runArgs({ name: pg, runId: this.runId, image: PG_IMAGE, network, user: PG_USER, tmpfs: ['/var/lib/postgresql/data:rw,nosuid,nodev,size=128m,uid=70,gid=70', '/var/run/postgresql:rw,nosuid,nodev,size=8m,uid=70,gid=70', '/tmp:rw,nosuid,nodev,size=32m'], env: { POSTGRES_PASSWORD: 'dummy', POSTGRES_DB: 'app' }, limits, cmd: [] }));
+            if (pgRun.code !== 0)
+                return fail('start_failed', `Postgres did not start: ${clip(pgRun.stderr)}`);
+            let up = false;
+            for (let t = Date.now(); Date.now() - t < limits.healthMs && !up; await this.sleep())
+                up = (await this.rt.run(['exec', pg, 'pg_isready', '-h', '127.0.0.1', '-U', 'postgres', '-d', 'app'], { timeoutMs: 5000 })).code === 0;
+            if (!up)
+                return fail('health_failed', 'Postgres did not become ready in time');
+            for (const f of [...recipe.data_store.migrations, ...(recipe.data_store.seed_sql ? [recipe.data_store.seed_sql] : [])]) {
+                const sql = readFileSync(join(this.req.sourceDir, f), 'utf8');
+                const r = await this.rt.run(['exec', '-i', pg, 'psql', '-v', 'ON_ERROR_STOP=1', '-q', '-U', 'postgres', '-d', 'app'], { input: sql, timeoutMs: 60_000 });
+                if (r.code !== 0)
+                    return fail('start_failed', `${f} did not apply: ${clip(r.stderr, 300)}`);
+            }
+            env.__PGURL = `postgres://postgres:dummy@${pg}:5432/app`;
+        }
+        for (const [k, v] of Object.entries(recipe.env))
+            env[k] = data(v).replace(/\{PGURL\}/g, env.__PGURL ?? '');
+        delete env.__PGURL;
+        const script = `${recipe.seed ? recipe.seed + ' && ' : ''}exec ${recipe.start}`;
+        const run = await this.rt.run(runArgs({ name, runId: this.runId, image: this.image, network, user: APP_USER, tmpfs, env, limits, cmd: ['sh', '-c', script] }));
+        if (run.code !== 0)
+            return fail('start_failed', `the container did not start: ${clip(run.stderr)}`);
+        for (let t = Date.now(); Date.now() - t < limits.healthMs; await this.sleep()) {
+            const h = await this.rt.run(['exec', name, 'node', '-e', healthScript(recipe.port, recipe.health_path)], { timeoutMs: 6000 });
+            if (h.code === 0) {
+                inst.arm();
+                return { ok: true, instance: inst };
+            }
+            const st = await this.rt.run(['inspect', '--format', '{{.State.Running}}', name]);
+            if (st.stdout.trim() === 'false')
+                return fail('start_failed', 'the app stopped before it answered (the seed step or the start command failed)');
+        }
+        return fail('health_failed', `the app did not answer on ${recipe.health_path} within ${Math.round(limits.healthMs / 1000)} seconds`);
+    }
+    sleep() { return sleep(this.pause); }
+    async dispose() {
+        for (const i of this.live)
+            await i.stop();
+        await this.rt.run(['rmi', '-f', this.image]);
+        const left = [];
+        for (const [what, args] of [['container', ['ps', '-a', '-q']], ['image', ['images', '-q']], ['network', ['network', 'ls', '-q']], ['volume', ['volume', 'ls', '-q']]]) {
+            const r = await this.rt.run([...args, '--filter', `label=${LABEL}=${this.runId}`]);
+            for (const l of r.stdout.split('\n').map((x) => x.trim()).filter(Boolean))
+                left.push(`${what} ${l}`);
+        }
+        return { left_behind: left };
+    }
+}
+class ContainerInstance {
+    baseUrl;
+    network = null;
+    extra = [];
+    stopped = false;
+    timer = null;
+    rt;
+    name;
+    recipe;
+    limits;
+    constructor(rt, name, recipe, limits) {
+        this.rt = rt;
+        this.name = name;
+        this.recipe = recipe;
+        this.limits = limits;
+        this.baseUrl = `http://127.0.0.1:${recipe.port}`;
+    }
+    arm() { this.timer = setTimeout(() => { void this.stop(); }, this.limits.instanceMs); this.timer.unref(); }
+    async exec(cmd, o = {}) {
+        if (this.stopped)
+            return { code: null, stdout: '', stderr: 'the instance time limit was reached or it was stopped', timedOut: false };
+        const ms = o.timeoutMs ?? this.limits.execMs;
+        // `timeout -s KILL` inside the container ends the process there. Killing the docker client alone would leave it running.
+        return this.rt.run(['exec', '-i', this.name, 'timeout', '-s', 'KILL', String(Math.max(1, Math.ceil(ms / 1000))), ...cmd], { input: o.input, timeoutMs: ms + 10_000 });
+    }
+    async runSpec(spec) {
+        assertSandboxTarget(this.baseUrl, this.recipe.port);
+        const r = await this.exec(['node', '--experimental-strip-types', `${EXEC_DIR}/exec-main.ts`, this.baseUrl], { input: JSON.stringify(spec) });
+        if (r.timedOut || r.code === 137)
+            return { ok: false, reason: 'the step executor ran past the time limit and was killed' };
+        const line = r.stdout.trim().split('\n').pop() ?? '';
+        try {
+            const j = JSON.parse(line);
+            if (!j.ok)
+                return { ok: false, reason: j.error ?? 'the step executor failed' };
+            return { ok: true, outcome: j.outcome, detail: j.detail ?? '', steps: j.steps ?? [] };
+        }
+        catch {
+            return { ok: false, reason: `the step executor gave no result (${clip(r.stderr, 200) || 'no output'})` };
+        }
+    }
+    async stop() {
+        if (this.timer)
+            clearTimeout(this.timer);
+        this.stopped = true;
+        for (const c of [this.name, ...this.extra])
+            await this.rt.run(['rm', '-f', '--volumes', c]);
+        if (this.network)
+            await this.rt.run(['network', 'rm', this.network]);
+        return { left_behind: [] };
+    }
+}

package/dist/prove/exec-main.js

@@ -0,0 +1,20 @@
+// Runs inside the sandbox: `node --experimental-strip-types /hp/exec-main.ts http://127.0.0.1:PORT` with a spec as JSON on standard
+// input. Prints one JSON line: the outcome, the detail and the redacted step records. Refuses any address but the sandbox's own loopback.
+import { executeSpec } from './executor.js';
+import { validateSpec } from './spec.js';
+const chunks = [];
+for await (const c of process.stdin)
+    chunks.push(c);
+try {
+    const v = validateSpec(JSON.parse(Buffer.concat(chunks).toString('utf8')));
+    if (!v.ok) {
+        process.stdout.write(JSON.stringify({ ok: false, error: `invalid spec: ${v.errors.join('; ')}` }) + '\n');
+        process.exit(0);
+    }
+    const r = await executeSpec(v.spec, { baseUrl: process.argv[2] ?? '' });
+    process.stdout.write(JSON.stringify({ ok: true, ...r }) + '\n');
+}
+catch (e) {
+    process.stdout.write(JSON.stringify({ ok: false, error: e.message.slice(0, 300) }) + '\n');
+}
+process.exit(0);