hullproof 0.0.0-stage → 0.5.0

package/dist/checks/map/entry-checks.js

@@ -0,0 +1,97 @@
+// Checks that read entry points from the code map: what protects each one and what it touches. All start as leads
+// (src/report/tiers.ts) until a measurement raises them. Each is a pattern over map facts, so a FAIL is a place to look.
+import { fileURLToPath } from 'node:url';
+import { ev, evAt, has, hasAuth, judged, mapCheck, stateChanging, weakAuth, where } from './shared.js';
+const source = fileURLToPath(import.meta.url);
+const exempt = (ep) => ep.tags.includes('auth_endpoint') || ep.tags.includes('public') || ep.tags.includes('webhook');
+const SENSITIVE = /user|account|profile|customer|member|order|payment|invoice|billing|card|address|email|message|note|file|upload|document|ticket|booking|patient|wallet|session|token|credential|subscription|contact|secret|key|transaction|history|log|basket|cart|chat|conversation|appointment|photo|prescription/i;
+export const mutatingRouteWithoutAuth = mapCheck({
+    id: 'check.map.mutating-route-without-auth', sec_ids: ['SEC-API-001'], name: 'mutating-route-without-auth', source,
+    pattern: 'a state changing entry point with no session read on the handler, a wrapper, the router or a gate',
+    none: 'the code map has no state changing entry point',
+    candidates: (m) => m.entry_points.filter((e) => judged(e) && stateChanging(e)).length,
+    fails: (m) => m.entry_points.filter((e) => judged(e) && stateChanging(e) && !exempt(e) && !hasAuth(e)).map((e) => {
+        const weak = weakAuth(e);
+        return ev(e, `${where(e)} changes state and no session read is reachable on it${weak ? ` (only a weak sign: ${weak.via} at ${weak.file}:${weak.line})` : ''}`);
+    }),
+});
+export const dataReadWithoutAuth = mapCheck({
+    id: 'check.map.data-read-without-auth', sec_ids: ['SEC-API-001', 'SEC-DATA-024'], name: 'data-read-without-auth', source,
+    pattern: 'a GET entry point that reads a table with a personal data name and has no session read',
+    none: 'the code map has no GET entry point that reads a data store',
+    candidates: (m) => m.entry_points.filter((e) => judged(e) && e.kind === 'http_route' && e.method !== 'POST' && e.data.some((d) => d.op === 'read')).length,
+    fails: (m) => m.entry_points.filter((e) => judged(e) && e.kind === 'http_route' && (e.method === 'GET' || e.method === 'HEAD' || e.method === 'ANY' || e.method === null) && !exempt(e) && !hasAuth(e)).flatMap((e) => {
+        const d = e.data.find((x) => x.op === 'read' && x.target && SENSITIVE.test(x.target) && x.store !== 'filesystem');
+        return d ? [evAt(e, `${where(e)} reads ${d.target} and no session read is reachable on it`, d.line)] : [];
+    }),
+});
+export const writeByIdWithoutOwner = mapCheck({
+    id: 'check.map.write-by-id-without-owner', sec_ids: ['SEC-AUTHZ-003'], name: 'write-by-id-without-owner', source,
+    pattern: 'an update or delete filtered by an id from the request with no owner, user or tenant value from the session',
+    none: 'the code map has no update or delete by id',
+    candidates: (m) => m.entry_points.filter((e) => judged(e) && e.data.some((d) => (d.op === 'write' || d.op === 'delete') && d.by_id)).length,
+    fails: (m) => m.entry_points.filter((e) => judged(e) && e.kind !== 'webhook' && !has(e, 'role_check')).flatMap((e) => e.data.filter((d) => (d.op === 'write' || d.op === 'delete') && d.by_id && !d.owner_scoped).map((d) => evAt(e, `${where(e)} ${d.op === 'delete' ? 'deletes from' : 'updates'} ${d.target ?? 'a record'} by an id from the request and no owner value from the session is in the query`, d.line))),
+});
+export const readByIdWithoutOwner = mapCheck({
+    id: 'check.map.read-by-id-without-owner', sec_ids: ['SEC-AUTHZ-003'], name: 'read-by-id-without-owner', source,
+    fixtures: { pass: 'test/fixtures/map-idor/pass', fail: 'test/fixtures/map-idor/fail' },
+    pattern: 'a signed in entry point that reads a record with a personal data name by an id from the request, with no owner, user or tenant value from the session in the query and no role check',
+    none: 'the code map has no signed in entry point that reads a record by an id from the request',
+    candidates: (m) => m.entry_points.filter((e) => judged(e) && e.kind !== 'webhook' && !exempt(e) && has(e, 'session_read') && e.data.some((d) => d.op === 'read' && d.by_id && d.store !== 'filesystem' && d.target && SENSITIVE.test(d.target))).length,
+    fails: (m) => m.entry_points.filter((e) => judged(e) && e.kind !== 'webhook' && !exempt(e) && has(e, 'session_read') && !has(e, 'role_check') && !has(e, 'owner_filter')).flatMap((e) => e.data.filter((d) => d.op === 'read' && d.by_id && !d.owner_scoped && d.store !== 'filesystem' && d.target && SENSITIVE.test(d.target)).slice(0, 1).map((d) => evAt(e, `${where(e)} reads ${d.target ?? 'a record'} by an id from the request and no owner value from the session is in the query`, d.line))),
+});
+export const adminRouteWithoutRole = mapCheck({
+    id: 'check.map.admin-route-without-role', sec_ids: ['SEC-AUTHZ-020', 'SEC-AUTHZ-002'], name: 'admin-route-without-role', source,
+    pattern: 'an entry point in an admin area with no role check on the handler, a wrapper, the router or a gate',
+    none: 'the code map has no entry point in an admin area',
+    candidates: (m) => m.entry_points.filter((e) => judged(e) && e.tags.includes('admin')).length,
+    fails: (m) => m.entry_points.filter((e) => judged(e) && e.tags.includes('admin') && !has(e, 'role_check')).map((e) => ev(e, `${where(e)} is in an admin area and no server side role check is reachable on it${has(e, 'session_read') ? ' (a session read is not a role check)' : ''}`)),
+});
+export const webhookVerifyBeforeUse = mapCheck({
+    id: 'check.map.webhook-verify-before-use', sec_ids: ['SEC-API-101'], name: 'webhook-verify-before-use', source,
+    pattern: 'a webhook entry point with no signature check, a check that does not stop the request, or a body parsed first',
+    none: 'the code map has no webhook entry point',
+    candidates: (m) => m.entry_points.filter((e) => !e.test_code && e.kind === 'webhook').length,
+    fails: (m) => m.entry_points.filter((e) => !e.test_code && e.kind === 'webhook').flatMap((e) => {
+        const sigs = e.protections.filter((p) => p.kind === 'signature_verify');
+        if (!sigs.length)
+            return [ev(e, `${where(e)} is a webhook and no signature check was found on it`)];
+        if (sigs.every((p) => p.enforced === false))
+            return [{ file: sigs[0].file, line: sigs[0].line, note: `${where(e)} checks the signature but carries on when it fails` }];
+        if (sigs.some((p) => p.after_parse) && !sigs.some((p) => !p.after_parse))
+            return [{ file: sigs[0].file, line: sigs[0].line, note: `${where(e)} parses the request body before it checks the signature` }];
+        return [];
+    }),
+});
+export const requestUrlFetched = mapCheck({
+    id: 'check.map.request-url-fetched', sec_ids: ['SEC-API-035'], name: 'request-url-fetched', source,
+    pattern: 'an outbound HTTP call whose target comes from the request, with no allowlist in the same function',
+    none: 'the code map has no outbound HTTP call in an entry point',
+    candidates: (m) => m.entry_points.filter((e) => !e.test_code && e.outbound.some((o) => o.kind === 'http')).length,
+    fails: (m) => m.entry_points.filter((e) => !e.test_code).flatMap((e) => e.outbound.filter((o) => o.kind === 'http' && o.request_derived && !o.guarded).map((o) => evAt(e, `${where(e)} fetches ${o.target}, which comes from the request, and no allowlist of hosts is checked`, o.line))),
+});
+export const privilegedFieldFromRequest = mapCheck({
+    id: 'check.map.privileged-field-from-request', sec_ids: ['SEC-AUTHZ-004'], name: 'privileged-field-from-request', source,
+    pattern: 'a write that sets role, plan, admin or similar columns from request data, or passes the whole request object to a create or update',
+    none: 'the code map has no write in an entry point',
+    candidates: (m) => m.entry_points.filter((e) => judged(e) && e.data.some((d) => d.op === 'write')).length,
+    fails: (m) => m.entry_points.filter((e) => judged(e) && e.kind !== 'webhook' && !has(e, 'role_check')).flatMap((e) => e.data.filter((d) => d.op === 'write' && (d.sets.length > 0 || d.mass_assign)).map((d) => evAt(e, d.sets.length ? `${where(e)} sets ${d.sets.join(', ')} on ${d.target ?? 'a record'} from request data` : `${where(e)} passes the whole request object into a write on ${d.target ?? 'a record'}`, d.line))),
+});
+export const privilegedActionWithoutAudit = mapCheck({
+    id: 'check.map.privileged-action-without-audit', sec_ids: ['SEC-LOG-003'], name: 'privileged-action-without-audit', source,
+    pattern: 'a write or delete in an admin area with no audit record call',
+    none: 'the code map has no write or delete in an admin area',
+    candidates: (m) => m.entry_points.filter((e) => judged(e) && e.tags.includes('admin') && e.data.some((d) => d.op === 'write' || d.op === 'delete')).length,
+    fails: (m) => m.entry_points.filter((e) => judged(e) && e.tags.includes('admin') && e.data.some((d) => d.op === 'write' || d.op === 'delete') && !e.protections.some((p) => p.kind === 'audit_log')).map((e) => ev(e, `${where(e)} changes data in an admin area and writes no audit record`)),
+});
+export const redirectFromRequest = mapCheck({
+    id: 'check.map.redirect-from-request', sec_ids: ['SEC-AUTH-030'], name: 'redirect-from-request', source,
+    pattern: 'a redirect target taken from the request with no allowlist comparison in the same function',
+    none: 'the code map has no redirect in an entry point',
+    candidates: (m) => m.entry_points.filter((e) => !e.test_code && e.outbound.some((o) => o.kind === 'redirect')).length,
+    fails: (m) => m.entry_points.filter((e) => !e.test_code).flatMap((e) => e.outbound.filter((o) => o.kind === 'redirect' && o.request_derived && !o.guarded).map((o) => evAt(e, `${where(e)} sends the user to ${o.target}, which comes from the request, and no allowlist is checked`, o.line))),
+});
+export const ENTRY_CHECKS = [
+    mutatingRouteWithoutAuth, dataReadWithoutAuth, writeByIdWithoutOwner, readByIdWithoutOwner, adminRouteWithoutRole, webhookVerifyBeforeUse,
+    requestUrlFetched, privilegedFieldFromRequest, privilegedActionWithoutAudit, redirectFromRequest,
+];

