hullproof 0.0.0-stage → 0.5.0

package/dist/prove/store.js

@@ -0,0 +1,65 @@
+// Where proof files live: <out>/<commit>/prove/. Specs go in, run transcripts and the result come out. Written through a temporary
+// file and a rename, with the engine's one JSON writer, so the same value is the same bytes.
+import { existsSync, mkdirSync, readdirSync, readFileSync, renameSync, rmSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { cmp, stableJson } from '../util.js';
+import { validateSpec } from './spec.js';
+export const proveDir = (scanDir) => join(scanDir, 'prove');
+const write = (p, text) => { mkdirSync(join(p, '..'), { recursive: true }); writeFileSync(`${p}.tmp`, text); renameSync(`${p}.tmp`, p); };
+const readJson = (p) => { try {
+    return JSON.parse(readFileSync(p, 'utf8'));
+}
+catch (e) {
+    throw new Error(`${p} cannot be read: ${e.message}`);
+} };
+export const specFile = (dir, id) => join(dir, 'specs', `${id}.json`);
+export const writeSpec = (dir, s) => write(specFile(dir, s.spec_id), stableJson(s));
+export const runFile = (dir, id, run) => join(dir, 'runs', id, `run-${run}.json`);
+export const writeRun = (dir, r) => write(runFile(dir, r.spec_id, r.run), stableJson(r));
+export const clearRuns = (dir) => rmSync(join(dir, 'runs'), { recursive: true, force: true });
+export const writeMeta = (dir, m) => write(join(dir, 'meta.json'), stableJson(m));
+export const readMeta = (dir) => (existsSync(join(dir, 'meta.json')) ? readJson(join(dir, 'meta.json')) : null);
+export const writeRecipe = (dir, r) => write(join(dir, 'recipe.json'), stableJson(r));
+export const writeProveResult = (dir, r) => write(join(dir, 'result.json'), stableJson(r));
+export const readProveResult = (dir) => (existsSync(join(dir, 'result.json')) ? readJson(join(dir, 'result.json')) : null);
+// Every spec file, validated. A file that fails validation is dropped and counted, with the reason.
+export function loadSpecs(dir) {
+    const specs = [];
+    const dropped = [];
+    const d = join(dir, 'specs');
+    if (!existsSync(d))
+        return { specs, dropped };
+    const seen = new Set();
+    for (const f of readdirSync(d).filter((n) => n.endsWith('.json')).sort(cmp)) {
+        let raw;
+        try {
+            raw = JSON.parse(readFileSync(join(d, f), 'utf8'));
+        }
+        catch {
+            dropped.push({ file: f, reason: 'not valid JSON' });
+            continue;
+        }
+        const v = validateSpec(raw);
+        if (!v.ok) {
+            dropped.push({ file: f, reason: v.errors.slice(0, 3).join('; ') });
+            continue;
+        }
+        if (`${v.spec.spec_id}.json` !== f) {
+            dropped.push({ file: f, reason: `spec_id ${v.spec.spec_id} does not match the file name` });
+            continue;
+        }
+        if (seen.has(v.spec.spec_id)) {
+            dropped.push({ file: f, reason: 'duplicate spec_id' });
+            continue;
+        }
+        seen.add(v.spec.spec_id);
+        specs.push(v.spec);
+    }
+    return { specs, dropped };
+}
+export function readRuns(dir, id) {
+    const d = join(dir, 'runs', id);
+    if (!existsSync(d))
+        return [];
+    return readdirSync(d).filter((n) => /^run-\d+\.json$/.test(n)).sort(cmp).map((n) => readJson(join(d, n))).sort((a, b) => a.run - b.run);
+}

package/dist/report/build.js

@@ -0,0 +1,297 @@
+// Builds results.json (one row per requirement in scope) and the findings record (schema 1.1.0) from the check results
+// and scanner hits. FAIL comes only from a FAIL check or a mapped rule hit; PASS (static) only from a check on a repo
+// authority requirement; every other requirement in scope is NOT ASSESSED with the sub state that closes it.
+import { createHash } from 'node:crypto';
+import { cmp, stableJson, stableJsonCompact } from '../util.js';
+import { ENGINE_VERSION } from '../version.js';
+import { checkMessage, ruleMessage } from './messages.js';
+import { highest, inScope } from './kit.js';
+import { TEST_ARTIFACT_IDS, testCodeReason } from './test-code.js';
+import { isSecretHit, leadReason, leadTier, leadTierForCheck, loadTiers } from './tiers.js';
+const MAX_NOTE = 600;
+// Checks whose FAIL means a control is missing everywhere searched (class missing_control, with the search recorded).
+const ABSENCE_CHECKS = new Set(['check.web.security-headers-configured', 'check.auth.login-rate-limit', 'check.supply.lockfile-committed']);
+// A fingerprint path has no spaces or colons.
+const fpPath = (f) => f.replace(/[\s:]/g, '_');
+const clip = (s, n) => (s.length <= n ? s : s.slice(0, n - 1).trimEnd() + '…');
+const slug = (s, max = 12) => s.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-|-$/g, '').split('-').filter(Boolean).slice(0, max).join('-') || 'x';
+const where = (e) => (e.line ? `${e.file}:${e.line}` : e.file);
+// The sub state for a requirement nothing settled, from its authority and how it is verified.
+export function routeFor(c) {
+    if (c.authority === 'dashboard')
+        return 'NEEDS DASHBOARD';
+    if (c.authority === 'runtime')
+        return 'NEEDS DYNAMIC TEST';
+    return 'UNKNOWN';
+}
+export const OWNER_ACTION = {
+    'NEEDS DASHBOARD': 'Export the provider setting (screenshot or export, dated, naming the project) and record it.',
+    'NEEDS BUILD': 'Run a production build from this commit and scan the output.',
+    'NEEDS DYNAMIC TEST': 'Test the running app or a staging copy and record the requests and responses.',
+    'ASK OWNER': 'Answer the question in writing.',
+    'ATTESTATION': 'Sign and date a statement.',
+    'UNKNOWN': 'No engine check or rule settles this from the files. A code review (a person, or the Hullproof audit) must read the code and record the result.',
+};
+// Splits hits and failed checks into what can fail a requirement and what is only reported. In order:
+// 1. A secret (a Gitleaks hit or a rule mapped to a SEC-SECRETS ID) stays in the gate wherever it is, unless the scanner marked the hit as an
+//    example value (h.noise: src/scanners/secret-noise.ts), which moves to an example value item.
+// 2. In a test path, a requirement about shipped test material (TEST_ARTIFACT_IDS) keeps failing; every other ID moves
+//    to a test code item.
+// 3. A hit of a rule whose tier is lead moves to a lead item.
+export function separateTestCode(input) {
+    const test = [];
+    const hits = [];
+    const tiers = loadTiers(input.rulesDirs ?? []);
+    for (const h of input.hits) {
+        // A secret stays in the gate, unless the scanner found the value to be an example (a placeholder, or a shapeless rule in docs or fixtures).
+        if (isSecretHit(h) && h.noise) {
+            test.push({ hit: h, ids: h.sec_ids, reason: h.noise, kind: 'test' });
+            continue;
+        }
+        const reason = isSecretHit(h) ? null : testCodeReason(h.file);
+        if (reason) {
+            const keep = h.sec_ids.filter((id) => TEST_ARTIFACT_IDS.has(id));
+            if (keep.length)
+                hits.push({ ...h, sec_ids: keep });
+            if (keep.length < h.sec_ids.length || !h.sec_ids.length)
+                test.push({ hit: h, ids: h.sec_ids.filter((id) => !TEST_ARTIFACT_IDS.has(id)), reason, kind: 'test' });
+            continue;
+        }
+        const lead = leadTier(h, tiers);
+        if (lead) {
+            test.push({ hit: h, ids: h.sec_ids, reason: leadReason(lead, tiers), kind: 'lead' });
+            continue;
+        }
+        hits.push(h);
+    }
+    const results = [];
+    for (const r of input.checks.results) {
+        // A check that reads the code map is a lead until it is measured: its FAIL is reported and never fails a requirement.
+        const leadCheck = r.result === 'FAIL' ? leadTierForCheck(r.check_id, tiers) : null;
+        if (leadCheck) {
+            const byFile = new Map();
+            for (const e of r.evidence)
+                byFile.set(e.file, [...(byFile.get(e.file) ?? []), e]);
+            const reason = leadReason(leadCheck, tiers);
+            // Past COLLAPSE_FILES files the check gets one record for all its places (the list stays in checks.json), so a repository
+            // with a thousand routes does not push the findings block past the kit limit.
+            if (byFile.size > COLLAPSE_FILES)
+                test.push({ check: r, ids: r.sec_ids, reason, kind: 'lead', total: r.evidence.length });
+            else
+                for (const f of [...byFile.keys()].sort(cmp))
+                    test.push({ check: { ...r, evidence: byFile.get(f) }, ids: r.sec_ids, reason, kind: 'lead' });
+            continue;
+        }
+        const secret = r.sec_ids.some((id) => id.startsWith('SEC-SECRETS-'));
+        const inTest = r.result === 'FAIL' && !secret && !r.sec_ids.some((id) => TEST_ARTIFACT_IDS.has(id)) ? r.evidence.filter((e) => testCodeReason(e.file)) : [];
+        const shipped = r.evidence.filter((e) => !inTest.includes(e));
+        if (inTest.length)
+            test.push({ check: { ...r, evidence: inTest }, ids: r.sec_ids, reason: testCodeReason(inTest[0].file), kind: 'test' });
+        // A FAIL whose evidence is all in test code no longer fails; one with no evidence (an absence check) still does.
+        if (!inTest.length || shipped.length)
+            results.push(inTest.length ? { ...r, evidence: shipped } : r);
+    }
+    return { input: { ...input, hits, checks: { ...input.checks, results } }, test };
+}
+function failsFor(input) {
+    const out = [];
+    for (const r of input.checks.results)
+        if (r.result === 'FAIL')
+            out.push({ source: r.check_id, sec_ids: r.sec_ids, evidence: r.evidence });
+    for (const h of input.hits)
+        if (h.sec_ids.length)
+            out.push({ source: `${h.tool} rule ${h.rule_id}`, sec_ids: h.sec_ids, evidence: [{ file: h.file, line: h.line || undefined, note: h.rule_id }] });
+    return out;
+}
+export function buildResults(all) {
+    const input = separateTestCode(all).input;
+    const { kit, scope } = input;
+    const fails = failsFor(input);
+    const checkWords = new Map();
+    for (const r of input.checks.results)
+        for (const id of r.sec_ids)
+            checkWords.set(id, [...(checkWords.get(id) ?? []), r]);
+    const skippedBy = new Map();
+    for (const m of input.metas)
+        if (m.status !== 'ran')
+            for (const id of m.not_assessed_sec_ids)
+                skippedBy.set(id, [...(skippedBy.get(id) ?? []), `${m.tool} (${m.status})`]);
+    const rows = [];
+    for (const c of kit.controls.filter((x) => inScope(x, scope)).sort((a, b) => cmp(a.id, b.id))) {
+        const mine = fails.filter((f) => f.sec_ids.includes(c.id));
+        if (mine.length) {
+            const where1 = mine.flatMap((f) => f.evidence.slice(0, 3).map((e) => `${f.source} at ${where(e)}`));
+            rows.push({ id: c.id, result: 'FAIL', notes: clip(`Failed by ${[...new Set(where1)].join('; ')}.`, MAX_NOTE) });
+            continue;
+        }
+        const words = checkWords.get(c.id) ?? [];
+        const pass = words.find((w) => w.result === 'PASS (static)');
+        if (pass && c.authority === 'repo') {
+            rows.push({ id: c.id, result: 'PASS (static)', notes: clip(`Settled by ${pass.check_id} on the files of this commit.`, MAX_NOTE) });
+            continue;
+        }
+        // A check that ran and found nothing wrong names the sub state that would settle the rest.
+        const routed = words.map((w) => w.result).find((w) => w.startsWith('NOT ASSESSED: '));
+        const state = (routed ? routed.slice('NOT ASSESSED: '.length) : routeFor(c));
+        const parts = [routed ? `${words.map((w) => w.check_id).join(', ')} found nothing wrong in the files; that cannot settle it.` : '', OWNER_ACTION[state]];
+        const skipped = skippedBy.get(c.id);
+        if (skipped)
+            parts.push(`Not run: ${skipped.join(', ')}.`);
+        rows.push({ id: c.id, result: `NOT ASSESSED: ${state}`, notes: clip(parts.filter(Boolean).join(' '), MAX_NOTE) });
+    }
+    return rows;
+}
+// Requirement IDs of a fail split into those in scope (they make a fail record) and the rest.
+function split(ids, input) {
+    const known = ids.filter((id) => input.kit.byId.has(id));
+    return {
+        scoped: known.filter((id) => inScope(input.kit.byId.get(id), input.scope)).sort(cmp),
+        known: known.sort(cmp),
+        unknown: ids.filter((id) => !input.kit.byId.has(id)).sort(cmp),
+    };
+}
+const refs = (ev) => ev.slice(0, 8).map((e) => ({ file: e.file, line: e.line && e.line > 0 ? e.line : 1, note: clip(e.note, 300) }));
+// Past the kit's size warning even on one line, a rule that matched more than COLLAPSE_FILES files gets one record for
+// all its files instead of one per file; every hit stays in scan/<tool>.json, and the record says how many files.
+// ponytail: fixed file count per rule; lower it or group per folder if a repository still passes the kit limit.
+const COLLAPSE_FILES = 20;
+export function buildFindings(all) {
+    const first = buildFindingsWith(all, null);
+    return stableJsonCompact(first.file).length <= KIT_WARN_BLOCK_CHARS ? first : buildFindingsWith(all, COLLAPSE_FILES);
+}
+function buildFindingsWith(all, collapse) {
+    const { input, test } = separateTestCode(all);
+    // tool and rule -> files it matched, in shipped code and in test code apart.
+    const filesOf = new Map();
+    const note = (k, f) => { filesOf.set(k, (filesOf.get(k) ?? new Set()).add(f)); };
+    for (const h of input.hits)
+        note(`${h.tool}\u0000${h.rule_id}`, h.file);
+    for (const t of test)
+        if (t.hit)
+            note(`${t.kind}\u0000${t.hit.tool}\u0000${t.hit.rule_id}`, t.hit.file);
+    const many = (k) => (collapse !== null && (filesOf.get(k)?.size ?? 0) > collapse ? filesOf.get(k).size : 0);
+    const records = [];
+    const dropped = [];
+    const add = (o) => {
+        const s = split(o.ids, input);
+        const file0 = fpPath(o.evidence[0]?.file ?? '-');
+        if (s.unknown.length)
+            dropped.push({ source: o.source, ids: s.unknown, where: where(o.evidence[0] ?? { file: '-' }) });
+        if (s.scoped.length === 0) {
+            // Outside this run's edition or stage, or unmapped: shown as an observation, never in the gate.
+            const obs = {
+                fingerprint: `OBS:${file0}:${slug(`${o.ruleId} ${o.line ?? ''}`)}`, kind: 'observation', sec_ids: s.known, title: clip(o.msg.title, 160),
+                where: refs(o.evidence).slice(0, 4),
+                note: clip(s.known.length ? `Outside this run's scope (${input.scope.edition} edition, ${input.scope.stage} stage): ${s.known.join(', ')}. ${o.msg.fix}` : `No requirement is mapped to ${o.source}${s.unknown.length ? ` in this kit (named: ${s.unknown.join(', ')})` : ''}. ${o.msg.fix}`, 400),
+                raised_by: ['hullproof-engine'],
+            };
+            records.push(obs);
+            return;
+        }
+        const sev = highest(s.scoped.map((id) => input.kit.byId.get(id).severity));
+        const rec = {
+            fingerprint: `${s.scoped[0]}:${file0}:${slug(`${o.ruleId} ${o.line ?? ''}`)}`,
+            kind: 'fail', sec_ids: s.scoped, title: clip(o.msg.title, 160),
+            class: o.tool === 'hullproof-check' && ABSENCE_CHECKS.has(o.ruleId) && o.absence ? 'missing_control' : 'finding',
+            gap_in_standard: false, severity: sev, confidence: 'SUSPECTED', demonstrated: false,
+            root_cause: clip(o.msg.root, 120), raised_by: ['hullproof-engine'], impact_statement: clip(o.msg.impact, 600),
+            remediation: { strategy: clip(o.msg.fix, 800), confirm: clip(o.msg.confirm, 400) },
+            evidence: refs(o.evidence),
+            machine_evidence: { tool: o.tool, rule_id: o.ruleId, tool_version: o.toolVersion.replace(/[^A-Za-z0-9._+-]/g, '-') || 'unknown', config_sha256: o.configSha },
+        };
+        if (rec.class === 'missing_control') {
+            rec.absence_search = { command: clip(`${o.ruleId}: ${o.absence.pattern} over ${o.absence.file_globs.join(' ') || 'the selected files'}`, 300), files_searched: o.absence.files_searched, count: o.absence.matches, practice: 'present_unsafe' };
+        }
+        records.push(rec);
+    };
+    for (const r of input.checks.results) {
+        if (r.result !== 'FAIL')
+            continue;
+        add({ source: r.check_id, ruleId: r.check_id, tool: 'hullproof-check', toolVersion: ENGINE_VERSION, configSha: input.checkShas[r.check_id] ?? null,
+            ids: r.sec_ids, evidence: r.evidence, msg: checkMessage(r.check_id), absence: r.absence_search });
+    }
+    // Scanner hits: one record per tool, rule and file, with up to 8 lines.
+    const groups = new Map();
+    for (const h of input.hits) {
+        const k = `${h.tool}\u0000${h.rule_id}\u0000${many(`${h.tool}\u0000${h.rule_id}`) ? '*' : h.file}`;
+        groups.set(k, [...(groups.get(k) ?? []), h]);
+    }
+    for (const k of [...groups.keys()].sort(cmp)) {
+        const hs = groups.get(k);
+        const h = hs[0];
+        const n = many(`${h.tool}\u0000${h.rule_id}`);
+        const meta = input.metas.find((m) => m.tool === h.tool);
+        const label = n ? `${h.tool} rule ${h.rule_id}, which matched ${n} files (all in scan/${h.tool}.json)` : `${h.tool} rule ${h.rule_id}`;
+        add({ source: `${h.tool} rule ${h.rule_id}`, ruleId: h.rule_id, tool: h.tool, toolVersion: meta?.version ?? 'unknown', configSha: meta?.config_sha256 ?? null,
+            ids: [...new Set(hs.flatMap((x) => x.sec_ids))], evidence: hs.map((x) => ({ file: x.file, line: x.line || undefined, note: clip(label, 300) })),
+            msg: ruleMessage(h.tool, h.rule_id, input.rulesDirs), absence: null, line: n ? undefined : h.line });
+    }
+    // Test code and leads: one observation per tool, rule and file, marked by a fingerprint slug that starts with
+    // test-code or lead.
+    const testGroups = new Map();
+    for (const t of test) {
+        const k = t.hit
+            ? `${t.kind}\u0000${t.hit.tool}\u0000${t.hit.rule_id}\u0000${many(`${t.kind}\u0000${t.hit.tool}\u0000${t.hit.rule_id}`) ? '*' : t.hit.file}`
+            : `${t.kind}\u0000hullproof-check\u0000${t.check.check_id}\u0000${t.check.evidence[0].file}`;
+        testGroups.set(k, [...(testGroups.get(k) ?? []), t]);
+    }
+    for (const k of [...testGroups.keys()].sort(cmp)) {
+        const ts = testGroups.get(k);
+        const [kind, tool, ruleId, key] = k.split('\u0000');
+        const file = key === '*' ? ts[0].hit.file : key;
+        const msg = ts[0].hit ? ruleMessage(tool, ruleId, input.rulesDirs) : checkMessage(ruleId);
+        const ev = ts.flatMap((t) => (t.hit ? [{ file: t.hit.file, line: t.hit.line || undefined, note: `${tool} rule ${ruleId}` }] : t.check.evidence));
+        const ids = [...new Set(ts.flatMap((t) => t.ids))].filter((id) => input.kit.byId.has(id)).sort(cmp);
+        const isLead = kind === 'lead';
+        const isExample = !isLead && ts.every((t) => !!t.hit?.noise);
+        records.push({
+            fingerprint: `OBS:${fpPath(file)}:${slug(`${isLead ? 'lead' : 'test code'} ${ruleId} ${ts[0].hit?.line ?? ''}`, 14)}`, kind: 'observation', sec_ids: ids,
+            title: clip(`${isLead ? 'Lead' : isExample ? 'Example value' : 'Test code'}: ${msg.title}`, 160), where: refs(ev).slice(0, 4),
+            note: clip(isLead
+                ? `Lead from ${ts[0].hit ? 'rule' : 'check'} ${ruleId}, whose confidence tier is lead: ${ts[0].reason}. Read the code; it never holds the gate.${ids.length ? ` If real it fails ${ids.join(', ')}.` : ''}${ts[0].total ? ` ${ts[0].total} places in all; the first 4 are listed here and every one is in checks.json.` : ''}`
+                : `${isExample ? 'Example value' : 'Test code'} (${ts[0].reason}): kept as a lead, never in the gate.${ids.length ? ` In shipped code it would fail ${ids.join(', ')}.` : ''} ${msg.fix}`, 400),
+            raised_by: ['hullproof-engine'],
+        });
+    }
+    // Fingerprints are unique: a second record with the same tail gets a short hash of its source.
+    const seen = new Set();
+    for (const r of records) {
+        let fp = r.fingerprint;
+        const tail = fp.slice(fp.indexOf(':') + 1);
+        if (seen.has(tail))
+            fp = `${fp}-${createHash('sha256').update(JSON.stringify(r)).digest('hex').slice(0, 6).replace(/[^a-z0-9]/g, 'a')}`;
+        seen.add(fp.slice(fp.indexOf(':') + 1));
+        r.fingerprint = fp;
+    }
+    records.sort((a, b) => cmp(a.fingerprint, b.fingerprint));
+    const needsVerifier = records.some((r) => r.kind === 'fail' && (r.severity === 'BLOCKER' || r.severity === 'CRITICAL' || r.sec_ids.some((id) => ['BLOCKER', 'CRITICAL'].includes(input.kit.byId.get(id).severity))));
+    const file = {
+        schema_version: '1.1.0',
+        report: {
+            commit: input.git.commit, tree: input.git.tree, tree_clean: input.git.clean, stage: input.scope.stage, profile: 'standard', scope: 'full',
+            // No model and no verifier run in Phase 1. A BLOCKER or CRITICAL record needs a verifier outcome in a complete run,
+            // so such a run is recorded incomplete with the kit's reason for exactly this: deterministic_only (schema 1.1.0).
+            run_status: needsVerifier ? 'incomplete' : 'complete',
+            ...(needsVerifier ? { incomplete_reason: 'deterministic_only' } : {}),
+            agent_calls: 0, budget: null,
+        },
+        records,
+    };
+    return { file, dropped: dropped.sort((a, b) => cmp(a.source + a.where, b.source + b.where)) };
+}
+// The kit validator warns on a findings block over 150000 characters and rejects one over 200000 (rule F3). Indented JSON
+// is written while it stays under the warning size; past it the same sorted JSON goes on one line, which is about 40
+// percent shorter on the targets measured (juice-shop with a large rule pack: 207103 indented).
+// ponytail: compact JSON only raises the ceiling; group records per rule instead of per file if a repository passes it.
+export const KIT_WARN_BLOCK_CHARS = 150000;
+export function findingsJson(f) {
+    const pretty = stableJson(f);
+    return pretty.length <= KIT_WARN_BLOCK_CHARS ? pretty : stableJsonCompact(f);
+}
+export function findingsMarkdown(f, json) {
+    return [
+        '# Findings record', '',
+        `Written by the Hullproof Engine ${ENGINE_VERSION} for commit ${f.report.commit}. ${f.records.some((r) => r.raised_by.includes('hullproof-hunt')) ? 'Every record comes from a check, a scanner rule or a lead the engine confirmed with evidence it can re run; no model decides any record.' : 'Every record comes from a check or a scanner rule, with no model.'} Validate it with tools/hullproof/ci/validate-findings.mjs from the kit.`, '',
+        '```hullproof-findings', json.trimEnd(), '```', '',
+    ].join('\n');
+}

