hullproof 0.0.0-stage → 0.5.0

package/schemas/hunt-output.schema.json

@@ -0,0 +1,46 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "Hullproof hunt output: what a model returns for one entry point",
+  "description": "Written to work as a strict structured output schema (every property required, no extra properties, no length keywords). The engine checks the limits itself in src/confirm/lead.ts.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["leads"],
+  "properties": {
+    "leads": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["lead_id", "entry_point", "requirement_ids", "claim", "path", "quoted_code", "evidence_proposal"],
+        "properties": {
+          "lead_id": { "type": "string" },
+          "entry_point": { "type": "string" },
+          "requirement_ids": { "type": "array", "items": { "type": "string" } },
+          "claim": { "type": "string" },
+          "path": {
+            "type": "array",
+            "items": {
+              "type": "object",
+              "additionalProperties": false,
+              "required": ["file", "line", "note"],
+              "properties": { "file": { "type": "string" }, "line": { "type": "integer" }, "note": { "type": "string" } }
+            }
+          },
+          "quoted_code": { "type": "string" },
+          "evidence_proposal": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["kind", "query_json", "rule_yaml", "control_code", "control_extension"],
+            "properties": {
+              "kind": { "type": "string", "enum": ["map_query", "semgrep_rule", "generated_test", "none"] },
+              "query_json": { "type": ["string", "null"] },
+              "rule_yaml": { "type": ["string", "null"] },
+              "control_code": { "type": ["string", "null"] },
+              "control_extension": { "type": ["string", "null"] }
+            }
+          }
+        }
+      }
+    }
+  }
+}

package/schemas/hunt-result.schema.json

@@ -0,0 +1,58 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "hunt/result.json: what the engine confirmed from the saved hunt answers",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schema_version", "engine_version", "commit", "runs", "entries_hunted", "calls", "incomplete", "malformed", "hallucinations", "confirmed", "leads", "usage"],
+  "properties": {
+    "schema_version": { "const": "1.0.0" },
+    "engine_version": { "type": "string" },
+    "commit": { "type": ["string", "null"] },
+    "runs": { "type": "integer", "minimum": 0 },
+    "entries_hunted": { "type": "integer", "minimum": 0 },
+    "calls": { "type": "object", "additionalProperties": false, "required": ["complete", "incomplete", "missing"], "properties": { "complete": { "type": "integer" }, "incomplete": { "type": "integer" }, "missing": { "type": "integer" } } },
+    "incomplete": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": ["entry_id", "run", "stop", "detail"], "properties": { "entry_id": { "type": "string" }, "run": { "type": "integer" }, "stop": { "type": "string" }, "detail": { "type": "string" } } } },
+    "malformed": { "$ref": "#/$defs/dropped" },
+    "hallucinations": { "$ref": "#/$defs/dropped" },
+    "confirmed": { "type": "array", "items": { "$ref": "#/$defs/lead" } },
+    "leads": { "type": "array", "items": { "$ref": "#/$defs/lead" } },
+    "usage": { "type": "object", "additionalProperties": false, "required": ["calls", "input_tokens", "output_tokens"], "properties": { "calls": { "type": "integer" }, "input_tokens": { "type": "integer" }, "output_tokens": { "type": "integer" } } }
+  },
+  "$defs": {
+    "dropped": {
+      "type": "object", "additionalProperties": false, "required": ["count", "items"],
+      "properties": {
+        "count": { "type": "integer", "minimum": 0 },
+        "items": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": ["run", "entry_id", "lead_id", "reason"], "properties": { "run": { "type": "integer" }, "entry_id": { "type": "string" }, "lead_id": { "type": "string" }, "reason": { "type": "string" } } } }
+      }
+    },
+    "lead": {
+      "type": "object", "additionalProperties": false,
+      "required": ["key", "entry_point", "requirement_ids", "claim", "path", "sink", "runs_raised", "runs", "confirmation"],
+      "properties": {
+        "key": { "type": "string" },
+        "entry_point": { "type": "string" },
+        "requirement_ids": { "type": "array", "items": { "type": "string", "pattern": "^SEC-[A-Z]+-[0-9]{3}$" } },
+        "claim": { "type": "string" },
+        "path": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": ["file", "line", "note"], "properties": { "file": { "type": "string" }, "line": { "type": "integer", "minimum": 1 }, "note": { "type": "string" } } } },
+        "sink": { "type": "object", "additionalProperties": false, "required": ["file", "line"], "properties": { "file": { "type": "string" }, "line": { "type": "integer", "minimum": 1 } } },
+        "runs_raised": { "type": "integer", "minimum": 1 },
+        "runs": { "type": "array", "items": { "type": "integer" } },
+        "confirmation": {
+          "type": "object",
+          "required": ["status", "method", "detail"],
+          "properties": {
+            "status": { "enum": ["confirmed", "not_confirmed", "not_run"] },
+            "method": { "enum": ["map_query", "semgrep_rule", "generated_test", "none"] },
+            "detail": { "type": "string" },
+            "run": { "type": "integer" },
+            "tool": { "type": "string" },
+            "rule_id": { "type": "string" },
+            "tool_version": { "type": "string" },
+            "config_sha256": { "type": "string", "pattern": "^[0-9a-f]{64}$" }
+          }
+        }
+      }
+    }
+  }
+}