package/dist/checks/map/shared.js

@@ -0,0 +1,44 @@
+import { buildCodeMap } from '../../map/build.js';
+const cache = new WeakMap();
+export function getMap(ctx) {
+    let m = cache.get(ctx);
+    if (!m) {
+        m = buildCodeMap(ctx);
+        cache.set(ctx, m);
+    }
+    return m;
+}
+// A protection that counts: not a weak guess, and not one the code is known to ignore.
+export const counts = (p) => p.confidence !== 'low' && p.enforced !== false;
+export const has = (ep, kind) => ep.protections.some((p) => p.kind === kind && counts(p));
+export const hasAuth = (ep) => has(ep, 'session_read') || has(ep, 'signature_verify');
+export const weakAuth = (ep) => ep.protections.find((p) => p.kind === 'session_read' && !counts(p));
+export const HANDLER_KINDS = new Set(['http_route', 'server_action', 'graphql_resolver', 'rpc']);
+// Entry points the checks judge: shipped code, a kind that handles requests.
+export const judged = (ep) => !ep.test_code && HANDLER_KINDS.has(ep.kind) && ep.framework !== 'django-admin';
+export const stateChanging = (ep) => ep.tags.includes('state_changing') || (ep.kind === 'graphql_resolver' && ep.method === 'MUTATION') || (ep.kind === 'rpc' && ep.method === 'MUTATION');
+// Evidence in the entry point's own file at the registration line, or, for a line inside the handler body (a data touch, an outbound
+// call), in the file that holds the handler: a route registered in one file can have its handler in another.
+export const ev = (ep, note) => ({ file: ep.file, line: ep.line, note });
+export const evAt = (ep, note, line) => ({ file: ep.handler?.file ?? ep.file, line, note });
+export const where = (ep) => `${ep.method && ep.method !== 'ANY' ? ep.method + ' ' : ''}${ep.path ?? ep.name ?? ep.file}`.trim();
+export function mapCheck(s) {
+    return {
+        id: s.id, sec_ids: s.sec_ids, applies_when: {}, op: 'code', on_true: 'NOT ASSESSED: NEEDS DYNAMIC TEST', on_false: 'FAIL',
+        fixtures: s.fixtures ?? { pass: 'test/fixtures/map/pass', fail: 'test/fixtures/map/fail' }, source: s.source,
+        run: (ctx) => {
+            const map = getMap(ctx);
+            const n = s.candidates(map);
+            if (n === 0)
+                return { value: 'not_applicable', reason: s.none, evidence: [], absence: null };
+            const bad = s.fails(map, ctx).sort((a, b) => (a.file < b.file ? -1 : a.file > b.file ? 1 : 0) || (a.line ?? 0) - (b.line ?? 0) || (a.note < b.note ? -1 : a.note > b.note ? 1 : 0));
+            return { value: bad.length === 0, evidence: bad, absence: { pattern: s.pattern, files_searched: n, file_globs: ['codemap.json'], matches: bad.length } };
+        },
+    };
+}
+// The text of an entry point's handler, with `above` lines before it (decorators and route options sit above).
+export function handlerText(ctx, ep, above = 0) {
+    const file = ep.handler?.file ?? ep.file;
+    const start = ep.handler?.line ?? ep.line;
+    return ctx.text(file).split('\n').slice(Math.max(0, start - 1 - above), Math.max(start, ep.end_line)).join('\n');
+}

