hullproof 0.0.0-stage → 0.5.0

package/src/report/report.ts

@@ -0,0 +1,160 @@
+// report.md: the plain English report for people who build with AI tools. Built from the scan folder only.
+// Same scan folder, same bytes: no clock, no absolute path, everything sorted.
+import { cmp } from '../util.ts';
+import { ENGINE_VERSION } from '../version.ts';
+import type { FailRecord, ObservationRecord, RouteState } from '../types/index.ts';
+import { OWNER_ACTION } from './build.ts';
+import type { GateOutcome } from '../gate/gate.ts';
+import { SEV_RANK, type Kit } from './kit.ts';
+import type { ScanFolder } from './load.ts';
+import { renderEntryPoints } from './entry-points.ts';
+import { reportSection } from '../packs/coverage.ts';
+import { renderHunt } from './hunt-section.ts';
+import { renderProve } from './prove-section.ts';
+import type { Merged } from '../confirm/merge.ts';
+
+const cell = (s: string): string => s.replace(/\|/g, '\\|').replace(/\n/g, ' ');
+const loc = (e: { file: string; line: number }): string => `\`${e.file}:${e.line}\``;
+const STATE_ORDER: RouteState[] = ['NEEDS DYNAMIC TEST', 'NEEDS DASHBOARD', 'NEEDS BUILD', 'ASK OWNER', 'ATTESTATION', 'UNKNOWN'];
+const STATE_MEANS: Record<RouteState, string> = {
+  'NEEDS DYNAMIC TEST': 'Only a test of the running app (or a staging copy) can settle these.',
+  'NEEDS DASHBOARD': 'Only a provider setting can settle these, shown by a dated export or screenshot.',
+  'NEEDS BUILD': 'Only a production build from this commit can settle these.',
+  'ASK OWNER': 'Only the owner can answer these.',
+  'ATTESTATION': 'These need a signed, dated statement.',
+  'UNKNOWN': 'These are settled by reading code, and no engine check or rule covers them yet. The engine has a code map and no model.',
+};
+
+export function renderReport(s: ScanFolder, kit: Kit, gate: GateOutcome, merged: Merged | null = null): string {
+  const out: string[] = [];
+  const p = (...l: string[]): void => { out.push(...l); };
+  const fails = s.findings.records.filter((r): r is FailRecord => r.kind === 'fail')
+    .sort((a, b) => SEV_RANK[b.severity] - SEV_RANK[a.severity] || cmp(a.fingerprint, b.fingerprint));
+  const allObs = s.findings.records.filter((r): r is ObservationRecord => r.kind === 'observation');
+  // Test code observations carry a fingerprint slug starting with test-code (src/report/build.ts).
+  const slugOf = (o: ObservationRecord): string => o.fingerprint.split(':')[2];
+  const isTest = (o: ObservationRecord): boolean => slugOf(o).startsWith('test-code-');
+  const isLead = (o: ObservationRecord): boolean => slugOf(o).startsWith('lead-');
+  const obs = allObs.filter((o) => !isTest(o) && !isLead(o));
+  const testObs = allObs.filter(isTest);
+  const leadObs = allObs.filter(isLead);
+  const count = (w: string): number => s.results.filter((r) => r.result.startsWith(w)).length;
+  const stageText = s.info.stage_source === 'STAGE.md' ? 'read from docs/security/STAGE.md' : s.info.stage_source === 'flag' ? 'set with --stage' : 'not declared, so LAUNCH is assumed';
+
+  p('# Hullproof report', '');
+  p(`Commit \`${s.info.commit}\`, tree \`${s.info.tree}\`, ${s.info.tree_clean ? 'no uncommitted changes to tracked files' : 'with uncommitted changes to tracked files (the report covers the files as they were, not the commit alone)'}. Hullproof Engine ${ENGINE_VERSION}, standard ${s.info.kit.standard_version}, ${s.info.edition} edition, stage ${s.info.stage} (${stageText}).`, '');
+  p('This report comes from code and configuration only, with no model. Every finding is a pattern match that nobody has confirmed yet, so treat each one as likely and use its check step to confirm it. A requirement that nothing settled is listed as NOT ASSESSED. That is never a pass.', '');
+
+  p(`## Verdict: ${gate.label}`, '');
+  const notMet = gate.conditions.filter((c) => !c.met);
+  if (gate.verdict === 'NOT READY') {
+    p(`The release gate is not met. ${notMet.length} of ${gate.conditions.length} conditions are open${gate.runSupportsReady ? '' : ', and a run with unconfirmed BLOCKER or CRITICAL findings cannot support READY'}. A scan of files alone can never reach READY: most BLOCKER and CRITICAL requirements are settled by provider settings, a production build or a test of the running app, which the owner supplies.`, '');
+  } else {
+    p('Every condition of the release gate is met for this commit with the evidence supplied.', '');
+  }
+  p('| Condition | Met | Why |', '|---|---|---|');
+  for (const c of gate.conditions) p(`| ${c.id} | ${c.met ? 'yes' : 'no'} | ${cell(c.why)} |`);
+  p('');
+
+  p('## Summary', '');
+  const bySev = ['BLOCKER', 'CRITICAL', 'HIGH', 'MEDIUM', 'LOW'].map((v) => [v, fails.filter((f) => f.severity === v).length] as const).filter(([, n]) => n > 0);
+  p(`1. Findings: ${fails.length}${bySev.length ? ` (${bySev.map(([v, n]) => `${n} ${v}`).join(', ')})` : ''}. In test code, reported apart and never in the gate: ${testObs.length}. Leads from rules still being measured, never in the gate: ${leadObs.length}.`);
+  p(`2. Requirements in scope: ${s.results.length}. FAIL ${count('FAIL')}, PASS (static) ${count('PASS')}, NOT ASSESSED ${count('NOT ASSESSED')}.`);
+  p(`3. Checks: ${s.info.checks.ran} ran, ${s.info.checks.not_run} did not run (listed below with the reason).`);
+  const ran = s.metas.filter((m) => m.status === 'ran').map((m) => m.tool);
+  p(`4. Scanners that ran: ${ran.length ? ran.join(', ') : 'none'}.${s.info.scanners_available ? '' : ' The scanner adapters were not available in this build, so no scanner ran.'}`);
+  const pack = s.info.rule_pack;
+  p(`5. Semgrep rule pack: ${pack ? `${pack.name}, ${pack.files.length} rule files added to the engine rules (sha256 ${pack.sha256.slice(0, 16)})` : 'none, the engine rules only'}.`, '');
+
+  p('## Findings, most severe first', '');
+  if (fails.length === 0) p('No check or mapped rule failed. That does not mean the requirements pass: see NOT ASSESSED below.', '');
+  fails.forEach((f, i) => {
+    const me = f.machine_evidence!;
+    p(`### F-${i + 1} ${f.severity}: ${f.title}`, '');
+    p(`Where: ${f.evidence.map(loc).join(', ')}`, '');
+    p(`Requirements: ${f.sec_ids.map((id) => `${id} (${kit.byId.get(id)?.title ?? 'unknown'})`).join('; ')}`, '');
+    p(`What could happen: ${f.impact_statement}`, '');
+    p(`How to fix it: ${f.remediation.strategy}`, '');
+    p(`How to check the fix: ${f.remediation.confirm}`, '');
+    p(`Found by: ${me.tool === 'hullproof-check' ? `engine check ${me.rule_id}` : `${me.tool} ${me.tool_version}, rule ${me.rule_id}`}. Each line: ${f.evidence.map((e) => `${e.file}:${e.line} ${e.note}`).join('; ')}.`, '');
+  });
+
+  p(...renderHunt(s.hunt, merged));
+  p(...renderProve(s.prove, merged));
+
+  if (obs.length) {
+    p('## Leads outside this run\'s scope', '');
+    p('These were found but do not count in this run: their requirement is above the declared stage, outside the edition, or not mapped to a requirement. They never affect the gate.', '');
+    for (const o of obs) p(`- ${o.title} at ${o.where.map(loc).join(', ')}. ${o.note}`);
+    p('');
+  }
+
+  if (leadObs.length) {
+    p('## Leads from rules still being measured', '');
+    p('Each rule has a confidence tier from measurement on public benchmarks (rules/tiers.json). A rule whose measured precision is below the threshold, or that has not been measured yet, reports leads: read the code at each place. Leads never fail a requirement or affect the gate. Secret findings are never leads.', '');
+    for (const o of leadObs) p(`- ${o.title} at ${o.where.map(loc).join(', ')}. ${o.note}`);
+    p('');
+  }
+
+  if (testObs.length) {
+    p('## Findings in test code', '');
+    p('These are in test, fixture, spec, mock or example files, found by folder and file name conventions. They are kept so a person can read them, and they never fail a requirement or affect the gate. Secret findings are not in this list: a live key is a leak wherever it is committed, so they stay findings.', '');
+    for (const o of testObs) p(`- ${o.title} at ${o.where.map(loc).join(', ')}. ${o.note}`);
+    p('');
+  }
+
+  p('## What could not run, and why', '');
+  p('| Scanner | Status | Why | Version | Requirements left NOT ASSESSED because of it |', '|---|---|---|---|---|');
+  if (s.metas.length === 0) p('| all | no scanner adapter ran | | none | the requirements their rules cover |');
+  for (const m of s.metas) p(`| ${m.tool} | ${m.status} | ${cell(s.reasons[m.tool] ?? '')} | ${m.version ?? 'none'}${m.version && !m.version_tested ? ' (not a tested version)' : ''} | ${m.not_assessed_sec_ids.join(', ') || 'none'} |`);
+  p('');
+  if (s.checks.not_run.length) {
+    p('| Check | Why it did not run |', '|---|---|');
+    for (const n of s.checks.not_run) p(`| ${n.check_id} | ${cell(n.reason)} |`);
+    p('');
+  }
+  if (s.info.dropped.length) {
+    p('Some checks name requirements that this kit\'s controls file does not hold yet, so those requirements are not in the results:', '');
+    for (const d of s.info.dropped) p(`- ${d.source} at \`${d.where}\`: ${d.ids.join(', ')}`);
+    p('');
+  }
+  p('Discovery reads files, not deployments. Anything set only in a provider dashboard is invisible to this scan.', '');
+
+  p('## What the scan read', '');
+  p(`${s.surface.files_listed} files were listed (dependency folders, build output, ignored files and the kit's own folders are left out).`, '');
+  p('| Kind | Files |', '|---|---|');
+  for (const k of s.surface.surfaces) p(`| ${k.kind} | ${k.count} |`);
+  p('');
+
+  if (s.codemap) p(...renderEntryPoints(s.codemap));
+  p(...reportSection(s.stack));
+
+  p('## Unverified controls (NOT ASSESSED)', '');
+  p('Nothing in the files settled these. They are open, not passed. Each group says what settles it.', '');
+  for (const st of STATE_ORDER) {
+    const rows = s.results.filter((r) => r.result === `NOT ASSESSED: ${st}`);
+    if (!rows.length) continue;
+    p(`### NOT ASSESSED: ${st} (${rows.length})`, '', `${STATE_MEANS[st]} ${OWNER_ACTION[st]}`, '');
+    p('| ID | Severity | Requirement |', '|---|---|---|');
+    for (const r of rows.slice().sort((a, b) => SEV_RANK[kit.byId.get(b.id)!.severity] - SEV_RANK[kit.byId.get(a.id)!.severity] || cmp(a.id, b.id))) {
+      const c = kit.byId.get(r.id)!;
+      p(`| ${r.id} | ${c.severity} | ${cell(c.title)} |`);
+    }
+    p('');
+  }
+  const passes = s.results.filter((r) => r.result === 'PASS (static)');
+  if (passes.length) {
+    p('## PASS (static)', '', 'Settled by reading the repository. Only requirements whose authority is the repository can pass this way.', '');
+    p('| ID | Requirement | How |', '|---|---|---|');
+    for (const r of passes) p(`| ${r.id} | ${cell(kit.byId.get(r.id)?.title ?? '')} | ${cell(r.notes)} |`);
+    p('');
+  }
+
+  p('## Reproducibility', '');
+  p('The same commit, engine version, kit files and tool versions give the same bytes in every file of the scan folder except run.json and scan/run.json.', '');
+  p('| Item | Value |', '|---|---|');
+  p(`| Engine | ${ENGINE_VERSION} |`, `| Controls file sha256 | ${s.info.kit.controls_sha256} |`, `| Checks | ${s.info.checks.total} |`);
+  for (const m of s.metas) p(`| ${m.tool} | ${m.version ?? 'not run'}, config sha256 ${m.config_sha256 ?? 'none'}, files scanned ${m.files_scanned ?? 'unknown'} of ${m.files_tracked ?? 'unknown'} tracked${m.db_date ? `, advisory data ${m.db_date}` : ''} |`);
+  p('');
+  return out.join('\n');
+}