package/schemas/results.schema.json

@@ -0,0 +1,17 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://hullproof.invalid/engine/results.schema.json",
+  "title": "Hullproof Engine per requirement results (results.json)",
+  "description": "The JSON form the kit gate (hullproof-gate.mjs, loadResults) already reads: an array of {id, result, notes}, sorted by id, one row per requirement ID.",
+  "type": "array",
+  "items": {
+    "type": "object",
+    "additionalProperties": false,
+    "required": ["id", "result", "notes"],
+    "properties": {
+      "id": {"type": "string", "pattern": "^SEC-[A-Z]+-[0-9]{3}$"},
+      "result": {"type": "string", "pattern": "^(FAIL|PASS \\(static\\)|NOT APPLICABLE|NOT ASSESSED: (NEEDS DASHBOARD|NEEDS BUILD|NEEDS DYNAMIC TEST|ASK OWNER|ATTESTATION|UNKNOWN))$"},
+      "notes": {"type": "string", "maxLength": 600, "description": "NOT APPLICABLE needs a reason here. Plain text, no secret values."}
+    }
+  }
+}

package/schemas/scan-hits.schema.json

@@ -0,0 +1,32 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://hullproof.invalid/engine/scan-hits.schema.json",
+  "title": "Hullproof Engine normalised scanner hits (scan/<tool>.json)",
+  "description": "One file per scanner. Hits are sorted by file, line, tool, rule_id. No secret value, no tool message text, no absolute path, no timing.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schema_version", "tool", "hits"],
+  "properties": {
+    "schema_version": {"const": "1.0.0"},
+    "tool": {"$ref": "#/$defs/tool"},
+    "hits": {
+      "type": "array",
+      "items": {
+        "type": "object", "additionalProperties": false,
+        "required": ["tool", "rule_id", "file", "line", "sec_ids", "severity_hint", "message_key"],
+        "properties": {
+          "tool": {"$ref": "#/$defs/tool"},
+          "rule_id": {"type": "string", "minLength": 1, "maxLength": 200},
+          "file": {"type": "string", "minLength": 1, "maxLength": 300, "pattern": "^[^/\\\\]"},
+          "line": {"type": "integer", "minimum": 0, "description": "1 based; 0 only when the tool reports no line"},
+          "sec_ids": {"type": "array", "items": {"type": "string", "pattern": "^SEC-[A-Z]+-[0-9]{3}$"}, "description": "empty means unmapped: shown in the report, never in the gate"},
+          "severity_hint": {"type": ["string", "null"], "maxLength": 40},
+          "message_key": {"type": "string", "minLength": 1, "maxLength": 240}
+        }
+      }
+    }
+  },
+  "$defs": {
+    "tool": {"enum": ["semgrep", "osv-scanner", "gitleaks", "trivy", "checkov"]}
+  }
+}

package/schemas/scan-meta.schema.json

@@ -0,0 +1,25 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://hullproof.invalid/engine/scan-meta.schema.json",
+  "title": "Hullproof Engine scanner reproducibility record (scan/<tool>.meta.json)",
+  "description": "What ran, with which version and config, on which commit. Written for every adapter, including skipped ones.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schema_version", "tool", "status", "version", "tested_version_range", "version_tested", "argv", "config_sha256", "commit", "files_scanned", "files_tracked", "exit_code", "db_date", "not_assessed_sec_ids"],
+  "properties": {
+    "schema_version": {"const": "1.0.0"},
+    "tool": {"enum": ["semgrep", "osv-scanner", "gitleaks", "trivy", "checkov"]},
+    "status": {"enum": ["ran", "skipped: not installed", "skipped: not applicable", "skipped: network not allowed", "failed"]},
+    "version": {"type": ["string", "null"]},
+    "tested_version_range": {"type": "string", "minLength": 1},
+    "version_tested": {"type": "boolean"},
+    "argv": {"type": "array", "items": {"type": "string"}},
+    "config_sha256": {"type": ["string", "null"], "pattern": "^[0-9a-f]{64}$"},
+    "commit": {"type": ["string", "null"], "pattern": "^[0-9a-f]{40}$"},
+    "files_scanned": {"type": ["integer", "null"], "minimum": 0},
+    "files_tracked": {"type": ["integer", "null"], "minimum": 0},
+    "exit_code": {"type": ["integer", "null"]},
+    "db_date": {"type": ["string", "null"], "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}$"},
+    "not_assessed_sec_ids": {"type": "array", "items": {"type": "string", "pattern": "^SEC-[A-Z]+-[0-9]{3}$"}}
+  }
+}

package/schemas/stack.schema.json