package/dist/report/entry-points.js

@@ -0,0 +1,75 @@
+import { cmp } from '../util.js';
+export const MAX_TABLE_ROWS = 300;
+const cell = (s) => s.replace(/\|/g, '\\|').replace(/\n/g, ' ');
+const real = (ep, kind) => ep.protections.filter((p) => p.kind === kind);
+// One cell for one protection kind: yes with its confidence, ignored (the code checks and carries on), weak, no.
+export function protectionCell(ep, kind) {
+    const ps = real(ep, kind);
+    const good = ps.filter((p) => p.confidence !== 'low' && p.enforced !== false);
+    if (good.length) {
+        const best = good.some((p) => p.confidence === 'high') ? 'high' : 'medium';
+        return `yes (${best})`;
+    }
+    if (ps.some((p) => p.enforced === false))
+        return 'ignored';
+    if (ps.length)
+        return 'weak';
+    return 'no';
+}
+function rowFor(ep) {
+    const state = ep.tags.includes('state_changing');
+    const admin = ep.tags.includes('admin');
+    const byId = ep.data.filter((d) => d.by_id);
+    const owner = !byId.length ? '-' : byId.every((d) => d.owner_scoped) ? 'yes' : 'no';
+    const isWebhook = ep.kind === 'webhook';
+    const readsBody = ep.reads.some((r) => r.source === 'body' || r.source === 'form');
+    const session = ep.kind === 'ai_tool' || ep.kind === 'job' || ep.kind === 'page' || isWebhook ? '-' : protectionCell(ep, 'session_read');
+    return [
+        session,
+        admin ? protectionCell(ep, 'role_check') : '-',
+        owner,
+        isWebhook ? protectionCell(ep, 'signature_verify') : '-',
+        ep.tags.includes('auth_endpoint') && state ? protectionCell(ep, 'rate_limit') : '-',
+        state && readsBody ? protectionCell(ep, 'input_validation') : '-',
+    ];
+}
+const label = (ep) => `${ep.method && ep.method !== 'ANY' ? ep.method + ' ' : ''}${ep.path ?? ep.name ?? ep.file}`.trim();
+export function renderEntryPoints(map) {
+    const out = [];
+    const p = (...l) => { out.push(...l); };
+    const eps = map.entry_points;
+    const shipped = eps.filter((e) => !e.test_code);
+    p('## Entry points and what protects them', '');
+    p('The code map lists every entry point the engine could find by reading the code: HTTP routes, webhooks, server actions, jobs, AI tools and similar. It comes from pattern reading, not from running the app, so each cell below is a place to look and not a proof. "yes" means the engine found that protection on the entry point, with the confidence of the match. "ignored" means the code checks and then carries on. "weak" means only a sign such as a cookie being present. "-" means the column does not apply.', '');
+    p('| Language | Files | Status | Entry points | Note |', '|---|---|---|---|---|');
+    if (map.coverage.length === 0)
+        p('| none | 0 | | 0 | No source language was found. |');
+    for (const c of map.coverage)
+        p(`| ${c.language} | ${c.files} | ${c.status === 'mapped' ? 'mapped' : c.status === 'partial' ? 'partly mapped' : 'not mapped'} | ${c.entry_points} | ${cell(c.note)} |`);
+    p('');
+    const incomplete = map.coverage.filter((c) => c.status !== 'mapped');
+    if (incomplete.length)
+        p(`The code map is incomplete for ${incomplete.map((c) => c.language).join(', ')}. Entry points in those files are not listed, and the checks that read the map did not look at them.`, '');
+    const kinds = Object.entries(map.counts.by_kind).map(([k, n]) => `${n} ${k.replace(/_/g, ' ')}`).join(', ');
+    const state = shipped.filter((e) => e.tags.includes('state_changing') && ['http_route', 'server_action', 'graphql_resolver', 'rpc'].includes(e.kind));
+    const noSession = state.filter((e) => !e.tags.includes('auth_endpoint') && !e.tags.includes('public') && protectionCell(e, 'session_read') !== 'yes (high)' && protectionCell(e, 'session_read') !== 'yes (medium)');
+    const admins = shipped.filter((e) => e.tags.includes('admin') && ['http_route', 'server_action', 'graphql_resolver', 'rpc'].includes(e.kind));
+    const noRole = admins.filter((e) => !protectionCell(e, 'role_check').startsWith('yes'));
+    const hooks = shipped.filter((e) => e.kind === 'webhook');
+    const badHooks = hooks.filter((e) => !protectionCell(e, 'signature_verify').startsWith('yes'));
+    p(`1. Entry points: ${map.counts.entry_points}${kinds ? ` (${kinds})` : ''}. In test code and left out of the checks: ${eps.length - shipped.length}.`);
+    p(`2. State changing entry points: ${state.length}. Without a session read the engine can see: ${noSession.length}.`);
+    p(`3. Entry points in an admin area: ${admins.length}. Without a role check the engine can see: ${noRole.length}.`);
+    p(`4. Webhooks: ${hooks.length}. Without a signature check that stops the request: ${badHooks.length}.`);
+    p('5. Gates (middleware, guards, router dependencies): ' + map.gates.length + '.', '');
+    p('| Entry point | Kind | Where | Session | Role | Owner | Signature | Rate limit | Schema |', '|---|---|---|---|---|---|---|---|---|');
+    const rows = eps.slice().sort((a, b) => cmp(a.file, b.file) || a.line - b.line || cmp(a.id, b.id)).slice(0, MAX_TABLE_ROWS);
+    for (const ep of rows) {
+        const r = rowFor(ep);
+        p(`| ${cell(label(ep))}${ep.test_code ? ' (test code)' : ''} | ${ep.kind.replace(/_/g, ' ')} | \`${ep.file}:${ep.line}\` | ${r.join(' | ')} |`);
+    }
+    if (eps.length > rows.length)
+        p('', `${eps.length - rows.length} more entry points are in codemap.json.`);
+    p('');
+    return out;
+}

