hullproof 0.0.0-stage → 0.5.0

package/dist/commands/scan.js

@@ -0,0 +1,158 @@
+var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExtension) || function (path, preserveJsx) {
+    if (typeof path === "string" && /^\.\.?\//.test(path)) {
+        return path.replace(/\.(tsx)$|((?:\.d)?)((?:\.[^./]+?)?)\.([cm]?)ts$/i, function (m, tsx, d, ext, cm) {
+            return tsx ? preserveJsx ? ".jsx" : ".js" : d && (!ext || !cm) ? m : (d + ext + "." + cm.toLowerCase() + "js");
+        });
+    }
+    return path;
+};
+// hullproof scan: discover, scanner adapters, checks, then results.json, the findings record and surface.json, all under
+// <out>/<commit>/. Every contract file is byte identical for the same commit, engine, kit files and tool versions.
+// Run times go to run.json and scan/run.json only.
+import { existsSync, mkdirSync, readdirSync, rmSync, statSync, writeFileSync } from 'node:fs';
+import { basename, join, resolve } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { discover } from '../discover/discover.js';
+import { makeContext } from '../checks/context.js';
+import { getMap } from '../checks/map/shared.js';
+import { checkSha, loadChecks, runChecks } from '../checks/run.js';
+import { buildFindings, buildResults, findingsJson, findingsMarkdown } from '../report/build.js';
+import { loadKit, readStage, resolveKitDir, VALIDATOR_REL } from '../report/kit.js';
+import { surface } from '../report/surface.js';
+import { runScanners } from '../scanners/index.js';
+import { dirSha256, RULES_DIR } from '../scanners/common.js';
+import { ruleFiles } from '../scanners/semgrep.js';
+import { stableJson } from '../util.js';
+import { ENGINE_VERSION } from '../version.js';
+import { gitSafety, gitState } from './git.js';
+import { kitOwnedFiles } from '../discover/kit-files.js';
+export const KIT_LOCAL = 'kit.local.json';
+export const outDirFor = (repo, out, commit) => join(resolve(out ?? join(repo, '.hullproof')), commit);
+function defaultScanners(o, stack, dir, controlsPath, kitDir, rulePack, skipFiles) {
+    const outs = runScanners({ repo: o.repo, out: dir, stack, allowNetwork: o.allowNetwork, edition: o.edition, controlsPath, history: true, kit: kitDir, rulePack, skipFiles }, o.tools ?? undefined);
+    return { hits: outs.flatMap((s) => s.hits.hits), metas: outs.map((s) => s.meta) };
+}
+// The rule pack folder from the option or HULLPROOF_RULE_PACK, checked before anything runs. A string is a bad input.
+export function resolveRulePack(given) {
+    const raw = given ?? process.env.HULLPROOF_RULE_PACK ?? null;
+    if (!raw)
+        return { path: null };
+    const path = resolve(raw);
+    if (!existsSync(path) || !statSync(path).isDirectory())
+        return `the rule pack folder ${raw} does not exist`;
+    try {
+        ruleFiles(join(RULES_DIR, 'semgrep'), path);
+    }
+    catch (e) {
+        return e.message;
+    }
+    return { path };
+}
+export async function scan(o) {
+    const log = o.log ?? ((s) => process.stderr.write(s + '\n'));
+    const repo = resolve(o.repo);
+    if (!existsSync(repo)) {
+        log(`hullproof scan: ${repo} does not exist`);
+        return 2;
+    }
+    const safety = gitSafety(repo);
+    if (!safety.ok) {
+        log(`hullproof scan: ${safety.message}`);
+        return 2;
+    }
+    if (safety.credentialUrl)
+        log('hullproof scan: note: a remote URL holds embedded credentials. Treat that credential as exposed and rotate it. The line is not printed.');
+    const git = gitState(repo);
+    if (!git) {
+        log('hullproof scan: could not read the commit and tree with git (is there a commit?)');
+        return 2;
+    }
+    const kitDir = resolveKitDir(repo, o.kit);
+    if (!kitDir) {
+        log('hullproof scan: no kit found. Pass --kit <folder holding docs/hullproof/security-controls.json> or set HULLPROOF_KIT.');
+        return 2;
+    }
+    const kit = loadKit(kitDir);
+    const pack = resolveRulePack(o.rulePack);
+    if (typeof pack === 'string') {
+        log(`hullproof scan: ${pack}`);
+        return 2;
+    }
+    const st = o.stage ? { stage: o.stage, source: 'flag' } : readStage(repo);
+    const scope = { edition: o.edition, stage: st.stage, stageSource: st.source };
+    const started = Date.now();
+    const dir = outDirFor(repo, o.out, git.commit);
+    // Start from an empty folder so files from an earlier run with other tools never mix in.
+    // The hunt folder holds saved model answers that cost the user tokens to get, and the prove folder holds specs and the transcripts
+    // that are the evidence of a proof, so a new scan never deletes either.
+    if (existsSync(dir))
+        for (const n of readdirSync(dir))
+            if (n !== 'hunt' && n !== 'prove')
+                rmSync(join(dir, n), { recursive: true, force: true });
+    mkdirSync(dir, { recursive: true });
+    const kitFiles = kitOwnedFiles(repo, kitDir);
+    if (kitFiles.size)
+        log(`hullproof scan: ${kitFiles.size} unchanged Hullproof kit files in the project are left out of the scan (they hold planted test samples)`);
+    const stack = discover(repo, { skipFiles: kitFiles });
+    writeFileSync(join(dir, 'stack.json'), stableJson(stack));
+    const controlsPath = join(kitDir, 'docs/hullproof/security-controls.json');
+    const sc = o.scanners ? o.scanners(stack, dir) : defaultScanners(o, stack, dir, controlsPath, kitDir, pack.path, kitFiles);
+    const hits = sc?.hits ?? [];
+    const metas = (sc?.metas ?? []).slice().sort((a, b) => (a.tool < b.tool ? -1 : 1));
+    if (o.scanners) {
+        // Stub scanners (tests) do not write their files; write them here in the adapters' layout.
+        mkdirSync(join(dir, 'scan'), { recursive: true });
+        for (const m of metas) {
+            writeFileSync(join(dir, 'scan', `${m.tool}.meta.json`), stableJson(m));
+            writeFileSync(join(dir, 'scan', `${m.tool}.json`), stableJson({ schema_version: '1.0.0', tool: m.tool, hits: hits.filter((h) => h.tool === m.tool) }));
+        }
+    }
+    const checkDefs = loadChecks();
+    const ctx = makeContext(repo, stack, hits, kitDir);
+    const checks = runChecks(ctx, checkDefs);
+    writeFileSync(join(dir, 'checks.json'), stableJson(checks));
+    const codemap = getMap(ctx);
+    writeFileSync(join(dir, 'codemap.json'), stableJson(codemap));
+    const input = { kit, scope, git, checks, hits, metas, checkShas: Object.fromEntries(checkDefs.map((c) => [c.id, checkSha(c)])), rulesDirs: [join(RULES_DIR, 'semgrep'), ...(pack.path ? [pack.path] : [])] };
+    const results = buildResults(input);
+    writeFileSync(join(dir, 'results.json'), stableJson(results));
+    const { file: findings, dropped } = buildFindings(input);
+    const findingsMd = findingsMarkdown(findings, findingsJson(findings));
+    writeFileSync(join(dir, 'report.findings.md'), findingsMd);
+    writeFileSync(join(dir, 'surface.json'), stableJson(surface(ctx)));
+    const info = {
+        schema_version: '1.0.0', engine_version: ENGINE_VERSION, commit: git.commit, tree: git.tree, tree_clean: git.clean,
+        edition: scope.edition, stage: scope.stage, stage_source: scope.stageSource,
+        kit: { controls_sha256: kit.controlsSha256, standard_version: kit.standardVersion, controls_found: true },
+        scanners_available: true, tools: metas.map((m) => m.tool),
+        rule_pack: pack.path ? { name: basename(pack.path), files: ruleFiles(pack.path).map((f) => basename(f)), sha256: dirSha256(pack.path) } : null,
+        checks: { total: checkDefs.length, ran: checks.results.length, not_run: checks.not_run.length },
+        codemap: { entry_points: codemap.counts.entry_points, incomplete: codemap.coverage.filter((c) => c.status !== 'mapped').map((c) => ({ language: c.language, status: c.status })) },
+        dropped,
+    };
+    writeFileSync(join(dir, 'scan.json'), stableJson(info));
+    writeFileSync(join(dir, 'run.json'), JSON.stringify({ seconds: (Date.now() - started) / 1000 }) + '\n');
+    // The kit this scan used, so report and gate find the same kit without --kit. A machine path, so it lives outside the
+    // byte identical contract (like run.json); the controls sha256 in it is also in scan.json.
+    writeFileSync(join(dir, KIT_LOCAL), JSON.stringify({ kit_dir: kitDir, controls_sha256: kit.controlsSha256 }) + '\n');
+    // Self check with the kit's own validator: a record file the kit rejects is a bug, never a result.
+    const problems = await validateWithKit(kitDir, findingsMd, kit.byId);
+    if (problems.length) {
+        for (const p of problems)
+            log(`hullproof scan: findings record: ${p}`);
+        return 2;
+    }
+    const fails = results.filter((r) => r.result === 'FAIL').length;
+    const records = findings.records.filter((r) => r.kind === 'fail').length;
+    log(`hullproof scan: wrote ${dir}`);
+    log(`hullproof scan: requirements in scope ${results.length}, FAIL ${fails}, PASS (static) ${results.filter((r) => r.result === 'PASS (static)').length}, NOT ASSESSED ${results.filter((r) => r.result.startsWith('NOT ASSESSED')).length}; fail records ${records}; tools ran ${metas.filter((m) => m.status === 'ran').map((m) => m.tool).join(', ') || 'none'}`);
+    return 0;
+}
+export async function validateWithKit(kitDir, text, byId) {
+    const path = join(kitDir, VALIDATOR_REL);
+    if (!existsSync(path))
+        return [];
+    const v = await import(__rewriteRelativeImportExtension(pathToFileURL(path).href));
+    const res = v.validateFindingsText(text, { controls: byId });
+    return res.c.errorCount ? res.c.lines() : [];
+}

