hullproof 0.0.0-stage → 0.5.0

package/dist/gate/gate.js

@@ -0,0 +1,173 @@
+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;
+};
+// The release gate of STANDARD.md (G-1 to G-8 and the three outcomes), on top of the kit's own checklist gate.
+// The checklist part (G-3 to G-5 on the results rows) and the record cross checks are the kit's functions from
+// tools/hullproof/ci/hullproof-gate.mjs, imported, not copied. This file adds what the kit gate leaves out: G-1, G-2,
+// G-6, G-7, G-8, written risk acceptance within the kit's limits, and the verdict.
+// It blocks only on FAIL rows (from FAIL checks and mapped rule hits, never unmapped observations) and on requirements
+// nothing settled, exactly as the kit gate counts them.
+import { existsSync, readFileSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { cmp } from '../util.js';
+import { GATE_REL, inScope, SEV_RANK, VALIDATOR_REL } from '../report/kit.js';
+export async function loadKitGate(kitDir) {
+    const g = await import(__rewriteRelativeImportExtension(pathToFileURL(join(kitDir, GATE_REL)).href));
+    const v = await import(__rewriteRelativeImportExtension(pathToFileURL(join(kitDir, VALIDATOR_REL)).href));
+    return { evaluate: g.evaluate, collapseRows: g.collapseRows, crossChecks: g.crossChecks, isStaticPass: g.isStaticPass, validateFindingsText: v.validateFindingsText };
+}
+// Hullproof policy (STANDARD.md, Protected classes): no acceptance for credentials and secrets, authentication,
+// tenant isolation or payments. The class is read from the control's domains; authorization counts as tenant isolation.
+const PROTECTED = new Set(['secrets', 'auth', 'authorization', 'tenancy', 'payments']);
+const DAY = 86_400_000;
+const days = (a, b) => Math.round((Date.parse(b) - Date.parse(a)) / DAY);
+const isDate = (s) => typeof s === 'string' && /^\d{4}-\d{2}-\d{2}$/.test(s) && !Number.isNaN(Date.parse(s));
+function currentAcceptances(list, byId, today) {
+    const ok = new Map();
+    const problems = [];
+    let critical = 0;
+    for (const a of [...list].sort((x, y) => cmp(x.id, y.id))) {
+        const c = byId.get(a.id);
+        const bad = (why) => { problems.push(`${a.id}: acceptance not current (${why})`); };
+        if (!c) {
+            bad('not a requirement in scope');
+            continue;
+        }
+        if (c.severity === 'BLOCKER') {
+            bad('a BLOCKER is never accepted');
+            continue;
+        }
+        if (c.severity !== 'CRITICAL' && c.severity !== 'HIGH') {
+            bad('only CRITICAL and HIGH need acceptance');
+            continue;
+        }
+        if (c.domains.some((d) => PROTECTED.has(d))) {
+            bad('protected class: secrets, authentication, tenant isolation or payments');
+            continue;
+        }
+        if (![a.owner, a.approver, a.compensating_control].every((s) => typeof s === 'string' && s.trim())) {
+            bad('owner, approver and compensating control are all needed');
+            continue;
+        }
+        if (a.owner.trim().toLowerCase() === a.approver.trim().toLowerCase()) {
+            bad('the approver must not be the risk owner');
+            continue;
+        }
+        if (!isDate(a.effective) || !isDate(a.expires)) {
+            bad('effective and expires must be YYYY-MM-DD dates');
+            continue;
+        }
+        const limit = c.severity === 'CRITICAL' ? 90 : 180;
+        if (days(a.effective, a.expires) > limit) {
+            bad(`lasts more than ${limit} days`);
+            continue;
+        }
+        if (a.effective > today || a.expires < today) {
+            bad(a.expires < today ? 'expired' : 'not in effect yet');
+            continue;
+        }
+        if (c.severity === 'CRITICAL' && ++critical > 3) {
+            bad('more than 3 CRITICAL acceptances for one release');
+            continue;
+        }
+        ok.set(a.id, a);
+    }
+    return { ok, problems };
+}
+const isGated = (c) => c.severity === 'BLOCKER' || c.severity === 'CRITICAL';
+export function evaluateGate(g) {
+    const scoped = g.controls.filter((c) => inScope(c, g.scope));
+    const byId = new Map(scoped.map((c) => [c.id, c]));
+    const problems = [];
+    // Rows: the engine's, then the owner's for anything the engine did not FAIL.
+    const engine = new Map(g.rows.map((r) => [r.id, r]));
+    for (const r of g.owner?.results ?? []) {
+        if (engine.get(r.id)?.result === 'FAIL')
+            continue;
+        engine.set(r.id, r);
+    }
+    const rows = [...engine.values()].sort((a, b) => cmp(a.id, b.id)).map((r) => [r.id, r.result, r.notes]);
+    // The kit's checklist gate on the in scope controls; scope 'all' because the stage filter is already applied.
+    const { counts, ok } = g.kitGate.evaluate(scoped, rows, 'all');
+    const checklistLine = `hullproof checklist (${g.scope.edition}, ${g.scope.stage}): checked ${counts.checked}, pass ${counts.pass}, not applicable ${counts.notApplicable}, fail ${counts.fail}, not assessed ${counts.notAssessed} (missing rows ${counts.missing}, PASS (static) rejected ${counts.passStaticRejected}, NOT APPLICABLE without a reason ${counts.naWithoutReason}), duplicate rows ${counts.duplicates}, unknown ids ${counts.unknownIds}`;
+    // The findings record: validated by the kit, then cross checked against the rows by the kit.
+    // Validation and cross checks see every known requirement: an observation may name one outside this run's scope.
+    const all = new Map(g.controls.map((c) => [c.id, c]));
+    const v = g.kitGate.validateFindingsText(g.findingsText, { controls: all });
+    if (v.c.errorCount)
+        problems.push(...v.c.lines().map((l) => `findings ${l}`));
+    const findings = v.data;
+    const { got } = g.kitGate.collapseRows(rows);
+    if (findings && !v.c.errorCount)
+        problems.push(...g.kitGate.crossChecks(all, got, findings).problems);
+    const runSupportsReady = !!findings && findings.report.run_status === 'complete' && findings.report.scope === 'full' && findings.report.profile !== 'quick';
+    // Open gated items, the same way the kit's evaluate counts them.
+    const open = [];
+    for (const c of scoped.filter(isGated)) {
+        const r = got.get(c.id);
+        const settled = r !== undefined && ((r.state === 'PASS' && !(g.kitGate.isStaticPass(r.raw) && c.authority !== 'repo')) || (r.state === 'NOT APPLICABLE' && r.note !== ''));
+        if (!settled)
+            open.push({ id: c.id, severity: c.severity, state: r?.raw ?? 'missing row', accepted: false });
+    }
+    if ((open.length === 0) !== ok)
+        problems.push('internal: the open item list does not agree with the kit gate');
+    const acc = currentAcceptances(g.owner?.acceptances ?? [], byId, g.today);
+    for (const o of open)
+        if (o.severity === 'CRITICAL' && acc.ok.has(o.id))
+            o.accepted = true;
+    const highFails = (findings?.records ?? []).filter((r) => r.kind === 'fail' && r.severity === 'HIGH')
+        .flatMap((r) => (r.kind === 'fail' ? r.sec_ids : [])).filter((id) => byId.get(id)?.severity === 'HIGH');
+    const highOpen = [...new Set(highFails)].filter((id) => !acc.ok.has(id)).sort(cmp);
+    const used = [...new Set([...open.filter((o) => o.accepted).map((o) => o.id), ...highFails.filter((id) => acc.ok.has(id))])].sort(cmp);
+    const stagePath = join(g.repo, 'docs/security/STAGE.md');
+    const inRepo = (p) => { if (!p)
+        return null; const abs = resolve(g.repo, p); return abs.startsWith(resolve(g.repo)) && existsSync(abs) ? abs : null; };
+    const report = inRepo(g.owner?.audit_report);
+    const rollback = inRepo(g.owner?.rollback);
+    const ranOk = (t) => g.metas.some((m) => m.tool === t && m.status === 'ran' && m.files_scanned !== 0);
+    const g7missing = ['gitleaks', 'semgrep', 'osv-scanner'].filter((t) => !ranOk(t));
+    const blockerOpen = open.filter((o) => o.severity === 'BLOCKER');
+    const blockerFail = blockerOpen.filter((o) => o.state.toUpperCase().startsWith('FAIL'));
+    const criticalOpen = open.filter((o) => o.severity === 'CRITICAL' && !o.accepted);
+    const conditions = [
+        { id: 'G-1', met: existsSync(stagePath) && g.scope.stageSource === 'STAGE.md', why: existsSync(stagePath) ? (g.scope.stageSource === 'STAGE.md' ? `stage ${g.scope.stage} recorded in docs/security/STAGE.md` : 'docs/security/STAGE.md names no stage') : 'docs/security/STAGE.md is missing' },
+        { id: 'G-2', met: !!report && readFileSync(report, 'utf8').includes(g.commit), why: report ? (readFileSync(report, 'utf8').includes(g.commit) ? 'audit report names this commit' : 'the audit report does not name this commit') : 'no audit report supplied (owner file, audit_report)' },
+        { id: 'G-3', met: blockerFail.length === 0, why: blockerFail.length ? `${blockerFail.length} BLOCKER requirement(s) FAIL` : 'no BLOCKER requirement FAILs' },
+        { id: 'G-4', met: blockerOpen.length === 0, why: blockerOpen.length ? `${blockerOpen.length} BLOCKER requirement(s) open (FAIL or NOT ASSESSED)` : 'every BLOCKER requirement is settled' },
+        { id: 'G-5', met: criticalOpen.length === 0, why: criticalOpen.length ? `${criticalOpen.length} CRITICAL requirement(s) open and not under a current acceptance` : 'every CRITICAL requirement is settled or accepted' },
+        g.scope.edition === 'free'
+            ? { id: 'G-6', met: true, why: 'outside the free scope' }
+            : { id: 'G-6', met: highOpen.length === 0, why: highOpen.length ? `${highOpen.length} HIGH requirement(s) with a fail record and no current acceptance` : 'no open HIGH finding' },
+        { id: 'G-7', met: g7missing.length === 0, why: g7missing.length ? `did not run on this commit: ${g7missing.join(', ')}` : 'gitleaks, semgrep and osv-scanner ran on this commit' },
+        { id: 'G-8', met: !!rollback, why: rollback ? 'rollback path supplied' : 'no rollback path supplied (owner file, rollback)' },
+    ];
+    const allMet = conditions.every((c) => c.met) && runSupportsReady;
+    const verdict = !allMet ? 'NOT READY' : used.length ? 'READY WITH ACCEPTED RISK' : 'READY';
+    const label = verdict !== 'NOT READY' && g.scope.edition === 'free' ? `${verdict} (FREE SCOPE)` : verdict;
+    return {
+        verdict, label, exit: problems.length ? 2 : verdict === 'NOT READY' ? 1 : 0, problems, conditions, counts,
+        open: open.sort((a, b) => SEV_RANK[b.severity] - SEV_RANK[a.severity] || cmp(a.id, b.id)), acceptancesUsed: used, acceptanceProblems: acc.problems,
+        runSupportsReady, checklistLine,
+    };
+}
+export function gateLines(o) {
+    const lines = [o.checklistLine];
+    for (const c of o.conditions)
+        lines.push(`${c.id}: ${c.met ? 'met' : 'not met'}, ${c.why}`);
+    if (!o.runSupportsReady)
+        lines.push('note: this run cannot support READY (the findings record says the run is incomplete, partial or quick)');
+    for (const p of o.acceptanceProblems)
+        lines.push(`note: ${p}`);
+    if (o.problems.length) {
+        lines.push('RESULT: stopped, the records or a cross check need attention (exit 2)');
+        return lines;
+    }
+    lines.push(`RESULT: ${o.label}`);
+    return lines;
+}

package/dist/hooks/install.js

@@ -0,0 +1,153 @@
+// hullproof hooks install and uninstall: a git pre-commit hook for plain git, a Husky entry, or a pre-commit framework entry.
+// The hook only calls `hullproof hooks run` (src/hooks/run.ts). Only exit code 1 from it blocks a commit; a missing command or an
+// engine error lets the commit through, because the hook must never be the reason a team cannot work. `git commit --no-verify` skips it.
+import { chmodSync, existsSync, mkdirSync, readFileSync, realpathSync, rmSync, writeFileSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { spawnSync } from 'node:child_process';
+export const MARKER_BEGIN = '# >>> hullproof >>>';
+export const MARKER_END = '# <<< hullproof <<<';
+const HOOK_TAG = '# hullproof pre-commit hook';
+const sh = (s) => `'${s.replace(/'/g, `'\\''`)}'`;
+const git = (repo, ...a) => {
+    const r = spawnSync('git', ['-C', repo, ...a], { encoding: 'utf8' });
+    return r.status === 0 ? r.stdout.trim() : null;
+};
+export function detect(repo) {
+    const root = git(repo, 'rev-parse', '--show-toplevel');
+    if (!root)
+        return `${resolve(repo)} is not inside a git repository`;
+    const hooksPath = git(root, 'config', '--get', 'core.hooksPath');
+    let pkgHusky = false;
+    try {
+        const p = JSON.parse(readFileSync(join(root, 'package.json'), 'utf8'));
+        pkgHusky = !!(p.devDependencies?.husky || p.dependencies?.husky);
+    }
+    catch { /* no package.json */ }
+    const husky = existsSync(join(root, '.husky')) || pkgHusky || (hooksPath ?? '').replace(/^\.\//, '').startsWith('.husky');
+    const framework = existsSync(join(root, '.pre-commit-config.yaml'));
+    return { root, husky, framework, hooksPath, huskyV8: existsSync(join(root, '.husky/_/husky.sh')), mode: husky ? 'husky' : framework ? 'pre-commit' : 'git' };
+}
+// How the hook calls the engine: `hullproof` when it is on PATH now, else this very engine through node, by absolute path.
+export function runner() {
+    const onPath = spawnSync('sh', ['-c', 'command -v hullproof'], { encoding: 'utf8' });
+    if (onPath.status === 0 && onPath.stdout.trim())
+        return 'hullproof';
+    let cli = process.argv[1] ?? '';
+    try {
+        cli = realpathSync(cli);
+    }
+    catch { /* keep as given */ }
+    return `${sh(process.execPath)} ${sh(cli)}`;
+}
+const callLines = (cmd) => [
+    `${cmd} hooks run`,
+    'status=$?',
+    // Only a block (1) stops the commit. 127 (command not found) and any other code let it through.
+    'if [ "$status" -eq 1 ]; then exit 1; fi',
+];
+export const plainHook = (cmd) => ['#!/bin/sh', `${HOOK_TAG}. Installed by hullproof hooks install, removed by hullproof hooks uninstall.`, '# Skip it once with: git commit --no-verify', ...callLines(cmd), 'exit 0', ''].join('\n');
+export const huskyBlock = (cmd) => [MARKER_BEGIN, ...callLines(cmd), MARKER_END, ''].join('\n');
+export const frameworkBlock = (cmd) => [
+    `  ${MARKER_BEGIN}`,
+    '  - repo: local',
+    '    hooks:',
+    '      - id: hullproof',
+    '        name: hullproof (secrets and blocking findings in staged files)',
+    `        entry: ${cmd} hooks run`,
+    '        language: system',
+    '        pass_filenames: false',
+    '        always_run: true',
+    `  ${MARKER_END}`, '',
+].join('\n');
+const stripBlock = (text) => {
+    const re = new RegExp(`\\n?[ \\t]*${MARKER_BEGIN.replace(/[>]/g, '\\>')}[\\s\\S]*?${MARKER_END.replace(/[<]/g, '\\<')}\\n?`, 'g');
+    return text.replace(re, '\n').replace(/\n{3,}/g, '\n\n');
+};
+export function installHooks(o) {
+    const d = detect(o.repo);
+    if (typeof d === 'string')
+        return { code: 2, lines: [`hullproof hooks: ${d}`] };
+    const mode = o.mode ?? d.mode;
+    const lines = [`hullproof hooks: mode ${mode}${o.mode ? '' : ` (detected: Husky ${d.husky ? 'yes' : 'no'}, pre-commit framework ${d.framework ? 'yes' : 'no'})`}`];
+    const cmd = runner();
+    const write = (path, text, exec = false) => {
+        if (o.dryRun) {
+            lines.push(`would write ${path}`);
+            return;
+        }
+        mkdirSync(dirname(path), { recursive: true });
+        writeFileSync(path, text);
+        if (exec)
+            chmodSync(path, 0o755);
+        lines.push(`wrote ${path}`);
+    };
+    if (mode === 'git') {
+        const hooksDir = git(d.root, 'rev-parse', '--git-path', 'hooks');
+        if (!hooksDir)
+            return { code: 2, lines: [...lines, 'hullproof hooks: could not find the git hooks folder'] };
+        const path = resolve(d.root, hooksDir, 'pre-commit');
+        const current = existsSync(path) ? readFileSync(path, 'utf8') : null;
+        if (o.uninstall) {
+            if (current === null)
+                lines.push('no pre-commit hook to remove');
+            else if (!current.includes(HOOK_TAG))
+                return { code: 2, lines: [...lines, `${path} is not a Hullproof hook, so it was left alone`] };
+            else if (o.dryRun)
+                lines.push(`would remove ${path}`);
+            else {
+                rmSync(path);
+                lines.push(`removed ${path}`);
+            }
+            return { code: 0, lines };
+        }
+        if (current !== null && !current.includes(HOOK_TAG)) {
+            return { code: 2, lines: [...lines, `${path} already exists and is not a Hullproof hook. It was not changed.`, 'Add this to it, or use the Husky or pre-commit framework mode:', ...callLines(cmd)] };
+        }
+        write(path, plainHook(cmd), true);
+        return { code: 0, lines };
+    }
+    if (mode === 'husky') {
+        const path = join(d.root, '.husky/pre-commit');
+        const current = existsSync(path) ? readFileSync(path, 'utf8') : null;
+        if (o.uninstall) {
+            if (current === null || !current.includes(MARKER_BEGIN))
+                lines.push('no Hullproof entry in .husky/pre-commit');
+            else
+                write(path, stripBlock(current));
+            return { code: 0, lines };
+        }
+        if (current?.includes(MARKER_BEGIN)) {
+            lines.push('.husky/pre-commit already has the Hullproof entry');
+            return { code: 0, lines };
+        }
+        const head = current ?? `#!/usr/bin/env sh\n${d.huskyV8 ? '. "$(dirname -- "$0")/_/husky.sh"\n' : ''}`;
+        write(path, `${head.replace(/\n*$/, '\n')}${huskyBlock(cmd)}`, true);
+        return { code: 0, lines };
+    }
+    // pre-commit framework
+    const path = join(d.root, '.pre-commit-config.yaml');
+    const current = existsSync(path) ? readFileSync(path, 'utf8') : null;
+    if (o.uninstall) {
+        if (current === null || !current.includes(MARKER_BEGIN))
+            lines.push('no Hullproof entry in .pre-commit-config.yaml');
+        else
+            write(path, stripBlock(current));
+        return { code: 0, lines };
+    }
+    if (current?.includes(MARKER_BEGIN)) {
+        lines.push('.pre-commit-config.yaml already has the Hullproof entry');
+        return { code: 0, lines };
+    }
+    const block = frameworkBlock(cmd);
+    // The entry is appended at the end of the file, which is only right when `repos:` is the last top level key and a block list.
+    const topKeys = (current ?? '').split('\n').filter((l) => /^[A-Za-z_][\w-]*\s*:/.test(l));
+    const last = topKeys.at(-1) ?? '';
+    const appendable = current === null || (/^repos\s*:\s*$/.test(last) && last === topKeys.find((k) => k.startsWith('repos')));
+    if (!appendable) {
+        return { code: 0, lines: [...lines, 'could not add the entry safely (the file has keys after `repos:` or a flow style list). Add this under `repos:` yourself:', '', block.replace(/^ {2}# .*\n/gm, '')] };
+    }
+    const base = current ?? 'repos:\n';
+    write(path, `${base.replace(/\n*$/, '\n')}${block}`);
+    lines.push('run `pre-commit install` once so the framework runs it on each commit');
+    return { code: 0, lines };
+}

package/dist/hooks/run.js

@@ -0,0 +1,112 @@
+// hullproof hooks run: the fast check the pre-commit hook calls. It looks at the staged files only, for two things: a secret, and a
+// finding of the highest severity (BLOCKER) that a deterministic check or a mapped Semgrep rule raises in a staged file.
+// Nothing leaves the machine: no network, no model, no upload. The staged content is exported from the index into a temporary
+// folder, so the check sees what the commit will hold and not the working tree. Findings in files that are not staged never block.
+// Exit 0 pass, 1 blocked. Any error is reported and lets the commit through (fail open), unless HULLPROOF_HOOK_STRICT=1.
+import { copyFileSync, existsSync, mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join, resolve } from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { makeContext } from '../checks/context.js';
+import { checkSha, loadChecks, runChecks } from '../checks/run.js';
+import { discover } from '../discover/discover.js';
+import { buildFindings } from '../report/build.js';
+import { loadKit, readStage, resolveKitDir } from '../report/kit.js';
+import { RULES_DIR } from '../scanners/common.js';
+import { runScanner } from '../scanners/index.js';
+import { adapter as gitleaks } from '../scanners/gitleaks.js';
+import { adapter as semgrep } from '../scanners/semgrep.js';
+import { SEV_RANK } from '../report/kit.js';
+const SOURCE_FILES = /\.(js|mjs|cjs|ts|jsx|tsx|py|rb|php|go|java|kt|swift|yaml|yml|json|sql|tf|html)$/;
+const git = (repo, args, extra = {}) => {
+    // --no-ext-diff and --no-textconv are given where they matter, so a driver named in the repository configuration cannot run.
+    const r = spawnSync('git', ['-C', repo, ...args], { encoding: 'utf8', maxBuffer: 256 * 1024 * 1024, env: { ...process.env, GIT_TERMINAL_PROMPT: '0', GIT_OPTIONAL_LOCKS: '0', ...extra } });
+    return { ok: r.status === 0, out: r.stdout ?? '' };
+};
+export async function runHook(o) {
+    const started = Date.now();
+    const top = git(o.repo, ['rev-parse', '--show-toplevel']);
+    if (!top.ok)
+        return { code: 2, lines: ['hullproof: not inside a git repository'] };
+    const root = top.out.trim();
+    const staged = git(root, ['diff', '--cached', '--name-only', '--diff-filter=ACMR', '--no-ext-diff', '--no-textconv', '-z']).out.split('\0').filter(Boolean).sort();
+    if (staged.length === 0)
+        return { code: 0, lines: [] };
+    const stagedSet = new Set(staged);
+    const tmp = mkdtempSync(join(tmpdir(), 'hullproof-hook-'));
+    try {
+        const tree = join(tmp, 'tree');
+        mkdirSync(tree);
+        // The index as it will be committed, exported to a folder; its index file is copied so checks that ask which files git tracks
+        // get the right answer.
+        const exp = git(root, ['checkout-index', '-a', '-f', `--prefix=${tree}/`]);
+        if (!exp.ok)
+            throw new Error('could not read the staged files from the git index');
+        const idxPath = resolve(root, git(root, ['rev-parse', '--git-path', 'index']).out.trim());
+        mkdirSync(join(tree, '.git'));
+        if (existsSync(idxPath))
+            copyFileSync(idxPath, join(tree, '.git/index'));
+        writeFileSync(join(tree, '.git/HEAD'), 'ref: refs/heads/hook\n');
+        const kitDir = resolveKitDir(root, o.kit);
+        const kit = kitDir ? loadKit(kitDir) : null;
+        const edition = kit?.controls.some((c) => c.edition === 'pro') ? 'pro' : 'free';
+        const stack = discover(tree);
+        const controlsPath = kitDir ? join(kitDir, 'docs/hullproof/security-controls.json') : undefined;
+        const scanOpts = (extra = {}) => ({ repo: tree, out: join(tmp, 'out'), stack, allowNetwork: false, edition, history: false, kit: kitDir, controlsPath, ...extra });
+        const metas = [];
+        const hits = [];
+        const notes = [];
+        const run = (a, extra = {}) => {
+            const s = runScanner(a, scanOpts(extra));
+            metas.push(s.meta);
+            hits.push(...s.hits.hits);
+            if (s.meta.status !== 'ran')
+                notes.push(`${a.tool} did not run (${s.meta.status})`);
+        };
+        // 1. Secrets, which is the quick part: Gitleaks over the exported tree, kept to the staged files.
+        run(gitleaks);
+        const secretHits = hits.filter((h) => stagedSet.has(h.file));
+        const secretsBlock = blockers(secretHits, EMPTY, kit, edition, tree, metas, stagedSet);
+        if (secretsBlock.length || (secretHits.length && !kit)) {
+            const lines = secretsBlock.length ? render(secretsBlock) : secretHits.map((h) => `  BLOCKER ${h.file}:${h.line}  a secret shaped value (rule ${h.rule_id})`);
+            return done(1, lines, staged.length, started, notes);
+        }
+        if (!kit)
+            return done(0, [], staged.length, started, [...notes, 'no kit was found (pass --kit or set HULLPROOF_KIT), so only secrets were checked']);
+        // 2. Blocking findings from the deterministic checks and, when it is on, Semgrep on the staged source files.
+        const sources = staged.filter((f) => SOURCE_FILES.test(f));
+        if (o.semgrep && sources.length)
+            run(semgrep, { targets: sources });
+        const ctx = makeContext(tree, stack, hits, kitDir);
+        const checkDefs = loadChecks();
+        const checks = runChecks(ctx, checkDefs);
+        const found = blockers(hits.filter((h) => stagedSet.has(h.file)), checks, kit, edition, tree, metas, stagedSet, checkDefs);
+        return found.length ? done(1, render(found), staged.length, started, notes) : done(0, [], staged.length, started, notes);
+    }
+    finally {
+        rmSync(tmp, { recursive: true, force: true });
+    }
+}
+const EMPTY = { schema_version: '1.0.0', commit: null, results: [], not_run: [] };
+// Fail records of BLOCKER severity that point at a staged file. The same record builder the scan uses, so a rule or a check gives
+// the same title, requirement and fix here as in the report.
+function blockers(hits, checks, kit, edition, tree, metas, staged, defs = []) {
+    if (!kit)
+        return [];
+    const input = {
+        kit, scope: { edition, stage: readStage(tree).stage, stageSource: 'default' }, git: { commit: '0'.repeat(40), tree: '0'.repeat(40), clean: false },
+        checks, hits, metas, checkShas: Object.fromEntries(defs.map((c) => [c.id, checkSha(c)])), rulesDirs: [join(RULES_DIR, 'semgrep')],
+    };
+    const { file } = buildFindings(input);
+    return file.records.filter((r) => r.kind === 'fail' && SEV_RANK[r.severity] >= SEV_RANK.BLOCKER && r.evidence.some((e) => staged.has(e.file)));
+}
+const render = (fs) => fs.flatMap((f) => {
+    const e = f.evidence.find((x) => x.file) ?? f.evidence[0];
+    return [`  ${f.severity} ${e ? `${e.file}:${e.line}` : ''}  ${f.title} (${f.sec_ids.join(', ')})`, `    Fix: ${f.remediation.strategy}`];
+});
+function done(code, problems, n, started, notes) {
+    const secs = ((Date.now() - started) / 1000).toFixed(1);
+    const lines = [...(code === 1 ? [`hullproof: BLOCKED, ${problems.filter((l) => l.startsWith('  ') && !l.startsWith('    ')).length} problem(s) in the staged files`, ...problems] : []), ...notes.map((x) => `hullproof: note: ${x}`),
+        `hullproof: checked ${n} staged file${n === 1 ? '' : 's'} in ${secs}s on this machine, nothing was sent anywhere.${code === 1 ? ' To commit anyway: git commit --no-verify' : ''}`];
+    return { code, lines };
+}

package/dist/map/analyze.js

@@ -0,0 +1,201 @@
+import { scanFile } from '../checks/code/webhook-verify.js';
+import { EXITS, ifBody } from '../checks/code/shared.js';
+import { dataTouches, outboundCalls } from './touches.js';
+import { taintOf } from './taint.js';
+import { AUDIT, AUTH_PACKAGES, RATE, RATE_PACKAGES, ROLE_JS, ROLE_PY, SESSION_JS, SESSION_PY, SIGNATURE, VALIDATION_JS, VALIDATION_PY, } from './vocab.js';
+const usesText = (re) => /['"`]/.test(re.source);
+const CONF_RANK = { high: 0, medium: 1, low: 2 };
+const minConf = (a, b) => (CONF_RANK[a] >= CONF_RANK[b] ? a : b);
+function facts(kind, pats, view, from, to, scope, upgrade, viaPrefix = '') {
+    const out = [];
+    const seen = new Set();
+    const masked = view.masked.slice(from, to);
+    const text = view.text.slice(from, to);
+    for (const p of pats) {
+        p.re.lastIndex = 0;
+        const m = p.re.exec(usesText(p.re) ? text : masked);
+        if (!m || seen.has(p.via))
+            continue;
+        const ln = view.lines.at(from + m.index);
+        if (out.some((o) => o.line === ln))
+            continue;
+        seen.add(p.via);
+        const conf = upgrade && p.confidence === 'medium' ? 'high' : p.confidence;
+        out.push({ kind, scope, file: view.file, line: ln, via: viaPrefix + p.via, enforced: null, confidence: viaPrefix ? minConf(conf, 'medium') : conf });
+    }
+    return out;
+}
+// Whether a failed check provably stops the request. true: the check sits in an if whose body exits, or it is a throwing
+// guard (require..., a decorator). false: it is tested and the body does not exit. null: cannot tell.
+function enforcedFor(view, at, via) {
+    const { text } = view;
+    const lineStart = text.lastIndexOf('\n', at) + 1;
+    const lineEnd = text.indexOf('\n', at) < 0 ? text.length : text.indexOf('\n', at);
+    const before = text.slice(lineStart, at);
+    if (/^@|decorator|Depends|permission_classes|login/.test(via) && /(^|\n)\s*@|Depends\s*\(|permission_classes/.test(text.slice(lineStart, lineEnd)))
+        return true;
+    const ifAt = /\b(?:if|unless|elif|assert)\b/.exec(before);
+    if (ifAt) {
+        const body = view.lang === 'py' ? text.slice(lineStart + ifAt.index, Math.min(text.length, lineEnd + 400)).split('\n').slice(0, 4).join('\n') : ifBody(text, lineStart + ifAt.index);
+        return EXITS.test(body);
+    }
+    if ((/\b(?:require|ensure|assert)\w*/i.test(via) || /^local (?:auth|role) helper$/.test(via)) && !/=/.test(before))
+        return true;
+    const lhs = /(?:\b(?:const|let|var|val)\s+)?(\{[^}]*(?:\{[^}]*\}[^}]*)*\}|\[[^\]]*\]|[A-Za-z_$][\w$]*)\s*(?::[^=\n]+)?=\s*(?:await\s+)?[\w.$]*\s*$/.exec(before);
+    if (!lhs)
+        return null;
+    const names = [...lhs[1].matchAll(/[A-Za-z_$][\w$]*/g)].map((x) => x[0]).filter((n) => !['const', 'let', 'var', 'data', 'error', 'session'].includes(n) || lhs[1] === n);
+    const rest = text.slice(lineEnd, Math.min(text.length, lineEnd + 1500));
+    for (const n of names) {
+        const guard = view.lang === 'py'
+            ? new RegExp(`\\bif\\s+(?:not\\s+${n}\\b|${n}\\s+is\\s+None|${n}\\s*==\\s*None)`)
+            : new RegExp(`\\bif\\s*\\(\\s*(?:!\\s*${n}\\b|${n}\\s*(?:===?|==)\\s*(?:null|undefined)\\b|!\\s*${n}\\s*\\|\\||!${n}\\?)`);
+        const g = guard.exec(rest);
+        if (!g)
+            continue;
+        const body = view.lang === 'py' ? rest.slice(g.index, g.index + 300).split('\n').slice(0, 4).join('\n') : ifBody(rest, g.index);
+        return EXITS.test(body);
+    }
+    return null;
+}
+const READS = [
+    ['body', /\b(?:req|request|ctx\.request|c\.req)\s*\.\s*(?:body|json|get_json|data|text)\b|\bawait\s+\w+\.json\s*\(\)|\bJSON\.parse\s*\(\s*(?:raw|body|await)/, false],
+    ['query', /\b(?:req|request)\.(?:query|args|GET|query_params|nextUrl)\b|\bsearchParams\b|\bc\.req\.query\b|\bctx\.query\b|\bparse_qs\b/, false],
+    ['params', /\b(?:req|request|ctx|c\.req)\.params?\b|\bparams\s*[.\[]|\bc\.req\.param\b|\bview_args\b|\bkwargs\b|\bPath\s*\(/, false],
+    ['headers', /\b(?:req|request)\.headers\b|\bheaders\s*\(\s*\)|\bc\.req\.header\b|\bgetHeader\s*\(|\brequest\.META\b/, false],
+    ['cookies', /\b(?:req|request)\.cookies\b|\bcookies\s*\(\s*\)|\bgetCookie\s*\(|\bc\.req\.cookie\b/, false],
+    ['form', /\bformData\b|\brequest\.form\b|\brequest\.POST\b|\bFormData\s*\(|\bmultipart\b/i, false],
+    ['file', /\.get\s*\(\s*['"](?:file|files|upload|image|avatar|attachment|document|photo)s?['"]\s*\)|\bas\s+File\b|\bmulter\b|\breq\.files?\b|\brequest\.files\b|\bformidable\b|\bbusboy\b|\binstanceof\s+File\b|\bUploadFile\b|\brequest\.FILES\b|\.file\s*\(\s*['"]|\bupload\.(?:single|array|fields|any)\b|\bFileInterceptor\b|\bFilesInterceptor\b|\bgetAll\s*\(\s*['"]file/, false],
+];
+function readsOf(view, from, to) {
+    const masked = view.masked.slice(from, to);
+    const out = [];
+    for (const [source, re] of READS) {
+        const m = re.exec(masked);
+        if (m)
+            out.push({ source, line: view.lines.at(from + m.index) });
+    }
+    return out;
+}
+const PARSE_CALL = /\bawait\s+\w+\.json\s*\(\)|\b(?:req|request)\.(?:json|get_json)\s*\(|\bJSON\.parse\s*\(|\bjson\.loads\s*\(|\.formData\s*\(\)|\brequest\.(?:json|form)\b/;
+// A helper body that turns a request away: an error status, a throw, an abort or a redirect.
+const REJECT = /\b(?:401|403|unauthori[sz]ed|forbidden)\b|\bthrow\b|\braise\b|\babort\s*\(|\bnext\s*\(\s*(?:new\s+)?\w*Error|\bcreateError\b|\bHTTPException\b|\bPermissionDenied\b|\bAuthenticationFailed\b|\bredirect\s*\(|\bstatus\s*\(\s*4\d\d|\bdenyAll\b/i;
+const CALL = /(?<![.\w$])([A-Za-z_$][\w$]*)\s*\(/g;
+const SKIP_CALLS = new Set(['if', 'for', 'while', 'switch', 'function', 'return', 'catch', 'await', 'async', 'typeof', 'new', 'super', 'require', 'import', 'print', 'len', 'str', 'int', 'dict', 'list', 'set', 'tuple', 'range', 'isinstance', 'type', 'super', 'sorted', 'map', 'filter', 'json', 'Number', 'String', 'Boolean', 'Array', 'Object', 'Date', 'Promise', 'Error', 'parseInt', 'parseFloat', 'setTimeout', 'fetch', 'def', 'class', 'with', 'except', 'elif', 'lambda', 'not', 'and', 'or']);
+export function analyze(view, spec, helpers) {
+    const lang = view.lang;
+    const { start, end } = spec;
+    const upgradeSession = AUTH_PACKAGES.test(view.imports);
+    const upgradeRate = RATE_PACKAGES.test(view.imports);
+    const local = helpers.local ?? null;
+    const sessionPats = [...(lang === 'js' ? SESSION_JS : SESSION_PY), ...(local?.auth ? [local.auth] : [])];
+    const rolePats = [...(lang === 'js' ? ROLE_JS : ROLE_PY), ...(local?.role ? [local.role] : [])];
+    const valPats = lang === 'js' ? VALIDATION_JS : VALIDATION_PY;
+    const prot = [];
+    const own = (kind, pats, upgrade) => {
+        for (const f of facts(kind, pats, view, start, end, 'handler', upgrade)) {
+            prot.push({ ...f, enforced: kind === 'session_read' || kind === 'role_check' ? enforcedFor(view, firstIndex(view, start, end, pats, f.via, start), f.via) : null });
+        }
+    };
+    own('session_read', sessionPats, upgradeSession);
+    own('role_check', rolePats, false);
+    own('rate_limit', RATE, upgradeRate);
+    own('input_validation', valPats, false);
+    own('audit_log', AUDIT, false);
+    // Signature checks: where it is, whether a failed check stops the request, and whether the body is parsed first.
+    const sig = facts('signature_verify', SIGNATURE, view, start, end, 'handler', false);
+    if (sig.length) {
+        const region = view.text.slice(start, end);
+        const bad = scanFile(view.file, region);
+        const onlyMissing = bad.length > 0 && bad.every((b) => /^no call that checks/.test(b.note));
+        const enforced = bad.length === 0 ? true : onlyMissing ? null : false;
+        const first = sig.reduce((a, b) => (a.line <= b.line ? a : b));
+        const parse = PARSE_CALL.exec(view.masked.slice(start, end));
+        const parseLine = parse ? view.lines.at(start + parse.index) : null;
+        for (const f of sig)
+            prot.push({ ...f, enforced, after_parse: parseLine !== null && parseLine < first.line });
+    }
+    // Decorators, middleware and wrappers outside the handler body.
+    const extra = new Set(spec.extraCalls ?? []);
+    for (const d of spec.decorators ?? []) {
+        const dv = d.view;
+        const dl = dv.lang;
+        const keep = (kind, pats, up) => { for (const f of facts(kind, pats, dv, d.start, d.end, d.scope, up))
+            prot.push({ ...f, enforced: kind === 'session_read' || kind === 'role_check' ? (f.confidence === 'high' ? true : null) : null }); };
+        keep('session_read', [...(dl === 'js' ? SESSION_JS : SESSION_PY), ...(local?.auth ? [local.auth] : [])], AUTH_PACKAGES.test(dv.imports));
+        keep('role_check', [...(dl === 'js' ? ROLE_JS : ROLE_PY), ...(local?.role ? [local.role] : [])], false);
+        keep('rate_limit', RATE, RATE_PACKAGES.test(dv.imports));
+        keep('input_validation', dl === 'js' ? VALIDATION_JS : VALIDATION_PY, false);
+        keep('audit_log', AUDIT, false);
+        for (const f of facts('signature_verify', SIGNATURE, dv, d.start, d.end, d.scope, false))
+            prot.push({ ...f, enforced: null });
+        for (const m of dv.masked.slice(d.start, d.end).matchAll(CALL))
+            if (!SKIP_CALLS.has(m[1]))
+                extra.add(m[1]);
+    }
+    // One hop into the repository's own helper functions the handler calls.
+    const have = (k) => prot.some((p) => p.kind === k);
+    const names = new Set();
+    for (const m of view.masked.slice(start, end).matchAll(CALL))
+        if (!SKIP_CALLS.has(m[1]))
+            names.add(m[1]);
+    for (const n of extra)
+        names.add(n);
+    let hops = 0;
+    for (const name of [...names].sort()) {
+        if (hops >= 30)
+            break;
+        const h = helpers.find(name, view.file);
+        if (!h)
+            continue;
+        hops++;
+        const hv = h.view;
+        const hf = [
+            ['session_read', [...(hv.lang === 'js' ? SESSION_JS : SESSION_PY), ...(local?.auth ? [local.auth] : [])], AUTH_PACKAGES.test(hv.imports)],
+            ['role_check', [...(hv.lang === 'js' ? ROLE_JS : ROLE_PY), ...(local?.role ? [local.role] : [])], false], ['rate_limit', RATE, RATE_PACKAGES.test(hv.imports)],
+            ['input_validation', hv.lang === 'js' ? VALIDATION_JS : VALIDATION_PY, false], ['audit_log', AUDIT, false],
+        ];
+        for (const [kind, pats, up] of hf) {
+            if (kind === 'session_read' && have('session_read'))
+                continue;
+            if (have(kind) && kind !== 'audit_log')
+                continue;
+            const found = facts(kind, pats.filter((p) => p.confidence !== 'low'), hv, h.start, h.end, 'handler', up, `helper:${name} `);
+            if (found.length) {
+                const idx = view.masked.slice(start, end).search(new RegExp(`(?<![.\\w$])${name.replace(/\$/g, '\\$')}\\s*\\(`));
+                const at = idx < 0 ? view.lines.at(start) : view.lines.at(start + idx);
+                const rejects = REJECT.test(hv.text.slice(h.start, h.end));
+                const enforced = rejects ? true : spec.gate && (kind === 'session_read' || kind === 'role_check') ? false : null;
+                prot.push({ ...found[0], file: view.file, line: at, via: `helper:${name} ${found[0].via.replace(`helper:${name} `, '')}`, enforced });
+            }
+        }
+    }
+    // Taint, then data touches and outbound calls.
+    const maskedBody = view.masked.slice(start, end);
+    const textBody = view.text.slice(start, end);
+    const taint = taintOf(maskedBody, textBody, spec.seeds, lang, local?.auth ? [local.auth] : []);
+    const region = { masked: maskedBody, text: textBody, base: start, line: (i) => view.lines.at(start + i) };
+    const data = dataTouches(region, taint, lang);
+    const outbound = outboundCalls(region, taint, lang, spec.returnsJson ?? true, view.imports);
+    // owner_filter: a data touch that names an owner is a protection on that read or write.
+    for (const d of data)
+        if (d.owner_scoped && (d.by_id || d.request_derived || d.op !== 'read'))
+            prot.push({ kind: 'owner_filter', scope: 'handler', file: view.file, line: d.line, via: `${d.store} ${d.target ?? ''}`.trim(), enforced: null, confidence: d.store === 'sql' ? 'medium' : 'medium' });
+    prot.sort((a, b) => a.line - b.line || (a.kind < b.kind ? -1 : a.kind > b.kind ? 1 : 0) || (a.via < b.via ? -1 : a.via > b.via ? 1 : 0));
+    return { protections: dedupe(prot), reads: readsOf(view, start, end), data, outbound, taint };
+}
+function dedupe(ps) {
+    const seen = new Set();
+    return ps.filter((p) => { const k = `${p.kind}|${p.scope}|${p.line}|${p.via}`; if (seen.has(k))
+        return false; seen.add(k); return true; });
+}
+// The character index of the first match of the pattern with this `via` inside [from, to), for enforcedFor.
+function firstIndex(view, from, to, pats, via, fallback) {
+    const p = pats.find((x) => x.via === via);
+    if (!p)
+        return fallback;
+    p.re.lastIndex = 0;
+    const src = usesText(p.re) ? view.text.slice(from, to) : view.masked.slice(from, to);
+    const m = p.re.exec(src);
+    return m ? from + m.index : fallback;
+}