package/dist/report/hunt-section.js

@@ -0,0 +1,71 @@
+import { readableKey } from '../confirm/agreement.js';
+import { cmp } from '../util.js';
+const loc = (e) => `\`${e.file}:${e.line}\``;
+const METHOD = { map_query: 'a query over the code map', semgrep_rule: 'a generated Semgrep rule and a negative control', sandbox_test: 'a test run in a local sandbox, 3 of 3 runs' };
+export function renderHunt(h, merged) {
+    const out = [];
+    const p = (...l) => { out.push(...l); };
+    if (!h.result) {
+        if (h.skipped)
+            p('## Hunt', '', `Hunt: not run, ${h.skipped}.`, '');
+        return out;
+    }
+    const r = h.result;
+    const syn = new Map((h.synthesis?.explanations ?? []).map((e) => [e.key, e.text]));
+    const gateSet = new Set((merged?.inGate ?? []).map((c) => c.key));
+    const provenSet = new Set((merged?.proven ?? []).map((c) => c.key));
+    p('## Hunt: leads and confirmed findings', '');
+    p('A model proposed these and the engine checked them. Only a lead that the engine confirmed with evidence a machine can re run is a finding. Every other lead is listed for a person to read and can never hold or release the gate. The number of runs that raised a lead only orders the list.', '');
+    p(`1. Runs: ${r.runs}. Entry points hunted: ${r.entries_hunted}. Calls: ${r.calls.complete} complete, ${r.calls.incomplete} incomplete, ${r.calls.missing} never saved.`);
+    p(`2. Confirmed findings: ${r.confirmed.length}. Leads not confirmed: ${r.leads.length}.`);
+    p(`3. Hallucinations (leads that cited code that is not there, dropped): ${r.hallucinations.count}. Malformed leads (dropped): ${r.malformed.count}.`);
+    p(`4. Tokens used, reported and not limited: ${r.usage.input_tokens} in, ${r.usage.output_tokens} out, over ${r.usage.calls} calls.`, '');
+    if (h.synthesis) {
+        p('### Summary of all runs', '');
+        p(h.synthesis.status === 'complete' ? (h.synthesis.summary || 'The synthesis step returned no summary.') : `The synthesis step did not finish (${h.synthesis.stop ?? 'stopped'}). It only explains, so no finding is affected.`, '');
+    }
+    const conf = (c, i) => {
+        const e = c.confirmation;
+        p(`#### H-${i + 1} ${c.claim}${c.claim_truncated ? ' (claim shortened to the limit)' : ''}`, '');
+        p(`Where: ${c.path.map(loc).join(' to ')}. Requirements: ${c.requirement_ids.join(', ') || 'none named'}. Raised in ${c.runs_raised} of ${r.runs} runs.`);
+        if (e.status === 'confirmed')
+            p(`Evidence: confirmed by ${METHOD[e.method]} (${e.tool} ${e.tool_version}, ${e.rule_id}). ${e.detail}.`);
+        if (provenSet.has(c.key))
+            p('Proven by a test in the sandbox: yes, see the proof sandbox section.');
+        p(gateSet.has(c.key) ? 'Counts in the gate: yes, as a fail record with machine evidence.' : 'Counts in the gate: no, none of its requirements is in this run\'s scope (or it names none).');
+        if (syn.has(c.key))
+            p(`Explanation: ${syn.get(c.key)}`);
+        p('');
+    };
+    if (r.confirmed.length) {
+        p('### Confirmed findings', '');
+        r.confirmed.forEach(conf);
+    }
+    if (r.leads.length) {
+        p('### Leads (not confirmed, never in the gate)', '');
+        p('| Raised in | Where | Requirements | Claim | Why not confirmed |', '|---|---|---|---|---|');
+        for (const l of r.leads) {
+            const why = provenSet.has(l.key) ? 'proven by a test in the sandbox, see the proof sandbox section' : l.confirmation.status === 'confirmed' ? '' : l.confirmation.detail;
+            p(`| ${l.runs_raised} of ${r.runs} runs | ${loc(l.sink)} | ${l.requirement_ids.join(', ') || 'none named'} | ${l.claim_truncated ? '(claim shortened) ' : ''}${l.claim.replace(/\|/g, '\\|')}${syn.has(l.key) ? ' Explanation: ' + syn.get(l.key).replace(/\|/g, '\\|') : ''} | ${why.replace(/\|/g, '\\|')} |`);
+        }
+        p('');
+    }
+    if (r.incomplete.length) {
+        p('### Incomplete hunts', '', 'These calls did not finish. A provider stop (a refusal, a safety stop, a rate limit, a timeout) is recorded and never retried around, so the entry point below was not fully hunted in that run.', '');
+        p('| Run | Entry point | Why |', '|---|---|---|');
+        for (const i of r.incomplete.slice().sort((a, b) => a.run - b.run || cmp(a.entry_id, b.entry_id)))
+            p(`| ${i.run} | ${i.entry_id.replace(/\|/g, '\\|')} | ${i.stop}${i.detail ? ': ' + i.detail.replace(/\|/g, '\\|') : ''} |`);
+        p('');
+    }
+    if (r.hallucinations.count) {
+        p('### Dropped as hallucinations', '');
+        for (const x of r.hallucinations.items.slice(0, 30))
+            p(`- Run ${x.run}, ${readableKey(x.entry_id)}: ${x.reason}.`);
+        if (r.hallucinations.count > 30)
+            p(`- and ${r.hallucinations.count - 30} more (all are in hunt/result.json).`);
+        p('');
+    }
+    if (merged?.outOfScope.length)
+        p(`${merged.outOfScope.length} confirmed finding(s) name no requirement in this run's scope, so they are shown above and are not in the gate.`, '');
+    return out;
+}