package/dist/confirm/agreement.js

@@ -0,0 +1,18 @@
+import { cmp } from '../util.js';
+export const sinkOf = (l) => { const s = l.path[l.path.length - 1]; return { file: s.file, line: s.line }; };
+export const leadKey = (l) => { const s = sinkOf(l); return `${l.entry_point}\u0000${l.requirement_ids.join('+')}\u0000${s.file}:${s.line}`; };
+export const readableKey = (k) => k.split('\u0000').join(' | ');
+// Groups leads by identity. Within a group the leads are in run order, then lead_id order, so the first proposal tried is stable.
+export function groupLeads(raised) {
+    const by = new Map();
+    for (const r of raised) {
+        const k = leadKey(r.lead);
+        by.set(k, [...(by.get(k) ?? []), r]);
+    }
+    return [...by.entries()].map(([key, leads]) => {
+        leads.sort((a, b) => a.run - b.run || cmp(a.lead.lead_id, b.lead.lead_id));
+        return { key, leads, runs: [...new Set(leads.map((l) => l.run))] };
+    });
+}
+// Most runs first, then by key. A pure ordering: no group is added or dropped.
+export const byAgreement = (xs) => xs.slice().sort((a, b) => b.runs.length - a.runs.length || cmp(a.key, b.key));