package/src/report/surface.ts

@@ -0,0 +1,32 @@
+// surface.json: what the scan looked at, by kind of entry point or configuration, so the report can say what was read.
+// A file level summary found with the same selectors the older checks use. The entry point inventory is in codemap.json.
+import type { CheckContext } from '../checks/context.ts';
+import { handlerFiles } from '../checks/code/shared.ts';
+
+export interface SurfaceFile {
+  schema_version: '1.0.0';
+  files_listed: number;
+  surfaces: { kind: string; count: number; files: string[] }[];
+}
+
+const MAX_LISTED = 50;
+
+export function surface(ctx: CheckContext): SurfaceFile {
+  const handlers = handlerFiles(ctx);
+  const kinds: [string, string[]][] = [
+    ['server request handlers', handlers],
+    ['webhook handlers', handlers.filter((f) => /webhook/i.test(f))],
+    ['admin handlers', handlers.filter((f) => /(^|\/)(admin|backoffice|staff)(\/|\.|$)/i.test(f))],
+    ['sign in and account routes', handlers.filter((f) => /login|signin|sign-in|signup|sign-up|register|password|otp|auth/i.test(f))],
+    ['AI tool and model code', ctx.select(['**/{ai,llm,agent,agents,mcp}/**/*', '**/*tool*.{ts,js,py}'])],
+    ['database migrations and rules', ctx.select(['**/migrations/**/*.sql', '**/schema.sql', '**/*.rules', '**/database.rules.json'])],
+    ['CI workflows', ctx.select(['.github/workflows/*.{yml,yaml}', '.gitlab-ci.yml', 'bitbucket-pipelines.yml', '.circleci/config.yml', 'azure-pipelines.yml'])],
+    ['infrastructure code', ctx.select(['**/*.tf', '**/*.tf.json', '**/*.bicep', '**/template.{yml,yaml}', '**/Dockerfile*', '**/*compose*.{yml,yaml}', '**/k8s/**/*.{yml,yaml}'])],
+    ['framework and platform configuration', ctx.select(['next.config.*', 'nuxt.config.*', 'vite.config.*', 'vercel.json', 'netlify.toml', 'firebase.json', 'supabase/config.toml', '**/settings.py', 'app.json', 'app.config.*'])],
+  ];
+  return {
+    schema_version: '1.0.0',
+    files_listed: ctx.files.length,
+    surfaces: kinds.map(([kind, files]) => ({ kind, count: files.length, files: files.slice(0, MAX_LISTED) })),
+  };
+}