package/dist/report/kit.js

@@ -0,0 +1,41 @@
+// Finds the Hullproof kit (docs/hullproof and tools/hullproof) and reads the controls file, the source of truth for
+// severity, authority, edition and stage. The engine never copies severities into its own code.
+import { createHash } from 'node:crypto';
+import { existsSync, readFileSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+export const CONTROLS_REL = 'docs/hullproof/security-controls.json';
+export const GATE_REL = 'tools/hullproof/ci/hullproof-gate.mjs';
+export const VALIDATOR_REL = 'tools/hullproof/ci/validate-findings.mjs';
+// The Hullproof Free kit in a folder called hullproof-free next to this repository, used when nothing else names a kit
+// (same default as src/mapping).
+const SIBLING_KIT = fileURLToPath(new URL('../../../hullproof-free/kit/', import.meta.url));
+// Order: --kit, HULLPROOF_KIT, the scanned repository when the kit is installed in it, then the kit next to this repository.
+export function resolveKitDir(repo, flag) {
+    const tries = [flag, process.env.HULLPROOF_KIT ?? null, repo, SIBLING_KIT].filter((x) => !!x).map((d) => resolve(d));
+    return tries.find((d) => existsSync(join(d, CONTROLS_REL))) ?? null;
+}
+export function loadKit(dir) {
+    const raw = readFileSync(join(dir, CONTROLS_REL));
+    const doc = JSON.parse(raw.toString('utf8'));
+    const controls = doc.controls.filter((c) => c.status === 'active' || c.status === undefined);
+    return {
+        dir, controls, byId: new Map(controls.map((c) => [c.id, c])),
+        controlsSha256: createHash('sha256').update(raw).digest('hex'), standardVersion: String(doc.standard_version ?? 'unknown'),
+    };
+}
+export const STAGES = ['LAUNCH', 'GROWTH', 'SCALE'];
+// A requirement is in scope when its edition is in the run's edition and its stage is at or below the declared stage.
+export function inScope(c, s) {
+    return (s.edition === 'pro' || c.edition === 'free') && STAGES.indexOf(c.stage) <= STAGES.indexOf(s.stage);
+}
+// The stage from docs/security/STAGE.md ("Stage: GROWTH" or a heading or table cell naming one stage), else LAUNCH.
+export function readStage(repo) {
+    const p = join(repo, 'docs/security/STAGE.md');
+    if (!existsSync(p))
+        return { stage: 'LAUNCH', source: 'default' };
+    const m = /\b(?:stage|declared stage)\b[^\n]{0,20}?\b(LAUNCH|GROWTH|SCALE)\b/i.exec(readFileSync(p, 'utf8'));
+    return m ? { stage: m[1].toUpperCase(), source: 'STAGE.md' } : { stage: 'LAUNCH', source: 'default' };
+}
+export const SEV_RANK = { BLOCKER: 5, CRITICAL: 4, HIGH: 3, MEDIUM: 2, LOW: 1 };
+export const highest = (sevs) => sevs.reduce((a, b) => (SEV_RANK[b] > SEV_RANK[a] ? b : a), sevs[0]);

package/dist/report/load.js

@@ -0,0 +1,35 @@
+// Reads a scan folder (<out>/<commit>/) back. The report and the gate read only these files, never the source.
+import { existsSync, readFileSync, readdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { cmp } from '../util.js';
+import { huntDir, readResult, readSkipped, readSynthesis } from '../confirm/store.js';
+import { loadProveFiles } from './prove-section.js';
+const json = (p) => JSON.parse(readFileSync(p, 'utf8'));
+export function loadScan(dir) {
+    for (const f of ['scan.json', 'stack.json', 'checks.json', 'results.json', 'report.findings.md', 'surface.json']) {
+        if (!existsSync(join(dir, f)))
+            throw new Error(`${join(dir, f)} is missing. Run hullproof scan first.`);
+    }
+    const findingsText = readFileSync(join(dir, 'report.findings.md'), 'utf8');
+    const block = /```hullproof-findings\n([\s\S]*?)\n```/.exec(findingsText);
+    if (!block)
+        throw new Error('report.findings.md holds no hullproof-findings block');
+    const scanDir = join(dir, 'scan');
+    const metas = existsSync(scanDir)
+        ? readdirSync(scanDir).filter((n) => n.endsWith('.meta.json')).sort(cmp).map((n) => json(join(scanDir, n)))
+        : [];
+    const reasons = {};
+    for (const m of metas) {
+        const p = join(scanDir, `${m.tool}.detail.json`);
+        reasons[m.tool] = existsSync(p) ? json(p).not_run_reason : null;
+    }
+    const hd = huntDir(dir);
+    return {
+        hunt: { result: readResult(hd), synthesis: readSynthesis(hd), skipped: readSkipped(hd) },
+        prove: loadProveFiles(dir),
+        reasons, dir, info: json(join(dir, 'scan.json')), stack: json(join(dir, 'stack.json')), checks: json(join(dir, 'checks.json')),
+        results: json(join(dir, 'results.json')), findingsText, findings: JSON.parse(block[1]), metas,
+        surface: json(join(dir, 'surface.json')),
+        codemap: existsSync(join(dir, 'codemap.json')) ? json(join(dir, 'codemap.json')) : null,
+    };
+}