package/dist/confirm/chain.js

@@ -0,0 +1,84 @@
+const MAX_LINES = 8;
+// Names that plausibly act on the caller or the request. A wrapper such as withErrors or asyncHandler does not match.
+const RELEVANT = /(auth|user|owner|session|token|guard|verify|check|permission|role|tenant|account|csrf|protect|secure|policy|allow|deny|require|login|acl|admin|scope|bind|append|limit|throttle|sanit|validate|can[A-Z]|is[A-Z])/;
+const REGISTER = /^(app|router|server|api|[A-Za-z_$][\w$]*Router)\.(get|post|put|patch|delete|all|options|head|use|route)$/;
+// Top level arguments of the first call that opens in `text`, as strings.
+function firstCallArgs(text) {
+    const open = text.indexOf('(');
+    if (open < 0)
+        return [];
+    const args = [];
+    let depth = 0, cur = '', quote = '';
+    for (let i = open + 1; i < text.length; i++) {
+        const c = text[i];
+        if (quote) {
+            cur += c;
+            if (c === quote && text[i - 1] !== '\\')
+                quote = '';
+            continue;
+        }
+        if (c === '"' || c === "'" || c === '`') {
+            quote = c;
+            cur += c;
+            continue;
+        }
+        if (c === '(' || c === '[' || c === '{')
+            depth++;
+        if (c === ')' || c === ']' || c === '}') {
+            if (depth === 0) {
+                args.push(cur.trim());
+                return args;
+            }
+            depth--;
+        }
+        if (c === ',' && depth === 0) {
+            args.push(cur.trim());
+            cur = '';
+            continue;
+        }
+        cur += c;
+    }
+    return args;
+}
+const callName = (arg) => /^([A-Za-z_$][\w$]*(?:\.[A-Za-z_$][\w$]*)*)\s*\(/.exec(arg)?.[1] ?? null;
+// Calls on the chain, in order. Express style: every argument between the path and the last argument (the handler). Wrapper style
+// (`export const POST = withX(...)`): the wrapper name. Decorator style (Flask): every decorator that is not the route.
+export function chainCalls(text, line) {
+    const lines = text.split('\n').slice(line - 1, line - 1 + MAX_LINES);
+    const first = lines.join('\n');
+    const out = [];
+    const reg = /^\s*([A-Za-z_$][\w$]*(?:\.[A-Za-z_$][\w$]*)*)\s*\(/.exec(first);
+    if (reg && REGISTER.test(reg[1])) {
+        const args = firstCallArgs(first);
+        for (const a of args.slice(1, -1)) {
+            const n = callName(a);
+            if (n)
+                out.push(n);
+        }
+        return out;
+    }
+    const wrap = /^\s*(?:export\s+)?(?:const|let)\s+\w+\s*=\s*(?:async\s*)?([A-Za-z_$][\w$]*)\s*\(/.exec(first);
+    if (wrap)
+        out.push(wrap[1]);
+    for (const l of lines) {
+        const d = /^\s*@([A-Za-z_][\w.]*)/.exec(l);
+        if (d && !/\.route$|\.(get|post|put|delete|patch)$/.test(d[1]))
+            out.push(d[1]);
+        if (/^\s*(async\s+)?def\s/.test(l))
+            break;
+    }
+    return out;
+}
+const known = (name, ep, map) => {
+    const last = name.split('.').pop().toLowerCase();
+    const vias = [...ep.protections, ...map.gates.flatMap((g) => g.protections)].map((p) => p.via.toLowerCase());
+    const vocab = [...map.config.local_vocab.auth_helpers, ...map.config.local_vocab.role_helpers].map((v) => v.toLowerCase());
+    return vias.some((v) => v.includes(last)) || vocab.includes(last);
+};
+// Names on the chain of `ep` that look like they act on the caller or the request and that the map does not know.
+export function unknownProtections(ep, map, files) {
+    const text = files.read(ep.file);
+    if (!text)
+        return [];
+    return [...new Set(chainCalls(text, ep.line).filter((n) => RELEVANT.test(n.split('.').pop()) && !known(n, ep, map)))].sort();
+}

package/dist/confirm/confirm.js

@@ -0,0 +1,112 @@
+// The confirmation engine. From the saved answers of a hunt, the repository and the code map it decides, with no model and no
+// clock, which leads are confirmed findings and which stay leads. The same inputs give the same result.json byte for byte.
+// The result holds nothing a model wrote except the claim and the notes, which are plain text and never decide anything.
+import { createHash } from 'node:crypto';
+import { cmp } from '../util.js';
+import { ENGINE_VERSION } from '../version.js';
+import { byAgreement, groupLeads, sinkOf } from './agreement.js';
+import { unknownProtections } from './chain.js';
+import { checkLead, FileCache } from './honesty.js';
+import { parseOutput } from './lead.js';
+import { runQuery } from './query.js';
+import { confirmRule, spawnSemgrep } from './rule.js';
+function tryGroup(g, input, files) {
+    let last = { status: 'not_confirmed', method: 'none', detail: 'the lead proposed no evidence the engine can check' };
+    for (const { run, lead } of g.leads) {
+        const p = lead.evidence_proposal;
+        if (p.kind === 'map_query') {
+            const o = runQuery(input.map, p.query, lead.entry_point, lead.path);
+            if (o.confirmed) {
+                // The map cannot vouch for a claim about input, ownership or protection when the route chain holds a helper it does not know.
+                const ep = input.map.entry_points.find((e) => e.id === lead.entry_point);
+                const unknown = ep ? unknownProtections(ep, input.map, files) : [];
+                if (unknown.length) {
+                    last = { status: 'not_confirmed', method: 'map_query', reason: 'unknown_protection', helpers: unknown, detail: `unknown_protection: the route chain holds ${unknown.join(', ')}, which the code map does not recognise, so the map cannot say this claim is true` };
+                    continue;
+                }
+                const cfg = createHash('sha256').update(JSON.stringify(p.query)).digest('hex');
+                return { status: 'confirmed', method: 'map_query', run, detail: o.detail, tool: 'hullproof-hunt', rule_id: `hunt.query.${cfg.slice(0, 12)}`, tool_version: ENGINE_VERSION, config_sha256: cfg };
+            }
+            last = { status: 'not_confirmed', method: 'map_query', detail: o.detail };
+        }
+        else if (p.kind === 'semgrep_rule') {
+            const o = confirmRule(lead, input.repo, input.semgrep ?? spawnSemgrep);
+            if (o.status === 'confirmed')
+                return { status: 'confirmed', method: 'semgrep_rule', run, detail: o.detail, tool: 'semgrep', rule_id: o.rule_id, tool_version: o.tool_version, config_sha256: o.config_sha256 };
+            last = o.status === 'not_run' ? { status: 'not_run', method: 'semgrep_rule', detail: o.detail } : { status: 'not_confirmed', method: 'semgrep_rule', detail: o.detail };
+        }
+        else if (p.kind === 'generated_test') {
+            if (last.status === 'not_confirmed' && last.method === 'none')
+                last = { status: 'not_confirmed', method: 'generated_test', detail: 'a generated test has to be written and run with hullproof prove; until it proves the flaw 3 of 3 the lead stays a lead' };
+        }
+        else if (p.kind === 'none' && p.rejected && last.status === 'not_confirmed' && last.method === 'none') {
+            last = { status: 'not_confirmed', method: 'none', detail: `the proposal was not usable: ${p.rejected}` };
+        }
+    }
+    return last;
+}
+export function confirmHunt(input) {
+    const files = new FileCache(input.repo);
+    const incomplete = [];
+    const malformed = [];
+    const hallucinations = [];
+    const raised = [];
+    const usage = { calls: 0, input_tokens: 0, output_tokens: 0 };
+    const seen = new Set();
+    let complete = 0;
+    for (const a of input.answers) {
+        seen.add(`${a.run}\u0000${a.entry_id}`);
+        usage.calls++;
+        usage.input_tokens += a.usage.input_tokens;
+        usage.output_tokens += a.usage.output_tokens;
+        if (a.status !== 'complete') {
+            incomplete.push({ entry_id: a.entry_id, run: a.run, stop: a.stop ?? 'unknown', detail: a.detail ?? '' });
+            continue;
+        }
+        complete++;
+        const p = parseOutput(a.output, a.entry_id);
+        for (const m of p.malformed)
+            malformed.push({ run: a.run, entry_id: a.entry_id, lead_id: m.lead_id, reason: m.reason });
+        for (const lead of p.leads) {
+            const h = checkLead(lead, files, input.map);
+            if (h.ok)
+                raised.push({ run: a.run, lead });
+            else
+                hallucinations.push({ run: a.run, entry_id: a.entry_id, lead_id: lead.lead_id, reason: h.reason });
+        }
+    }
+    // Calls that were planned and never saved: the run was interrupted or not finished.
+    let missing = 0;
+    if (input.plan) {
+        for (let r = 1; r <= input.plan.runs; r++) {
+            for (const e of input.plan.entries) {
+                if (seen.has(`${r}\u0000${e}`))
+                    continue;
+                missing++;
+                incomplete.push({ entry_id: e, run: r, stop: 'not_run', detail: 'no answer was saved for this call' });
+            }
+        }
+    }
+    const out = (g, c) => {
+        const first = g.leads[0].lead;
+        return { key: g.key, ...(first.claim_truncated ? { claim_truncated: true } : {}), entry_point: first.entry_point, requirement_ids: first.requirement_ids, claim: first.claim, path: first.path, sink: sinkOf(first), runs_raised: g.runs.length, runs: g.runs, confirmation: c };
+    };
+    const groups = byAgreement(groupLeads(raised));
+    const confirmed = [];
+    const leads = [];
+    for (const g of groups) {
+        const c = tryGroup(g, input, files);
+        (c.status === 'confirmed' ? confirmed : leads).push(out(g, c));
+    }
+    const by = (a, b) => a.run - b.run || cmp(a.entry_id, b.entry_id);
+    return {
+        schema_version: '1.0.0', engine_version: ENGINE_VERSION, commit: input.commit,
+        runs: Math.max(input.plan?.runs ?? 0, ...input.answers.map((a) => a.run), 0),
+        entries_hunted: new Set(input.answers.map((a) => a.entry_id)).size,
+        calls: { complete, incomplete: input.answers.length - complete, missing },
+        incomplete: incomplete.sort(by),
+        malformed: { count: malformed.length, items: malformed.sort((a, b) => a.run - b.run || cmp(a.entry_id, b.entry_id) || cmp(a.lead_id, b.lead_id)) },
+        hallucinations: { count: hallucinations.length, items: hallucinations.sort((a, b) => a.run - b.run || cmp(a.entry_id, b.entry_id) || cmp(a.lead_id, b.lead_id)) },
+        confirmed, leads, usage,
+    };
+}

package/dist/confirm/honesty.js

@@ -0,0 +1,75 @@
+// The honesty check. A lead is kept only when every file it cites exists in the repository, every cited line is inside its file,
+// and the code it quotes is really there beside the sink (the last step of its path). A lead that fails is dropped and counted
+// as a hallucination. Nothing here reads the lead's claim: it only asks whether the cited code exists.
+import { lstatSync, readFileSync } from 'node:fs';
+import { resolve, sep } from 'node:path';
+import { LIMITS } from './lead.js';
+export const QUOTE_SLACK = 2; // the quote may start or end this many lines from the cited sink line
+const MAX_FILE_BYTES = 2_000_000;
+const norm = (s) => s.replace(/\s+/g, ' ').trim();
+export class FileCache {
+    repo;
+    files = new Map();
+    constructor(repo) { this.repo = resolve(repo); }
+    // The text of a repository file, or null: absolute paths, "..", links, folders and files over 2 MB are all null.
+    read(file) {
+        if (this.files.has(file))
+            return this.files.get(file);
+        let text = null;
+        if (file && !file.startsWith('/') && !file.includes('\\') && !file.includes('\0') && !file.split('/').includes('..')) {
+            const abs = resolve(this.repo, file);
+            try {
+                const st = lstatSync(abs);
+                if (abs.startsWith(this.repo + sep) && st.isFile() && st.size <= MAX_FILE_BYTES)
+                    text = readFileSync(abs, 'utf8');
+            }
+            catch {
+                text = null;
+            }
+        }
+        this.files.set(file, text);
+        return text;
+    }
+}
+// Line ranges [start, end] (1 based) of every place the normalised quote occurs in the normalised file.
+function occurrences(text, quote) {
+    const starts = []; // offset in the joined text where each original line begins
+    let joined = '';
+    text.split('\n').forEach((raw) => {
+        const t = norm(raw);
+        starts.push(joined.length);
+        joined += t + ' ';
+    });
+    const lineAt = (off) => {
+        let lo = 0, hi = starts.length - 1;
+        while (lo < hi) {
+            const m = (lo + hi + 1) >> 1;
+            if (starts[m] <= off)
+                lo = m;
+            else
+                hi = m - 1;
+        }
+        return lo + 1;
+    };
+    const out = [];
+    for (let at = joined.indexOf(quote); at >= 0; at = joined.indexOf(quote, at + 1))
+        out.push([lineAt(at), lineAt(at + quote.length - 1)]);
+    return out;
+}
+export function checkLead(lead, files, map) {
+    if (!map.entry_points.some((e) => e.id === lead.entry_point))
+        return { ok: false, reason: 'the entry point is not in the code map' };
+    for (const s of lead.path) {
+        const t = files.read(s.file);
+        if (t === null)
+            return { ok: false, reason: `the cited file ${s.file} does not exist in the repository` };
+        if (s.line > t.split('\n').length)
+            return { ok: false, reason: `line ${s.line} is past the end of ${s.file}` };
+    }
+    const sink = lead.path[lead.path.length - 1];
+    const quote = norm(lead.quoted_code);
+    if (quote.length < LIMITS.minQuote || !/[A-Za-z0-9]/.test(quote))
+        return { ok: false, reason: 'the quoted code is too short to check' };
+    const near = occurrences(files.read(sink.file), quote).some(([a, b]) => b >= sink.line - QUOTE_SLACK && a <= sink.line + QUOTE_SLACK);
+    return near ? { ok: true } : { ok: false, reason: `the quoted code is not in ${sink.file} at line ${sink.line}` };
+}

package/dist/confirm/lead.js

@@ -0,0 +1,92 @@
+// The lead schema: what a model returns for one entry point, checked against the limits below. A lead that breaks a limit is
+// malformed and is counted apart from a hallucination (a lead whose cited code is not there, see honesty.ts).
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { parseQuery } from './query.js';
+export const LIMITS = { leadId: 80, claim: 500, note: 200, path: 12, requirements: 6, quote: 2000, leadsPerAnswer: 10, ruleYaml: 8000, controlCode: 20000, queryJson: 6000, minQuote: 8 };
+export const CONTROL_EXTENSIONS = ['js', 'mjs', 'cjs', 'ts', 'tsx', 'jsx', 'py', 'go', 'rb', 'php', 'java'];
+// The schema handed to a provider as the structured output shape.
+export const MODEL_OUTPUT_SCHEMA = JSON.parse(readFileSync(fileURLToPath(new URL('../../schemas/hunt-output.schema.json', import.meta.url)), 'utf8'));
+const isObj = (v) => !!v && typeof v === 'object' && !Array.isArray(v);
+const SEC = /^SEC-[A-Z]+-\d{3}$/;
+// One line of plain text: control characters removed, spaces collapsed, clipped.
+export const plain = (s, max) => {
+    const t = s.replace(/[\u0000-\u001f\u007f]+/g, ' ').replace(/\s+/g, ' ').trim();
+    return t.length <= max ? t : t.slice(0, max - 1).trimEnd() + '…';
+};
+function proposal(p) {
+    if (!isObj(p) || typeof p.kind !== 'string')
+        return { kind: 'none', rejected: 'no evidence proposal' };
+    if (p.kind === 'generated_test')
+        return { kind: 'generated_test' };
+    if (p.kind === 'none')
+        return { kind: 'none' };
+    if (p.kind === 'map_query') {
+        if (typeof p.query_json !== 'string' || !p.query_json.trim())
+            return { kind: 'none', rejected: 'map_query without query_json' };
+        if (p.query_json.length > LIMITS.queryJson)
+            return { kind: 'none', rejected: 'query_json is too long' };
+        let v;
+        try {
+            v = JSON.parse(p.query_json);
+        }
+        catch {
+            return { kind: 'none', rejected: 'query_json is not JSON' };
+        }
+        const q = parseQuery(v);
+        return q.ok ? { kind: 'map_query', query: q.query } : { kind: 'none', rejected: `query: ${q.reason}` };
+    }
+    if (p.kind === 'semgrep_rule') {
+        const { rule_yaml: r, control_code: c, control_extension: e } = p;
+        if (typeof r !== 'string' || !r.trim() || r.length > LIMITS.ruleYaml)
+            return { kind: 'none', rejected: 'rule_yaml is missing or too long' };
+        if (typeof c !== 'string' || !c.trim() || c.length > LIMITS.controlCode)
+            return { kind: 'none', rejected: 'a rule needs control_code (the safe sample)' };
+        const ext = typeof e === 'string' ? e.replace(/^\./, '') : '';
+        if (!CONTROL_EXTENSIONS.includes(ext))
+            return { kind: 'none', rejected: 'control_extension is not one of the allowed extensions' };
+        return { kind: 'semgrep_rule', rule_yaml: r, control_code: c, control_extension: ext };
+    }
+    return { kind: 'none', rejected: `unknown proposal kind` };
+}
+// The leads of one saved output, for the entry point that was hunted. A lead that names another entry point is malformed.
+export function parseOutput(raw, entryId) {
+    if (!isObj(raw) || !Array.isArray(raw.leads))
+        return { leads: [], malformed: [{ lead_id: '', reason: 'the output has no leads list' }] };
+    const leads = [];
+    const malformed = [];
+    raw.leads.forEach((x, i) => {
+        const id = isObj(x) && typeof x.lead_id === 'string' ? plain(x.lead_id, LIMITS.leadId) : `#${i + 1}`;
+        const bad = (reason) => { malformed.push({ lead_id: id, reason }); };
+        if (i >= LIMITS.leadsPerAnswer)
+            return bad(`more than ${LIMITS.leadsPerAnswer} leads in one answer`);
+        if (!isObj(x))
+            return bad('a lead must be an object');
+        if (typeof x.lead_id !== 'string' || !x.lead_id.trim() || x.lead_id.length > LIMITS.leadId)
+            return bad('lead_id is missing or too long');
+        if (x.entry_point !== entryId)
+            return bad('entry_point is not the entry point that was hunted');
+        // An empty list is allowed: the lead names no requirement. It can still be confirmed, and then it is reported and stays out of the gate (merge.ts).
+        if (!Array.isArray(x.requirement_ids) || x.requirement_ids.length > LIMITS.requirements || !x.requirement_ids.every((r) => typeof r === 'string' && SEC.test(r)))
+            return bad('requirement_ids needs at most 6 ids written like SEC, an area and three digits');
+        if (typeof x.claim !== 'string' || !x.claim.trim())
+            return bad('claim is missing');
+        if (!Array.isArray(x.path) || x.path.length === 0 || x.path.length > LIMITS.path)
+            return bad('path needs 1 to 12 steps');
+        const path = [];
+        for (const s of x.path) {
+            if (!isObj(s) || typeof s.file !== 'string' || !s.file || !Number.isInteger(s.line) || s.line < 1 || typeof s.note !== 'string')
+                return bad('a path step needs file, line and note');
+            path.push({ file: s.file, line: s.line, note: plain(s.note, LIMITS.note) });
+        }
+        if (typeof x.quoted_code !== 'string' || x.quoted_code.length > LIMITS.quote)
+            return bad('quoted_code is missing or too long');
+        leads.push({
+            lead_id: plain(x.lead_id, LIMITS.leadId), entry_point: entryId, requirement_ids: [...new Set(x.requirement_ids)].sort(),
+            claim: plain(x.claim, LIMITS.claim), path, quoted_code: x.quoted_code, evidence_proposal: proposal(x.evidence_proposal),
+            // A claim over the limit is shortened and marked, not dropped. The mark is only written when true, so older results keep their bytes.
+            ...(plain(x.claim, Infinity).length > LIMITS.claim ? { claim_truncated: true } : {}),
+        });
+    });
+    return { leads, malformed };
+}

package/dist/confirm/merge.js

@@ -0,0 +1,88 @@
+// Puts confirmed hunt findings, and findings proven by a test in the sandbox, into the rows and the findings record that the report and
+// the gate read. Only the `confirmed` list of the hunt result and the specs the prove result marks `proven` (3 of 3 runs) are read. Leads (the `leads` list), their claims, their agreement counts and the synthesis never reach this code, so
+// no lead can change a row, a record or the verdict. A confirmed finding becomes a fail record with machine_evidence, as findings
+// schema 1.1.0 asks, and makes its requirement a FAIL row.
+import { createHash } from 'node:crypto';
+import { cmp } from '../util.js';
+import { findingsJson, findingsMarkdown } from '../report/build.js';
+import { highest, inScope } from '../report/kit.js';
+const clip = (s, n) => (s.length <= n ? s : s.slice(0, n - 1).trimEnd() + '…');
+const fpPath = (f) => f.replace(/[\s:]/g, '_');
+const slug = (s, max = 12) => s.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-|-$/g, '').split('-').filter(Boolean).slice(0, max).join('-') || 'x';
+const METHOD = { map_query: 'a query over the code map', semgrep_rule: 'a generated Semgrep rule with a negative control', sandbox_test: 'a test run in a local sandbox, 3 of 3 runs, with the transcripts kept' };
+// A spec the sandbox proved, as a confirmed finding. When it tests a hunt lead, the lead's own path and requirements are kept and the
+// test replaces the weaker evidence: a test that fails the way the lead claims, 3 of 3 times, is the strongest confirmation there is.
+function provenLead(sp, p, base) {
+    const conf = {
+        status: 'confirmed', method: 'sandbox_test', run: p.runs_required, tool: 'hullproof-prove', rule_id: `prove.test.${sp.spec_sha256.slice(0, 12)}`,
+        tool_version: p.engine_version, config_sha256: sp.spec_sha256,
+        detail: `spec ${sp.spec_id} passed its positive control and showed the flaw in ${sp.runs.length} of ${p.runs_required} runs (transcripts ${sp.runs.map((r) => r.transcript_sha256.slice(0, 12)).join(', ')})`,
+    };
+    if (base)
+        return { ...base, confirmation: conf };
+    return { key: sp.lead_key ?? `spec:${sp.spec_id}`, entry_point: sp.entry_point, requirement_ids: sp.requirement_ids, claim: sp.claim, path: [{ file: sp.sink.file, line: sp.sink.line, note: `proven by test ${sp.spec_id}` }], sink: sp.sink, runs_raised: 0, runs: [], confirmation: conf };
+}
+// A lead that names no requirement can borrow the requirements of the engine's own map checks that flagged the same entry point (a FAIL in the
+// same file). It only borrows when the scan folder carries the checks and the code map; the finding says so.
+function borrowed(s, entryPoint) {
+    const e = s.codemap?.entry_points.find((x) => x.id === entryPoint);
+    if (!e || !s.checks)
+        return { ids: [], checks: [] };
+    const hit = s.checks.results.filter((r) => r.result === 'FAIL' && r.check_id.startsWith('check.map.') && r.evidence.some((ev) => ev.file === e.file));
+    return { ids: [...new Set(hit.flatMap((r) => r.sec_ids))].sort(cmp), checks: hit.map((r) => r.check_id).sort(cmp) };
+}
+export function mergeHunt(s, kit, hunt, prove = null) {
+    const scope = { edition: s.info.edition, stage: s.info.stage, stageSource: s.info.stage_source };
+    const rows = new Map(s.results.map((r) => [r.id, r]));
+    const records = [...s.findings.records];
+    const tails = new Set(records.filter((r) => r.kind === 'fail').map((r) => r.fingerprint.slice(r.fingerprint.indexOf(':') + 1)));
+    const inGate = [];
+    const outOfScope = [];
+    const byKey = new Map([...(hunt?.confirmed ?? []), ...(hunt?.leads ?? [])].map((l) => [l.key, l]));
+    const proven = (prove?.specs ?? []).filter((x) => x.outcome === 'proven' && x.runs.length >= prove.runs_required && x.runs.every((r) => r.outcome === 'proven')).map((x) => provenLead(x, prove, x.lead_key ? byKey.get(x.lead_key) : undefined));
+    const provenKeys = new Set(proven.map((l) => l.key));
+    const confirmed = [...(hunt?.confirmed ?? []).filter((l) => !provenKeys.has(l.key)), ...proven];
+    for (const c of confirmed) {
+        if (c.confirmation.status !== 'confirmed')
+            continue;
+        const lend = c.requirement_ids.length ? { ids: [], checks: [] } : borrowed(s, c.entry_point);
+        const ids = (c.requirement_ids.length ? c.requirement_ids : lend.ids).filter((id) => { const k = kit.byId.get(id); return !!k && inScope(k, scope); }).sort(cmp);
+        if (!ids.length) {
+            outOfScope.push(c);
+            continue;
+        }
+        const ev = c.confirmation;
+        const first = kit.byId.get(ids[0]);
+        let tail = `${fpPath(c.sink.file)}:${slug(`${ev.method === 'sandbox_test' ? 'proven' : 'hunt'} ${c.entry_point} ${c.sink.line}`)}`;
+        if (tails.has(tail))
+            tail = `${tail}-${createHash('sha256').update(c.key).digest('hex').slice(0, 6).replace(/[^a-z0-9]/g, 'a')}`;
+        tails.add(tail);
+        const trace = c.path.map((p, i) => ({ kind: i === c.path.length - 1 ? 'sink' : i === 0 ? 'entrypoint' : 'handoff', file: p.file, line: p.line, note: clip(p.note || 'step', 300) }));
+        const rec = {
+            fingerprint: `${ids[0]}:${tail}`, kind: 'fail', sec_ids: ids, title: clip(`${ev.method === 'sandbox_test' ? 'Proven by test' : 'Confirmed lead'}: ${c.claim}`, 160), class: 'finding', gap_in_standard: false,
+            severity: highest(ids.map((id) => kit.byId.get(id).severity)), confidence: 'SUSPECTED', demonstrated: false,
+            root_cause: clip(c.claim, 120), raised_by: [ev.method === 'sandbox_test' ? 'hullproof-prove' : 'hullproof-hunt'],
+            impact_statement: clip(`${c.claim} ${ev.method === 'sandbox_test' ? 'The engine proved it with' : 'A model proposed this and the engine confirmed it with'} ${METHOD[ev.method]}: ${ev.detail}.${lend.checks.length && ids.length ? ` The lead named no requirement, so the requirement is taken from ${lend.checks.join(', ')}, which flagged this entry point.` : ''}`, 600),
+            remediation: { strategy: clip(`Fix the code at ${c.sink.file}:${c.sink.line} so it meets ${ids.join(', ')}: ${first.title}.`, 800), confirm: ev.method === 'sandbox_test' ? 'Run hullproof prove again after the fix, then hullproof report. The finding is gone when the test no longer shows the flaw. Test the fixed request by hand as well.' : 'Run hullproof hunt with --replay and then hullproof report again. The finding is gone when the lead no longer confirms. Test the fixed request by hand as well.' },
+            evidence: c.path.slice(0, 8).map((p) => ({ file: p.file, line: p.line, note: clip(p.note || 'step', 300) })),
+            trace: trace.slice(0, 12),
+            machine_evidence: { tool: ev.tool, rule_id: ev.rule_id, tool_version: ev.tool_version, config_sha256: ev.config_sha256 },
+        };
+        records.push(rec);
+        inGate.push(c);
+        for (const id of ids) {
+            const old = rows.get(id);
+            if (old?.result === 'FAIL')
+                continue;
+            rows.set(id, { id, result: 'FAIL', notes: clip(`Failed by ${ev.method === 'sandbox_test' ? 'a finding proven by test' : 'hunt lead confirmed by'} ${ev.rule_id} at ${c.sink.file}:${c.sink.line}.`, 600) });
+        }
+    }
+    records.sort((a, b) => cmp(a.fingerprint, b.fingerprint));
+    // A BLOCKER or CRITICAL record needs a verifier outcome in a complete run. No verifier ran, so such a run is recorded the way the
+    // scan records it: incomplete, reason deterministic_only, with the agent calls of the kit's own audit at 0. The model calls of the
+    // hunt are counted in hunt/result.json, not here.
+    const needsVerifier = records.some((r) => r.kind === 'fail' && r.sec_ids.some((id) => { const v = kit.byId.get(id)?.severity; return v === 'BLOCKER' || v === 'CRITICAL'; }));
+    const report = needsVerifier && s.findings.report.run_status === 'complete' ? { ...s.findings.report, run_status: 'incomplete', incomplete_reason: 'deterministic_only' } : s.findings.report;
+    const findings = { ...s.findings, report, records };
+    return { results: [...rows.values()].sort((a, b) => cmp(a.id, b.id)), findings, findingsText: findingsMarkdown(findings, findingsJson(findings)), inGate, outOfScope, proven };
+}