package/src/report/test-code.ts

@@ -0,0 +1,56 @@
+// Test code: findings in test, fixture, spec, mock and example files are kept, marked as test code and reported apart.
+// They never fail a requirement or reach the gate, except for requirements whose subject is test material that ships
+// (TEST_ARTIFACT_IDS), where a test file is exactly the thing the requirement is about.
+
+import { existsSync, readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+
+// A path is test code when a folder in it, or its file name, follows a convention the language's own tools use:
+//
+// | Kind | Folder names (any folder in the path, any case) | File names |
+// |---|---|---|
+// | any language | test, tests, __tests__, __test__, spec, specs, e2e, cypress, __mocks__, mocks, mock, fixtures, fixture, __fixtures__, testdata, test-data, test_data, testfixtures, androidtest, example, examples, sample, samples | |
+// | JavaScript, TypeScript | | *.test.*, *.spec.*, *.e2e.*, *.cy.*, *.mock.*, *.fixture.*, *.fixtures.* (js, jsx, ts, tsx, mjs, cjs, mts, cts) |
+// | Python | | test_*.py, *_test.py, conftest.py, tests.py |
+// | Go | | *_test.go (testdata/ is Go's fixture folder, above) |
+// | Java, Kotlin, Groovy, Scala | | *Test, *Tests, *IT, *Spec (.java, .kt, .groovy, .scala); src/test/ through the folder rule |
+// | PHP | | *Test.php |
+// | Ruby | | *_spec.rb, *_test.rb |
+// | C# | | *Test.cs, *Tests.cs |
+// | Dart | | *_test.dart |
+//
+// "testing" is not on the list: Go and Python use it for shipped helper packages. A production file that happens to sit
+// in a folder named like this (an `examples/` folder that is deployed, for instance) is still marked test code; the
+// report lists every such record so a person can see it.
+
+const TEST_FOLDERS = new Set([
+  'test', 'tests', '__tests__', '__test__', 'spec', 'specs', 'e2e', 'cypress', '__mocks__', 'mocks', 'mock', 'fixtures',
+  'fixture', '__fixtures__', 'testdata', 'test-data', 'test_data', 'testfixtures', 'androidtest', 'example', 'examples',
+  'sample', 'samples',
+]);
+
+const TEST_FILES: { re: RegExp; kind: string }[] = [
+  { re: /\.(test|spec|e2e|cy|mock|fixtures?)\.[cm]?[jt]sx?$/i, kind: 'JavaScript or TypeScript test file name' },
+  { re: /^(test_.*|.*_test|conftest|tests)\.py$/, kind: 'Python test file name' },
+  { re: /_test\.go$/, kind: 'Go test file name' },
+  { re: /(Test|Tests|IT|Spec)\.(java|kt|groovy|scala)$/, kind: 'JVM test class name' },
+  { re: /Test\.php$/, kind: 'PHP test class name' },
+  { re: /_(spec|test)\.rb$/, kind: 'Ruby test file name' },
+  { re: /Tests?\.cs$/, kind: 'C# test class name' },
+  { re: /_test\.dart$/, kind: 'Dart test file name' },
+];
+
+// Requirements about test material in the shipped product (test routes, seed scripts and sample code kept out of
+// production, seed and fixture data kept out of the migration chain): a hit in a test path still fails these. The IDs
+// are data in rules/test-artifact-ids.json, so each edition of the rules lists the ones it has.
+const ARTIFACT_FILE = fileURLToPath(new URL('../../rules/test-artifact-ids.json', import.meta.url));
+export const TEST_ARTIFACT_IDS = new Set<string>(existsSync(ARTIFACT_FILE) ? (JSON.parse(readFileSync(ARTIFACT_FILE, 'utf8')) as { sec_ids: string[] }).sec_ids : []);
+
+// Why a repository relative POSIX path counts as test code, or null when it does not.
+export function testCodeReason(file: string): string | null {
+  const parts = file.split('/');
+  const name = parts.pop() ?? '';
+  const folder = parts.find((p) => TEST_FOLDERS.has(p.toLowerCase()));
+  if (folder) return `folder ${folder}/`;
+  return TEST_FILES.find((t) => t.re.test(name))?.kind ?? null;
+}

package/src/report/tiers.ts

@@ -0,0 +1,50 @@
+// Rule confidence tiers (rules/tiers.json). A Semgrep rule is "gate" or "lead". A gate rule's hit fails its requirements
+// as before. A lead rule's hit is listed in the report as a lead and never fails a requirement or holds the gate.
+// The tier comes from measurement: a rule whose measured precision is below the threshold in the file is a lead until a
+// later measurement raises it. A rule not in the file keeps a default: engine taint rules (taint-*.yaml, rule ids
+// hullproof-taint-*) are leads, every other rule is gate, which is how the kit rules with fixtures behaved before tiers.
+// Gitleaks hits, Semgrep rules mapped to a SEC-SECRETS ID, engine checks, Trivy and OSV are always gate.
+import { existsSync, readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import type { Hit } from '../types/index.ts';
+
+// needs_judged: a minimum judged count for this entry alone, above the file's min_judged (a decision to wait for more evidence).
+export interface TierEntry { tier: 'gate' | 'lead'; precision: number | null; judged: number; evidence: string; date: string | null; needs_judged?: number }
+export interface TierFile { threshold: number; min_judged: number; rules: Record<string, TierEntry> }
+
+// The tier file sits next to each Semgrep rule folder (rules/tiers.json, and a tier file next to a rule pack). Later folders (the rule
+// pack) win for the same rule id; the threshold and minimum come from the first file found.
+const DEFAULT: TierFile = { threshold: 0.8, min_judged: 3, rules: {} };
+export function loadTiers(semgrepDirs: string[]): TierFile {
+  const files = semgrepDirs.map((d) => join(dirname(d), 'tiers.json')).filter((p) => existsSync(p)).map((p) => JSON.parse(readFileSync(p, 'utf8')) as TierFile);
+  if (!files.length) return DEFAULT;
+  return { threshold: files[0].threshold, min_judged: files[0].min_judged, rules: Object.assign({}, ...files.map((f) => f.rules)) };
+}
+
+// A hit that is about a secret: a live key is a leak wherever it is committed, so it always holds the gate.
+export const isSecretHit = (h: Hit): boolean => h.tool === 'gitleaks' || h.sec_ids.some((id) => id.startsWith('SEC-SECRETS-'));
+
+// The tier entry for a hit, or null when the hit is gate.
+export function leadTier(h: Hit, t: TierFile): TierEntry | null {
+  if (h.tool !== 'semgrep' || isSecretHit(h)) return null;
+  const e = t.rules[h.rule_id] ?? (h.rule_id.startsWith('hullproof-taint-')
+    ? { tier: 'lead' as const, precision: null, judged: 0, evidence: 'not measured yet', date: null } : null);
+  return e && e.tier === 'lead' ? e : null;
+}
+
+// An engine check that reads the code map (check.map.*) is a lead until a measurement puts it in tiers.json with a precision at
+// or above the threshold. Every other engine check is gate, as before.
+export const isMapCheck = (id: string): boolean => id.startsWith('check.map.');
+export function leadTierForCheck(id: string, t: TierFile): TierEntry | null {
+  if (!isMapCheck(id)) return null;
+  const e = t.rules[id] ?? { tier: 'lead' as const, precision: null, judged: 0, evidence: 'not measured yet', date: null };
+  return e.tier === 'lead' ? e : null;
+}
+
+// Plain English reason for a lead record.
+export function leadReason(e: TierEntry, t: TierFile): string {
+  if (e.precision === null || e.judged === 0) return 'this rule has not been measured yet';
+  const m = `precision ${e.precision.toFixed(2)} on ${e.judged} judged hits (${e.evidence}, ${e.date})`;
+  const need = Math.max(t.min_judged, e.needs_judged ?? 0);
+  return e.judged < need ? `${m}, fewer than the ${need} needed to change its default` : `${m}, below ${t.threshold.toFixed(2)}`;
+}

package/src/scanners/common.ts

@@ -0,0 +1,149 @@
+// Helpers shared by the adapters: running a tool, reading the git index without git, hashing, masking, path rules.
+import { spawnSync } from 'node:child_process';
+import { createHash } from 'node:crypto';
+import { existsSync, lstatSync, readdirSync, readFileSync, statSync } from 'node:fs';
+import { isAbsolute, join, relative, resolve, sep } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { cmp } from '../util.ts';
+import type { Exec } from './types.ts';
+
+export const ENGINE_ROOT = fileURLToPath(new URL('../../', import.meta.url));
+export const RULES_DIR = join(ENGINE_ROOT, 'rules');
+const MAX_BUFFER = 512 * 1024 * 1024;
+
+// An address nothing listens on. Go, Python and git clients send all HTTP and HTTPS traffic to it and fail,
+// so a tool that tries the network while network is not allowed gets an error instead of a connection.
+const BLACKHOLE = 'http://127.0.0.1:9';
+
+export function toolEnv(base: NodeJS.ProcessEnv, allowNetwork: boolean): NodeJS.ProcessEnv {
+  const env: NodeJS.ProcessEnv = {
+    ...base,
+    GIT_CONFIG_GLOBAL: '/dev/null', GIT_CONFIG_SYSTEM: '/dev/null', GIT_CONFIG_NOSYSTEM: '1',
+    GIT_OPTIONAL_LOCKS: '0', GIT_TERMINAL_PROMPT: '0', NO_COLOR: '1',
+    SEMGREP_SEND_METRICS: 'off', SEMGREP_ENABLE_VERSION_CHECK: '0',
+    // Set by the container entry point of the GitHub Action only (see src/commands/git.ts).
+    ...(process.env.HULLPROOF_TRUST_REPO_OWNER === '1' ? { GIT_CONFIG_COUNT: '1', GIT_CONFIG_KEY_0: 'safe.directory', GIT_CONFIG_VALUE_0: '*' } : {}),
+  };
+  if (!allowNetwork) {
+    for (const k of ['HTTP_PROXY', 'HTTPS_PROXY', 'ALL_PROXY', 'http_proxy', 'https_proxy', 'all_proxy']) env[k] = BLACKHOLE;
+    env.NO_PROXY = ''; env.no_proxy = '';
+  }
+  return env;
+}
+
+export function exec(argv: string[], cwd: string, env: NodeJS.ProcessEnv): Exec {
+  const r = spawnSync(argv[0], argv.slice(1), { cwd, env, encoding: 'utf8', maxBuffer: MAX_BUFFER, shell: false });
+  const error = r.error ? ((r.error as NodeJS.ErrnoException).code ?? r.error.message) : undefined;
+  return { argv, stdout: r.stdout ?? '', stderr: r.stderr ?? '', status: r.status, error };
+}
+
+// First x.y.z in the version command's output. null when the tool is missing.
+export function detectVersion(argv: string[], env: NodeJS.ProcessEnv): string | null {
+  const r = exec(argv, process.cwd(), env);
+  if (r.error) return null;
+  return /(\d+\.\d+\.\d+)/.exec(r.stdout + '\n' + r.stderr)?.[1] ?? null;
+}
+
+// "1.176.x" style ranges: the installed version must have the same major and minor.
+export function versionTested(version: string | null, range: string): boolean {
+  if (!version) return false;
+  const [maj, min] = range.split('.');
+  const [vmaj, vmin] = version.split('.');
+  return maj === vmaj && min === vmin;
+}
+
+export const sha256 = (data: string | Buffer): string => createHash('sha256').update(data).digest('hex');
+export const fileSha256 = (p: string): string => sha256(readFileSync(p));
+
+// The scan.sh method for a folder: sha256 over the per file sha256 lines, files in sorted path order.
+export function dirSha256(dir: string): string {
+  const files: string[] = [];
+  const walk = (d: string): void => {
+    for (const e of readdirSync(d, { withFileTypes: true })) {
+      const p = join(d, e.name);
+      if (e.isDirectory()) walk(p); else if (e.isFile()) files.push(relative(dir, p).split(sep).join('/'));
+    }
+  };
+  walk(dir);
+  return sha256(files.sort(cmp).map((f) => fileSha256(join(dir, f)) + '\n').join(''));
+}
+
+// Repository relative POSIX path. Absolute paths inside the repository lose the prefix; "./" is dropped.
+export function relPath(p: string, repo: string): string {
+  let out = p.replace(/\\/g, '/');
+  if (isAbsolute(p)) {
+    const r = relative(resolve(repo), p);
+    out = r.startsWith('..') ? out : r.split(sep).join('/');
+  }
+  return out.replace(/^(\.\/)+/, '');
+}
+
+// Replaces long token shaped runs (keys, hashes, encoded blobs: 20 or more key characters with both a letter and a
+// digit) so evidence text does not carry a secret value. Plain identifiers such as AWS_SECRET_ACCESS_KEY stay readable.
+// ponytail: a secret with no digit passes; evidence for secret rules is the Gitleaks redacted form or null anyway.
+const TOKEN = /[A-Za-z0-9+/_-]{20,}={0,2}/g;
+export function mask(text: string, max = 160): string {
+  const one = text.replace(/\s+/g, ' ').trim().replace(TOKEN, (m) => (/\d/.test(m) && /[A-Za-z]/.test(m) ? '***' : m));
+  return one.length > max ? one.slice(0, max - 3) + '...' : one;
+}
+
+// One masked source line read from the repository, or null when the file or line is not there.
+export function sourceLine(repo: string, file: string, line: number): string | null {
+  if (line < 1) return null;
+  try {
+    const p = join(repo, file);
+    if (!lstatSync(p).isFile() || statSync(p).size > 4 * 1024 * 1024) return null;
+    const text = readFileSync(p, 'utf8').split('\n')[line - 1];
+    return text === undefined ? null : mask(text);
+  } catch { return null; }
+}
+
+// Paths tracked by git, read from .git/index (versions 2, 3 and 4) without running git. Stage 0 to 3 entries are one
+// path; submodule entries (mode 160000) are left out. null when there is no index.
+export function readTracked(repo: string): Set<string> | null {
+  let gitDir = join(repo, '.git');
+  if (!existsSync(gitDir)) return null;
+  if (statSync(gitDir).isFile()) {
+    const m = /^gitdir:\s*(.+)$/m.exec(readFileSync(gitDir, 'utf8'));
+    if (!m) return null;
+    gitDir = resolve(repo, m[1].trim());
+  }
+  const idx = join(gitDir, 'index');
+  if (!existsSync(idx)) return null;
+  return parseIndex(readFileSync(idx));
+}
+
+export function parseIndex(buf: Buffer): Set<string> {
+  if (buf.toString('latin1', 0, 4) !== 'DIRC') throw new Error('not a git index');
+  const version = buf.readUInt32BE(4);
+  if (version < 2 || version > 4) throw new Error(`git index version ${version} is not supported`);
+  const count = buf.readUInt32BE(8);
+  const out = new Set<string>();
+  let off = 12;
+  let prev: Buffer = Buffer.alloc(0);
+  for (let i = 0; i < count; i++) {
+    const start = off;
+    const mode = buf.readUInt32BE(off + 24);
+    const flags = buf.readUInt16BE(off + 60);
+    off += 62;
+    if (version >= 3 && flags & 0x4000) off += 2;
+    let name: Buffer;
+    if (version === 4) {
+      let c = buf[off++];
+      let strip = c & 127;
+      while (c & 128) { c = buf[off++]; strip = ((strip + 1) << 7) | (c & 127); }
+      const end = buf.indexOf(0, off);
+      name = Buffer.concat([prev.subarray(0, prev.length - strip), buf.subarray(off, end)]);
+      off = end + 1;
+    } else {
+      const end = buf.indexOf(0, off);
+      name = buf.subarray(off, end);
+      off = start + Math.floor((end - start + 8) / 8) * 8; // NUL padding to a multiple of 8
+    }
+    prev = name;
+    if ((mode >>> 12) !== 0o16) out.add(name.toString('utf8')); // 0o160000 is a submodule
+  }
+  return out;
+}
+
+export const isRegularFile = (p: string): boolean => { try { return lstatSync(p).isFile(); } catch { return false; } };

package/src/scanners/gitleaks.ts

@@ -0,0 +1,89 @@
+// Gitleaks adapter. `gitleaks dir` over the working tree always; `gitleaks git` over history only when the caller says
+// the git configuration was checked (opts.history), because it runs git. Both use the kit config in rules/gitleaks.toml,
+// --redact, --ignore-gitleaks-allow and an empty ignore folder, so the scanned repository cannot hide its own findings.
+// Kept per hit: rule id, file, line, the redacted match (masked again) and the Gitleaks fingerprint. Never the secret,
+// the entropy, the author or the date.
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { secretNoise } from './secret-noise.ts';
+import { sortUnique } from '../util.ts';
+import { fileSha256, mask, relPath } from './common.ts';
+import { inEdition, loadControls } from '../mapping/controls.ts';
+import { mapHit, tableSecIds } from '../mapping/map.ts';
+import type { Adapter, DetailHit, Env, Exec, ScanOptions } from './types.ts';
+
+interface Finding { RuleID: string; StartLine: number; EndLine: number; Match: string; File: string; Commit: string; Fingerprint: string }
+
+const flags = (config: string, ignoreDir: string): string[] => ['--redact', '--no-banner', '--no-color', '--config', config,
+  '--ignore-gitleaks-allow', '--gitleaks-ignore-path', ignoreDir, '--report-format', 'json', '--report-path', '-', '--exit-code', '0'];
+
+export const adapter: Adapter = {
+  id: 'gitleaks',
+  tool: 'gitleaks',
+  versionCommand: ['gitleaks', 'version'],
+  testedVersions: '8.30.x',
+  needsNetwork: false,
+  applies: () => true,
+  notApplicableReason: () => null,
+  configFiles: (ctx) => [join((ctx as ScanOptions).rulesDir ?? '', 'gitleaks.toml')],
+  command: (ctx) => ['gitleaks', 'dir', '.', ...flags(join((ctx as ScanOptions).rulesDir ?? '', 'gitleaks.toml'), '<empty-dir>')],
+  parse: (stdout, ctx) => parseGitleaks(stdout, ctx as ScanOptions, 'dir', null, '').hits,
+  possibleSecIds: (o) => sortUnique(inEdition(tableSecIds('gitleaks'), o.edition, loadControls(o.controlsPath))),
+
+  execute(o, env) {
+    const config = join(env.rulesDir, 'gitleaks.toml');
+    const configSha256 = fileSha256(config);
+    const ruleVersion = `gitleaks ${env.version}, config sha256:${configSha256.slice(0, 16)}`;
+    const show = (argv: string[]): string[] => argv.map((a) => (a === config ? '<engine>/rules/gitleaks.toml' : a === env.scratch ? '<empty-dir>' : a));
+    const runOne = (mode: 'dir' | 'git'): Exec => {
+      // Trace logging is the only place Gitleaks names each file it read. The log also prints skipped candidate values,
+      // so stderr is read here for the file names only, never stored and never printed.
+      const argv = ['gitleaks', mode, '.', ...flags(config, env.scratch), ...(mode === 'dir' ? ['--log-level', 'trace'] : [])];
+      const r = env.run(argv);
+      if (r.status !== 0) throw new Error(`gitleaks ${mode} exited with ${r.status ?? r.error}`);
+      return r;
+    };
+    const dir = runOne('dir');
+    // The engine's own output folder is left out: it is written by this tool, so reading it would change the next run.
+    const own = (f: string): boolean => f === '.hullproof' || f.startsWith('.hullproof/');
+    const scanned = sortUnique([...dir.stderr.matchAll(/scanning path path=(.+)$/gm)].map((m) => relPath(m[1].trim(), o.repo))).filter((f) => !own(f));
+    const hits = parseGitleaks(dir.stdout, o, 'dir', env.tracked, ruleVersion).hits.filter((h) => !own(h.file));
+    const commands = [show(dir.argv)];
+    if (o.history) {
+      const git = runOne('git');
+      hits.push(...parseGitleaks(git.stdout, o, 'git', env.tracked, ruleVersion).hits);
+      commands.push(show(git.argv));
+    }
+    return { hits, commands, configSha256, scanned, exitCode: dir.status, toolErrors: [] };
+  },
+};
+
+export function parseGitleaks(stdout: string, o: ScanOptions, source: 'dir' | 'git', tracked: Set<string> | null, ruleVersion: string): { hits: DetailHit[] } {
+  const controls = loadControls(o.controlsPath);
+  const list = (stdout.trim() ? JSON.parse(stdout) : []) as Finding[];
+  // The source line is the only place a placeholder can be told from a key, because the scanner redacts the value. History hits
+  // cannot be matched to the checked out files, so they get the path rules only.
+  const lines = new Map<string, string[] | null>();
+  const lineOf = (file: string, n: number): string | null => {
+    if (source === 'git') return null;
+    if (!lines.has(file)) { try { lines.set(file, readFileSync(join(o.repo, file), 'utf8').split('\n')); } catch { lines.set(file, null); } }
+    return lines.get(file)?.[n - 1] ?? null;
+  };
+  return {
+    hits: list.map((f): DetailHit => {
+      const file = relPath(f.File, o.repo);
+      const isTracked = source === 'git' || !tracked || tracked.has(file);
+      const m = mapHit({ tool: 'gitleaks', rule_id: f.RuleID, file, tracked: isTracked }, o.edition, controls);
+      const redacted = mask(f.Match);
+      const noise = secretNoise(f.RuleID, file, lineOf(file, f.StartLine));
+      return {
+        tool: 'gitleaks', rule_id: f.RuleID, file, line: f.StartLine, end_line: f.EndLine, sec_ids: m.sec_ids, severity_hint: null,
+        ...(noise ? { noise } : {}), message_key: `gitleaks:${f.RuleID}`, rule_version: ruleVersion, evidence: redacted, mapped_by: m.mapped_by, unmapped: !m.sec_ids.length,
+        secret: { redacted, fingerprint: relFingerprint(f.Fingerprint, o.repo), source, commit: f.Commit || null, tracked: isTracked },
+      };
+    }),
+  };
+}
+
+// The fingerprint is [commit:]file:rule:line; make its file part repository relative too.
+const relFingerprint = (fp: string, repo: string): string => fp.includes(repo) ? fp.split(repo.replace(/\/$/, '') + '/').join('') : fp;