@@ -0,0 +1,93 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://hullproof.invalid/engine/stack.schema.json",
+  "title": "Hullproof Engine stack.json",
+  "description": "Written by hullproof discover. Arrays of items are sorted by id; evidence by confidence, then file, then line; skipped by path; unknown by file then note. No timestamp, so the same files and detector files give the same bytes.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schema_version", "engine_version", "detectors_sha256", "commit", "confirmed_by_user", "files", "limits", "skipped",
+    "languages", "runtimes", "frameworks", "package_managers", "data_stores", "auth", "payments", "ai", "hosting", "iac", "containers", "ci", "mobile", "unknown"],
+  "properties": {
+    "schema_version": {"const": "1.0.0"},
+    "engine_version": {"type": "string", "minLength": 1},
+    "detectors_sha256": {"type": "string", "pattern": "^[0-9a-f]{64}$"},
+    "commit": {"type": ["string", "null"], "pattern": "^[0-9a-f]{40}$"},
+    "confirmed_by_user": {"type": "boolean"},
+    "files": {
+      "type": "object", "additionalProperties": false, "required": ["listed", "scanned_for_imports"],
+      "properties": {"listed": {"type": "integer", "minimum": 0}, "scanned_for_imports": {"type": "integer", "minimum": 0}}
+    },
+    "limits": {
+      "type": "object", "additionalProperties": false, "required": ["max_files", "max_bytes_per_file", "file_cap_reached", "truncated_files"],
+      "properties": {
+        "max_files": {"type": "integer", "minimum": 1},
+        "max_bytes_per_file": {"type": "integer", "minimum": 1},
+        "file_cap_reached": {"type": "boolean"},
+        "truncated_files": {"type": "array", "items": {"$ref": "#/$defs/path"}}
+      }
+    },
+    "skipped": {
+      "type": "array",
+      "items": {
+        "type": "object", "additionalProperties": false, "required": ["path", "reason"],
+        "properties": {
+          "path": {"type": "string", "minLength": 1},
+          "reason": {"enum": ["gitignore", "dependency folder", "build output", "tool folder", "symlink"]}
+        }
+      }
+    },
+    "languages": {"$ref": "#/$defs/items"},
+    "runtimes": {"$ref": "#/$defs/items"},
+    "frameworks": {"$ref": "#/$defs/items"},
+    "package_managers": {"$ref": "#/$defs/items"},
+    "data_stores": {"$ref": "#/$defs/items"},
+    "auth": {"$ref": "#/$defs/items"},
+    "payments": {"$ref": "#/$defs/items"},
+    "ai": {"$ref": "#/$defs/items"},
+    "hosting": {"$ref": "#/$defs/items"},
+    "iac": {"$ref": "#/$defs/items"},
+    "containers": {"$ref": "#/$defs/items"},
+    "ci": {"$ref": "#/$defs/items"},
+    "mobile": {"$ref": "#/$defs/items"},
+    "unknown": {
+      "type": "array",
+      "items": {
+        "type": "object", "additionalProperties": false, "required": ["file", "note"],
+        "properties": {"file": {"$ref": "#/$defs/path"}, "note": {"type": "string", "minLength": 1}}
+      }
+    }
+  },
+  "$defs": {
+    "path": {"type": "string", "minLength": 1, "pattern": "^[^/\\\\]", "description": "repository relative POSIX path"},
+    "confidence": {"enum": ["high", "medium", "low"], "description": "high: a manifest dependency or a file whose only purpose is this thing. medium: a source import, an SDK dependency, or a content pattern. low: a weak hint."},
+    "evidence": {
+      "type": "object", "additionalProperties": false, "required": ["file", "rule", "confidence"],
+      "description": "Exactly one of line or key is present.",
+      "properties": {
+        "file": {"$ref": "#/$defs/path"},
+        "line": {"type": "integer", "minimum": 1},
+        "key": {"type": "string", "minLength": 1},
+        "rule": {"type": "string", "pattern": "^[a-z_]+\\.[a-z0-9.-]+\\.(dep|import|content|file|extension)(\\.[a-z0-9]+)?$"},
+        "confidence": {"$ref": "#/$defs/confidence"}
+      }
+    },
+    "items": {
+      "type": "array",
+      "items": {
+        "type": "object", "additionalProperties": false, "required": ["id", "confidence", "evidence", "evidence_count"],
+        "properties": {
+          "id": {"type": "string", "pattern": "^[a-z0-9][a-z0-9.-]*$"},
+          "confidence": {"$ref": "#/$defs/confidence"},
+          "evidence": {"type": "array", "minItems": 1, "maxItems": 5, "items": {"$ref": "#/$defs/evidence"}},
+          "evidence_count": {"type": "integer", "minimum": 1},
+          "versions": {"type": "array", "items": {"type": "string", "minLength": 1}, "description": "package@declared version or range, as written in the manifest"},
+          "file_count": {"type": "integer", "minimum": 1},
+          "kind": {"enum": ["platform", "cloud"]},
+          "clouds": {"type": "array", "items": {"type": "string", "minLength": 1}},
+          "lockfiles": {"type": "array", "items": {"$ref": "#/$defs/path"}},
+          "manifests": {"type": "array", "items": {"$ref": "#/$defs/path"}}
+        }
+      }
+    }
+  }
+}

