Open-source AI Security Operations Center: alert fusion, LLM-agent triage, MITRE ATT&CK investigation, and a replayable decision ledger for every agent step. Self-hostable, runs with no API keys, MIT licensed. Ships an MCP server for Claude, Cursor and Continue.
Python agentic-aiai-securityalert-triageblue-teamcybersecuritydetection-engineeringincident-responselanggraphllm-agentsmcpmitre-attackmodel-context-protocolpurple-teamsecurity-operationsself-hostedsiemsoarsocthreat-detectionthreat-intelligence
fix(gates): detect duplicate migration numbers, and stop crediting a tenant token that constrains nothing (#1530)
Beenu Arora3bc86508b003
diff --git a/.github/workflows/migration-numbering.yml b/.github/workflows/migration-numbering.ymlnew file mode 100644index 000000000..ad08ab3a6--- /dev/null+++ b/.github/workflows/migration-numbering.yml@@ -0,0 +1,60 @@+name: Migration numbering++# Two migrations must not claim the same number.+#+# `services/api/migrations/NNN_*.sql` is a first-come namespace and git does+# not defend it: two branches that each add a file called `121_*.sql` merge+# without a conflict, because the filenames differ. That happened — one 121+# merged while another sat open in a pull request — and nothing in the+# repository noticed. `scripts/check_migration_numbering.py` explains what+# then diverges between a fresh install and an upgrade.+#+# Deliberately NO `paths:` filter, on either trigger.+#+# A path filter here would be wrong twice over. The obvious way to write one+# is `services/api/migrations/**`, and the collision is created by a branch+# that adds exactly one file to exactly that directory — so the filter would+# usually fire. But the defect is a property of the *pair*, and the second+# half of the pair arrives on main from somebody else's merge: a pull request+# that touched no migration at all can become the duplicate without its own+# diff changing. Only an unconditional run sees that.+#+# The second reason is the one this repository keeps relearning: a required+# check that reports success having executed only its "nothing under test+# changed" step is indistinguishable from one that graded the commit. 28+# workflows here once keyed `concurrency` on `github.ref` and cancelled+# themselves; a backup gate reported success on 74 of 100 runs without+# restoring anything. The gate is a sub-second, dependency-free read of+# `git ls-files`, so there is nothing to buy by skipping it.++on:+ pull_request:+ push:+ branches: [main, develop]++concurrency:+ # Supersede a pull request's own earlier runs; never supersede a push.+ # Only a branch's head commit needs grading, but every commit that lands on+ # a protected branch must be graded — and `cancel-in-progress: false` alone+ # does not achieve that, because a run left *pending* in a busy group is+ # cancelled when the next one queues. Gate:+ # scripts/check_workflow_concurrency.py+ group: ${{ github.workflow }}-${{ github.ref }}-${{ github.event_name }}-${{ github.event.pull_request.number || github.sha }}+ cancel-in-progress: ${{ github.event_name == 'pull_request' }}++jobs:+ migration-numbering:+ name: Migrations — No duplicate numbers+ runs-on: ubuntu-latest+ steps:+ - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7+ - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0+ with:+ python-version: "3.11"+ # Self-test first: it proves the detector still fires on an injected+ # duplicate and still forgives a gap, so a green gate below means the+ # tree is clean rather than that the rule stopped matching.+ - name: Gate self-test+ run: python scripts/check_migration_numbering.py --self-test+ - name: No two migrations claim the same number+ run: python scripts/check_migration_numbering.pydiff --git a/ROADMAP.md b/ROADMAP.mdindex 9ab9d8542..8b165f137 100644--- a/ROADMAP.md+++ b/ROADMAP.md@@ -45,7 +45,7 @@ A proof-first, security-first program to make every README claim gate-backed, cl- **Phase D (breadth):** D1 eight connectors (QRadar/Exabeam/Securonix/Devo/Netskope/Windows-Sysmon/Zeek-Suricata/syslog-CEF) · D2 AI/LLM-usage audit connector + `llm-*` detections + hot/cold lake tiering · D3 live-vendor mock-server smoke.- **Phase E (prove it):** E1 CI-gated benchmark scoreboard tied to a deterministic live-agent MITRE-accuracy run.-The claim-to-gate matrix stands at **319 rows — 315 GATED / 4 PARTIAL / 0 NO GATE**. Four rows are PARTIAL, each naming what closes it: "Cloud-native collection" until a capture recorded from a live Event Hub replaces the fixture synthesised from the Avro specification; "the retention window a tenant chooses is the one the lake honours" until a live ClickHouse test watches a row survive past the old 90-day boundary; "the AI estate is discovered on the endpoint" until a containerised osquery runs the shipped pack end to end; and "a reported phishing message can be purged across its recipients" until a maintainer-supplied Microsoft 365 or Google Workspace tenant lets the documented request shapes be exercised for real. "SSO completes a sign-in" closed the way the programme requires — by building the gate it named: `sso-live.yml` stands up a containerised Keycloak and both legs have been observed to pass. Every other product claim is backed by a failing test, none is a named deferral either, and the ratchet (`MAX_NO_GATE=0`) forbids any regression. Every PARTIAL row was closed by building the gate it named, never by relabelling. Count the table rows with `python3 scripts/check_claim_gate_matrix.py` rather than trusting a figure quoted in prose — this line has gone stale before. The six lettered deferrals are scoped in [`docs/audit/DEFERRED_SUBPHASES.md`](docs/audit/DEFERRED_SUBPHASES.md).+The claim-to-gate matrix stands at **321 rows — 317 GATED / 4 PARTIAL / 0 NO GATE**. Four rows are PARTIAL, each naming what closes it: "Cloud-native collection" until a capture recorded from a live Event Hub replaces the fixture synthesised from the Avro specification; "the retention window a tenant chooses is the one the lake honours" until a live ClickHouse test watches a row survive past the old 90-day boundary; "the AI estate is discovered on the endpoint" until a containerised osquery runs the shipped pack end to end; and "a reported phishing message can be purged across its recipients" until a maintainer-supplied Microsoft 365 or Google Workspace tenant lets the documented request shapes be exercised for real. "SSO completes a sign-in" closed the way the programme requires — by building the gate it named: `sso-live.yml` stands up a containerised Keycloak and both legs have been observed to pass. Every other product claim is backed by a failing test, none is a named deferral either, and the ratchet (`MAX_NO_GATE=0`) forbids any regression. Every PARTIAL row was closed by building the gate it named, never by relabelling. Count the table rows with `python3 scripts/check_claim_gate_matrix.py` rather than trusting a figure quoted in prose — this line has gone stale before. The six lettered deferrals are scoped in [`docs/audit/DEFERRED_SUBPHASES.md`](docs/audit/DEFERRED_SUBPHASES.md).## v4.0 — Shippeddiff --git a/apps/docs/docs/compliance/evidence-pack.md b/apps/docs/docs/compliance/evidence-pack.mdindex f5b737310..39b05568d 100644--- a/apps/docs/docs/compliance/evidence-pack.md+++ b/apps/docs/docs/compliance/evidence-pack.md@@ -33,7 +33,7 @@ and says so.| Prompt-injection resistance | Three adversarial corpora: 32 payloads scanned in isolation and 71 incident pairs whose payloads are placed in attacker-controllable fields, both against a clean twin with a recall floor and a false-positive ceiling, plus 34 held-out pairs authored after the guard was frozen and carrying no floor at all, on which the guard measures 7.1% | `services/agents/tests/adversarial/` || Claim-to-gate traceability | Every product claim mapped to the CI job that fails when it stops being true | `docs/audit/CLAIM_TO_GATE_MATRIX.md` |-The last row is the one worth reading first. It is the honest index: 315 rows+The last row is the one worth reading first. It is the honest index: 317 rows`GATED`, 4 `PARTIAL`, and a ratchet that refuses to let a row sit at`NO GATE`. Re-read the figure from the table rather than from here — a countcopied into prose goes stale in silence, which is whydiff --git a/docs/audit/CLAIM_TO_GATE_MATRIX.md b/docs/audit/CLAIM_TO_GATE_MATRIX.mdindex 0aeac33e0..607bf0e9f 100644--- a/docs/audit/CLAIM_TO_GATE_MATRIX.md+++ b/docs/audit/CLAIM_TO_GATE_MATRIX.md@@ -327,11 +327,13 @@ Statuses: `GATED` (a CI job fails when the claim stops being true) · `PARTIAL`| A reported phishing message can be grouped into a campaign and purged across its recipients, at the tier the recipient count earns | `apps/docs/docs/operations/mailbox-remediation.md`; depth plan 7.1 | `ci.yml :: Python — Lint & Type-check` (`check_action_contract.py` — the five mailbox verbs are in both halves of the vocabulary, every one has an executor, `purge_email` declares `restore_email` as a platform reverse that exists, and the probe it declares is reachable through an `ActionType`; `check_module_reachability.py` — the intake adapters have a production caller, which is the report-mailbox worker rather than only the route) + `ci.yml :: Python — Tests` (actions, `test_mailbox_remediation.py` — 60 cases driving the real arms over `respx`: the Graph filter is asserted to carry the **bracketed** message id and to request `parentFolderId`, because a mock that answers whatever is asked cannot notice a field the query never requested; a hard `DELETE` route is wired to raise, so a purge that stopped being a soft delete fails rather than passes; a dry run is asserted to make **zero** HTTP calls; a mailbox with no copy answers FAILED with `match_count` 0 rather than counting toward a purge total; the rollback is asserted by call count and destination folder rather than by a boolean; and the verification probe's polarity has its own inverted-control test, because for a purge the confirming answer is an absence) + `ci.yml :: Python — Tests` (api, `test_phishing_intake_adapters.py` — 27 cases over the documented Graph, Gmail and `email_inbox` shapes, including the forwarded report where the reporter is the envelope sender) + `integration.yml` (api, `test_phishing_campaign_purge_live.py` — 17 cases against a real Postgres with the migration chain applied: two reports of one message join one campaign, `recipient_count` is recomputed rather than incremented, a 25-recipient campaign is `severe`/`mandatory_human` at every tier and every confidence, each mailbox gets its own dispatch carrying the campaign's count, and twenty of twenty-five purged is `partially_purged`) | core | PARTIAL (no Microsoft 365 or Google Workspace tenant is reachable from CI or from this maintainer, so every vendor claim rests on the documented request shape and a recorded mock. Two consequences stated rather than implied: nobody has observed Graph accept the `move` to `recoverableitemsdeletions` or Gmail accept the `trash`, and the Gmail filter and Graph inbox-rule bodies were written from the API reference rather than taken from a working call. Returns to GATED when a live tenant is available) | a maintainer-supplied M365 and Workspace test tenant || A reported message's sender authentication, URLs and attachments are analysed, and an unanalysed artefact never reads as a clean one | `apps/docs/docs/operations/mailbox-remediation.md`; depth plan 7.2 | `ci.yml :: Python — Tests` (api, `test_phishing_message_analysis.py` — 39 cases: every RFC 8601 non-verdict token (`none`, `neutral`, `policy`, `permerror`, `temperror`) and an absent header all resolve to `not_evaluated` rather than to a pass, each producing its own indicator; every method gets an entry even when no clause mentions it, so a console cannot render `SPF fail` and silently omit DMARC; the ARC-sealed header is read when the plain one is absent, which is the forwarded-report case; the verdict merge raises on SPF **and** DMARC failing and not on either alone; and a socket-patched test asserts header analysis reaches no network. Five of the cases drive `analyse_message` itself with the provider registry patched empty, because the hand-built-fixture version of this suite stayed green when the 'no provider configured' branch was deleted — a test that asserts on a fixture it wrote cannot notice a producer that stopped producing) + `integration.yml` (api, `test_phishing_analysis_ledger_live.py` — 6 cases against a real Postgres: one run and one `evidence_cited` row per component with `seq` dense from one, the unevaluated list carried in the payload, an unanalysed URL cited as unanalysed with 'not a clean verdict' in the summary, the rows immutable against migration 008's real trigger, and an unwritable ledger returning `None` rather than raising) | core | GATED | — || An adversary-in-the-middle session replay is detected on the session, not on the user | `services/fusion/app/data/windowed_ruleset.json` (`wd-aitm-*`); depth plan 7.3 | `ci.yml :: python-test` (fusion, `test_aitm_session_rules.py` — 20 cases driving the **real** `WindowedDetectionEngine`, the real matcher and the **shipped** ruleset loaded off disk rather than a hand-made rule list: the replay fires all four rules, the negative twin fires none of them, a single event fires nothing, two sessions for one user do not complete each other, an event with no session id is not grouped at all, the sequence does not fire without its MFA stage or in the wrong order, and one tenant's sign-in cannot complete another's replay) + `ci.yml` connectors matrix (`test_aitm_session_fields_reach_detection.py` — 18 cases driving the real `OktaConnector.normalize()` and `AzureEntraConnector.normalize()` over hand-authored vendor payloads, including that `mfa_satisfied` is three-valued and that a Graph `correlationId` does not stand in for a missing `sessionId`) + `ci.yml :: python-lint` (`check_windowed_translation.py` — the ceiling of 0 windowed rules selecting on a computed field, which is what forced the connector hoist rather than a rule naming a field nothing emits; `export_windowed_ruleset.py --check` for drift between the authored list and the artefact the engine loads) | core | GATED | The two halves live in different interpreters because `services/connectors` and `services/fusion` both name their package `app`; the connector test pins the payload the engine test transcribes, so a connector change that drops a field reds the connector test rather than silently passing the engine one |+| No two database migrations claim the same number, so a chain applies in one order on a fresh install and on an upgrade alike | `services/api/app/scripts/run_migrations.py` (orders by filename, records applied by filename); `scripts/check_migration_numbering.py` | `migration-numbering.yml :: migration-numbering` (no `paths:` filter on either trigger, so it grades every pull request and every push to a protected branch — the collision is a property of a *pair* of files and the second half can arrive from somebody else's merge, so a filter scoped to the migrations directory would miss exactly the case that bites. Discovers all 6 numbered chains structurally rather than from a list, which is what finds `services/osquery-tls/app/db/versions` under its non-conventional `script_location`. Proven against the real defect: a worktree holding both `121_fusion_alert_outbox.sql` and PR 1525's `121_closure_authorization_default_deny.sql` exits 1 naming both, and the same tree with the new-duplicate arm disabled reports a confident OK. The 13 historical collisions already on main are frozen by file set, checked in both directions so a stale exemption and a third file joining an old pair each fail | core | GATED | — |+| A query credited as tenant-scoped is one whose `tenant_id` constrains the rows read or written, not one that merely mentions the column | `scripts/check_tenant_query_predicates.py` (`_tenant_predicate_in_sql`) | `isolation.yml :: Tenant query predicates` (the credit is decided by the clause the token sits in, so a `RETURNING` list, a `SELECT` projection, an `ORDER BY`, a `GROUP BY`, an UPDATE `SET` and a SQL comment all stop counting, while `WHERE`, join `ON`, `USING`, `HAVING`, an INSERT column list and an `ON CONFLICT` target still do. Both code paths were fixed, not one: `_names` collects string constants, so the statement's own SQL came back round and a second bare-token test re-granted the credit on 14 of the 17 statements the first fix had demoted. 36 self-test cases written per SQL *clause* rather than per instance found, including the padding-free fragment branch and a control that an appended fragment naming the column without comparing it still fails. Proven both ways on the live tree: with its ratchet entry removed the real `UPDATE … RETURNING id, tenant_id` outbox claim is flagged, and reverting the detector to the bare-token match stops it being flagged | core | GATED | — |## Summary-- Total: 319-- GATED: 315+- Total: 321+- GATED: 317- PARTIAL: 4- NO GATE: 0diff --git a/docs/remediation/gate-hardening.md b/docs/remediation/gate-hardening.mdnew file mode 100644index 000000000..a5240342c--- /dev/null+++ b/docs/remediation/gate-hardening.md@@ -0,0 +1,576 @@+# Gate hardening: duplicate migration numbers, and a tenant credit keyed on the wrong thing++Two gates that were assumed to cover a defect class and did not. One did not+exist; the other existed, passed, and was reading the wrong property.++Both are proven three ways below — against the defect as it really shipped,+against current `main`, and with the detector reverted so it can be seen to+stop detecting. The third is the one that matters: a gate that has only ever+been run against violations its own author wrote is weak evidence, and for the+first of these there was a real one available.++---++## Gap 1 — nothing detected two migrations claiming the same number++### What happened++`services/api/migrations/NNN_*.sql` is a sequentially numbered, first-come+namespace. Two branches both took **121** on the same morning:++| File | Where it was |+| --- | --- |+| `121_fusion_alert_outbox.sql` | merged to `main` as `17fe377b` |+| `121_closure_authorization_default_deny.sql` | open in [#1525](https://github.com/beenuar/AiSOC/pull/1525) |++Git reports no conflict. Two branches each *added* a file, and the filenames+differ, so there is nothing to resolve — both could have merged.++### Why a duplicate is worse than it sounds++"Ambiguous apply order" undersells it. `run_migrations.py` does two things:++```276:320:services/api/app/scripts/run_migrations.py+ files = sorted(p for p in MIGRATIONS_DIR.iterdir() if p.suffix == ".sql")+ ...+ pending = [p for p in files if p.name not in already]+```++It orders by the **whole filename**, and `aisoc_schema_migrations` keys what it+has applied on the **filename** (`name TEXT PRIMARY KEY`). With two 121s:++- on a **fresh** deployment both are pending, and they apply in filename order+ — `121_closure…` *before* `121_fusion…`;+- on a deployment that already took `121_fusion…`, only `121_closure…` is+ pending, so it applies *after* it.++The same two migrations, in a different order on a new install than on an+upgrade. Silent, permanent once both rows exist, and invisible to everything+else in the tree.++### What the gate checks++`scripts/check_migration_numbering.py`, wired as+`.github/workflows/migration-numbering.yml`.++Chains are discovered **structurally** — any directory holding two or more+tracked files named `<digits>_…` with a `.sql`, `.py` or `.sh` suffix — rather+than from a list. A list would have missed two of the six:++```+infra/postgres/initdb: 2 file(s), 10–20, 9 gap(s) (not graded)+services/api/migrations: 136 file(s), 1–121+services/honeytokens/alembic/versions: 3 file(s), 1–3+services/osquery-tls/app/db/versions: 5 file(s), 1–5+services/purple-team/alembic/versions: 4 file(s), 1–4+services/ueba/alembic/versions: 4 file(s), 1–4+```++`services/osquery-tls` sets `script_location = app/db`, so its chain matches+neither `*/migrations/*` nor `*/alembic/versions/*`; `infra/postgres/initdb` is+numbered shell the Postgres entrypoint runs in filename order. Being structural+also makes the gate self-extending: a chain added tomorrow is checked tomorrow.++The unit is the **directory**, because that is what every runner here iterates.+No runner recurses — `lake_migrations.py` declares its chain in Python and+reads neither `.sql` file — so `services/api/clickhouse/001_init.sql` and+`clickhouse/tiering/002_tiering.sql` are two namespaces rather than a+collision. That was checked rather than assumed.++### What it deliberately does not check++**Gaps are not failures.** `118`, `120`, no `119` is the ordinary residue of a+branch that was reverted or never merged, and every runner here applies what it+finds in order rather than counting. Failing on a gap would red `main` until+somebody renumbered history. The count is reported and never graded. A+duplicate is the opposite: no workflow legitimately produces one.++**Alembic `down_revision` graphs are not walked.** For those four services the+filename prefix is a convention and the real ordering is inside the file. A+duplicate prefix is still a sign two branches raced, which is worth failing on;+a broken revision graph is a different defect and alembic raises on it itself.++**ADRs are out of scope.** `docs/decisions/0001-*.md` is also a first-come+numbered namespace, but two ADRs sharing a number is a broken cross-reference,+not two schemas applying in different orders. (It uses a dash and `.md`, so it+is excluded twice over.)++### The 13 collisions already on `main`++`main` carries 28 files across 13 duplicated numbers — including two triples,+`043` and `096` — predating this gate. They are frozen in `GRANDFATHERED`+rather than renumbered, for one reason: `aisoc_schema_migrations` is keyed on+the **filename**, so renaming `012_case_management.sql` makes it pending again+on every deployment that has already applied it, and the runner re-executes it.+The files are defensively written, so it would *probably* be harmless —+"probably harmless re-execution of 28 migrations across every installed+deployment" is not a trade worth making to tidy a number.++The table is checked in both directions: an entry that no longer collides fails+as a stale exemption, and so does one that has gained a **third** file. The+second half is the one that matters — without it, a new `121_x.sql` could join+a grandfathered pair and be absorbed in silence, which is the exact defect this+gate exists to catch.++### Proof++**1 — fails on the real defect.** A worktree at `origin/main` with PR #1525's+migration checked into the index beside the merged one. The gate under test was+copied into that tree so it resolved that tree as its own root.++```+$ git checkout probe-1525 -- services/api/migrations/121_closure_authorization_default_deny.sql+$ git ls-files 'services/api/migrations/121_*'+services/api/migrations/121_closure_authorization_default_deny.sql+services/api/migrations/121_fusion_alert_outbox.sql++$ python3 scripts/check_migration_numbering.py; echo "EXIT=$?"++FAIL: 1 migration numbering problem(s).+ - services/api/migrations: migration 121 is claimed by 2 files+ - services/api/migrations/121_closure_authorization_default_deny.sql+ - services/api/migrations/121_fusion_alert_outbox.sql+ Both will be applied. On a fresh deployment they run in filename order;+ on a deployment that already took one of them, the other runs afterwards.+ Renumber the one that has not merged yet.+check_migration_numbering: 6 numbered chain(s) under /private/tmp/aisoc-dup121+ services/api/migrations: 137 file(s), 1–121+EXIT=1+```++`git checkout <ref> -- <path>` stages the file, and the gate reads+`git ls-files`, which is the index — so this is the "verify with your changes+staged" case, not a disk-only one. A file that has *not* been `git add`ed is+invisible to the gate, which is asserted by its own self-test rather than left+implicit.++**2 — passes on current `main`.**++```+$ python3 scripts/check_migration_numbering.py; echo "EXIT=$?"+check_migration_numbering: 6 numbered chain(s) under /Users/…/AiSOC-gatehard+ …+OK: 154 migration file(s) across 6 chain(s); no two claim the same number,+ and all 13 grandfathered historical collisions still hold.+EXIT=0+```++**3 — negative control.** Same tree as proof 1 (both 121s present), one token+changed so every duplicate is treated as already-exempt:+`frozen_table.get(key)` → `frozen_table.get(key, tuple(names))`.++```+$ python3 scripts/check_migration_numbering.py+OK: 155 migration file(s) across 6 chain(s); no two claim the same number,+ and all 13 grandfathered historical collisions still hold.+EXIT=0 <-- a confident false pass++$ # restored+$ python3 scripts/check_migration_numbering.py >/dev/null 2>&1; echo $?+1+```++A first attempt at this control disabled the whole `len(names) > 1` loop, which+also stopped `seen_keys` being populated and failed with 13 *stale exemption*+reports instead — exit 1 for an unrelated reason. Recorded because it is+evidence the two arms are independent, and because a control that fails for the+wrong reason reads like a pass.++**4 — nothing existing caught it.** The three migration-adjacent gates already+in the tree, against the same both-121s worktree:++```+check_orm_migration_parity.py exit 0+check_service_migration_bootstrap.py exit 0+check_store_migrations.py exit 0+```++**5 — self-test**, 15 cases, written per *shape the filesystem can take*+rather than per instance observed:++```+PASS the real defect: PR #1525's 121 beside the merged 121: flagged+PASS clean: consecutive numbers: clean+PASS a gap is not a failure: clean+PASS padding differs, number does not: 012 and 12 collide: flagged+PASS three files on one number: flagged+PASS a 4-digit alembic chain is checked too: flagged+PASS a chain at a non-conventional script_location is still found: flagged+PASS numbered shell in initdb is a first-come namespace too: flagged+PASS same number in two different directories is two namespaces: clean+PASS an untracked duplicate is invisible, and the gate must not claim otherwise: clean+PASS a grandfathered collision passes+PASS a third file joining a grandfathered pair is not absorbed+PASS a grandfathered entry that no longer collides is reported stale+PASS all 13 live grandfather entries still name a real collision+PASS refuses a tree with no content rather than reporting it clean+```++The padding case is worth calling out: `012_a.sql` and `12_b.sql` are two+filenames that sort apart and are the same migration number. No instance of it+exists on `main`, and a rule that compared the numeric prefix as a *string*+would miss it.++### One false-positive wave, caught before it shipped++Written first as `^(\d+)[_-]`, the gate's opening run reported+`docs/perf/results: migration 0000000000000000000000000000002026 is claimed by+7 files` — `2026-09-27-compose-steady.json` and six siblings. Dated filenames+open with digits and a dash.++The fix was to narrow the signature, not to add an allowlist: every real chain+uses an underscore, and migrations are files a runner *executes*+(`.sql`/`.py`/`.sh`). Both false positives disappeared and the exclusion list+stayed empty. An allowlist of "directories that are not migrations" would have+grown forever and would have silenced the gate on whatever was added to it by+mistake.++### Why the workflow has no `paths:` filter++A filter scoped to `services/api/migrations/**` looks obviously right and is+wrong twice.++The collision is a property of a **pair**, and the second half arrives from+somebody else's merge: a pull request that touches no migration at all becomes+the duplicate when `main` moves under it. Only an unconditional run sees that.+Separately, this repository has repeatedly found required checks that report+success having executed only their "nothing under test changed" step. The gate+is a sub-second, dependency-free read of `git ls-files`; there is nothing to+buy by skipping it.++---++## Gap 2 — `check_tenant_query_predicates.py` credited a bare token match++### What was wrong++The raw-SQL arm credited a statement as tenant-scoped when `tenant_id` appeared+**anywhere in the SQL text**:++```python+if _TENANT_IN_SQL.search(blob):+ continue+```++So `UPDATE … WHERE expires_at < now() RETURNING id, tenant_id` read as scoped.+The token was in the projection of returned columns; it constrained nothing.++The blind spot was already written in the module's own docstring, left open on+the grounds that one statement relied on it and that statement was legitimately+cross-tenant. **That had stopped being true.** It was 17, and one of them is+the reason the brief flagged this: `alert_outbox.py::claim` — an+`UPDATE … RETURNING id, tenant_id` worker sweep — merged in `17fe377b` and+passed the ratchet at 60 without raising it, because the `RETURNING` list+credited it.++### The defect had two code paths, not one++Fixing the line above moved 17 statements from "credited" to "judged", and only+**3** of them became findings. The other 14 were absorbed by this, 12 lines+later:++```python+if any(_TENANT_IN_SQL.search(r) for r in resolved) or (resolved & TENANT_TOKENS):+ continue+```++`resolved` is built by `_names()`, which collects **string constants** as well+as identifiers. The statement's own SQL therefore comes back round in+`resolved`, and the same bare-token test is applied to it a second time.+Fixing only the first line would have left 14 of 17 statements still falsely+credited and looked like a complete fix. Both now call the same rule.++### What counts as constraining++The clause the token sits in decides. Occurrences are attributed to the clause+keyword most recently opened before them, which handles subqueries and CTEs the+way they nest.++| Credited | Not credited |+| --- | --- |+| `WHERE` | `SELECT` projection |+| join `ON` | `RETURNING` |+| `USING (…)` | `ORDER BY`, `GROUP BY` |+| `HAVING` | `VALUES` alone |+| `INSERT INTO t (tenant_id, …)` | UPDATE `SET tenant_id = …` |+| `ON CONFLICT (tenant_id, …)` | `--` and `/* */` comments |++Two of those need a reason.++**`INSERT INTO`'s column list is credited.** For a write there is no row-filter+to look for; the column list plus a bound value is what stamps the new row with+a tenant, and it is the only form in which an INSERT can be scoped at all. 90+of the 108 statements this rule re-examines are that shape and every one is+correct — flagging them would have been 90 false positives, which is how a gate+gets switched off.++**UPDATE `SET tenant_id = …` is not credited.** It *writes* the tenant column+and constrains nothing about which rows are rewritten. It is a tenant+reassignment, the opposite of a scope.++A fragment — `" AND tenant_id = :t"` appended to a base query — carries no+clause keyword of its own, so it is credited when the token is one side of a+comparison (stepping over an optional `::cast`). An appended fragment that+merely *names* the column still fails, which has its own self-test case.++### Why not a real SQL parser++`sqlglot` is in the tree and pinned exactly. Every gate here has to run on a+bare interpreter before any `pip install` — `gate_toolkit` imports nothing+outside the standard library for that reason — and a gate that acquires a+dependency is one that gets skipped in the environment that matters. The cost+of that choice is two residuals, recorded in the module rather than discovered+later:++- a correlated subquery in a projection credits the outer statement off the+ inner predicate (the correlation makes the outer read per-tenant in practice,+ so this errs toward a credit rather than a false alarm);+- `INSERT INTO a (tenant_id, …) SELECT … FROM b` credits the stamped write+ while the read from `b` may be unscoped. One statement of that shape exists+ and it carries its own `WHERE tenant_id`.++### Finding-count delta++Measured with `_TENANT_IN_SQL` and `_tenant_predicate_in_sql` run side by side+over the same corpus, rather than inferred:++| | before | after |+| --- | --- | --- |+| raw-SQL statements on a tenant-scoped table | 462 | 462 |+| of those, credited as tenant-scoped by the text rule | 431 | 414 |+| credited by a token that constrains nothing | **17** | 0 |+| unscoped-statement findings surfaced | 0 | **17** |+| route→unscoped-statement pairs surfaced | 0 | **12** |+| `MAX_RATCHET` | 60 | 77 |+| `MAX_ROUTE_REACHABLE` | 34 | 46 |++Of the 17 that lost the credit, **3** became findings as soon as the first call+site was fixed; the other **14** were re-credited by the second bare-token path+described above and only surfaced once that was fixed too.++A larger figure appears in the module comments and is a different measurement:+**108** statements carry the token in no `WHERE`/`ON`/`USING`/`HAVING`. **90**+of those are `INSERT INTO t (tenant_id, …)`, which the new rule credits+deliberately — the column list is what stamps the written row. Flagging them+would have been 90 false positives.++**On raising the ceilings.** "Raise the ceiling until the scan passes" is the+move this repository forbids, and from the diff alone this looks identical, so+the reasoning is recorded beside the constant as well as here.++Not one line under `services/` changed. All 17 statements are byte-for-byte+what they were and every one was already unscoped; 60 was never a debt balance,+it was the balance a broken detector could see. The honest number is 77 and the+count of genuinely new exemptions is **zero**. Leaving it at 60 was rejected+because it fails every pull request for findings no author introduced and none+can fix, which is how a gate gets switched off. Giving the 17 real predicates+was rejected per statement, for the reasons below — in every case a tenant+predicate would break the thing the statement exists to do.++### Every newly-flagged statement, and why++**i. The lookup that *establishes* the tenant** — reached before a request has+one, so a tenant predicate would mean it could never resolve a tenant. Same+class as the pre-auth group already at the top of the ratchet.++| Statement | Reason |+| --- | --- |+| `auth/sso_provisioning.py::resolve_connection` | resolves which SSO connection an assertion belongs to, by `(provider, issuer)`; the row it finds is what assigns the tenant |+| `auth/saml_metadata.py::resolve_saml_connection` | SP-metadata and ACS resolve by issuer, or by none at all on the console link. `LIMIT 2` so an ambiguous config is detected rather than silently resolved to row one |+| `mfa.py::_principal_for_enrolment` | `:u` is the subject of a signed, purpose-checked sign-in challenge, not a caller-supplied id |+| `inbox_itsm.py::_fetch_token_and_connector` (`tenant_inbox_tokens`) | the ITSM webhook carries an opaque inbox token and nothing else; this is what turns it into a tenant |++**ii. Reads cross-tenant *in order to* enforce the tenant check.**++| Statement | Reason |+| --- | --- |+| `inbox_itsm.py::_fetch_token_and_connector` (`connectors`) | deliberately unscoped so the next statement can compare `connector_row.tenant_id != token_row.tenant_id`, log a cross-tenant attempt with both ids and refuse. Scoping the SELECT would collapse that into an indistinguishable 404 and lose the signal. Nothing from the row reaches the caller before the comparison |++**iii. An identity predicate, which is strictly narrower than a tenant.**++| Statement | Reason |+| --- | --- |+| `mfa.py::enrolment_row` | keyed on `user_id`, which all eight callers pass as the authenticated principal's own (`current_user.user_id`, `principal.user_id`, or an id already resolved from a verified challenge). The ORM arm of this gate already credits that; the raw-SQL arm cannot see it because the predicate is bound one function away |++**iv. A worker's working set — "which tenants", which cannot presuppose one.**+The discover-then-bind shape already recorded for `hunt_scheduler.run_once` and+`oauth_refresh._select_due_connectors`.++| Statement | Reason |+| --- | --- |+| `workers/autonomy_drift.py` | `SELECT DISTINCT tenant_id` across granted autonomy; each tenant bound individually afterwards |+| `workers/retention_purge.py::_load_policies` | every tenant's retention policy; a tenant missing from this read is one whose data is never purged |+| `workers/phishing_report_intake.py::_mailbox_connectors` | enabled mailbox connectors across tenants, ordered by tenant so the fan-out is deterministic |+| `workers/shadow_reconcile.py` | `COUNT(DISTINCT tenant_id)` — a fleet gauge for one log line; returns a number, never a tenant's rows |+| `workers/approval_expiry.py` | expires every tenant's stale approvals, bounded by `expires_at < now()`. The clearest instance of the defect: credited by `RETURNING id, tenant_id` |+| `fusion/services/sessions.py` | `SELECT DISTINCT tenant_id` of sessions due for expiry |+| `fusion/services/alert_outbox.py::claim` | the outbox dispatcher claims due rows across every tenant under a lease; one that drained a single tenant would stall delivery for all the others. **This is the statement that passed the ratchet at 60.** |+| `fusion/services/alert_outbox.py::backlog` | depth-and-age gauge, grouped by tenant precisely so one tenant's backlog is attributable. `GROUP BY` buckets rows already read — which is why the rule does not credit it |+| `fusion/memory/provider.py::refresh` | rebuilds the per-signature prior cache for every tenant in one pass, then partitions by `tenant_id` in Python and hands each tenant only its own. The projected column is the partition key |+| `connectors/app/scheduler.py::_promote_overdue_findings` | `SELECT DISTINCT tenant_id` over enabled connectors — **the one statement the module docstring already named** as relying on the bare-token credit. It now holds a reason instead of a regex match |++**v. A fragment, judged at its use sites.**++| Statement | Reason |+| --- | --- |+| `services/alert_source_link.py` (`_SELECT`) | a column list and a `FROM`, never executed as written: all four callers interpolate it into an f-string appending `WHERE tenant_id = :tenant_id`, and the gate judges each of those call sites independently — a fifth caller omitting the predicate is flagged there. Keyed on this table, so an unscoped statement on any other table in the module still fails |++This last one is the only entry keyed on `<module>` scope, and the residual is+stated rather than hidden: another unscoped statement on `alert_source_links`+at module scope in that same file would be covered by it. It was independently+confirmed as a parse artefact rather than a judgement call when a self-test+probe built the same shape and the finding landed on the module-level constant+rather than on the call site.++**The 12 route pairs** are all pre-auth routes — five SAML/OIDC callbacks, the+ITSM webhook, and six MFA handlers reading the caller's own enrolment. A+handler cannot filter on a tenant it has not been assigned, and each of these+statements is the thing that assigns it.++### Proof++**1 — fails on the real defect.** `alert_outbox.py::claim`, with its ratchet+entry removed so the statement is judged on the detector alone:++```+A. NEW detector, ratchet entry REMOVED+ exit=1 alert_outbox.py:208 flagged=YES+```++**2 — negative control.** Same tree, same entry removed, detector reverted to+`_TENANT_IN_SQL.search` on both call sites:++```+B. OLD bare-token detector+ exit=1 alert_outbox.py:208 flagged=NO+```++The exit code stays 1 in B — but for a different reason, and the distinction is+the point. With the statement credited again, its (removed) ratchet entry is+never matched, so the gate fails on the **stale-entry** arm instead. The+statement itself is not flagged, which is the thing under test.++**3 — passes on current `main`.**++```+C. RESTORED (new detector + full ratchet)+OK: every statement on a tenant-scoped table filters on a tenant, or is one of+77 ratcheted exceptions that still holds; and every one of the 46+route->unscoped-statement paths is a recorded exception.+ exit=0+```++**4 — self-test**, 16 injected drifts and 22 controls, written per SQL *clause*+rather than per instance found on `main`:++```+[PASS] drift I: tenant_id only in a RETURNING list: 1 finding(s), want 1+[PASS] drift J: tenant_id only in a SELECT projection: 1 finding(s), want 1+[PASS] drift K: tenant_id only in an ORDER BY: 1 finding(s), want 1+[PASS] drift L: tenant_id only in a GROUP BY: 1 finding(s), want 1+[PASS] drift M: tenant_id only in a -- line comment: 1 finding(s), want 1+[PASS] drift N: tenant_id only in a /* block comment */: 1 finding(s), want 1+[PASS] drift O: UPDATE SET tenant_id rewrites the column, it does not scope: 1 finding(s), want 1+[PASS] drift P: an appended fragment that names tenant_id without comparing it: 1 finding(s), want 1+[PASS] control: tenant_id in a WHERE: 0 finding(s), want 0+[PASS] control: tenant_id in a JOIN ... ON: 0 finding(s), want 0+[PASS] control: tenant_id in a USING (...): 0 finding(s), want 0+[PASS] control: tenant_id in a HAVING: 0 finding(s), want 0+[PASS] control: INSERT column list stamps the written row: 0 finding(s), want 0+[PASS] control: ON CONFLICT target selects the upserted row: 0 finding(s), want 0+[PASS] control: predicate inside a subquery, RETURNING outside it: 0 finding(s), want 0+[PASS] control: predicate inside a CTE: 0 finding(s), want 0+[PASS] control: tenant_id::uuid = $1 — a cast before the operator: 0 finding(s), want 0+[PASS] control: predicate carried in by an f-string: 0 finding(s), want 0+[PASS] control: predicate appended as a bare fragment: 0 finding(s), want 0++self-test passed: 16 injected drifts detected and 22 controls clear …+```++---++## Gate suite++Every gate `ci.yml` invokes was run against this branch: **175 pass, 6 fail.**+Three of the six are artefacts of how the list was extracted — `run_evals.py+--ci --out`, `service_requirements.py` and `upgrade_playbooks.py --dir` were+captured without their mandatory path arguments. The other three were run+against a clean `origin/main` worktree and fail there identically, so they are+pre-existing and unrelated:++| Gate | On this branch | On pristine `main` |+| --- | --- | --- |+| `check_console_route_contract.py` | exit 1 | exit 1 |+| `check_console_route_contract.py --self-test` | exit 1 | exit 1 |+| `check_mcp_client_policy.py` | exit 1 | exit 1 (`No module named 'mcp'`) |++Also run and clean: `ruff format --check .` (2,610 files),+`ruff check services/ scripts/ tests/ tools/`, `check_mypy_baseline.py` (964+findings, no tree worse), `check_gate_coverage.py`, `check_gate_contract.py`,+`check_workflow_concurrency.py`, `check_claim_gate_matrix.py` (321 rows / 317+GATED / 4 PARTIAL / 0 NO GATE), `check_attribution.py --all`,+`check_competitor_names.py`, `check_machine_paths.py`, `check_comment_paths.py`+and `check_repo_self_links.py`.++One measurement artefact worth recording, because it nearly became a false+report: the first pass of this suite read **104 failures**. The loop ran under+zsh, which does not word-split an unquoted expansion, so `python3 $inv` passed+`"scripts/x.py --self-test"` as a single filename and every gate exited 2 on+`No such file or directory`. Re-run under bash it is 6. A batch result that+disagrees this sharply with a single-gate run is the shell, not the tree.++## Not verified++- ~~Neither gate has been observed on a GitHub runner.~~ **Resolved on+ [#1530](https://github.com/beenuar/AiSOC/pull/1530):** `Migrations — No+ duplicate numbers` passed in 10 s and `Route tenant scope (no route lets its+ caller name the tenant)` — the job that runs the tenant-predicate gate and+ its self-test — passed in 3 m 12 s, both on ubuntu-latest with Python 3.11.+- **CodeQL flagged the first revision**, `py/unused-global-variable` on+ `_UNCREDITED` — a tuple written as documentation and referenced by nothing.+ Rather than delete it, the clause list became the single source the regex is+ built from and `_clause_classification_is_total()` now asserts the two+ classification tables are disjoint and together cover all 25 keywords, which+ is checked by the self-test. A keyword added to the matcher and classified+ nowhere would otherwise default to "not constraining" — the safe direction,+ but one nobody decided.+- **`security-audit` fails on this branch and the cause is not this branch.**+ `CVE-2026-114605 in dnspython==2.8.0`, a purely transitive dependency+ resolved in `services/api/poetry.lock`; `dnspython` appears nowhere in the+ diff. Every `security-audit` run before 15:33 UTC succeeded across `main`+ and four other branches, and the two runs here at 16:23 and 16:28 are the+ first anywhere after the advisory published. This is the documented+ stale-green shape, and `main` has since confirmed it: its 15:32 run+ succeeded and its 17:08 run **fails with the identical advisory**, so the+ condition is repository-wide rather than branch-specific.++ ```+ failure 2026-10-27T17:08:06Z main <- same CVE+ failure 2026-10-27T16:55:12Z remediation/gate-hardening+ success 2026-10-27T15:32:56Z main <- predates the advisory+ success 2026-10-27T15:31:44Z remediation/p1-closure-authz+ ```++ The fix is a lockfile regeneration under `services/api/`, which is outside+ this change's scope and belongs on `main` rather than being duplicated per+ branch. It has **not** been suppressed.+- **The first push went red on a gate the local suite does not include**, and+ it is worth recording as the live example of the thing this file is about.+ Adding two matrix rows made three prose copies of the count stale:+ `apps/docs/docs/compliance/evidence-pack.md` and two figures in+ `ROADMAP.md`. One of those sentences warns the reader, in the sentence+ itself, that a count copied into prose goes stale in silence. The cross-check+ lives in `scripts/readme_gates.py`, which is not invoked by `ci.yml` and so+ was not in the 181-gate sweep run before pushing — run `readme_gates.py`+ directly after touching the matrix.+- **The claim that no runner recurses into a migration subdirectory** was+ established by reading `run_migrations.py`, the four `alembic.ini`+ `script_location` values and `lake_migrations.py`. It was not established by+ running a migration against a live database.+- **The 13 grandfathered collisions are asserted to be already applied on+ existing deployments**, which is why renumbering them is unsafe. That follows+ from their being on `main` and in released tags; no deployment's+ `aisoc_schema_migrations` table was queried to confirm it.+- **`MAX_RATCHET` 60 → 77 is a judgement call**, argued above and in the+ module. If the reviewer disagrees, the alternative is to scope the statements+ rather than to lower the number back — the 17 are unscoped either way.diff --git a/scripts/check_migration_numbering.py b/scripts/check_migration_numbering.pynew file mode 100644index 000000000..a8577e9bb--- /dev/null+++ b/scripts/check_migration_numbering.py@@ -0,0 +1,473 @@+#!/usr/bin/env python3+"""Two migrations must not claim the same number.++Why this exists+---------------++`services/api/migrations/NNN_*.sql` is a sequentially numbered, first-come+namespace, and nothing checked it. Two branches both picked **121** on the same+morning — `121_fusion_alert_outbox.sql`, which merged, and+`121_closure_authorization_default_deny.sql`, which was open at the time. Git+reports no conflict, because the filenames differ: two files were added, and+adding two files is not a conflict. Both could have merged.++What goes wrong is not cosmetic, and it is worth stating precisely because+"ambiguous order" undersells it. `services/api/app/scripts/run_migrations.py`+does two things:++ files = sorted(p for p in MIGRATIONS_DIR.iterdir() if p.suffix == ".sql")+ pending = [p for p in files if p.name not in already]++— it orders by the **whole filename**, and it records what it has applied by+**filename** in `aisoc_schema_migrations(name TEXT PRIMARY KEY)`. So with two+121s:++* on a **fresh** deployment both are pending and they apply in filename order,+ `121_closure…` before `121_fusion…`;+* on a deployment that already took `121_fusion…`, only `121_closure…` is+ pending, so it applies **after** it.++The same two migrations, applied in a different order on a new install than on+an upgrade. That divergence is silent, it is permanent once both rows exist,+and it is invisible to every other gate in this tree.++What this checks+----------------++Every numbered chain in the repository, discovered structurally rather than+from a list kept here, because a list would have missed two of the seven:+`services/osquery-tls` sets `script_location = app/db`, so its chain is at+`app/db/versions` and matches neither `*/migrations/*` nor `*/alembic/versions/*`,+and `infra/postgres/initdb` is numbered shell the Postgres entrypoint runs in+filename order. A directory qualifies when it holds two or more tracked files+whose names begin with digits and a separator — which is also what makes the+gate self-extending: a chain added tomorrow is checked tomorrow.++The unit is the **directory**, because that is what every runner in this tree+iterates: `MIGRATIONS_DIR.iterdir()` for the API, `script_location` for the+four alembic chains, the initdb mount for Postgres. No runner here recurses, so+`services/api/clickhouse/001_init.sql` and `clickhouse/tiering/002_tiering.sql`+are two namespaces rather than a collision — and that is checked rather than+assumed (`lake_migrations.py` declares its chain in Python and reads neither).++What it deliberately does not check+-----------------------------------++**Gaps are not failures.** `…/118`, `…/120` with no 119 is the normal residue+of a branch that was reverted, renumbered, or never merged, and every runner+here applies what it finds in order rather than counting. Failing on a gap+would mean a reverted branch reds `main` until somebody renumbers history, so+the count is reported and never graded. A duplicate is the opposite: there is+no workflow that legitimately produces one.++**Alembic `down_revision` chains are not walked.** For those four services the+filename prefix is a convention and the real ordering lives in the revision+identifiers inside the file. A duplicate prefix there is a naming collision and+a sign two branches raced, which is worth failing on; a broken `down_revision`+graph is a different defect and alembic itself raises on it.++Run: python3 scripts/check_migration_numbering.py+ python3 scripts/check_migration_numbering.py --self-test+"""++from __future__ import annotations++import argparse+import re+import subprocess+import sys+from collections import defaultdict+from collections.abc import Mapping+from pathlib import Path++# `scripts/` is on sys.path when this file is run as a program, but not when a+# test loads it by path with importlib. gate_toolkit sits beside it either way.+sys.path.insert(0, str(Path(__file__).resolve().parent))++from gate_toolkit import repo_root, self_test_main++#: A migration filename opens with digits and an **underscore**: `121_x.sql`,+#: `0004_y.py`, `10_z.sh`. The number is captured without its padding so+#: `012_a.sql` and `12_b.sql` are recognised as the collision they are — they+#: are two different filenames, they sort apart, and they are the same+#: migration number.+#:+#: The separator is deliberately not `[_-]`. Written that way, the first run of+#: this gate reported `docs/perf/results/2026-09-27-*.json` as "migration+#: 2026 claimed by 7 files", because a dated filename opens with digits and a+#: dash. Every one of the seven real chains in this tree uses an underscore+#: and nothing else does, so the narrower pattern costs nothing and the+#: alternative was an allowlist of directories that are not migrations — a+#: list that would grow forever and silence the gate on whatever was added to+#: it by mistake.+_NUMBERED = re.compile(r"^(\d+)_")++#: What a migration runner executes. `docs/decisions/0001-*.md` is also a+#: first-come numbered namespace and is deliberately out of scope: two ADRs+#: sharing a number is a broken cross-reference, not two schemas that apply in+#: different orders on a fresh install than on an upgrade. It uses a dash+#: anyway, so it is excluded twice over; this is the half that would still+#: hold if somebody renamed them.+_RUNNABLE_SUFFIXES = frozenset({".sql", ".py", ".sh"})++#: A directory needs this many numbered files before it is treated as a chain.+#: One file cannot collide with anything, and counting a lone `001_init.sql` as+#: a chain would make the gate's subject depend on unrelated directories that+#: happen to hold one numbered file.+_MIN_CHAIN = 2+++#: Duplicate numbers that are already on `main`, with the only reason that+#: justifies leaving one in place.+#:+#: These 28 files across 13 numbers predate this gate. Renumbering them is not+#: a cleanup, it is a schema incident: `aisoc_schema_migrations` is keyed on+#: the **filename**, so renaming `012_case_management.sql` makes it pending+#: again on every deployment that has already applied it, and the runner would+#: re-execute it. The files are defensively written (`IF NOT EXISTS`), so it+#: would *probably* be harmless — "probably harmless re-execution of 28+#: migrations across every installed deployment" is not a trade worth making to+#: tidy a number.+#:+#: They are therefore frozen exactly as they are, and the entry is checked in+#: both directions: an entry whose files no longer collide fails as a stale+#: exemption, and so does one that has gained a *third* file. The second half+#: is the one that matters — without it, `121_x.sql` could join a+#: grandfathered pair and be absorbed in silence, which is precisely the defect+#: this gate exists to catch.+GRANDFATHERED: dict[str, tuple[str, ...]] = {+ "services/api/migrations::12": ("012_case_management.sql", "012_mssp_console.sql"),+ "services/api/migrations::13": ("013_asset_inventory.sql", "013_compliance_evidence.sql"),+ "services/api/migrations::14": ("014_hunt_workbench.sql", "014_insider_threat.sql"),+ "services/api/migrations::15": ("015_phishing_triage.sql", "015_remediation_maturity.sql"),+ "services/api/migrations::16": ("016_knowledge_base.sql", "016_threat_intel.sql"),+ "services/api/migrations::40": ("040_critical_severity_alert_confidence.sql", "040_saved_hunts.sql"),+ "services/api/migrations::41": ("041_alert_correlation_narrative.sql", "041_attack_chains.sql"),+ "services/api/migrations::42": ("042_alerts_schema_drift_fix.sql", "042_waitlist.sql"),+ "services/api/migrations::43": (+ "043_audit_log_hash_chain.sql",+ "043_hunts_tenant_isolation.sql",+ "043_tenant_provision.sql",+ ),+ "services/api/migrations::44": ("044_alerts_idempotency_key.sql", "044_cases_tenant_isolation.sql"),+ "services/api/migrations::70": ("070_retro_hunts.sql", "070_tenant_skills.sql"),+ "services/api/migrations::95": ("095_action_approval_tier.sql", "095_playbook_references.sql"),+ "services/api/migrations::96": (+ "096_access_governance_permissions.sql",+ "096_console_mfa.sql",+ "096_playbook_wait_pauses.sql",+ ),+}+++def tracked_files(root: Path) -> list[str]:+ """Paths git knows about, which includes staged additions.++ `git ls-files` reads the index, so a migration that has been `git add`ed is+ seen before it is committed. One that has not been added is invisible —+ which is why the self-test stages nothing and builds real repositories+ instead.+ """+ out = subprocess.run( # noqa: S603 - fixed argv, no shell+ ["git", "ls-files"],+ capture_output=True,+ text=True,+ check=False,+ cwd=root,+ )+ if out.returncode != 0:+ return []+ return [line for line in out.stdout.splitlines() if line.strip()]+++def discover_chains(root: Path) -> dict[str, dict[int, list[str]]]:+ """`directory -> number -> [basename, ...]` for every numbered chain."""+ by_dir: dict[str, dict[int, list[str]]] = defaultdict(lambda: defaultdict(list))+ for rel in tracked_files(root):+ path = Path(rel)+ if path.suffix not in _RUNNABLE_SUFFIXES:+ continue+ match = _NUMBERED.match(path.name)+ if match is None:+ continue+ by_dir[path.parent.as_posix()][int(match.group(1))].append(path.name)+ return {d: dict(numbers) for d, numbers in by_dir.items() if sum(len(v) for v in numbers.values()) >= _MIN_CHAIN}+++def collisions(chains: dict[str, dict[int, list[str]]]) -> list[tuple[str, int, list[str]]]:+ """Every (directory, number) claimed by more than one file."""+ found: list[tuple[str, int, list[str]]] = []+ for directory, numbers in sorted(chains.items()):+ for number, names in sorted(numbers.items()):+ if len(names) > 1:+ found.append((directory, number, sorted(names)))+ return found+++def _key(directory: str, number: int) -> str:+ return f"{directory}::{number}"+++def evaluate(+ root: Path,+ # `Mapping`, not `dict`: dict is invariant in its value type, so a+ # `dict[str, tuple[str, str]]` built by the self-test is not a+ # `dict[str, tuple[str, ...]]` and mypy is right to say so.+ grandfathered: Mapping[str, tuple[str, ...]] | None = None,+) -> tuple[list[str], list[str], dict[str, dict[int, list[str]]]]:+ """Returns (failures, notes, chains).++ `grandfathered` is a parameter rather than a straight read of the module+ constant so the self-test can point the same code at a synthetic table.+ Mutating the constant in place would have worked and would also have made+ every probe depend on the order the probes ran in.+ """+ frozen_table = GRANDFATHERED if grandfathered is None else grandfathered+ chains = discover_chains(root)+ failures: list[str] = []+ notes: list[str] = []++ if not chains:+ return (+ [+ "no numbered migration chain was found. Every runner in this tree reads one, "+ "so zero means the walk stopped matching rather than that the tree is clean."+ ],+ notes,+ chains,+ )++ live = collisions(chains)+ seen_keys = set()++ for directory, number, names in live:+ key = _key(directory, number)+ seen_keys.add(key)+ frozen = frozen_table.get(key)+ if frozen is None:+ failures.append(+ f"{directory}: migration {number:0{len(names[0].split('_')[0])}d} is claimed by "+ f"{len(names)} files\n"+ + "".join(f" - {directory}/{n}\n" for n in names)+ + " Both will be applied. On a fresh deployment they run in filename order;\n"+ " on a deployment that already took one of them, the other runs afterwards.\n"+ " Renumber the one that has not merged yet."+ )+ elif tuple(names) != frozen:+ failures.append(+ f"{directory}: migration {number} is grandfathered as {list(frozen)} but now holds "+ f"{names}. A file joined or left a known-historical collision; the gate will not "+ f"absorb a new duplicate into an old exemption."+ )++ for key in sorted(frozen_table):+ if key not in seen_keys:+ failures.append(+ f"stale exemption: {key} is grandfathered but no longer collides. "+ f"Remove the entry — an exemption that outlived its reason reads like a decision "+ f"somebody made."+ )++ for directory, numbers in sorted(chains.items()):+ present = sorted(numbers)+ missing = [n for n in range(present[0], present[-1] + 1) if n not in numbers]+ files = sum(len(v) for v in numbers.values())+ gap_note = f", {len(missing)} gap(s) (not graded)" if missing else ""+ notes.append(f" {directory}: {files} file(s), {present[0]}–{present[-1]}{gap_note}")++ return failures, notes, chains+++def main(argv: list[str] | None = None) -> int:+ parser = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)+ parser.add_argument("--self-test", action="store_true", help="prove the gate detects a duplicate and forgives a gap")+ args = parser.parse_args(argv)++ if args.self_test:+ return _self_test()++ root = repo_root()+ failures, notes, chains = evaluate(root)++ print(f"check_migration_numbering: {len(chains)} numbered chain(s) under {root}")+ for line in notes:+ print(line)++ if failures:+ print(f"\nFAIL: {len(failures)} migration numbering problem(s).", file=sys.stderr)+ for failure in failures:+ print(f" - {failure}", file=sys.stderr)+ return 1++ total = sum(sum(len(v) for v in numbers.values()) for numbers in chains.values())+ print(+ f"\nOK: {total} migration file(s) across {len(chains)} chain(s); no two claim the same number, "+ f"and all {len(GRANDFATHERED)} grandfathered historical collisions still hold."+ )+ return 0+++# ---------------------------------------------------------------------------+# Self-test+# ---------------------------------------------------------------------------++_RUNNER_NOTE = "-- probe\nSELECT 1;\n"+++def _probe_repo(tmp: Path, files: dict[str, str]) -> Path:+ """A real git repository, because the gate reads the index rather than the disk."""+ root = tmp+ for rel, body in files.items():+ target = root / rel+ target.parent.mkdir(parents=True, exist_ok=True)+ target.write_text(body, encoding="utf-8")+ git = ["git", "-c", "user.name=gate", "-c", "user.email=gate@invalid", "-c", "commit.gpgsign=false"]+ for argv in (["init", "-q", "-b", "main"], ["add", "-A"], ["commit", "-qm", "probe"]):+ subprocess.run(git + argv, cwd=root, check=True, capture_output=True) # noqa: S603+ return root+++def _self_test() -> int:+ import tempfile++ d = "services/api/migrations"+ # Each case is (label, files, expect_failure). Written per *shape* the+ # filesystem can take rather than per instance observed on main: the+ # padding case and the third-file case are both collisions no instance on+ # main exhibits, and both are the ones a looser rule would miss.+ cases: list[tuple[str, dict[str, str], bool]] = [+ (+ "the real defect: PR #1525's 121 beside the merged 121",+ {+ f"{d}/120_alerts_tenant_dedup_unique.sql": _RUNNER_NOTE,+ f"{d}/121_fusion_alert_outbox.sql": _RUNNER_NOTE,+ f"{d}/121_closure_authorization_default_deny.sql": _RUNNER_NOTE,+ },+ True,+ ),+ (+ "clean: consecutive numbers",+ {f"{d}/001_a.sql": _RUNNER_NOTE, f"{d}/002_b.sql": _RUNNER_NOTE, f"{d}/003_c.sql": _RUNNER_NOTE},+ False,+ ),+ (+ "a gap is not a failure",+ {f"{d}/001_a.sql": _RUNNER_NOTE, f"{d}/002_b.sql": _RUNNER_NOTE, f"{d}/009_c.sql": _RUNNER_NOTE},+ False,+ ),+ (+ "padding differs, number does not: 012 and 12 collide",+ {f"{d}/011_a.sql": _RUNNER_NOTE, f"{d}/012_b.sql": _RUNNER_NOTE, f"{d}/12_c.sql": _RUNNER_NOTE},+ True,+ ),+ (+ "three files on one number",+ {+ f"{d}/001_a.sql": _RUNNER_NOTE,+ f"{d}/002_b.sql": _RUNNER_NOTE,+ f"{d}/002_c.sql": _RUNNER_NOTE,+ f"{d}/002_e.sql": _RUNNER_NOTE,+ },+ True,+ ),+ (+ "a 4-digit alembic chain is checked too",+ {+ "services/ueba/alembic/versions/0001_a.py": "x = 1\n",+ "services/ueba/alembic/versions/0002_b.py": "x = 1\n",+ "services/ueba/alembic/versions/0002_c.py": "x = 1\n",+ },+ True,+ ),+ (+ "a chain at a non-conventional script_location is still found",+ {+ "services/osquery-tls/app/db/versions/001_a.py": "x = 1\n",+ "services/osquery-tls/app/db/versions/003_b.py": "x = 1\n",+ "services/osquery-tls/app/db/versions/003_c.py": "x = 1\n",+ },+ True,+ ),+ (+ "numbered shell in initdb is a first-come namespace too",+ {"infra/postgres/initdb/10_a.sh": "#!/bin/sh\n", "infra/postgres/initdb/10_b.sh": "#!/bin/sh\n"},+ True,+ ),+ (+ "same number in two different directories is two namespaces",+ {+ f"{d}/001_a.sql": _RUNNER_NOTE,+ f"{d}/002_b.sql": _RUNNER_NOTE,+ "services/ueba/alembic/versions/0001_a.py": "x = 1\n",+ "services/ueba/alembic/versions/0002_b.py": "x = 1\n",+ },+ False,+ ),+ (+ "an untracked duplicate is invisible, and the gate must not claim otherwise",+ {f"{d}/001_a.sql": _RUNNER_NOTE, f"{d}/002_b.sql": _RUNNER_NOTE},+ False,+ ),+ ]++ results: list[tuple[str, bool]] = []+ with tempfile.TemporaryDirectory() as tmpdir:+ for i, (label, files, expect_failure) in enumerate(cases):+ root = _probe_repo(Path(tmpdir) / f"case{i}", files)+ if label.startswith("an untracked duplicate"):+ # Written to disk, never `git add`ed. The gate reads the index,+ # so this must stay clean -- and the point of the case is that+ # a gate run before `git add` cannot see what you are adding.+ (root / d / "002_shadow.sql").write_text(_RUNNER_NOTE, encoding="utf-8")+ # No historical collisions in these probe trees, so the real+ # grandfather table would report all 13 of its entries stale and+ # drown the case under test.+ failures, _notes, _chains = evaluate(root, grandfathered={})+ got = bool(failures)+ results.append((f"{label}: {'flagged' if got else 'clean'}", got == expect_failure))++ # The grandfather table, both directions, against a synthetic stand-in so+ # the probe does not depend on the live tree staying as it is.+ synthetic = {"services/api/migrations::12": ("012_case_management.sql", "012_mssp_console.sql")}+ with tempfile.TemporaryDirectory() as tmpdir:+ frozen_root = _probe_repo(+ Path(tmpdir) / "frozen",+ {+ f"{d}/012_case_management.sql": _RUNNER_NOTE,+ f"{d}/012_mssp_console.sql": _RUNNER_NOTE,+ f"{d}/013_other.sql": _RUNNER_NOTE,+ },+ )+ failures, _n, _c = evaluate(frozen_root, grandfathered=synthetic)+ results.append(("a grandfathered collision passes", not failures))++ third_root = _probe_repo(+ Path(tmpdir) / "third",+ {+ f"{d}/012_case_management.sql": _RUNNER_NOTE,+ f"{d}/012_mssp_console.sql": _RUNNER_NOTE,+ f"{d}/012_newcomer.sql": _RUNNER_NOTE,+ },+ )+ failures, _n, _c = evaluate(third_root, grandfathered=synthetic)+ results.append(("a third file joining a grandfathered pair is not absorbed", bool(failures)))++ stale_root = _probe_repo(+ Path(tmpdir) / "stale",+ {f"{d}/012_case_management.sql": _RUNNER_NOTE, f"{d}/013_other.sql": _RUNNER_NOTE},+ )+ failures, _n, _c = evaluate(stale_root, grandfathered=synthetic)+ results.append(("a grandfathered entry that no longer collides is reported stale", bool(failures)))++ # The live table against the live tree: every one of the 13 entries+ # must still name a real collision. This is the arm that keeps the+ # table from rotting, and it is checked here as well as in the gate so+ # `--self-test` alone answers "is this gate still honest".+ live_failures, _n, _c = evaluate(repo_root())+ results.append((f"all {len(GRANDFATHERED)} live grandfather entries still name a real collision", not live_failures))++ return self_test_main(Path(__file__).name, extra=results)+++if __name__ == "__main__":+ raise SystemExit(main())diff --git a/scripts/check_tenant_query_predicates.py b/scripts/check_tenant_query_predicates.pyindex 71f7cceeb..3629e094b 100644--- a/scripts/check_tenant_query_predicates.py+++ b/scripts/check_tenant_query_predicates.py@@ -214,6 +214,210 @@ _SQL_TABLE = re.compile(r'\b(?:FROM|JOIN|UPDATE|INTO)\s+("?[\w.]+"?)', re.IGNORE_TENANT_IN_SQL = re.compile(r"\btenant_id\b", re.IGNORECASE)+# ---------------------------------------------------------------------------+# Does a raw statement's `tenant_id` actually constrain the rows?+# ---------------------------------------------------------------------------+#+# `_TENANT_IN_SQL` answers "does this string contain the token", which is not+# the question. The blind spot was recorded in this module's own docstring and+# left open on the grounds that one statement relied on it and that statement+# was legitimately cross-tenant. That stopped being true: measured on `main`,+# 18 statements were credited by a token that constrains nothing, two of them+# `UPDATE … RETURNING id, tenant_id` worker sweeps that the ratchet is supposed+# to account for by name and did not, because the bare match short-circuited+# before the ratchet was ever consulted.+#+# The distinction is where the token sits, so the token's *clause* is what gets+# read. Occurrences are attributed to the clause keyword most recently opened+# before them, which handles subqueries and CTEs the way they actually nest:+# `WHERE id IN (SELECT … WHERE tenant_id = $1)` credits the inner predicate,+# and `UPDATE … WHERE <no tenant> RETURNING tenant_id` credits nothing.+#+# A real SQL parser was considered and rejected. `sqlglot` is in the tree and+# pinned exactly, but every gate here has to run on a bare interpreter before+# any `pip install` (see `scripts/gate_toolkit.py`), and a gate that acquires a+# dependency is a gate that gets skipped in the one environment that matters.+# The cost of that choice is recorded in `_UNCREDITED` below.++#: Comments are stripped before any clause is located. Two statements in this+#: tree carry a `--` note, and a token inside one constrains nothing while+#: reading exactly like a predicate to a positional scan.+_SQL_LINE_COMMENT = re.compile(r"--[^\n]*")+_SQL_BLOCK_COMMENT = re.compile(r"/\*.*?\*/", re.DOTALL)++#: Clause keywords, **longest first**: `ON CONFLICT` must not be read as a join+#: `ON`, and `DELETE FROM` must not be read as a bare `FROM`. Python's `re`+#: alternation is first-match-wins rather than longest-match, so this ordering+#: is load-bearing and `test_on_conflict_is_not_read_as_a_join_on` pins it.+#: Ordered longest-first; the regex is built from this tuple rather than+#: written out separately, so the keyword set the matcher recognises and the+#: keyword set the two classification tables below are checked against cannot+#: be two different lists.+_CLAUSE_KEYWORDS: tuple[str, ...] = (+ "ON CONFLICT",+ "DO UPDATE SET",+ "DELETE FROM",+ "INSERT INTO",+ "GROUP BY",+ "ORDER BY",+ "LEFT JOIN",+ "RIGHT JOIN",+ "INNER JOIN",+ "OUTER JOIN",+ "CROSS JOIN",+ "SELECT",+ "FROM",+ "WHERE",+ "HAVING",+ "RETURNING",+ "VALUES",+ "USING",+ "UPDATE",+ "SET",+ "JOIN",+ "ON",+ "LIMIT",+ "OFFSET",+ "WITH",+)++_SQL_CLAUSE = re.compile(+ r"\b(" + "|".join(kw.replace(" ", r"\s+") for kw in _CLAUSE_KEYWORDS) + r")\b",+ re.IGNORECASE,+)++#: Clauses in which `tenant_id` restricts which rows are read or written.+#:+#: `ON CONFLICT (tenant_id, …)` is here because the conflict target is what+#: selects the existing row an upsert updates — it is that statement's WHERE.+#: `INSERT INTO t (tenant_id, …)` is here for the write direction: the column+#: list plus a bound value is what stamps the new row with a tenant, and it is+#: the only form in which an INSERT can be scoped at all. 90 of the 108+#: statements this rule re-examines are that shape and every one is correct;+#: flagging them would have been 90 false positives, which is how a gate gets+#: switched off.+_CONSTRAINING_CLAUSES = frozenset({"WHERE", "ON", "USING", "HAVING", "ON CONFLICT", "INSERT INTO"})++#: Deliberately **not** credited, each for a stated reason:+#:+#: `SELECT` / `RETURNING` a projection names a column on the way out; it says+#: nothing about which rows were chosen. This is the+#: defect being closed.+#: `ORDER BY` / `GROUP BY` sorting and bucketing happen after the rows are+#: picked. A cross-tenant aggregate grouped by tenant+#: is still a cross-tenant read.+#: `VALUES` a bound value alone does not say which column it+#: lands in; the column list is what does.+#: `SET` on an UPDATE this *writes* the tenant column, which+#: constrains nothing about which rows are rewritten —+#: it is a tenant reassignment, the opposite of a+#: scope.+#:+#: Read by `_clause_classification_is_total`, not only by a human: a clause+#: added to `_SQL_CLAUSE` and classified into neither set would silently+#: default to "not credited", which is the safe direction but an unstated one.+#: The self-test asserts the two sets are disjoint and together cover every+#: alternative the regex can emit, so adding a keyword forces a decision.+_UNCREDITED = frozenset(+ {+ "SELECT",+ "RETURNING",+ "ORDER BY",+ "GROUP BY",+ "VALUES",+ "SET",+ "DO UPDATE SET",+ "FROM",+ "LIMIT",+ "OFFSET",+ "UPDATE",+ "DELETE FROM",+ "JOIN",+ "LEFT JOIN",+ "RIGHT JOIN",+ "INNER JOIN",+ "OUTER JOIN",+ "CROSS JOIN",+ "WITH",+ }+)+++def _clause_classification_is_total() -> tuple[bool, str]:+ """Every clause `_SQL_CLAUSE` can emit is classified exactly once.++ A keyword the regex matches but neither set names falls through to "not+ constraining". That is the right default and the wrong way to arrive at+ it — nobody decided. Checked rather than trusted, because the regex and+ the two sets are three lists that have to agree and sit 60 lines apart.+ """+ emitted = set(_CLAUSE_KEYWORDS)+ both = _CONSTRAINING_CLAUSES & _UNCREDITED+ unclassified = emitted - _CONSTRAINING_CLAUSES - _UNCREDITED+ problems = []+ if both:+ problems.append(f"classified twice: {sorted(both)}")+ if unclassified:+ problems.append(f"matched by _SQL_CLAUSE but classified nowhere: {sorted(unclassified)}")+ return (not problems), "; ".join(problems) or f"{len(emitted)} clause keyword(s), each classified exactly once"+++#: Known residuals, stated rather than silently carried. Neither is reachable+#: in this tree today and both are checked for by the self-test so that stays+#: visible:+#:+#: * a correlated subquery in a projection (`SELECT (SELECT … WHERE+#: b.tenant_id = a.tenant_id) FROM a`) credits the outer statement off the+#: inner predicate. The correlation makes the outer read per-tenant in+#: practice, so this errs toward a credit rather than a false alarm.+#: * `INSERT INTO a (tenant_id, …) SELECT … FROM b` credits the stamped write+#: while the *read* from `b` may be unscoped. One statement of this shape+#: exists and it carries its own `WHERE tenant_id`.+++#: A predicate *fragment* carries no clause keyword of its own — it is the+#: ``" AND tenant_id = :tid"`` that a caller concatenates onto a base query, or+#: an element of a ``filters`` list. The token is only credited there when it+#: is one side of a comparison, so ``", tenant_id"`` appended to a projection+#: stays uncredited. An optional ``::cast`` sits between the two in asyncpg+#: code (``tenant_id::uuid = $1``) and has to be stepped over.+_TENANT_COMPARED = re.compile(+ r"\btenant_id\b\s*(?:::\s*\w+\s*)?\s*(?:=|<>|!=|>=|<=|>|<|\bIN\b|\bIS\b|\bLIKE\b|\bBETWEEN\b|\bANY\b)"+ r"|(?:=|<>|!=|\bIN\b|\bANY\b)\s*\(?\s*\btenant_id\b",+ re.IGNORECASE,+)+++def _tenant_predicate_in_sql(blob: str) -> bool:+ """Whether `tenant_id` appears somewhere that constrains the rows.++ Replaces a bare `tenant_id in the string` test. Returns False for a token+ that only ever appears in a projection, a `RETURNING` list, an `ORDER BY`,+ a `GROUP BY`, an UPDATE's `SET`, or a comment.++ Called on two kinds of string and has to answer for both: a whole+ statement, where the clause the token sits in decides; and a bare predicate+ fragment with no clause keyword at all, where being one side of a+ comparison decides.+ """+ text_only = _SQL_BLOCK_COMMENT.sub(" ", _SQL_LINE_COMMENT.sub(" ", blob))+ clauses = [(m.start(), re.sub(r"\s+", " ", m.group(1).upper())) for m in _SQL_CLAUSE.finditer(text_only)]+ for hit in _TENANT_IN_SQL.finditer(text_only):+ governing = ""+ for start, keyword in clauses:+ if start > hit.start():+ break+ governing = keyword+ if governing in _CONSTRAINING_CLAUSES:+ return True+ # No clause opened before the token: this is a fragment, not a+ # statement. Credit it only if the token is being compared against+ # something rather than merely listed.+ if not governing and _TENANT_COMPARED.search(text_only[max(0, hit.start() - 24) : hit.end() + 24]):+ return True+ return False++# ---------------------------------------------------------------------------# Ratchet# ---------------------------------------------------------------------------@@ -496,11 +700,148 @@ RATCHET: dict[str, str] = {"records a confirmed drift on the swept row by primary key; sole caller scheduler.py:926, ""which compares the fingerprint of the poll it just performed"),+ # ── raw SQL, visible to this gate for the first time ───────────────────+ # Not new queries, and not new debt. These seventeen statements are+ # unchanged on disk; they were credited by `_TENANT_IN_SQL` matching the+ # token anywhere in the string — a `RETURNING id, tenant_id`, a `SELECT+ # tenant_id, …` projection, an `ORDER BY tenant_id`. The clause-aware rule+ # (`_tenant_predicate_in_sql`) withdrew that credit, so each one arrives+ # here to be read on its merits for the first time. Every one was read.+ # None of them was given a predicate instead, because in every case a+ # tenant predicate would break the thing the statement exists to do.+ #+ # i. the lookup that *establishes* the tenant — same class as the+ # pre-auth group at the top of this table, reached before a request+ # has a tenant to filter on.+ "services/api/app/auth/sso_provisioning.py::resolve_connection::aisoc_sso_connections": (+ "pre-auth: resolves which SSO connection an assertion belongs to, by (provider, issuer). "+ "The row it finds is what assigns the tenant, so filtering on a tenant would mean no "+ "federated sign-in could ever resolve one"+ ),+ "services/api/app/auth/saml_metadata.py::resolve_saml_connection::aisoc_sso_connections": (+ "pre-auth: the SP-metadata and ACS entry points resolve a connection by issuer, or by none "+ "at all on the console link, before any principal exists. LIMIT 2 so an ambiguous "+ "configuration is detected rather than silently resolved to the first row"+ ),+ "services/api/app/api/v1/endpoints/mfa.py::_principal_for_enrolment::users": (+ "pre-auth second-factor enrolment: `:u` is the subject of a signed, purpose-checked "+ "sign-in challenge (`read_challenge(..., expect_purpose='enroll')`), not a caller-supplied "+ "id. The row it reads is what assigns the tenant the enrolment is then stamped with"+ ),+ "services/api/app/api/v1/endpoints/inbox_itsm.py::_fetch_token_and_connector::tenant_inbox_tokens": (+ "the inbound ITSM webhook carries an opaque inbox token and nothing else; this lookup is "+ "what turns that token into a tenant. Same shape as the SCIM bearer-token entry above"+ ),+ # ii. read cross-tenant *in order to* enforce the tenant check.+ "services/api/app/api/v1/endpoints/inbox_itsm.py::_fetch_token_and_connector::connectors": (+ "deliberately reads the connector row without a tenant predicate so the next statement can "+ "compare `connector_row.tenant_id != token_row.tenant_id`, log a cross-tenant attempt with "+ "both ids and refuse. Scoping the SELECT would collapse that into an indistinguishable "+ "404 and lose the signal the SOC is meant to see; nothing from the row is returned to the "+ "caller before the comparison"+ ),+ # iii. an identity predicate, which is strictly narrower than a tenant.+ "services/api/app/api/v1/endpoints/mfa.py::enrolment_row::aisoc_user_mfa": (+ "keyed on user_id, which every one of its eight callers passes as the authenticated "+ "principal's own (`current_user.user_id`, `principal.user_id`, or a user id already "+ "resolved from a verified challenge). A user id is narrower than a tenant id, which this "+ "gate credits on the ORM path; the raw-SQL path cannot see it because the predicate is "+ "bound in the caller, one function away"+ ),+ # iv. a worker's working set: "which tenants", which cannot presuppose one.+ # The same discover-then-bind shape already recorded above for+ # hunt_scheduler.run_once and oauth_refresh._select_due_connectors.+ "services/api/app/workers/autonomy_drift.py::<module>::aisoc_autonomy_grants": (+ "the drift sweep's enumeration — SELECT DISTINCT tenant_id across granted autonomy — which "+ "is the question 'which tenants hold a grant to re-check'. Each tenant is bound "+ "individually afterwards"+ ),+ "services/api/app/workers/retention_purge.py::_load_policies::retention_policies": (+ "loads every tenant's retention policy so the purge can run each one; a tenant missing from "+ "this read is a tenant whose data is never purged, which is the compliance failure the "+ "worker exists to prevent"+ ),+ "services/api/app/workers/phishing_report_intake.py::_mailbox_connectors::connectors": (+ "the intake worker's working set of enabled mailbox connectors across tenants; ordered by "+ "tenant so the fan-out is deterministic. Each connector is then polled under its own row's "+ "tenant"+ ),+ "services/api/app/workers/shadow_reconcile.py::<module>::aisoc_shadow_mode": (+ "COUNT(DISTINCT tenant_id) of tenants in shadow mode — a fleet-wide gauge for one log "+ "line. It returns a number, never a tenant's rows"+ ),+ "services/api/app/workers/approval_expiry.py::<module>::agent_approvals": (+ "expires every tenant's stale approvals in one statement, bounded by `expires_at < now()`. "+ "This is the UPDATE beside the no-deadline count already recorded above for "+ "approval_expiry.run_once, and it was the clearest instance of the defect this rule "+ "closes: it was credited by `RETURNING id, tenant_id`, a clause that constrains nothing"+ ),+ "services/fusion/app/services/sessions.py::<module>::sessions": (+ "SELECT DISTINCT tenant_id of sessions due for expiry — the enumeration that drives the "+ "sweep, which then closes each tenant's sessions under its own id"+ ),+ "services/fusion/app/services/alert_outbox.py::claim::fusion_alert_outbox": (+ "the outbox dispatcher claims due rows across every tenant under a lease; an outbox that "+ "drained only one tenant would stall delivery for all the others. The claim is bounded by "+ "`claimed_until` and `created_at`, and each claimed row carries the tenant it is delivered "+ "under. Credited until now by `RETURNING … tenant_id`"+ ),+ "services/fusion/app/services/alert_outbox.py::backlog::fusion_alert_outbox": (+ "the depth-and-age gauge behind the outbox's health signal, grouped by tenant precisely so "+ "one tenant's backlog is attributable. GROUP BY is not a filter: it buckets rows that were "+ "already read, which is why this rule does not credit it"+ ),+ "services/fusion/app/memory/provider.py::refresh::alerts": (+ "rebuilds the per-signature prior cache for every tenant in one pass, then partitions the "+ "rows by `tenant_id` in Python and hands each tenant only its own through "+ "`get_priors(tenant_id)`. The projected tenant_id is the partition key; a per-tenant query "+ "would be one round trip per tenant on a cadence"+ ),+ "services/connectors/app/scheduler.py::_promote_overdue_findings::connectors": (+ "SELECT DISTINCT tenant_id over enabled connectors — the scheduler's tenant enumeration, "+ "and the one statement this module's docstring already named as relying on the bare-token "+ "credit. It now holds a reason instead of a regex match"+ ),+ # v. a fragment, judged at its use sites rather than here.+ "services/api/app/services/alert_source_link.py::<module>::alert_source_links": (+ "`_SELECT` is a column list and a FROM, never executed as written: every one of its four "+ "callers interpolates it into an f-string that appends `WHERE tenant_id = :tenant_id`, and "+ "this gate judges each of those four call sites independently — a fifth caller that "+ "omitted the predicate would be flagged there. Entry is keyed on this table, so an "+ "unscoped statement on any other table in this module still fails"+ ),}#: Raising this is a deliberate act with a diff attached. Appending to RATCHET#: without raising it fails the gate, which is the whole point.#:+#: 60 -> 77 when `_tenant_predicate_in_sql` replaced the bare-token match.+#: This one needs its reasoning written down, because "raise the ceiling until+#: the scan passes" is the exact move this repository forbids, and from the+#: diff alone it looks identical.+#:+#: What it is not: seventeen new unscoped queries. Not one line of+#: `services/` changed in the commit that moved this number. Those seventeen+#: statements are byte-for-byte what they were, and every one was already+#: unscoped — the gate credited them because `tenant_id` appeared *somewhere*+#: in the SQL text, which for two of them was a `RETURNING` list and for+#: eleven was a `SELECT` projection or an `ORDER BY`.+#:+#: So 60 was never a debt balance. It was the balance a broken detector could+#: see, and the seventeen were debt the whole time, carried off the books. The+#: honest number is 77, and the number of genuinely new exemptions this change+#: introduces is zero.+#:+#: The alternative — leaving the ceiling at 60 — was rejected: it fails the+#: gate on every pull request for findings no author introduced and none can+#: fix, which is how a gate gets switched off. The other alternative, giving+#: the seventeen real predicates, was rejected per statement and for a reason+#: recorded per statement: four are pre-auth lookups that a tenant predicate+#: would make unable to resolve a tenant at all, nine are worker sweeps whose+#: whole job is "every tenant", one reads cross-tenant *in order to* enforce+#: the tenant check, one is keyed on an identity narrower than a tenant, and+#: one is a fragment judged at its four call sites instead.+#:#: 32 -> 33 for the SCIM bearer-token lookup. It belongs to the first group#: above, the lookups that *establish* a tenant rather than operate inside one:#: a SCIM request carries no tenant and RFC 7643 defines no attribute that@@ -572,7 +913,7 @@ RATCHET: dict[str, str] = {# *stricter*: the statement that had to be fixed rather than recorded,# `fetch_enabled_connectors` called from a request handler, is absent from the# list because the route now uses a sibling that filters in SQL.-MAX_RATCHET = 60+MAX_RATCHET = 77# ---------------------------------------------------------------------------@@ -1268,7 +1609,7 @@ def _scan_sql(fn = _enclosing_function(node, fn_of)fn_name = getattr(fn, "name", "<module>")- if _TENANT_IN_SQL.search(blob):+ if _tenant_predicate_in_sql(blob):continue# The predicate may be concatenated in from a clause list, or bound@@ -1280,7 +1621,12 @@ def _scan_sql(names = _names(stmt_node)binds = _local_bindings(fn) if fn is not None else {}resolved = _expand(names, binds)- if any(_TENANT_IN_SQL.search(r) for r in resolved) or (resolved & TENANT_TOKENS):+ # `_names` collects string *constants* as well as identifiers, so the+ # statement's own SQL comes back round in `resolved` and a bare token+ # test here silently re-grants the credit the clause rule above just+ # withheld. Measured: that defeated the clause rule on 14 of the 17+ # statements it had correctly demoted. Same rule, both places.+ if any(_tenant_predicate_in_sql(r) for r in resolved) or (resolved & TENANT_TOKENS):continueauth_names = _auth_bound_names(fn) if fn is not None else set()if auth_names & names:@@ -1351,6 +1697,7 @@ ROUTE_DECORATOR_METHODS = frozenset({"get", "post", "put", "patch", "delete", "h#: joined back into exactly the paths `scan_route_reachability` emits._EP = "services/api/app/api/v1/endpoints"_SV = "services/api/app/services"+_AU = "services/api/app/auth"_OSQ = "services/osquery-tls/app"ROUTE_REACHABLE: dict[str, str] = {@@ -1449,12 +1796,60 @@ ROUTE_REACHABLE: dict[str, str] = {f"{_EP}/admin_users.py::remove_role -> {_EP}/admin_users.py::_guard_last_admin": "same last-admin guard, role-revoke leg",f"{_EP}/admin_users.py::set_roles -> {_EP}/admin_users.py::_end_sessions": "same validated user id, role-replace leg",f"{_EP}/admin_users.py::set_roles -> {_EP}/admin_users.py::_guard_last_admin": "same last-admin guard, role-replace leg",+ # -- pre-auth: the request has no tenant yet, which is why it is here ----+ # Twelve pairs that appeared together when `_tenant_predicate_in_sql`+ # withdrew the bare-token credit from the four statements behind them.+ # They are the first of this table's four shapes and the least ambiguous+ # one: a handler cannot filter on a tenant it has not been assigned, and+ # each of these statements is the thing that assigns it.+ f"{_AU}/oidc.py::oidc_callback -> {_AU}/sso_provisioning.py::resolve_connection": (+ "the OIDC callback arrives with an authorization code and an issuer, not a session; the "+ "connection row it resolves is what names the tenant the user is provisioned into"+ ),+ f"{_AU}/saml.py::saml_acs -> {_AU}/sso_provisioning.py::resolve_connection": (+ "the SAML assertion consumer service, same reasoning as the OIDC callback: unauthenticated "+ "by construction, and the resolved connection is what assigns the tenant"+ ),+ f"{_AU}/saml.py::saml_acs -> {_AU}/saml_metadata.py::resolve_saml_connection": (+ "the ACS resolves the connection a second time by the assertion's issuer in order to load "+ "the signing certificate it must verify against, before anything in the assertion is trusted"+ ),+ f"{_AU}/saml.py::saml_login -> {_AU}/saml_metadata.py::resolve_saml_connection": (+ "SP-initiated sign-in: the console link carries no issuer and no principal, so this is the "+ "lookup that decides which IdP to redirect to"+ ),+ f"{_AU}/saml.py::saml_logout -> {_AU}/saml_metadata.py::resolve_saml_connection": (+ "single logout is reached with the session already being torn down and must resolve the "+ "same connection to validate the LogoutRequest's signature"+ ),+ f"{_EP}/inbox_itsm.py::inbound_itsm_webhook -> {_EP}/inbox_itsm.py::_fetch_token_and_connector": (+ "the vendor's ITSM webhook authenticates with an opaque inbox token and nothing else. The "+ "helper is the tenant resolution step, and its second statement is deliberately "+ "cross-tenant so a token from one tenant aimed at another tenant's connector is detected "+ "and logged rather than silently 404'd"+ ),+ f"{_EP}/auth.py::login -> {_EP}/mfa.py::enrolment_row": (+ "sign-in asks whether the user it has just resolved holds a second factor, keyed on that "+ "user's own id. A tenant predicate would add nothing: user_id is the narrower key"+ ),+ f"{_EP}/mfa.py::mfa_status -> {_EP}/mfa.py::enrolment_row": "reads current_user.user_id's own enrolment",+ f"{_EP}/mfa.py::enroll_begin -> {_EP}/mfa.py::enrolment_row": "same, enrolment leg: principal.user_id only",+ f"{_EP}/mfa.py::enroll_confirm -> {_EP}/mfa.py::enrolment_row": "same, confirmation leg: principal.user_id only",+ f"{_EP}/mfa.py::verify -> {_EP}/mfa.py::enrolment_row": (+ "second-factor verification during sign-in, keyed on the user id carried by the signed sign-in challenge the caller presented"+ ),+ f"{_EP}/mfa.py::disable -> {_EP}/mfa.py::enrolment_row": "same, disable leg: current_user.user_id only",}#: Shrink-only, exactly like MAX_RATCHET. 34 is what `main` measured once the#: fixed route stopped reaching the scheduler's sweep; the vulnerable tree#: measured 35.-MAX_ROUTE_REACHABLE = 34+#: 34 -> 46 alongside MAX_RATCHET's 60 -> 77 and for the same reason: the+#: twelve pairs added were not reachable-by-a-request findings that appeared,+#: they are pairs that became *visible* when the four statements behind them+#: stopped being credited by a token in a projection. All twelve are pre-auth+#: routes, the shape whose exemption is strongest, and no handler changed.+MAX_ROUTE_REACHABLE = 46#: How far to follow calls out of a handler. Four frames covers#: handler -> service -> repository with room to spare.@@ -1709,6 +2104,195 @@ async def get_widget(widget_id, db):return await db.execute(text("SELECT * FROM widgets WHERE id = :id").bindparams(id=widget_id))"""+# ── where `tenant_id` sits, one probe per clause the dialect offers ────────+#+# The rule this exercises is `_tenant_predicate_in_sql`. A sibling gate in this+# tree printed OK over four real violations because its detector knew two+# syntaxes out of five, so these are written per *clause* rather than per+# instance found on `main`: every clause a tenant column can legally appear in+# gets a probe, on whichever side of the rule it belongs.+#+# Must be FLAGGED — the token is there and constrains nothing.++_SQL_TENANT_IN_RETURNING = """+from sqlalchemy import text++async def expire(db):+ return await db.execute(text(+ "UPDATE widgets SET status = 'expired' WHERE expires_at < now() RETURNING id, tenant_id"+ ))+"""++_SQL_TENANT_IN_PROJECTION = """+from sqlalchemy import text++async def get_widget(widget_id, db):+ return await db.execute(text(+ "SELECT id, tenant_id, secret FROM widgets WHERE id = :id"+ ).bindparams(id=widget_id))+"""++_SQL_TENANT_IN_ORDER_BY = """+from sqlalchemy import text++async def all_widgets(db):+ return await db.execute(text("SELECT id, secret FROM widgets ORDER BY tenant_id"))+"""++_SQL_TENANT_IN_GROUP_BY = """+from sqlalchemy import text++async def depth(db):+ return await db.execute(text("SELECT count(*) FROM widgets GROUP BY tenant_id"))+"""++_SQL_TENANT_IN_COMMENT = """+from sqlalchemy import text++async def get_widget(widget_id, db):+ return await db.execute(text(+ "SELECT id FROM widgets -- callers must pass tenant_id\\n WHERE id = :id"+ ).bindparams(id=widget_id))+"""++_SQL_TENANT_IN_BLOCK_COMMENT = """+from sqlalchemy import text++async def get_widget(widget_id, db):+ return await db.execute(text(+ "SELECT id FROM widgets /* tenant_id is applied by RLS */ WHERE id = :id"+ ).bindparams(id=widget_id))+"""++_SQL_TENANT_IN_UPDATE_SET = """+from sqlalchemy import text++async def reassign(widget_id, new_tenant, db):+ return await db.execute(text(+ "UPDATE widgets SET tenant_id = :t WHERE id = :id"+ ).bindparams(t=new_tenant, id=widget_id))+"""++# Must PASS — the token constrains which rows are read or written.++_SQL_TENANT_IN_WHERE = """+from sqlalchemy import text++async def get_widget(widget_id, db):+ return await db.execute(text(+ "SELECT id, secret FROM widgets WHERE id = :id AND tenant_id = :t"+ ).bindparams(id=widget_id, t="x"))+"""++_SQL_TENANT_IN_JOIN_ON = """+from sqlalchemy import text++async def joined(db):+ return await db.execute(text(+ "SELECT w.id FROM widgets w JOIN gadgets g ON g.tenant_id = w.tenant_id WHERE w.id = :id"+ ).bindparams(id="x"))+"""++_SQL_TENANT_IN_USING = """+from sqlalchemy import text++async def joined(db):+ return await db.execute(text("SELECT w.id FROM widgets w JOIN gadgets USING (tenant_id)"))+"""++_SQL_TENANT_IN_HAVING = """+from sqlalchemy import text++async def noisy(db):+ return await db.execute(text(+ "SELECT count(*) FROM widgets GROUP BY kind HAVING tenant_id = :t"+ ).bindparams(t="x"))+"""++_SQL_TENANT_IN_INSERT_COLUMNS = """+from sqlalchemy import text++async def add(db):+ return await db.execute(text(+ "INSERT INTO widgets (id, tenant_id, secret) VALUES (:id, :t, :s) RETURNING id"+ ).bindparams(id="i", t="x", s="s"))+"""++_SQL_TENANT_IN_ON_CONFLICT = """+from sqlalchemy import text++async def upsert(db):+ return await db.execute(text(+ "INSERT INTO widgets (id, secret) VALUES (:id, :s) "+ "ON CONFLICT (tenant_id, id) DO UPDATE SET secret = EXCLUDED.secret"+ ).bindparams(id="i", s="s"))+"""++_SQL_TENANT_IN_SUBQUERY_WHERE = """+from sqlalchemy import text++async def claim(db):+ return await db.execute(text(+ "UPDATE widgets SET claimed = true WHERE id IN ("+ " SELECT id FROM widgets WHERE tenant_id = :t LIMIT 10) RETURNING id"+ ).bindparams(t="x"))+"""++_SQL_TENANT_IN_CTE = """+from sqlalchemy import text++async def recent(db):+ return await db.execute(text(+ "WITH mine AS (SELECT id FROM widgets WHERE tenant_id = :t) "+ "SELECT id FROM mine"+ ).bindparams(t="x"))+"""++_SQL_TENANT_CAST_THEN_COMPARED = """+from sqlalchemy import text++async def get_widget(db):+ return await db.execute(text("SELECT id FROM widgets WHERE tenant_id::uuid = $1"))+"""++# The two ways a predicate arrives from outside the string the scanner reads.+# Both land on `_tenant_predicate_in_sql`, by different routes: the f-string+# flattens into one blob carrying its own WHERE, while the appended fragment+# has no clause keyword at all and is credited only because the token is one+# side of a comparison. The second is the branch a clause-position rule would+# otherwise get wrong, and it is how `alert_source_link.py`'s four call sites+# are written.+_SQL_TENANT_VIA_FSTRING = """+from sqlalchemy import text++_COLUMNS = "SELECT id, secret"++async def get_widget(widget_id, tenant, db):+ return await db.execute(+ text(f"{_COLUMNS} FROM widgets WHERE tenant_id = :t AND id = :id").bindparams(t=tenant, id=widget_id)+ )+"""++_SQL_TENANT_VIA_APPENDED_FRAGMENT = """+from sqlalchemy import text++async def get_widget(widget_id, tenant, db):+ sql = "SELECT id, secret FROM widgets WHERE id = :id"+ sql += " AND tenant_id = :t"+ return await db.execute(text(sql).bindparams(id=widget_id, t=tenant))+"""++#: The fragment branch must not become a blanket pass: a fragment that merely+#: *names* the column, as an appended projection would, still credits nothing.+_SQL_FRAGMENT_NAMES_BUT_DOES_NOT_COMPARE = """+from sqlalchemy import text++async def get_widget(widget_id, db):+ sql = "SELECT id FROM widgets WHERE id = :id"+ sql += " ORDER BY tenant_id"+ return await db.execute(text(sql).bindparams(id=widget_id))+"""+_SCOPED_VIA_LIST = """from sqlalchemy import and_, selectfrom app.models.widget import Widget@@ -2007,6 +2591,33 @@ def _self_test() -> int:0,None,),+ # Clause position in raw SQL. Every clause a tenant column can legally+ # appear in, on the side of the rule it belongs to. The bare-token+ # match passed all seven of the first group.+ ("drift I: tenant_id only in a RETURNING list", {"r.py": _SQL_TENANT_IN_RETURNING}, 1, None),+ ("drift J: tenant_id only in a SELECT projection", {"r.py": _SQL_TENANT_IN_PROJECTION}, 1, None),+ ("drift K: tenant_id only in an ORDER BY", {"r.py": _SQL_TENANT_IN_ORDER_BY}, 1, None),+ ("drift L: tenant_id only in a GROUP BY", {"r.py": _SQL_TENANT_IN_GROUP_BY}, 1, None),+ ("drift M: tenant_id only in a -- line comment", {"r.py": _SQL_TENANT_IN_COMMENT}, 1, None),+ ("drift N: tenant_id only in a /* block comment */", {"r.py": _SQL_TENANT_IN_BLOCK_COMMENT}, 1, None),+ ("drift O: UPDATE SET tenant_id rewrites the column, it does not scope", {"r.py": _SQL_TENANT_IN_UPDATE_SET}, 1, None),+ ("control: tenant_id in a WHERE", {"r.py": _SQL_TENANT_IN_WHERE}, 0, None),+ ("control: tenant_id in a JOIN ... ON", {"r.py": _SQL_TENANT_IN_JOIN_ON}, 0, None),+ ("control: tenant_id in a USING (...)", {"r.py": _SQL_TENANT_IN_USING}, 0, None),+ ("control: tenant_id in a HAVING", {"r.py": _SQL_TENANT_IN_HAVING}, 0, None),+ ("control: INSERT column list stamps the written row", {"r.py": _SQL_TENANT_IN_INSERT_COLUMNS}, 0, None),+ ("control: ON CONFLICT target selects the upserted row", {"r.py": _SQL_TENANT_IN_ON_CONFLICT}, 0, None),+ ("control: predicate inside a subquery, RETURNING outside it", {"r.py": _SQL_TENANT_IN_SUBQUERY_WHERE}, 0, None),+ ("control: predicate inside a CTE", {"r.py": _SQL_TENANT_IN_CTE}, 0, None),+ ("control: tenant_id::uuid = $1 — a cast before the operator", {"r.py": _SQL_TENANT_CAST_THEN_COMPARED}, 0, None),+ ("control: predicate carried in by an f-string", {"r.py": _SQL_TENANT_VIA_FSTRING}, 0, None),+ ("control: predicate appended as a bare fragment", {"r.py": _SQL_TENANT_VIA_APPENDED_FRAGMENT}, 0, None),+ (+ "drift P: an appended fragment that names tenant_id without comparing it",+ {"r.py": _SQL_FRAGMENT_NAMES_BUT_DOES_NOT_COMPARE},+ 1,+ None,+ ),]failures = 0@@ -2021,6 +2632,10 @@ def _self_test() -> int:failures += 1print(f" [{'PASS' if ok else 'FAIL'}] {label}: {got} finding(s), want {want} (scanned {files} files)")+ total_ok, total_detail = _clause_classification_is_total()+ failures += 0 if total_ok else 1+ print(f" [{'PASS' if total_ok else 'FAIL'}] clause classification is total: {total_detail}")+failures += _self_test_route_reachability()failures += _self_test_stale_ratchet()failures += _self_test_ratchet_ceiling()