package/dist/checks/ops.js

@@ -0,0 +1,307 @@
+// The declarative check operations. Each takes the op's params and the repository view and returns an outcome.
+// Params per op are documented in src/checks/README.md. No op runs a program or uses the network.
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { cmp } from '../util.js';
+import { MAX_EVIDENCE, byFileLine, lineOf } from './context.js';
+const strs = (v) => (Array.isArray(v) ? v.map(String) : typeof v === 'string' ? [v] : []);
+const str = (v, d = '') => (typeof v === 'string' ? v : d);
+const cap = (ev) => ev.sort(byFileLine).slice(0, MAX_EVIDENCE);
+const na = (reason) => ({ value: 'not_applicable', reason, evidence: [], absence: null });
+const cannot = (reason) => ({ value: 'cannot_run', reason, evidence: [], absence: null });
+export function compile(pattern, ignoreCase) {
+    return new RegExp(pattern, ignoreCase ? 'gim' : 'gm');
+}
+// Every match of re in text, as evidence.
+export function matchesIn(file, text, re, note) {
+    const out = [];
+    re.lastIndex = 0;
+    for (let m = re.exec(text); m; m = re.exec(text)) {
+        out.push({ file, line: lineOf(text, m.index), note });
+        if (m[0] === '')
+            re.lastIndex++;
+    }
+    return out;
+}
+// Files the op reads: params.files minus params.exclude, kept only when they match params.only_if.
+function selected(ctx, p) {
+    const files = ctx.select(strs(p.files), strs(p.exclude));
+    if (typeof p.only_if !== 'string')
+        return files;
+    const re = compile(p.only_if, p.ignore_case === true);
+    return files.filter((f) => { re.lastIndex = 0; return re.test(ctx.text(f)); });
+}
+// params.precondition {files, exclude?, pattern?}: when no file meets it the check does not apply. Returns the files that do.
+function precondition(ctx, p) {
+    const pre = p.precondition;
+    if (!pre)
+        return null;
+    const files = ctx.select(strs(pre.files), strs(pre.exclude));
+    if (typeof pre.pattern !== 'string')
+        return files;
+    const re = compile(pre.pattern, pre.ignore_case === true);
+    return files.filter((f) => { re.lastIndex = 0; return re.test(ctx.text(f)); });
+}
+function preEvidence(ctx, p, files) {
+    const pre = p.precondition;
+    const note = str(p.precondition_note, 'searched here');
+    if (typeof pre.pattern !== 'string')
+        return files.map((file) => ({ file, line: 1, note }));
+    const re = compile(pre.pattern, pre.ignore_case === true);
+    return files.map((file) => ({ file, line: matchesIn(file, ctx.text(file), re, note)[0]?.line ?? 1, note }));
+}
+function regexOp(ctx, p, present) {
+    const pre = precondition(ctx, p);
+    if (pre && pre.length === 0)
+        return na(str(p.not_applicable_reason, 'no file meets the precondition'));
+    const files = selected(ctx, p);
+    const pattern = str(p.pattern);
+    if (!pattern)
+        return cannot('params.pattern is missing');
+    const absence = (matches) => ({ pattern, files_searched: files.length, file_globs: strs(p.files), matches });
+    if (files.length === 0) {
+        const w = str(p.when_no_files, 'not_applicable');
+        if (w === 'not_applicable')
+            return na(str(p.not_applicable_reason, 'no file to search'));
+        const value = w === 'true';
+        return { value, evidence: !value && pre ? cap(preEvidence(ctx, p, pre)) : [], absence: absence(0) };
+    }
+    const re = compile(pattern, p.ignore_case === true);
+    const note = str(p.note, present ? 'matches the pattern' : 'matches the pattern this check forbids');
+    const perFile = files.map((f) => ({ f, ev: matchesIn(f, ctx.text(f), re, note) }));
+    const all = perFile.flatMap((x) => x.ev);
+    if (!present)
+        return { value: all.length === 0, evidence: cap(all), absence: absence(all.length) };
+    if (p.each_file === true) {
+        const missing = perFile.filter((x) => x.ev.length === 0).map((x) => x.f);
+        const missNote = str(p.missing_note, 'the pattern is not in this file');
+        return missing.length
+            ? { value: false, evidence: cap(missing.map((file) => ({ file, line: 1, note: missNote }))), absence: absence(all.length) }
+            : { value: true, evidence: cap(all), absence: absence(all.length) };
+    }
+    if (all.length)
+        return { value: true, evidence: cap(all), absence: absence(all.length) };
+    // Nothing found anywhere: point at the files where the thing is normally configured, when the check names them.
+    return { value: false, evidence: pre ? cap(preEvidence(ctx, p, pre)) : [], absence: absence(0) };
+}
+function fileExists(ctx, p, wantPresent) {
+    const found = ctx.select(strs(p.files), strs(p.exclude));
+    const note = str(p.note, wantPresent ? 'file present' : 'file present that this check forbids');
+    const evidence = cap(found.map((file) => ({ file, key: '(present)', note })));
+    const absence = { pattern: strs(p.files).join(' '), files_searched: ctx.files.length, file_globs: strs(p.files), matches: found.length };
+    return { value: wantPresent ? found.length > 0 : found.length === 0, evidence, absence };
+}
+// params.manifests: manifest file name to the lockfile names that pin it. A lockfile in the same folder or any parent counts.
+function fileExistsForEach(ctx, p) {
+    const table = (p.manifests ?? {});
+    const names = Object.keys(table);
+    const have = new Set(ctx.files);
+    const manifests = ctx.files.filter((f) => names.includes(f.slice(f.lastIndexOf('/') + 1)));
+    if (manifests.length === 0)
+        return na('no package manifest in the repository');
+    const missing = [];
+    for (const m of manifests) {
+        const locks = table[m.slice(m.lastIndexOf('/') + 1)];
+        const parts = m.split('/').slice(0, -1);
+        let ok = false;
+        for (let i = parts.length; i >= 0 && !ok; i--) {
+            const dir = parts.slice(0, i).join('/');
+            ok = locks.some((l) => have.has(dir ? `${dir}/${l}` : l));
+        }
+        if (!ok)
+            missing.push({ file: m, line: 1, note: str(p.note, `no lockfile (${locks.join(', ')}) in this folder or above`) });
+    }
+    const absence = { pattern: [...new Set(Object.values(table).flat())].sort(cmp).join(' '), files_searched: manifests.length, file_globs: names, matches: manifests.length - missing.length };
+    return missing.length ? { value: false, evidence: cap(missing), absence } : { value: true, evidence: cap(manifests.map((file) => ({ file, line: 1, note: 'lockfile found' }))), absence };
+}
+// Strips SQL comments, keeping line breaks so line numbers stay right.
+const stripSqlComments = (t) => t.replace(/--[^\n]*/g, '').replace(/\/\*[\s\S]*?\*\//g, (m) => m.replace(/[^\n]/g, ' '));
+const tableName = (raw) => {
+    const parts = raw.replace(/"/g, '').toLowerCase().split('.');
+    return parts.length > 1 ? { schema: parts[0], name: parts[1] } : { schema: null, name: parts[0] };
+};
+// Every table created in an exposed schema has row level security enabled after it, reading files in name order.
+function sqlEveryTableHas(ctx, p) {
+    const files = ctx.select(strs(p.files), strs(p.exclude));
+    if (files.length === 0)
+        return na('no migration files');
+    const schemas = strs(p.schemas).length ? strs(p.schemas) : ['public'];
+    const ident = '((?:"[^"]+"|[\\w$]+)(?:\\.(?:"[^"]+"|[\\w$]+))?)';
+    const re = new RegExp(`\\b(create\\s+(?:unlogged\\s+)?table\\s+(?:if\\s+not\\s+exists\\s+)?${ident}|alter\\s+table\\s+(?:if\\s+exists\\s+)?(?:only\\s+)?${ident}\\s+(enable|disable|force)\\s+row\\s+level\\s+security|drop\\s+table\\s+(?:if\\s+exists\\s+)?${ident})`, 'gi');
+    const tables = new Map();
+    const key = (raw) => {
+        const t = tableName(raw);
+        const schema = t.schema ?? schemas[0];
+        return schemas.includes(schema) ? `${schema}.${t.name}` : null;
+    };
+    for (const f of files) {
+        const text = stripSqlComments(ctx.text(f));
+        re.lastIndex = 0;
+        for (let m = re.exec(text); m; m = re.exec(text)) {
+            if (m[2]) {
+                const k = key(m[2]);
+                if (k)
+                    tables.set(k, { file: f, line: lineOf(text, m.index), rls: false });
+            }
+            else if (m[3]) {
+                const k = key(m[3]);
+                const t = k ? tables.get(k) : undefined;
+                if (t)
+                    t.rls = m[4].toLowerCase() !== 'disable';
+            }
+            else if (m[5]) {
+                const k = key(m[5]);
+                if (k)
+                    tables.delete(k);
+            }
+        }
+    }
+    if (tables.size === 0)
+        return na('no table created in an exposed schema');
+    const without = [...tables.entries()].filter(([, t]) => !t.rls);
+    const absence = { pattern: 'alter table <name> enable row level security', files_searched: files.length, file_globs: strs(p.files), matches: tables.size - without.length };
+    const evidence = without.map(([name, t]) => ({ file: t.file, line: t.line, note: `table ${name} is created and row level security is never enabled on it` }));
+    return { value: without.length === 0, evidence: cap(evidence), absence };
+}
+function workflows(ctx, p) {
+    return ctx.select(strs(p.files).length ? strs(p.files) : ['.github/workflows/*.yml', '.github/workflows/*.yaml']);
+}
+// Every third party action is referenced by a full 40 character commit SHA.
+function workflowUsesPinnedSha(ctx, p) {
+    const files = workflows(ctx, p);
+    if (files.length === 0)
+        return na('no CI workflow files');
+    const re = /^[ \t-]*uses:\s*["']?([^\s"'#]+)/gm;
+    const bad = [];
+    let total = 0;
+    for (const f of files) {
+        const text = ctx.text(f);
+        re.lastIndex = 0;
+        for (let m = re.exec(text); m; m = re.exec(text)) {
+            const ref = m[1];
+            if (ref.startsWith('./') || ref.startsWith('docker://'))
+                continue;
+            total++;
+            const at = ref.lastIndexOf('@');
+            if (at < 0 || !/^[0-9a-f]{40}$/.test(ref.slice(at + 1)))
+                bad.push({ file: f, line: lineOf(text, m.index), note: `${ref} is not pinned to a full commit SHA` });
+        }
+    }
+    if (total === 0)
+        return na('no third party action is used');
+    const absence = { pattern: 'uses: <owner>/<repo>@<40 hex>', files_searched: files.length, file_globs: strs(p.files), matches: total - bad.length };
+    return { value: bad.length === 0, evidence: cap(bad), absence };
+}
+// Every workflow declares token permissions (at the top or on every job) and none grants write-all.
+function workflowPermissions(ctx, p) {
+    const files = workflows(ctx, p);
+    if (files.length === 0)
+        return na('no CI workflow files');
+    const bad = [];
+    for (const f of files) {
+        const text = ctx.text(f);
+        for (const m of text.matchAll(/^[ \t]*permissions:[ \t]*write-all\b/gm))
+            bad.push({ file: f, line: lineOf(text, m.index), note: 'the token is granted write access to everything' });
+        if (/^permissions:/m.test(text))
+            continue;
+        const jobsAt = /^jobs:\s*$/m.exec(text);
+        if (!jobsAt)
+            continue;
+        const body = text.slice(jobsAt.index);
+        const jobs = [...body.matchAll(/^ {2}([\w-]+):\s*$/gm)];
+        const withPerms = jobs.filter((j, i) => {
+            const end = jobs[i + 1]?.index ?? body.length;
+            return /^ {4}permissions:/m.test(body.slice(j.index, end));
+        });
+        if (jobs.length === 0 || withPerms.length < jobs.length) {
+            bad.push({ file: f, line: lineOf(text, jobsAt.index), note: 'no permissions block for the workflow or for every job, so the token gets the repository default' });
+        }
+    }
+    const absence = { pattern: 'permissions: (top level or per job), write-all', files_searched: files.length, file_globs: strs(p.files), matches: bad.length };
+    return { value: bad.length === 0, evidence: cap(bad), absence };
+}
+// Reads the kit's framework support table: per heading, release line to status.
+export function supportTable(markdown, heading) {
+    const lines = markdown.split(/\r?\n/);
+    const at = lines.findIndex((l) => l.trim() === `## ${heading}`);
+    if (at < 0)
+        return null;
+    const rows = new Map();
+    for (let i = at + 1; i < lines.length && !lines[i].startsWith('## '); i++) {
+        const l = lines[i].trim();
+        if (!l.startsWith('|') || /^\|[\s|:-]+\|$/.test(l))
+            continue;
+        const cells = l.slice(1, -1).split('|').map((c) => c.trim());
+        if (cells[0] === 'Release line')
+            continue;
+        rows.set(cells[0], cells[cells.length - 1]);
+    }
+    return rows;
+}
+// The release line of a declared version: "13.4.0" -> "13", "^0.85.2" -> "0.85", "~=5.2.1" -> "5.2".
+export function releaseLine(version, digits) {
+    const m = /(\d+)(?:\.(\d+))?/.exec(version);
+    if (!m)
+        return null;
+    return digits === 2 ? (m[2] === undefined ? null : `${m[1]}.${m[2]}`) : m[1];
+}
+// params.table: kit relative path. params.frameworks: stack id to {heading, package, digits}.
+function versionInTable(ctx, p) {
+    if (!ctx.kitDir)
+        return cannot('the kit folder is not known, so the framework support table cannot be read');
+    let md;
+    try {
+        md = readFileSync(join(ctx.kitDir, str(p.table)), 'utf8');
+    }
+    catch {
+        return cannot(`cannot read ${str(p.table)} in the kit`);
+    }
+    const table = (p.frameworks ?? {});
+    const items = [...ctx.stack.frameworks, ...ctx.stack.mobile].filter((i) => table[i.id]);
+    if (items.length === 0)
+        return na('no framework from the support table is in stack.json');
+    const bad = [];
+    const good = [];
+    const unknown = [];
+    for (const item of items) {
+        const row = table[item.id];
+        const rows = supportTable(md, row.heading);
+        const ev = item.evidence.find((e) => e.rule.includes('.dep.')) ?? item.evidence[0];
+        const declared = (item.versions ?? []).filter((v) => v.startsWith(`${row.package}@`)).map((v) => v.slice(row.package.length + 1));
+        if (!rows || declared.length === 0) {
+            unknown.push(item.id);
+            continue;
+        }
+        for (const v of declared) {
+            const line = releaseLine(v, row.digits ?? 1);
+            const status = line ? rows.get(line) : undefined;
+            const where = { file: ev?.file ?? 'package.json', ...(ev?.line ? { line: ev.line } : { key: ev?.key ?? `(present)` }) };
+            if (/canary|alpha|beta|rc|next|experimental|nightly/i.test(v))
+                bad.push({ ...where, note: `${row.package} ${v} is a prerelease or canary version` });
+            else if (status === 'Supported')
+                good.push({ ...where, note: `${row.package} ${v}: release line ${line} is supported in the kit table` });
+            else if (status)
+                bad.push({ ...where, note: `${row.package} ${v}: release line ${line} is ${status.toLowerCase()} in the kit's framework support table` });
+            else
+                unknown.push(`${item.id} ${v}`);
+        }
+    }
+    const absence = { pattern: `release lines in ${str(p.table)}`, files_searched: 1, file_globs: [str(p.table)], matches: good.length };
+    if (bad.length)
+        return { value: false, evidence: cap(bad), absence };
+    if (unknown.length)
+        return cannot(`no row in the framework support table for ${unknown.sort(cmp).join(', ')}`);
+    return { value: true, evidence: cap(good), absence };
+}
+export const OPS = {
+    file_exists: (c, p) => fileExists(c, p, true),
+    file_absent: (c, p) => fileExists(c, p, false),
+    file_exists_for_each: fileExistsForEach,
+    regex_present: (c, p) => regexOp(c, p, true),
+    regex_absent: (c, p) => regexOp(c, p, false),
+    sql_every_table_has: sqlEveryTableHas,
+    workflow_uses_pinned_sha: workflowUsesPinnedSha,
+    workflow_permissions: workflowPermissions,
+    version_in_table: versionInTable,
+    // json_value is in the op list of the design and not built: no check needs it yet.
+};

package/dist/checks/pro-map.js

@@ -0,0 +1 @@
+export const PRO_MAP_CHECKS = [];

package/dist/checks/run.js

@@ -0,0 +1,92 @@
+// Loads every check (checks/*.json and the TypeScript checks in src/checks/code/), runs the ones that apply, and returns
+// checks.json. Deterministic: files and checks are sorted, no clock, no network, no program is run.
+import { createHash } from 'node:crypto';
+import { existsSync, readFileSync, readdirSync } from 'node:fs';
+import { join, sep } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { cmp } from '../util.js';
+import { OPS } from './ops.js';
+import { check as webhookVerify } from './code/webhook-verify.js';
+import { ownerFilter, toolOwnerFilter } from './code/owner-filter.js';
+import { check as adminRole } from './code/admin-role.js';
+import { ENTRY_CHECKS } from './map/entry-checks.js';
+import { CONFIG_CHECKS } from './map/config-checks.js';
+import { PRO_MAP_CHECKS } from './pro-map.js';
+export const CHECKS_DIR = fileURLToPath(new URL('../../checks/', import.meta.url));
+export const CODE_CHECKS = [webhookVerify, ownerFilter, toolOwnerFilter, adminRole, ...ENTRY_CHECKS, ...PRO_MAP_CHECKS, ...CONFIG_CHECKS];
+export function loadChecks(dir = CHECKS_DIR) {
+    const json = readdirSync(dir).filter((n) => n.endsWith('.json')).sort(cmp)
+        .map((n) => ({ ...JSON.parse(readFileSync(join(dir, n), 'utf8')), source: join(dir, n) }));
+    return [...json, ...CODE_CHECKS].sort((a, b) => cmp(a.id, b.id));
+}
+// sha256 of the check's own file: a JSON definition or the TypeScript module. Goes into machine_evidence.config_sha256.
+const shaCache = new Map();
+// A module running from dist/ is hashed through its TypeScript twin in src/ (shipped with the package), so the same check gives the
+// same hash whether the engine runs from the sources or from the compiled build.
+const sourceFile = (p) => {
+    if (!p.endsWith('.js'))
+        return p;
+    const twin = p.replace(/\.js$/, '.ts').replace(`${sep}dist${sep}`, `${sep}src${sep}`);
+    return existsSync(twin) ? twin : p;
+};
+export function checkSha(c) {
+    let s = shaCache.get(c.source);
+    if (!s) {
+        s = createHash('sha256').update(readFileSync(sourceFile(c.source))).digest('hex');
+        shaCache.set(c.source, s);
+    }
+    return s;
+}
+// The check applies when every category it names has an item whose id it lists (or any item for "*").
+export function appliesTo(c, stack) {
+    for (const [cat, want] of Object.entries(c.applies_when)) {
+        const items = stack[cat] ?? [];
+        const ok = want === '*' ? items.length > 0 : items.some((i) => want.includes(i.id));
+        if (!ok)
+            return `not applicable: stack.json has no ${cat} item${want === '*' ? '' : ` of ${want.join(', ')}`}`;
+    }
+    return null;
+}
+export function runOne(c, ctx) {
+    if (c.op === 'code')
+        return c.run(ctx);
+    const op = OPS[c.op];
+    if (!op)
+        return { value: 'cannot_run', reason: `the op ${c.op} is not built in this engine version`, evidence: [], absence: null };
+    return op(ctx, c.params);
+}
+export function runChecks(ctx, checks = loadChecks()) {
+    const results = [];
+    const notRun = [];
+    for (const c of checks) {
+        const skip = appliesTo(c, ctx.stack);
+        if (skip) {
+            notRun.push({ check_id: c.id, reason: skip });
+            continue;
+        }
+        let o;
+        try {
+            o = runOne(c, ctx);
+        }
+        catch (e) {
+            o = { value: 'cannot_run', reason: `the check failed: ${e.message}`, evidence: [], absence: null };
+        }
+        if (o.value === 'not_applicable') {
+            notRun.push({ check_id: c.id, reason: `not applicable: ${o.reason ?? ''}`.trim() });
+            continue;
+        }
+        if (o.value === 'cannot_run') {
+            notRun.push({ check_id: c.id, reason: `cannot run: ${o.reason ?? ''}`.trim() });
+            continue;
+        }
+        results.push({
+            check_id: c.id,
+            sec_ids: [...c.sec_ids].sort(cmp),
+            result: o.value ? c.on_true : c.on_false,
+            evidence: o.evidence,
+            absence_search: o.absence,
+            message_key: c.id,
+        });
+    }
+    return { schema_version: '1.0.0', commit: ctx.stack.commit, results, not_run: notRun };
+}

package/dist/checks/types.js

@@ -0,0 +1 @@
+export {};

package/dist/ci/comment.js

@@ -0,0 +1,44 @@
+// pr-comment.md: the summary posted on a pull request. Same findings, same bytes: no clock, no link to a run.
+// The first line is a marker so the Action can find and update its own comment instead of adding a new one each push.
+import { cmp } from '../util.js';
+import { ENGINE_VERSION } from '../version.js';
+import { SEV_RANK } from '../report/kit.js';
+export const COMMENT_MARKER = '<!-- hullproof-ci -->';
+export const FAIL_ON_LEVELS = ['blocker', 'critical', 'high', 'medium', 'low', 'none'];
+const MAX_ROWS = 15;
+// The CI verdict. A fail record blocks when its severity is at or above the chosen level. Only fail records count: observations,
+// leads and routed items never do, as in the release gate. "none" never blocks.
+export function ciVerdict(f, failOn) {
+    const fails = f.records.filter((r) => r.kind === 'fail')
+        .sort((a, b) => SEV_RANK[b.severity] - SEV_RANK[a.severity] || cmp(a.fingerprint, b.fingerprint));
+    const min = failOn === 'none' ? 99 : SEV_RANK[failOn.toUpperCase()];
+    const blocking = fails.filter((r) => SEV_RANK[r.severity] >= min);
+    return { blocked: blocking.length > 0, blocking, others: fails.filter((r) => !blocking.includes(r)) };
+}
+const cell = (s) => s.replace(/\|/g, '\\|').replace(/\s+/g, ' ').trim();
+const where = (r) => (r.evidence[0] ? `\`${r.evidence[0].file}:${r.evidence[0].line}\`` : 'repository');
+export function prComment(i) {
+    const { findings, verdict, failOn } = i;
+    const out = [COMMENT_MARKER];
+    const p = (...l) => { out.push(...l); };
+    const n = verdict.blocking.length;
+    p(`## Hullproof: ${verdict.blocked ? `${n} blocking finding${n === 1 ? '' : 's'}` : 'no blocking findings'}`, '');
+    p(`Commit \`${findings.report.commit.slice(0, 12)}\`. Hullproof Engine ${ENGINE_VERSION}, ${i.edition} edition, stage ${findings.report.stage}. This check fails on ${failOn === 'none' ? 'nothing (report only)' : `${failOn.toUpperCase()} and above`}. Scanners that ran: ${i.scanners.length ? i.scanners.join(', ') : 'none'}.`, '');
+    if (verdict.blocked) {
+        p('| Severity | Where | Finding | Requirement |', '|---|---|---|---|');
+        for (const r of verdict.blocking.slice(0, MAX_ROWS))
+            p(`| ${r.severity} | ${where(r)} | ${cell(r.title)} | ${r.sec_ids.join(', ')} |`);
+        if (n > MAX_ROWS)
+            p('', `${n - MAX_ROWS} more blocking findings are in report.md.`);
+        p('', '### How to fix the first one', '');
+        const first = verdict.blocking[0];
+        p(cell(first.impact_statement), '', cell(first.remediation.strategy), '', `To check the fix: ${cell(first.remediation.confirm)}`);
+    }
+    else {
+        p('Nothing at or above the chosen level failed a check or a mapped rule. That does not mean the requirements pass: most are settled by provider settings or a test of the running app, and report.md lists what nothing settled.');
+    }
+    if (verdict.others.length)
+        p('', `Other findings below the blocking level: ${verdict.others.length} (see report.md).`);
+    p('', 'This comment comes from code and configuration only, with no model. The full report and results.sarif are in the workflow artifacts.', '');
+    return out.join('\n');
+}