package/src/checks/README.md

@@ -0,0 +1,32 @@
+# Executable checks
+
+A check settles part of one or more requirements from the files of a commit. It returns PASS (static), FAIL or a NOT ASSESSED sub state through its `on_true` and `on_false` words, or it does not run and says why in `checks.json` under `not_run` (`not applicable: ...` or `cannot run: ...`). No check runs a program, uses the network or a model.
+
+Rules every check follows:
+
+1. `PASS (static)` only when every requirement it names has repo authority. A check may FAIL a dashboard or runtime requirement for the part a file settles and never PASS it (STANDARD.md, "A file can fail what it cannot pass"). `test/checks.test.ts` enforces this against the kit's controls file.
+2. A check that does not apply never becomes NOT APPLICABLE for its requirement: the requirement stays NOT ASSESSED.
+3. Every check has `test/fixtures/checks/<name>/pass` and `.../fail`.
+4. Checks never search `.hullproof/`, the kit's own folders or `docs/security/` (`LEFT_OUT` in `context.ts`).
+
+Two forms:
+
+1. Declarative: `checks/<area>.<name>.json`, shaped by `schemas/check.schema.json`, run by `ops.ts`.
+2. TypeScript, for what no op can say: `src/checks/code/*.ts`, each exporting a `CodeCheck` (`types.ts`) and listed in `CODE_CHECKS` in `run.ts`.
+
+## Op parameters
+
+| Op | Params | True when |
+|---|---|---|
+| `file_exists` | `files` (globs), `exclude`, `note` | a listed file matches |
+| `file_absent` | same | no listed file matches; the matches are the evidence |
+| `file_exists_for_each` | `manifests`: manifest name to lockfile names, `note` | every manifest has a lockfile in its folder or a parent |
+| `regex_present` | `files`, `exclude`, `only_if` (a file is searched only if it matches), `pattern`, `ignore_case`, `each_file` (every file must match), `when_no_files` (`not_applicable`, `true`, `false`), `precondition` {`files`, `exclude`, `pattern`} (no file meets it: not applicable; when nothing is found, its files are the evidence), `note`, `missing_note`, `precondition_note`, `not_applicable_reason` | the pattern is found (in every file with `each_file`) |
+| `regex_absent` | the same | the pattern is found nowhere; the matches are the evidence |
+| `sql_every_table_has` | `files`, `schemas` (default `public`) | every table created in those schemas has row level security enabled later in file order |
+| `workflow_uses_pinned_sha` | `files` (default GitHub workflows) | every third party `uses:` ends in a 40 character SHA |
+| `workflow_permissions` | `files` | every workflow declares permissions at the top or on every job, and none says `write-all` |
+| `version_in_table` | `table` (kit relative path), `frameworks`: stack id to {`heading`, `package`, `digits`} | every declared version of a listed framework is on a line the kit's support table marks Supported |
+| `json_value` | | not built; no check needs it yet |
+
+Regex ops record an `absence_search` (pattern, file globs, files searched, matches) on every result.

package/src/checks/code/admin-role.ts

@@ -0,0 +1,49 @@
+// check.authz.admin-role-check: every server handler under an admin path checks an admin role on the server.
+// A session check alone (any signed in user) is not a role check. Middleware or a shared guard that checks the role for
+// the whole admin path is not followed in Phase 1; such a project sees this FAIL and the report says how to confirm it.
+import { fileURLToPath } from 'node:url';
+import type { CheckEvidence } from '../../types/index.ts';
+import { byFileLine, lineOf, type CheckContext } from '../context.ts';
+import type { OpOutcome } from '../ops.ts';
+import type { CodeCheck } from '../types.ts';
+import { handlerFiles } from './shared.ts';
+
+const ADMIN_PATH = /(^|\/)(admin|backoffice|staff|superuser)(\/|\.|$)/i;
+const ROLE_CHECK = new RegExp([
+  String.raw`\brole\s*(?:===?|!==?|==)\s*["'\x60](?:admin|owner|superadmin|staff)`,
+  String.raw`["'\x60](?:admin|owner|superadmin|staff)["'\x60]\s*(?:===?|!==?)\s*[\w.?]*role`,
+  String.raw`\b(?:is_?admin|isAdmin|requireAdmin|require_admin|assertAdmin|ensureAdmin|adminOnly|admin_required|requireRole|require_role|checkRole|withRole|hasRole|has_role|hasPermission|has_perm|is_staff|is_superuser|authorize)\b`,
+  String.raw`@(?:PreAuthorize|Secured|RolesAllowed|Roles|staff_member_required|user_passes_test|permission_required)`,
+  String.raw`\bcurrent_user\.admin\?|\buser\.admin\b|roles?\.includes\(\s*["']admin`,
+].join('|'));
+const HANDLER = /export\s+(?:async\s+)?(?:function\s+|const\s+)(GET|POST|PUT|PATCH|DELETE|default|handler)\b|@(?:app|router|api_view|\w+)\.(?:get|post|put|patch|delete|route)\(|\bdef\s+(?:get|post|put|patch|delete|index|show|create|update|destroy)\b|\b(?:router|app)\.(?:get|post|put|patch|delete)\(/g;
+
+export function run(ctx: CheckContext): OpOutcome {
+  const files = handlerFiles(ctx).filter((f) => ADMIN_PATH.test(f));
+  if (files.length === 0) return { value: 'not_applicable', reason: 'no server handler under an admin path', evidence: [], absence: null };
+  const bad: CheckEvidence[] = [];
+  for (const file of files) {
+    const text = ctx.text(file);
+    if (ROLE_CHECK.test(text)) continue;
+    const handlers = [...text.matchAll(HANDLER)];
+    const lines = handlers.length ? handlers.map((h) => lineOf(text, h.index!)) : [1];
+    for (const line of lines) bad.push({ file, line, note: 'admin handler with no server side admin role check' });
+  }
+  return {
+    value: bad.length === 0,
+    evidence: bad.sort(byFileLine),
+    absence: { pattern: ROLE_CHECK.source, files_searched: files.length, file_globs: ['handler files under an admin path'], matches: files.length - new Set(bad.map((b) => b.file)).size },
+  };
+}
+
+export const check: CodeCheck = {
+  id: 'check.authz.admin-role-check',
+  sec_ids: ['SEC-AUTHZ-020'],
+  applies_when: {},
+  op: 'code',
+  on_true: 'NOT ASSESSED: NEEDS DYNAMIC TEST',
+  on_false: 'FAIL',
+  fixtures: { pass: 'test/fixtures/checks/admin-role-check/pass', fail: 'test/fixtures/checks/admin-role-check/fail' },
+  source: fileURLToPath(import.meta.url),
+  run,
+};

package/src/checks/code/owner-filter.ts

@@ -0,0 +1,95 @@
+// Two checks from one detector: a record read by an id that came from the request (or from a model's tool arguments)
+// must also be filtered by its owner. check.authz.owner-filter-on-id-read covers request handlers (SEC-AUTHZ-003);
+// check.ai.tool-owner-filter covers functions handed to a model as tools (SEC-AI-021).
+// Detected read forms: SQL text (any driver), Prisma and Drizzle style where objects, Supabase .eq('id'), Mongoose
+// findById, Django .get(pk=) and get_object_or_404, Rails .find(params[:id]), Laravel ::find / findOrFail.
+// It reads code, so it can FAIL those runtime requirements for the part a file settles and never PASS them.
+import { fileURLToPath } from 'node:url';
+import type { CheckEvidence } from '../../types/index.ts';
+import { byFileLine, lineOf, type CheckContext } from '../context.ts';
+import type { OpOutcome } from '../ops.ts';
+import type { CodeCheck } from '../types.ts';
+import { handlerFiles, NOT_HANDLER } from './shared.ts';
+
+const READS: { re: RegExp; what: string }[] = [
+  { re: /\bSELECT\b[^;"'`]*?\bWHERE\s+(?:\w+\.)?(?:id|pk|uuid)\s*=\s*(?:\?|\$\d+|:\w+|%s|@\w+|\$\{)/gi, what: 'SQL read by id' },
+  { re: /\.(?:findUnique|findFirst|findOne|findOneBy|findOneOrFail)\(\s*\{\s*where:\s*\{\s*id\s*[:,}]/g, what: 'ORM read by id' },
+  { re: /\.(?:findById|findByPk|findOneById)\(/g, what: 'ORM read by id' },
+  { re: /\.eq\(\s*["'](?:id|uuid)["']\s*,/g, what: 'Supabase read by id' },
+  { re: /\.objects\.get\(\s*(?:id|pk)\s*=|get_object_or_404\(\s*\w+\s*,\s*(?:id|pk)\s*=/g, what: 'Django read by id' },
+  { re: /\.find\(\s*params\[:id\]\s*\)|::(?:find|findOrFail)\(\s*\$(?:id|request)/g, what: 'Rails or Laravel read by id' },
+];
+// Words that show the read is scoped to the caller.
+const OWNER = /owner|user_?id|userId|tenant|account_?id|accountId|org_?id|orgId|organization|workspace|created_by|createdBy|author|auth\.uid|current_?user|request\.user|session\.user|\.user\.id|ctx\.user|scope|policy/i;
+// Words that show the id came from the request or from model arguments.
+const INPUT = /params|args|arguments|req\.|request\.|query|body|input|searchParams|\$_(GET|POST|REQUEST)|kwargs/;
+const WRITE = /\b(UPDATE|DELETE|INSERT)\b/i;
+
+// The statement around a match: from the match to the first semicolon or blank line, at most 6 lines.
+function statement(text: string, at: number): string {
+  const lines = text.slice(at).split('\n').slice(0, 6);
+  const out: string[] = [];
+  for (const l of lines) { if (out.length && l.trim() === '') break; out.push(l); if (/;\s*$/.test(l)) break; }
+  return out.join('\n');
+}
+
+function scan(files: string[], ctx: CheckContext): CheckEvidence[] {
+  const bad: CheckEvidence[] = [];
+  for (const file of files) {
+    const text = ctx.text(file);
+    for (const { re, what } of READS) {
+      re.lastIndex = 0;
+      for (let m = re.exec(text); m; m = re.exec(text)) {
+        // For SQL, judge only the WHERE clause onward: an owner column in the select list filters nothing.
+        const where = m[0].search(/\bWHERE\b/i);
+        const stmt = statement(text, m.index + Math.max(0, where));
+        if (WRITE.test(m[0]) || OWNER.test(stmt) || !INPUT.test(stmt)) continue;
+        bad.push({ file, line: lineOf(text, m.index), note: `${what} with an id from the request and no owner filter` });
+      }
+    }
+  }
+  return bad.sort(byFileLine);
+}
+
+const AI_TOOL_GLOBS = ['**/{ai,llm,agent,agents,mcp,tools}/**/*.{ts,js,mjs,py}', '**/*tool*.{ts,js,mjs,py}'];
+const aiToolFiles = (ctx: CheckContext): string[] =>
+  ctx.select(AI_TOOL_GLOBS, NOT_HANDLER).filter((f) => /\btools?\b|tool_call|function_call|bind_tools|@tool\b/.test(ctx.text(f)));
+
+function outcome(files: string[], ctx: CheckContext, none: string): OpOutcome {
+  if (files.length === 0) return { value: 'not_applicable', reason: none, evidence: [], absence: null };
+  const bad = scan(files, ctx);
+  return {
+    value: bad.length === 0,
+    evidence: bad,
+    absence: { pattern: 'reads by id (SQL, ORM, Supabase, Django, Rails, Laravel) with no owner, user or tenant term in the statement', files_searched: files.length, file_globs: [], matches: bad.length },
+  };
+}
+
+const source = fileURLToPath(import.meta.url);
+
+export const ownerFilter: CodeCheck = {
+  id: 'check.authz.owner-filter-on-id-read',
+  sec_ids: ['SEC-AUTHZ-003'],
+  applies_when: {},
+  op: 'code',
+  on_true: 'NOT ASSESSED: NEEDS DYNAMIC TEST',
+  on_false: 'FAIL',
+  fixtures: { pass: 'test/fixtures/checks/owner-filter-on-id-read/pass', fail: 'test/fixtures/checks/owner-filter-on-id-read/fail' },
+  source,
+  run: (ctx) => {
+    const ai = new Set(aiToolFiles(ctx));
+    return outcome(handlerFiles(ctx).filter((f) => !ai.has(f)), ctx, 'no request handler found');
+  },
+};
+
+export const toolOwnerFilter: CodeCheck = {
+  id: 'check.ai.tool-owner-filter',
+  sec_ids: ['SEC-AI-021'],
+  applies_when: {},
+  op: 'code',
+  on_true: 'NOT ASSESSED: NEEDS DYNAMIC TEST',
+  on_false: 'FAIL',
+  fixtures: { pass: 'test/fixtures/checks/tool-owner-filter/pass', fail: 'test/fixtures/checks/tool-owner-filter/fail' },
+  source,
+  run: (ctx) => outcome(aiToolFiles(ctx), ctx, 'no file that defines tools for a model was found'),
+};

package/src/checks/code/shared.ts

@@ -0,0 +1,66 @@
+// Shared helpers for the TypeScript checks: which files are server request handlers, and small text scanners.
+import type { CheckContext } from '../context.ts';
+
+// Server side request handlers across common stacks. Stack specific globs are marked by the framework they serve.
+export const HANDLER_GLOBS = [
+  '**/app/**/route.{ts,js,mjs,tsx,jsx}',            // Next.js App Router
+  '**/pages/api/**/*.{ts,js,mjs}',                   // Next.js Pages Router
+  '**/app/actions/**/*.{ts,js}',                     // Next.js Server Actions folder
+  '**/api/**/*.{ts,js,mjs,py,go,php,rb}',            // Vercel and Netlify functions, generic api folders
+  '**/routes/**/*.{ts,js,mjs,py,php,rb}',            // Express, Remix, SvelteKit, FastAPI routers, Laravel routes
+  '**/routers/**/*.py', '**/views.py', '**/views/**/*.py', '**/app.py', '**/main.py', // Django, Flask, FastAPI
+  '**/controllers/**/*.{ts,js,rb,php}', 'app/Http/Controllers/**/*.php', // Rails, Laravel, Nest, Adonis
+  '**/*Controller.{java,kt,cs}',                     // Spring, ASP.NET
+  '**/handlers/**/*.{go,ts,js}', '**/*handler*.go', // Go
+  'supabase/functions/**/*.ts', 'netlify/functions/**/*.{ts,js}', 'functions/**/*.{ts,js,py}', // edge and cloud functions
+  '**/server/**/*.{ts,js}', '**/hooks.server.{ts,js}', '**/+server.{ts,js}', '**/+page.server.{ts,js}',
+];
+export const NOT_HANDLER = ['**/*.test.*', '**/*.spec.*', '**/__tests__/**', '**/test/**', '**/tests/**', '**/*.d.ts'];
+
+// Handler files, without browser only modules ("use client").
+export function handlerFiles(ctx: CheckContext): string[] {
+  return ctx.select(HANDLER_GLOBS, NOT_HANDLER).filter((f) => !/^\s*["']use client["']/.test(ctx.text(f)));
+}
+
+// The index just past the bracket that closes the one at `open`, or -1. Skips string literals and comments, roughly.
+export function closeOf(text: string, open: number): number {
+  const pair: Record<string, string> = { '(': ')', '{': '}', '[': ']' };
+  const stack: string[] = [];
+  for (let i = open; i < text.length; i++) {
+    const c = text[i];
+    if (c === '"' || c === "'" || c === '`') {
+      for (i++; i < text.length && text[i] !== c; i++) if (text[i] === '\\') i++;
+      continue;
+    }
+    if (c === '/' && text[i + 1] === '/') { while (i < text.length && text[i] !== '\n') i++; continue; }
+    if (c === '/' && text[i + 1] === '*') { const e = text.indexOf('*/', i + 2); i = e < 0 ? text.length : e + 1; continue; }
+    if (pair[c]) stack.push(pair[c]);
+    else if (c === stack[stack.length - 1]) { stack.pop(); if (stack.length === 0) return i + 1; }
+  }
+  return -1;
+}
+
+// The body of the `if` whose keyword starts at `at`: a braced block, an indented Python block, or the rest of the statement.
+export function ifBody(text: string, at: number): string {
+  const py = /^if\s+[^\n(]*:\s*(#.*)?$/m.exec(text.slice(at, text.indexOf('\n', at) < 0 ? text.length : text.indexOf('\n', at)));
+  if (py) {
+    const lineEnd = text.indexOf('\n', at);
+    const lineStart = text.lastIndexOf('\n', at) + 1;
+    const indent = /^\s*/.exec(text.slice(lineStart))![0].length;
+    const rest = text.slice(lineEnd + 1).split('\n');
+    const body: string[] = [];
+    for (const l of rest) { if (l.trim() === '') continue; if (/^\s*/.exec(l)![0].length <= indent) break; body.push(l); }
+    return text.slice(at, lineEnd) + '\n' + body.join('\n');
+  }
+  const paren = text.indexOf('(', at);
+  const condEnd = paren < 0 ? -1 : closeOf(text, paren);
+  if (condEnd < 0) return text.slice(at, at + 200);
+  const after = text.slice(condEnd).search(/\S/);
+  const start = condEnd + (after < 0 ? 0 : after);
+  if (text[start] === '{') { const e = closeOf(text, start); return text.slice(at, e < 0 ? start + 400 : e); }
+  const end = text.slice(start).search(/[;\n]/);
+  return text.slice(at, end < 0 ? text.length : start + end + 1);
+}
+
+// A statement that stops the request: return, throw, raise, abort, or an explicit 4xx or 5xx response.
+export const EXITS = /\b(return|throw|raise|abort|panic|exit|die)\b|\bstatus\(\s*[45]\d\d|\bhttp\.Error\b|res\.sendStatus\(\s*[45]/;

package/src/checks/code/webhook-verify.ts

@@ -0,0 +1,75 @@
+// check.api.webhook-verified-before-use: a webhook handler checks the sender's signature, and a failed check stops the
+// request before the event is used. Works on any stack whose handlers are found by handlerFiles() (JS, TS, Python, Go,
+// PHP, Ruby). It reads code, so it can FAIL SEC-API-101 for the part a file settles and never PASS it.
+import { fileURLToPath } from 'node:url';
+import type { CheckEvidence } from '../../types/index.ts';
+import { byFileLine, lineOf, type CheckContext } from '../context.ts';
+import type { OpOutcome } from '../ops.ts';
+import type { CodeCheck } from '../types.ts';
+import { EXITS, handlerFiles, ifBody } from './shared.ts';
+
+// A file is a webhook handler when its path says webhook or it reads a provider signature header.
+const WEBHOOK_PATH = /webhook/i;
+const SIGNATURE_HEADER = /\b[xX]-[a-zA-Z-]*[sS]ignature\b|stripe-signature|paystack-signature|svix-signature|webhook-signature|HTTP_X_[A-Z_]*SIGNATURE/;
+// Calls that check a signature and return a result the caller must act on.
+const VERIFY_CALL = /\b((?:\w+\.)?(?:verify\w*|validate\w*[sS]ignature\w*|check\w*[sS]ignature\w*|is\w*[vV]alid\w*[sS]ignature\w*|compare_digest|hash_equals|secure_compare|timingSafeEqual|hmac\.Equal|ValidatePayload))\s*\(/g;
+// Calls documented by their providers to throw (or raise) on a bad signature, so code after them runs only when valid.
+const THROWING = /constructEvent|construct_event|webhooks\.verify|wh\.verify|Webhook\.construct|unwrap\(|constructEventAsync|validateRequest/;
+
+export function scanFile(file: string, text: string): CheckEvidence[] {
+  const bad: CheckEvidence[] = [];
+  let calls = 0;
+  VERIFY_CALL.lastIndex = 0;
+  for (let m = VERIFY_CALL.exec(text); m; m = VERIFY_CALL.exec(text)) {
+    if (/function\s+$|def\s+$|func\s+(\([^)]*\)\s*)?$/.test(text.slice(Math.max(0, m.index - 30), m.index))) continue; // a definition, not a call
+    calls++;
+    const lineStart = text.lastIndexOf('\n', m.index) + 1;
+    const lineText = text.slice(lineStart, text.indexOf('\n', m.index) < 0 ? text.length : text.indexOf('\n', m.index));
+    if (THROWING.test(m[1]) || THROWING.test(lineText)) continue;
+    // The call sits in an if condition: `if (!verify(...)) return ...` or `if not verify(...): raise ...`.
+    const ifAt = /\bif\b/.exec(lineText);
+    if (ifAt && lineStart + ifAt.index < m.index) {
+      const body = ifBody(text, lineStart + ifAt.index);
+      if (!EXITS.test(body.slice(body.indexOf(m[0]) + m[0].length))) bad.push({ file, line: lineOf(text, m.index), note: 'a failed signature check does not stop the request' });
+      continue;
+    }
+    // The result is stored: `const ok = verify(...)`, `ok := verify(...)`, `ok = verify(...)`.
+    const assigned = /(?:const|let|var|val)?\s*([A-Za-z_$][\w$]*)\s*(?::=|=)\s*(?:await\s+)?[\w.$]*$/.exec(text.slice(lineStart, m.index));
+    if (!assigned) continue; // a bare call: its result is not used as a gate, and most such helpers throw
+    const name = assigned[1];
+    const after = text.slice(m.index);
+    const guard = new RegExp(`\\bif\\s*\\(?\\s*(?:!\\s*${name}\\b|not\\s+${name}\\b|${name}\\s*(?:===?|is)\\s*(?:false|False|nil|None)|${name}\\s*!==?\\s*true)`, 'g');
+    const guards = [...after.matchAll(guard)];
+    if (guards.length === 0) { bad.push({ file, line: lineOf(text, m.index), note: `the result ${name} of the signature check is never used to stop the request` }); continue; }
+    const stops = guards.some((g) => EXITS.test(ifBody(text, m!.index + g.index!)));
+    if (!stops) bad.push({ file, line: lineOf(text, m.index + guards[0].index!), note: `when ${name} is false the handler carries on and uses the event` });
+  }
+  if (calls === 0 && !THROWING.test(text)) {
+    const handler = /export\s+(?:async\s+)?(?:function|const)\s+(?:POST|PUT|handler|default)\b|@(?:app|router)\.post|\bdef\s+\w*webhook\w*|func\s+\w*[Ww]ebhook\w*/.exec(text);
+    bad.push({ file, line: handler ? lineOf(text, handler.index) : 1, note: 'no call that checks the sender signature was found in this webhook handler' });
+  }
+  return bad;
+}
+
+export function run(ctx: CheckContext): OpOutcome {
+  const files = handlerFiles(ctx).filter((f) => WEBHOOK_PATH.test(f) || SIGNATURE_HEADER.test(ctx.text(f)));
+  if (files.length === 0) return { value: 'not_applicable', reason: 'no webhook handler found', evidence: [], absence: null };
+  const bad = files.flatMap((f) => scanFile(f, ctx.text(f))).sort(byFileLine);
+  return {
+    value: bad.length === 0,
+    evidence: bad.length ? bad : files.map((file) => ({ file, line: 1, note: 'signature check found and a failure stops the request' })),
+    absence: { pattern: `${VERIFY_CALL.source} followed by a guard that returns or throws`, files_searched: files.length, file_globs: ['handler files whose path says webhook or that read a signature header'], matches: files.length - new Set(bad.map((b) => b.file)).size },
+  };
+}
+
+export const check: CodeCheck = {
+  id: 'check.api.webhook-verified-before-use',
+  sec_ids: ['SEC-API-101', 'SEC-API-126'],
+  applies_when: {},
+  op: 'code',
+  on_true: 'NOT ASSESSED: NEEDS DYNAMIC TEST',
+  on_false: 'FAIL',
+  fixtures: { pass: 'test/fixtures/checks/webhook-verified-before-use/pass', fail: 'test/fixtures/checks/webhook-verified-before-use/fail' },
+  source: fileURLToPath(import.meta.url),
+  run,
+};