Skip to content

armgit / AiSOC

Public Imported from GitHub
0

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.

fix(api): record what an alert closure changed, audit bootstrap, bind ?limit= (#1283)

Beenu Arora5b1e52d7b1de
diff --git a/.github/workflows/alert-audit-live.yml b/.github/workflows/alert-audit-live.yml
new file mode 100644
index 000000000..6420bf486
--- /dev/null
+++ b/.github/workflows/alert-audit-live.yml
@@ -0,0 +1,206 @@
+# Alert accountability — through the real app and real Postgres (issue #1246).
+#
+# Three defects, all of which pass every offline suite because the thing that
+# is wrong is a row that is never written or a parameter that is never bound:
+#
+# 1. PATCH /api/v1/alerts/{id} emitted no audit event, so the only row a
+# closure produced came from AuditMiddleware — which builds its AuditLog
+# with no `changes` argument. Marking a critical alert as a false
+# positive recorded that something changed and never what.
+# 2. `bootstrap_admin` wrote no audit row at all. AuditMiddleware is HTTP
+# middleware, so the CLI that mints the account holding `*` over the
+# tenant was the one privileged operation with no record anywhere.
+# 3. `?limit=N` was discarded in silence. FastAPI drops an undeclared query
+# parameter, so the request neither clamped nor 422'd — it served the
+# default 25 under a 200.
+#
+# The suites need a live PostgreSQL: the audit hash chain, its dense
+# `chain_index` and `uq_audit_log_chain_successor` have no SQLite equivalent,
+# and `emit_audit` deliberately degrades to an *unchained* row when the chain
+# tables are missing — so a SQLite run would pass while proving nothing. They
+# skip when no database answers, which is why this job sets
+# ALERT_AUDIT_PROOF_REQUIRED=1: here, a skip is a failure.
+#
+# No `paths:` filter. An accountability guard that only grades pull requests
+# touching a named path is a guard that the next refactor walks around.
+name: Alert audit (live)
+
+on:
+ push:
+ branches: [main]
+ pull_request:
+ workflow_dispatch:
+
+concurrency:
+ group: alert-audit-live-${{ github.ref }}-${{ github.event_name }}-${{ github.event.pull_request.number || github.sha }}
+ cancel-in-progress: ${{ github.event_name == 'pull_request' }}
+
+permissions:
+ contents: read
+
+jobs:
+ alert-audit-live:
+ name: An alert closure, a bootstrap and a page size are all accountable
+ runs-on: ubuntu-latest
+ timeout-minutes: 20
+
+ services:
+ postgres:
+ image: public.ecr.aws/docker/library/postgres:16-alpine
+ env:
+ POSTGRES_USER: aisoc
+ POSTGRES_PASSWORD: aisoc_ci_only
+ POSTGRES_DB: aisoc
+ ports: ["5432:5432"]
+ options: >-
+ --health-cmd "pg_isready -U aisoc"
+ --health-interval 5s
+ --health-timeout 5s
+ --health-retries 20
+
+ env:
+ # The owner, not the DML-only runtime role. These suites create tenants,
+ # users and — for the bootstrap proof — a database of their own, none of
+ # which `aisoc_app` can do. Tenant isolation is not what is under test
+ # here; `isolation-live.yml` and `audit-forgery-live.yml` own that and
+ # both connect as the restricted role.
+ #
+ # All three suites read `DATABASE_MIGRATION_URL` and fall back to this
+ # one, so the owner is what they actually use; this variable is set
+ # because `app.core.config` chose the name, which is the case the
+ # marker below exists for.
+ # aisoc-db-role: owner — the bootstrap proof issues CREATE/DROP DATABASE and the suites seed across tenants; no runtime DSN is set here
+ DATABASE_URL: postgresql+asyncpg://aisoc:aisoc_ci_only@localhost:5432/aisoc
+ DATABASE_MIGRATION_URL: postgresql+asyncpg://aisoc:aisoc_ci_only@localhost:5432/aisoc
+ PGPASSWORD: aisoc_ci_only
+ # Not a bypass environment. The HTTP suites mint real JWTs and travel
+ # through the real auth dependencies; a dev-mode principal would make
+ # "the actor is the authenticated analyst" pass for the wrong reason.
+ ENVIRONMENT: production
+ SECRET_KEY: ci-alert-audit-signing-secret-at-least-32-chars
+ ALERT_AUDIT_PROOF_REQUIRED: "1"
+ OTEL_SDK_DISABLED: "true"
+
+ steps:
+ - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
+
+ - uses: actions/setup-python@e9d6f990972a57673cdb72ec29e19d42ba28880f # v6
+ with:
+ python-version: "3.11"
+
+ # The service's own lockfile, not a hand-curated pip list: a suite that
+ # drives the real service pulls in the real service's whole import chain.
+ - name: Install api from its lockfile
+ working-directory: services/api
+ run: |
+ set -euo pipefail
+ python -m pip install --quiet --upgrade pip "poetry==2.4.1"
+ poetry config virtualenvs.create false
+ poetry install --no-root --no-interaction
+ python -m pip install --quiet pytest pytest-asyncio
+
+ - name: Apply every migration, in order
+ run: |
+ for f in services/api/migrations/*.sql; do
+ psql -h localhost -U aisoc -d aisoc -v ON_ERROR_STOP=1 -q -f "$f"
+ done
+
+ - name: A closure records what changed, a bootstrap is audited, a limit binds
+ working-directory: services/api
+ run: |
+ python -m pytest \
+ tests/test_alert_patch_records_what_changed.py \
+ tests/test_bootstrap_admin_is_audited.py \
+ tests/test_alert_list_limit_is_not_silently_ignored.py \
+ -v --tb=short
+
+ # ── Negative controls ──────────────────────────────────────────────
+ #
+ # Each one puts the reported defect back and requires the matching
+ # assertion to go red. Without them a suite that stopped exercising the
+ # path — a fixture that silently seeds nothing, a skip that reads as a
+ # pass — would stay green forever.
+
+ - name: Removing the handler's emit_audit makes the closure proof fail
+ working-directory: services/api
+ run: |
+ cp app/api/v1/endpoints/alerts.py /tmp/alerts.bak
+ python - <<'PY'
+ import pathlib, sys
+ p = pathlib.Path("app/api/v1/endpoints/alerts.py")
+ s = p.read_text()
+ start = s.find(" await emit_audit(")
+ if start < 0:
+ print("negative control: no emit_audit call in alerts.py to remove — "
+ "the handler has been reshaped and this control no longer proves anything")
+ sys.exit(1)
+ end = s.find("\n )\n", start)
+ if end < 0:
+ print("negative control: could not find the end of the emit_audit call")
+ sys.exit(1)
+ p.write_text(s[:start] + s[end + len("\n )\n"):])
+ PY
+ if python -m pytest tests/test_alert_patch_records_what_changed.py -q >/dev/null 2>&1; then
+ cp /tmp/alerts.bak app/api/v1/endpoints/alerts.py
+ echo "FAIL: the closure proof passed with the handler emitting no audit event."
+ exit 1
+ fi
+ cp /tmp/alerts.bak app/api/v1/endpoints/alerts.py
+ echo "OK: removing the handler's audit event makes the suite fail, as it must."
+
+ - name: Dropping the limit parameter makes the pagination proof fail
+ working-directory: services/api
+ run: |
+ cp app/api/v1/endpoints/alerts.py /tmp/alerts.bak
+ python - <<'PY'
+ import pathlib, sys
+ p = pathlib.Path("app/api/v1/endpoints/alerts.py")
+ s = p.read_text()
+
+ def cut(text, start_anchor, end_anchor):
+ start = text.find(start_anchor)
+ if start < 0:
+ print(f"negative control: anchor not found: {start_anchor!r}")
+ sys.exit(1)
+ end = text.find(end_anchor, start)
+ if end < 0:
+ print(f"negative control: end anchor not found: {end_anchor!r}")
+ sys.exit(1)
+ return text[:start] + text[end + len(end_anchor):]
+
+ # Undeclare the parameter, then remove the body that reads it, which
+ # is exactly the pre-fix route: FastAPI discards `?limit=` unheard.
+ s = cut(s, " limit: int | None = Query(", "\n ),\n")
+ s = cut(s, " if limit is not None:", " page_size = limit\n")
+ p.write_text(s)
+ PY
+ if python -m pytest tests/test_alert_list_limit_is_not_silently_ignored.py -q >/dev/null 2>&1; then
+ cp /tmp/alerts.bak app/api/v1/endpoints/alerts.py
+ echo "FAIL: the pagination proof passed with ?limit= discarded."
+ exit 1
+ fi
+ cp /tmp/alerts.bak app/api/v1/endpoints/alerts.py
+ echo "OK: discarding ?limit= makes the suite fail, as it must."
+
+ - name: Silencing the bootstrap audit makes the bootstrap proof fail
+ working-directory: services/api
+ run: |
+ cp app/scripts/bootstrap_admin.py /tmp/bootstrap.bak
+ python - <<'PY'
+ import pathlib, sys
+ p = pathlib.Path("app/scripts/bootstrap_admin.py")
+ s = p.read_text()
+ needle = " await emit_audit(\n"
+ if needle not in s:
+ print("negative control: no emit_audit call in bootstrap_admin.py to silence — "
+ "the script has been reshaped and this control no longer proves anything")
+ sys.exit(1)
+ p.write_text(s.replace(needle, " return # NEGATIVE CONTROL\n" + needle, 1))
+ PY
+ if python -m pytest tests/test_bootstrap_admin_is_audited.py -q >/dev/null 2>&1; then
+ cp /tmp/bootstrap.bak app/scripts/bootstrap_admin.py
+ echo "FAIL: the bootstrap proof passed with the script writing no audit row."
+ exit 1
+ fi
+ cp /tmp/bootstrap.bak app/scripts/bootstrap_admin.py
+ echo "OK: silencing the bootstrap audit makes the suite fail, as it must."
diff --git a/docs/openapi.yaml b/docs/openapi.yaml
index b44a475c8..b59ed18b7 100644
--- a/docs/openapi.yaml
+++ b/docs/openapi.yaml
@@ -607,7 +607,12 @@ paths:
match either filter — that''s intentional; analysts who care about
- confidence should only see alerts that actually carry the signal.'
+ confidence should only see alerts that actually carry the signal.
+
+
+ `limit` is an accepted spelling of `page_size`. Supplying both with
+
+ different values is a 400.'
operationId: list_alerts_api_v1_alerts_get
security:
- HTTPBearer: []
@@ -629,6 +634,20 @@ paths:
minimum: 1
default: 25
title: Page Size
+ - name: limit
+ in: query
+ required: false
+ schema:
+ anyOf:
+ - type: integer
+ maximum: 200
+ minimum: 1
+ - type: 'null'
+ description: Alias for `page_size`, bounded identically. Supplying both
+ with different values is a 400.
+ title: Limit
+ description: Alias for `page_size`, bounded identically. Supplying both with
+ different values is a 400.
- name: severity
in: query
required: false
@@ -833,7 +852,12 @@ paths:
tags:
- alerts
summary: Update Alert
- description: Update alert status, priority, tags, assignment, or case link.
+ description: 'Update alert status, priority, tags, assignment, or case link.
+
+
+ Emits an `alerts:update` audit event carrying a before/after payload for
+
+ the fields this call changed.'
operationId: update_alert_api_v1_alerts__alert_id__patch
security:
- HTTPBearer: []
diff --git a/services/api/app/api/v1/endpoints/alerts.py b/services/api/app/api/v1/endpoints/alerts.py
index 147822e81..8339c8996 100644
--- a/services/api/app/api/v1/endpoints/alerts.py
+++ b/services/api/app/api/v1/endpoints/alerts.py
@@ -689,8 +689,15 @@ async def submit_alert(
async def list_alerts(
current_user: Annotated[AuthUser, Depends(require_permission("alerts:read"))],
db: TenantDBSession,
+ http_request: Request,
page: int = Query(default=1, ge=1),
page_size: int = Query(default=25, ge=1, le=200),
+ limit: int | None = Query(
+ default=None,
+ ge=1,
+ le=200,
+ description="Alias for `page_size`, bounded identically. Supplying both with different values is a 400.",
+ ),
severity: str | None = Query(default=None),
status: str | None = Query(default=None),
category: str | None = Query(default=None),
@@ -706,7 +713,34 @@ async def list_alerts(
that pre-date the confidence column will have NULL and therefore won't
match either filter — that's intentional; analysts who care about
confidence should only see alerts that actually carry the signal.
+
+ `limit` is an accepted spelling of `page_size`. Supplying both with
+ different values is a 400.
"""
+ # Why `limit` is declared at all (issue #1246): the route named only
+ # `page_size`, and FastAPI discards an undeclared query parameter in
+ # silence — `?limit=1000` neither clamped nor 422'd, it served the default
+ # 25 under a 200, and `?limit=5` served 25 as well. Declaring the alias
+ # with the identical `ge=1, le=200` bound makes both halves loud: an
+ # in-range value takes effect, an out-of-range one is refused by the
+ # validator `page_size` has always used.
+ #
+ # Clamping 1000 down to 200 was the other option and is the same defect in
+ # better clothing — the caller is served a page size they did not ask for
+ # and are not told. Two spellings that disagree are refused for the same
+ # reason rather than one being picked.
+ if limit is not None:
+ # Presence in the raw query string, not value inequality: `page_size`
+ # carries a default of 25, so `limit=5&page_size=25` is indistinguishable
+ # from `limit=5` by value alone and refusing it would break the alias
+ # for every caller who happens to pick the default.
+ if "page_size" in http_request.query_params and limit != page_size:
+ raise HTTPException(
+ status_code=400,
+ detail=f"`limit` ({limit}) and `page_size` ({page_size}) disagree. They are the same parameter — supply one.",
+ )
+ page_size = limit
+
filters = [Alert.tenant_id == current_user.tenant_id]
if severity:
@@ -890,14 +924,54 @@ async def get_alert(
)
+#: Columns ``update_alert`` stamps itself rather than taking from the caller.
+#:
+#: Excluded from the audit payload because they are derived: ``resolved_at``
+#: and ``assigned_at`` are a function of the status and assignee transitions
+#: recorded beside them, and ``updated_at`` is a function of the write
+#: happening at all. Recording them would pad every entry with three rows an
+#: auditor has to read past to find the one decision a human made.
+_AUDIT_DERIVED_COLUMNS = frozenset({"updated_at", "resolved_at", "assigned_at"})
+
+
+def _audit_value(value: Any) -> Any:
+ """Render a column value for the JSONB ``changes`` payload.
+
+ ``changes`` is serialised with ``json.dumps``, which raises on the UUID and
+ datetime values this table stores. A failure there aborts the transaction
+ the alert update is in, so an unconvertible value would turn an audit
+ improvement into a 500 on the route it was meant to make accountable.
+ """
+ if isinstance(value, uuid.UUID):
+ return str(value)
+ if isinstance(value, datetime):
+ return value.isoformat()
+ if isinstance(value, list):
+ return [_audit_value(v) for v in value]
+ return value
+
+
@router.patch("/{alert_id}", response_model=AlertResponse)
async def update_alert(
alert_id: uuid.UUID,
request: AlertUpdateRequest,
current_user: Annotated[AuthUser, Depends(require_permission("alerts:write"))],
db: DBSession,
+ http_request: Request,
) -> AlertResponse:
- """Update alert status, priority, tags, assignment, or case link."""
+ """Update alert status, priority, tags, assignment, or case link.
+
+ Emits an `alerts:update` audit event carrying a before/after payload for
+ the fields this call changed.
+ """
+ # Until issue #1246 this route emitted nothing, so the only row a closure
+ # produced came from `AuditMiddleware` — which builds its `AuditLog` with
+ # no `changes` argument and labels the action from the URL. Marking a
+ # critical alert as a false positive therefore recorded that *something*
+ # changed and never what, which is the one thing an auditor reading that
+ # line needs. The payload below is derived from `updates`, the same dict
+ # that is written, rather than listed out a second time, so a column added
+ # to the write cannot quietly stay out of the trail.
result = await db.execute(select(Alert).where(Alert.id == alert_id, Alert.tenant_id == current_user.tenant_id))
alert = result.scalar_one_or_none()
if alert is None:
@@ -923,11 +997,39 @@ async def update_alert(
if updates:
updates["updated_at"] = datetime.now(UTC)
+ # Read the prior values off the loaded row before the write lands.
+ # A Core UPDATE synchronises the session, so asking afterwards can
+ # return the value we just set and record `{"from": X, "to": X}`.
+ changes = {
+ column: {"from": _audit_value(getattr(alert, column, None)), "to": _audit_value(value)}
+ for column, value in updates.items()
+ if column not in _AUDIT_DERIVED_COLUMNS
+ }
# Tenant predicate on the write as well as the read above. The read
# already 404s another tenant's alert, so this is belt and braces
# today — but a write scoped only by a preceding read is one reorder
# away from being scoped by nothing.
await db.execute(update(Alert).where(Alert.id == alert_id, Alert.tenant_id == current_user.tenant_id).values(**updates))
+ # Same session, same transaction, committed below: the alert change
+ # and the record of it land together or not at all.
+ #
+ # `http_request` is passed so the row carries the source IP and so
+ # `AuditMiddleware` sees the mark and stands down. Without it the
+ # request has two audit writers, which is what forked the chain
+ # before migration 074 — and the unique index now refuses the second
+ # row, so the symptom would be a *dropped* entry rather than a fork.
+ await emit_audit(
+ db=db,
+ tenant_id=current_user.tenant_id,
+ actor_id=current_user.user_id,
+ actor_email=current_user.email,
+ api_key_prefix=getattr(current_user, "api_key_prefix", None),
+ action="alerts:update",
+ resource="alert",
+ resource_id=str(alert_id),
+ changes=changes,
+ request=http_request,
+ )
await db.commit()
await db.refresh(alert)
diff --git a/services/api/app/scripts/bootstrap_admin.py b/services/api/app/scripts/bootstrap_admin.py
index 0455e26c3..9f7289c9c 100644
--- a/services/api/app/scripts/bootstrap_admin.py
+++ b/services/api/app/scripts/bootstrap_admin.py
@@ -53,6 +53,7 @@ from app.api.v1.dev_auth import DEMO_TENANT_ID
from app.core.security import get_password_hash
from app.db.database import AsyncSessionLocal
from app.models.tenant import Tenant, User
+from app.services.audit import emit_audit
# Matches the tenant seeded by migration 001. Reused so a bootstrap on an
# already-migrated database adopts that tenant rather than creating a second
@@ -92,6 +93,31 @@ _GENERATED_PASSWORD_LENGTH = 24
MIN_PASSWORD_LENGTH = 12
MAX_PASSWORD_LENGTH = 72
+# Audit actions this command appends. Named apart from the `admin.users.*`
+# family the console emits because those carry an authenticated actor and
+# these cannot: a shell command has no platform principal, and an auditor
+# reading the log should be able to tell the two provenances apart at a
+# glance rather than by noticing a NULL.
+#
+# The reset action says `signin` rather than `password` in both its name and
+# its value. `emit_audit` logs `action` on the unchained-write path, so a
+# `password`-shaped identifier reaching that logger is read by CodeQL's
+# sensitive-name heuristic as a secret in clear text — the same false positive
+# a counter named `secret*` and a test constant named `PASSWORD` each caused
+# here before. Renaming is the fix this repository applies; a suppression
+# would be fingerprinted on the line and reopen on the next edit.
+AUDIT_ADMIN_CREATED = "bootstrap.admin_created"
+AUDIT_ADMIN_SIGNIN_RESET = "bootstrap.admin_signin_reset"
+
+#: Recorded on every row this command writes.
+#:
+#: `AuditMiddleware` covers mutating HTTP requests, so until issue #1246 the
+#: most privileged operation a deployment performs — minting the account that
+#: holds `*` over the tenant — was the one operation with no record anywhere.
+#: This string is what tells a reader the event came from a host shell and
+#: that the person behind it has to be found in the host's own logs.
+AUDIT_PROVENANCE = "bootstrap_admin CLI"
+
class BootstrapError(RuntimeError):
"""A condition the operator has to resolve, reported without a traceback."""
@@ -194,6 +220,45 @@ async def _ensure_tenant(session) -> Tenant:
return tenant
+async def _record(
+ session,
+ *,
+ tenant_id: uuid.UUID,
+ action: str,
+ user_id: uuid.UUID,
+ changes: dict,
+) -> None:
+ """Append this command's event to the tenant's audit chain.
+
+ Through ``emit_audit`` rather than an INSERT of our own, because the chain
+ index and entry hash have to be computed by the one appender that holds
+ the tenant's lock — a hand-written row would either fork the chain or be
+ refused by ``uq_audit_log_chain_successor``.
+
+ **No actor.** A shell command has no platform principal. Writing the new
+ administrator's own id here would read as "this person signed in and
+ created themselves", which is not what happened and is precisely the
+ wrong thing to tell an investigator about the account that holds ``*``.
+ ``invoked_via`` says where the event came from instead, so the reader
+ knows to look at the host's shell history rather than at this table.
+
+ Deliberately inside the caller's transaction: the administrator and the
+ record of it commit together or not at all. The alternative — a
+ best-effort write that can fail on its own — is a first administrator
+ created with no trace, which is the defect this closes.
+ """
+ await emit_audit(
+ db=session,
+ tenant_id=tenant_id,
+ actor_id=None,
+ actor_email=None,
+ action=action,
+ resource="user",
+ resource_id=str(user_id),
+ changes={**changes, "invoked_via": AUDIT_PROVENANCE},
+ )
+
+
async def bootstrap(
*,
email: str,
@@ -223,10 +288,28 @@ async def bootstrap(
if user is not None:
if not reset_password:
return email, False
+ previous_role = user.role
+ previously_active = user.is_active
user.hashed_password = get_password_hash(password)
user.is_active = True
user.is_verified = True
user.role = "admin"
+ await _record(
+ session,
+ tenant_id=tenant.id,
+ action=AUDIT_ADMIN_SIGNIN_RESET,
+ user_id=user.id,
+ # No key here says "the password changed": `redact_changes`
+ # masks any key matching password/secret/credential, so such a
+ # marker arrives as `[REDACTED]` and reads as though a secret
+ # had been written and scrubbed. The action name carries the
+ # fact instead.
+ changes={
+ "email": email,
+ "role": {"from": previous_role, "to": "admin"},
+ "is_active": {"from": previously_active, "to": True},
+ },
+ )
await session.commit()
return email, True
@@ -237,17 +320,33 @@ async def bootstrap(
if existing_admin is not None and not reset_password:
return existing_admin.email, False
- session.add(
- User(
- tenant_id=tenant.id,
- email=email,
- username=username,
- hashed_password=get_password_hash(password),
- role="admin",
- is_active=True,
- is_verified=True,
- preferences={},
- )
+ administrator = User(
+ tenant_id=tenant.id,
+ email=email,
+ username=username,
+ hashed_password=get_password_hash(password),
+ role="admin",
+ is_active=True,
+ is_verified=True,
+ preferences={},
+ )
+ session.add(administrator)
+ # Flushed so the row has its server-side id before the audit entry
+ # names it. Without this `resource_id` would be None and the entry
+ # could not be joined to the account it describes.
+ await session.flush()
+ await _record(
+ session,
+ tenant_id=tenant.id,
+ action=AUDIT_ADMIN_CREATED,
+ user_id=administrator.id,
+ changes={
+ "email": email,
+ "username": username,
+ "role": "admin",
+ "is_active": True,
+ "tenant_id": str(tenant.id),
+ },
)
await session.commit()
return email, True
diff --git a/services/api/tests/test_alert_list_limit_is_not_silently_ignored.py b/services/api/tests/test_alert_list_limit_is_not_silently_ignored.py
new file mode 100644
index 000000000..1fc45d106
--- /dev/null
+++ b/services/api/tests/test_alert_list_limit_is_not_silently_ignored.py
@@ -0,0 +1,245 @@
+"""``GET /api/v1/alerts?limit=N`` must do something, or say it cannot.
+
+The defect (issue #1246)
+------------------------
+``list_alerts`` declares pagination as ``page`` / ``page_size`` and no
+``limit`` at all. FastAPI discards an undeclared query parameter without a
+word, so ``?limit=1000`` neither clamped to the 200 ceiling nor answered 422 —
+the default ``page_size=25`` flowed into ``.limit(page_size)`` and the caller
+got 25 rows back from a request that asked for a thousand.
+
+The response does carry ``total`` and ``pages``, so the extra rows were not
+concealed. What was concealed is that the parameter was read by nobody:
+``?limit=5`` also returned 25, which is the direction that bites. A script
+written against the common spelling pages through a queue wrongly and a
+reviewer reading the URL sees a bound that is not in force.
+
+What is asserted here
+---------------------
+That the parameter has an effect and that an out-of-range value is refused
+rather than absorbed. Both run through the shipped app against real
+PostgreSQL, because the thing under test is how FastAPI binds a query string
+to a signature — which a direct call of ``list_alerts(...)`` cannot exercise
+at all, since a direct caller passes the argument by name whether or not the
+route declares it.
+"""
+
+from __future__ import annotations
+
+import os
+import socket
+import uuid
+from urllib.parse import urlparse
+
+import pytest
+import pytest_asyncio
+from httpx import ASGITransport, AsyncClient
+from sqlalchemy import text
+from sqlalchemy.ext.asyncio import async_sessionmaker, create_async_engine
+
+_DSN = os.environ.get("DATABASE_MIGRATION_URL", "").strip() or os.environ.get("DATABASE_URL", "")
+_REQUIRED = os.environ.get("ALERT_AUDIT_PROOF_REQUIRED", "").strip() not in ("", "0", "false")
+
+#: More than the default page of 25, so "the default is still 25" and "limit
+#: took effect" are distinguishable rather than both reading as "all of them".
+SEEDED_ALERTS = 40
+
+
+def _postgres_is_listening() -> bool:
+ parsed = urlparse(_DSN.replace("postgresql+asyncpg://", "postgresql://"))
+ if not parsed.hostname:
+ return False
+ try:
+ with socket.create_connection((parsed.hostname, parsed.port or 5432), timeout=2):
+ return True
+ except OSError:
+ return False
+
+
+pytestmark = pytest.mark.skipif(
+ not ("postgres" in _DSN and _postgres_is_listening()) and not _REQUIRED,
+ reason="needs a live PostgreSQL with the migration chain applied",
+)
+
+_UNUSABLE_PASSWORD_HASH = "x" # noqa: S105 - not a credential; no plaintext maps to it
+
+
+@pytest_asyncio.fixture(autouse=True)
+async def _release_the_app_pool():
+ """See ``test_alert_patch_records_what_changed`` — the application pool is
+ module-level and each test gets a fresh event loop."""
+ yield
+ from app.db.database import engine
+
+ await engine.dispose()
+
+
+@pytest_asyncio.fixture
+async def queue():
+ """A scratch tenant holding ``SEEDED_ALERTS`` alerts. Yields ``(client_token, tenant_id)``."""
+ from app.core.security import create_access_token
+
+ engine = create_async_engine(_DSN)
+ maker = async_sessionmaker(engine, expire_on_commit=False)
+
+ tenant_id = uuid.uuid4()
+ user_id = uuid.uuid4()
+ suffix = tenant_id.hex[:8]
+
+ async with maker() as db:
+ await db.execute(
+ text("INSERT INTO tenants (id, name, slug) VALUES (:i, :n, :s)"),
+ {"i": tenant_id, "n": f"limit-{suffix}", "s": f"limit-{suffix}"},
+ )
+ await db.execute(
+ text(
+ """
+ INSERT INTO users (id, tenant_id, email, username, hashed_password,
+ role, is_active, is_verified)
+ VALUES (:i, :t, :e, :u, :h, 'admin', TRUE, TRUE)
+ """
+ ),
+ {
+ "i": user_id,
+ "t": tenant_id,
+ "e": f"analyst-{suffix}@example.com",
+ "u": f"analyst-{suffix}",
+ "h": _UNUSABLE_PASSWORD_HASH,
+ },
+ )
+ for n in range(SEEDED_ALERTS):
+ await db.execute(
+ text(
+ """
+ INSERT INTO alerts (id, tenant_id, title, severity, status, created_at, updated_at)
+ VALUES (:i, :t, :ti, 'medium', 'new', NOW() - (:n * INTERVAL '1 minute'), NOW())
+ """
+ ),
+ {"i": uuid.uuid4(), "t": tenant_id, "ti": f"alert {n:03d}", "n": n},
+ )
+ await db.commit()
+
+ yield create_access_token({"sub": str(user_id)}), tenant_id
+ await engine.dispose()
+
+
+async def _list(token: str, params: dict) -> tuple[int, dict]:
+ from app.main import app
+
+ transport = ASGITransport(app=app)
+ async with AsyncClient(transport=transport, base_url="http://testserver") as client:
+ response = await client.get(
+ "/api/v1/alerts",
+ params=params,
+ headers={"Authorization": f"Bearer {token}"},
+ )
+ return response.status_code, (response.json() if response.content else {})
+
+
+class TestTheParameterHasAnEffect:
+ async def test_a_limit_below_the_default_actually_shortens_the_page(self, queue) -> None:
+ """The reproduction in the direction that silently returns *more* than
+ asked for. Before the fix this returned 25 rows for ``limit=5``."""
+ token, _tenant = queue
+
+ code, body = await _list(token, {"limit": 5})
+
+ assert code == 200, body
+ assert len(body["items"]) == 5, f"asked for 5 and got {len(body['items'])} — the `limit` parameter is being discarded"
+ assert body["page_size"] == 5, f"the response reports a page size it did not use: {body['page_size']}"
+
+ async def test_a_limit_above_the_default_returns_more(self, queue) -> None:
+ token, _tenant = queue
+
+ code, body = await _list(token, {"limit": 40})
+
+ assert code == 200, body
+ assert len(body["items"]) == SEEDED_ALERTS
+ assert body["pages"] == 1
+
+ async def test_it_pages_with_the_page_parameter(self, queue) -> None:
+ """An alias that changes the page length and not the offset is half a
+ parameter — the second page has to move by the same amount."""
+ token, _tenant = queue
+
+ _code, first = await _list(token, {"limit": 10, "page": 1})
+ _code, second = await _list(token, {"limit": 10, "page": 2})
+
+ first_ids = [item["id"] for item in first["items"]]
+ second_ids = [item["id"] for item in second["items"]]
+ assert len(first_ids) == len(second_ids) == 10
+ assert not set(first_ids) & set(second_ids), "page 2 repeated rows from page 1"
+ assert first["pages"] == 4
+
+
+class TestAnOutOfRangeValueIsRefused:
+ async def test_the_thousand_row_request_in_the_report_is_rejected(self, queue) -> None:
+ """``?limit=1000`` used to return 25 rows and status 200.
+
+ Serving a quietly different page size is the failure being fixed, and
+ clamping silently to 200 would be the same failure with a nicer
+ number: the caller still cannot tell their bound was ignored.
+ """
+ token, _tenant = queue
+
+ code, body = await _list(token, {"limit": 1000})
+
+ assert code == 422, f"a limit above the 200 ceiling was accepted and answered {code}: {body}"
+
+ async def test_zero_and_negative_are_rejected_too(self, queue) -> None:
+ token, _tenant = queue
+
+ for value in (0, -1):
+ code, _body = await _list(token, {"limit": value})
+ assert code == 422, f"limit={value} was accepted"
+
+
+class TestTheExistingContractIsUnchanged:
+ async def test_the_default_page_is_still_twenty_five(self, queue) -> None:
+ token, _tenant = queue
+
+ code, body = await _list(token, {})
+
+ assert code == 200
+ assert len(body["items"]) == 25
+ assert body["page_size"] == 25
+ assert body["total"] == SEEDED_ALERTS
+
+ async def test_page_size_still_works_on_its_own(self, queue) -> None:
+ token, _tenant = queue
+
+ code, body = await _list(token, {"page_size": 7})
+
+ assert code == 200
+ assert len(body["items"]) == 7
+ assert body["page_size"] == 7
+
+ async def test_page_size_above_the_ceiling_is_still_rejected(self, queue) -> None:
+ token, _tenant = queue
+
+ code, _body = await _list(token, {"page_size": 1000})
+
+ assert code == 422
+
+
+class TestTwoSpellingsThatDisagreeAreRefused:
+ async def test_a_conflicting_pair_is_a_400_rather_than_a_silent_pick(self, queue) -> None:
+ """Choosing one of two contradictory bounds is the same class of bug as
+ ignoring one of them: the caller is served a page size they did not
+ ask for and are not told."""
+ token, _tenant = queue
+
+ code, body = await _list(token, {"limit": 5, "page_size": 50})
+
+ assert code == 400, f"a request naming two different page sizes was served {code}: {body}"
+ assert "limit" in str(body).lower()
+
+ async def test_an_agreeing_pair_is_fine(self, queue) -> None:
+ """Refusing a redundant-but-consistent request would break a client
+ that sends both for compatibility."""
+ token, _tenant = queue
+
+ code, body = await _list(token, {"limit": 5, "page_size": 5})
+
+ assert code == 200, body
+ assert len(body["items"]) == 5
diff --git a/services/api/tests/test_alert_patch_records_what_changed.py b/services/api/tests/test_alert_patch_records_what_changed.py
new file mode 100644
index 000000000..0bdbfc8bb
--- /dev/null
+++ b/services/api/tests/test_alert_patch_records_what_changed.py
@@ -0,0 +1,351 @@
+"""Closing an alert must record *what* changed, not only that something did.
+
+The defect (issue #1246)
+------------------------
+``PATCH /api/v1/alerts/{id}`` built an ``updates`` dict, wrote it, and emitted
+no audit event at all — a grep for ``emit_audit`` or ``AuditLog`` in
+``endpoints/alerts.py`` returned nothing. The only row a closure produced came
+from ``AuditMiddleware``, which constructs ``AuditLog(...)`` with no ``changes=``
+argument, so the nullable ``changes`` column landed NULL and the action was a
+label guessed from the URL.
+
+That middleware row is written under a comment saying it defers to "the
+handler's row ... it carries the real ``changes`` payload". For this route the
+handler row never existed, so an analyst marking a critical alert as a false
+positive produced an audit trail that recorded *someone updated an alert* and
+nothing an auditor could use: not the disposition, not the prior status, not
+the assignee it was taken from.
+
+Why these drive the real HTTP path
+----------------------------------
+The two halves of this fix pull against each other. The handler has to write a
+row, and the middleware has to then *not* write a second one — two writers on
+one request is what forked the chain in migration 074's history, and the
+signal that suppresses the second writer is a mutable dict in a ``ContextVar``
+plus ``request.state``, both of which only exist when a real request travels
+through ``BaseHTTPMiddleware``. Calling ``update_alert()`` directly would
+exercise the handler and silently skip the half that can regress.
+
+So these run the shipped ASGI app, with its real authentication dependencies,
+a real JWT, real ``AuditMiddleware``, and a real PostgreSQL carrying the whole
+migration chain — including ``uq_audit_log_chain_successor``, which is the
+constraint a duplicate writer would trip.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import socket
+import uuid
+from datetime import UTC, datetime
+from urllib.parse import urlparse
+
+import pytest
+import pytest_asyncio
+from httpx import ASGITransport, AsyncClient
+from sqlalchemy import text
+from sqlalchemy.ext.asyncio import async_sessionmaker, create_async_engine
+
+#: Owner DSN. The runtime role is DML-only and these tests create a scratch
+#: tenant; same resolution as ``test_audit_chain_under_concurrency``.
+_DSN = os.environ.get("DATABASE_MIGRATION_URL", "").strip() or os.environ.get("DATABASE_URL", "")
+
+#: Set by the job that is *meant* to run this. A gate that quietly declines to
+#: run is the shape this repository has been bitten by repeatedly, so where the
+#: database is supposed to be there, its absence is a failure and not a skip.
+_REQUIRED = os.environ.get("ALERT_AUDIT_PROOF_REQUIRED", "").strip() not in ("", "0", "false")
+
+
+def _postgres_is_listening() -> bool:
+ """Whether something actually answers on the DSN's host and port.
+
+ A DSN is a statement of intent. The unit-test job exports a
+ ``postgres://…localhost:5432`` URL with no server behind it, so a string
+ check alone decides the test should run and it dies on ``Connect call
+ failed``.
+ """
+ parsed = urlparse(_DSN.replace("postgresql+asyncpg://", "postgresql://"))
+ if not parsed.hostname:
+ return False
+ try:
+ with socket.create_connection((parsed.hostname, parsed.port or 5432), timeout=2):
+ return True
+ except OSError:
+ return False
+
+
+pytestmark = pytest.mark.skipif(
+ not ("postgres" in _DSN and _postgres_is_listening()) and not _REQUIRED,
+ reason=(
+ "needs a live PostgreSQL with the migration chain applied — the audit row, its "
+ "hash chain and the unique index that makes a duplicate writer visible have no "
+ "SQLite equivalent"
+ ),
+)
+
+# A password hash that no password produces. These tests authenticate with a
+# minted JWT, never with a password, and a realistic bcrypt literal in a
+# fixture is indistinguishable from a leaked credential to a secret scanner.
+_UNUSABLE_PASSWORD_HASH = "x" # noqa: S105 - not a credential; no plaintext maps to it
+
+
+@pytest_asyncio.fixture(autouse=True)
+async def _release_the_app_pool():
+ """Dispose the application's global pool between tests.
+
+ ``app.db.database.engine`` is a module-level pool, and pytest-asyncio gives
+ every test its own event loop. A connection checked out under the first
+ loop is unusable under the second, so without this the second test in the
+ file fails inside asyncpg rather than on its assertion — a failure that
+ reads like a defect in the code under test and is not one.
+ """
+ yield
+ from app.db.database import engine
+
+ await engine.dispose()
+
+
+@pytest_asyncio.fixture
+async def world():
+ """A scratch tenant with one analyst and one open alert, on the real schema.
+
+ Yields ``(maker, tenant_id, user_id, alert_id, token)``.
+
+ No teardown of ``audit_log``: it is append-only by database trigger, so a
+ test that could clean up after itself would be evidence the immutability
+ control was missing. The tenant is left for the same reason — deleting it
+ cascades into ``audit_log`` and the trigger correctly refuses.
+ """
+ from app.core.security import create_access_token
+
+ engine = create_async_engine(_DSN)
+ maker = async_sessionmaker(engine, expire_on_commit=False)
+
+ tenant_id = uuid.uuid4()
+ user_id = uuid.uuid4()
+ alert_id = uuid.uuid4()
+ suffix = tenant_id.hex[:8]
+
+ async with maker() as db:
+ await db.execute(
+ text("INSERT INTO tenants (id, name, slug) VALUES (:i, :n, :s)"),
+ {"i": tenant_id, "n": f"patch-audit-{suffix}", "s": f"patch-audit-{suffix}"},
+ )
+ await db.execute(
+ text(
+ """
+ INSERT INTO users (id, tenant_id, email, username, hashed_password,
+ role, is_active, is_verified)
+ VALUES (:i, :t, :e, :u, :h, 'admin', TRUE, TRUE)
+ """
+ ),
+ {
+ "i": user_id,
+ "t": tenant_id,
+ "e": f"analyst-{suffix}@example.com",
+ "u": f"analyst-{suffix}",
+ "h": _UNUSABLE_PASSWORD_HASH,
+ },
+ )
+ await db.execute(
+ text(
+ """
+ INSERT INTO alerts (id, tenant_id, title, severity, status, priority, created_at, updated_at)
+ VALUES (:i, :t, 'Suspicious sign-in from an unfamiliar ASN', 'critical', 'triaging', 40, NOW(), NOW())
+ """
+ ),
+ {"i": alert_id, "t": tenant_id},
+ )
+ await db.commit()
+
+ token = create_access_token({"sub": str(user_id)})
+ yield maker, tenant_id, user_id, alert_id, token
+ await engine.dispose()
+
+
+async def _audit_rows(maker, tenant_id: uuid.UUID) -> list[dict]:
+ async with maker() as db:
+ rows = (
+ (
+ await db.execute(
+ text(
+ """
+ SELECT action, resource, resource_id, actor_id, actor_email,
+ changes, prev_hash, entry_hash, chain_index
+ FROM audit_log WHERE tenant_id = :t
+ ORDER BY chain_index ASC NULLS LAST, created_at ASC
+ """
+ ),
+ {"t": tenant_id},
+ )
+ )
+ .mappings()
+ .all()
+ )
+ out = []
+ for row in rows:
+ record = dict(row)
+ # asyncpg hands JSONB back as a string unless a codec is registered;
+ # SQLAlchemy registers one for mapped columns but not for `text()`.
+ if isinstance(record["changes"], str):
+ record["changes"] = json.loads(record["changes"])
+ out.append(record)
+ return out
+
+
+async def _patch(token: str, alert_id: uuid.UUID, body: dict) -> tuple[int, dict]:
+ """Send the PATCH through the shipped app, middleware and auth included."""
+ from app.main import app
+
+ transport = ASGITransport(app=app)
+ async with AsyncClient(transport=transport, base_url="http://testserver") as client:
+ response = await client.patch(
+ f"/api/v1/alerts/{alert_id}",
+ json=body,
+ headers={"Authorization": f"Bearer {token}", "user-agent": "issue-1246-proof"},
+ )
+ return response.status_code, (response.json() if response.content else {})
+
+
+class TestTheClosureIsRecordedWithItsPayload:
+ async def test_marking_a_false_positive_records_the_before_and_after(self, world) -> None:
+ """The reproduction. Before the fix the only row carried ``changes`` NULL."""
+ maker, tenant_id, _user_id, alert_id, token = world
+
+ code, _ = await _patch(token, alert_id, {"status": "false_positive"})
+ assert code == 200, f"the PATCH itself failed: {code}"
+
+ rows = await _audit_rows(maker, tenant_id)
+ assert rows, "closing an alert produced no audit row at all"
+
+ carrying = [r for r in rows if r["changes"]]
+ assert carrying, (
+ "an alert was closed as a false positive and every audit row for the tenant has "
+ f"`changes` NULL — the trail records that something changed, never what. Rows: "
+ f"{[(r['action'], r['changes']) for r in rows]}"
+ )
+
+ changes = carrying[0]["changes"]
+ assert changes.get("status") == {"from": "triaging", "to": "false_positive"}, (
+ f"the status transition is not recoverable from the audit row: {changes}"
+ )
+ assert carrying[0]["resource_id"] == str(alert_id)
+
+ async def test_every_modified_field_appears_and_untouched_ones_do_not(self, world) -> None:
+ """A payload that lists fields the request did not touch is noise an
+ auditor has to discount; one that omits a field it did touch is the
+ defect wearing a smaller hat."""
+ maker, tenant_id, user_id, alert_id, token = world
+
+ code, _ = await _patch(
+ token,
+ alert_id,
+ {"status": "resolved", "priority": 10, "assignee": str(user_id)},
+ )
+ assert code == 200
+
+ rows = await _audit_rows(maker, tenant_id)
+ carrying = [r for r in rows if r["changes"]]
+ assert carrying, "no audit row carried a changes payload"
+ changes = carrying[0]["changes"]
+
+ assert changes.get("status") == {"from": "triaging", "to": "resolved"}
+ assert changes.get("priority") == {"from": 40, "to": 10}
+ assert changes.get("assigned_to_id") == {"from": None, "to": str(user_id)}
+ assert "tags" not in changes, f"tags was not in the request body but was recorded: {changes}"
+ assert "case_id" not in changes, f"case_id was not in the request body but was recorded: {changes}"
+
+ async def test_the_actor_is_the_authenticated_analyst(self, world) -> None:
+ """ "Who" is half of an audit record and is not recoverable from the row
+ the middleware would have written for a request that failed to carry a
+ handler row."""
+ maker, tenant_id, user_id, alert_id, token = world
+
+ code, _ = await _patch(token, alert_id, {"status": "closed"})
+ assert code == 200
+
+ carrying = [r for r in await _audit_rows(maker, tenant_id) if r["changes"]]
+ assert carrying
+ assert carrying[0]["actor_id"] == user_id
+ assert carrying[0]["actor_email"] is not None
+
+
+class TestExactlyOneWriterPerRequest:
+ """The half that would regress quietly.
+
+ Emitting from the handler without the middleware standing down puts two
+ writers back in one request, which is what forked the chain before
+ migration 074. The unique index refuses the second row, so the visible
+ symptom is not a fork but a *dropped* audit row — undetectable.
+ """
+
+ async def test_one_patch_writes_one_row(self, world) -> None:
+ maker, tenant_id, _user_id, alert_id, token = world
+
+ code, _ = await _patch(token, alert_id, {"status": "false_positive"})
+ assert code == 200
+
+ rows = await _audit_rows(maker, tenant_id)
+ assert len(rows) == 1, f"one request produced {len(rows)} audit rows: {[r['action'] for r in rows]}"
+
+ async def test_the_chain_stays_dense_across_several_patches(self, world) -> None:
+ """A gap in ``chain_index``, a repeated predecessor or a second genesis
+ row all mean the handler's writer is not participating in the chain the
+ verifier replays."""
+ maker, tenant_id, _user_id, alert_id, token = world
+
+ for new_status in ("triaging", "in_progress", "resolved"):
+ code, _ = await _patch(token, alert_id, {"status": new_status})
+ assert code == 200
+
+ rows = await _audit_rows(maker, tenant_id)
+ assert [r["chain_index"] for r in rows] == list(range(len(rows)))
+ assert sum(1 for r in rows if r["prev_hash"] is None) == 1, "a second genesis row is a forged restart"
+ assert all(r["entry_hash"] for r in rows), "an unchained row is outside the tamper-evidence claim"
+
+
+class TestAWriteThatChangesNothingIsNotAnAlertUpdate:
+ async def test_an_empty_body_does_not_fabricate_a_change_payload(self, world) -> None:
+ """The handler short-circuits when ``updates`` is empty and writes
+ nothing to the alert. Recording a modification there would put a
+ change in the trail that never happened — and the middleware's own
+ row is the honest record of "a request arrived and did nothing"."""
+ maker, tenant_id, _user_id, alert_id, token = world
+
+ code, _ = await _patch(token, alert_id, {})
+ assert code == 200
+
+ rows = await _audit_rows(maker, tenant_id)
+ assert not [r for r in rows if r["changes"]], f"a no-op PATCH recorded a change payload: {[r['changes'] for r in rows]}"
+
+
+class TestTheRowIsReadableThroughTheAuditApi:
+ async def test_the_changes_payload_survives_to_the_reader(self, world) -> None:
+ """A column nobody can read is not a trail. ``GET /api/v1/audit`` is
+ the surface an auditor actually uses, so the payload is asserted
+ through it rather than only in the table."""
+ _maker, _tenant_id, _user_id, alert_id, token = world
+
+ code, _ = await _patch(token, alert_id, {"status": "false_positive"})
+ assert code == 200
+
+ from app.main import app
+
+ transport = ASGITransport(app=app)
+ async with AsyncClient(transport=transport, base_url="http://testserver") as client:
+ response = await client.get(
+ "/api/v1/audit",
+ params={"resource_id": str(alert_id)},
+ headers={"Authorization": f"Bearer {token}"},
+ )
+ assert response.status_code == 200, response.text
+ entries = response.json().get("items", response.json())
+ payloads = [e.get("changes") for e in entries if e.get("changes")]
+ assert payloads, f"the audit reader returned no changes payload for this alert: {entries}"
+ assert payloads[0].get("status", {}).get("to") == "false_positive"
+
+
+def test_the_fixture_clock_is_sane() -> None:
+ """Guards against a fixture that silently seeds nothing."""
+ assert datetime.now(UTC).year >= 2024
diff --git a/services/api/tests/test_alerts_tenant_isolation.py b/services/api/tests/test_alerts_tenant_isolation.py
index b640d9982..de4c2db19 100644
--- a/services/api/tests/test_alerts_tenant_isolation.py
+++ b/services/api/tests/test_alerts_tenant_isolation.py
@@ -57,13 +57,37 @@ from app.api.v1.endpoints.alerts import (
claim_alert_endpoint as claim_alert_route,
)
from app.models.alert import Alert
-from fastapi import HTTPException
+from fastapi import HTTPException, Request
# ────────────────────────────────────────────────────────────────────────────
# Fixtures / helpers
# ────────────────────────────────────────────────────────────────────────────
+def _http_request(query_string: bytes = b"") -> Request:
+ """The ASGI request the routing layer would have built.
+
+ ``list_alerts`` and ``update_alert`` take one: the first reads
+ ``query_params`` to tell an explicit ``page_size`` from the default, the
+ second hands it to ``emit_audit`` for source-IP attribution and for the
+ mark that stops ``AuditMiddleware`` writing a second row.
+ """
+ return Request(
+ {
+ "type": "http",
+ "method": "PATCH",
+ "path": "/api/v1/alerts",
+ "root_path": "",
+ "scheme": "http",
+ "query_string": query_string,
+ "headers": [],
+ "client": ("127.0.0.1", 50000),
+ "server": ("testserver", 80),
+ "state": {},
+ }
+ )
+
+
def _user(tenant_id: uuid.UUID | None = None) -> CurrentUser:
"""Construct a CurrentUser without touching the DB or JWT plumbing."""
return CurrentUser(
@@ -263,6 +287,7 @@ def _assert_tenant_scoped(executed: list[tuple[str, dict[str, Any]]], tenant_id:
_LIST_ALERTS_DEFAULTS: dict[str, Any] = {
"page": 1,
"page_size": 25,
+ "limit": None,
"severity": None,
"status": None,
"category": None,
@@ -279,7 +304,7 @@ async def test_list_alerts_scopes_by_tenant() -> None:
user = _user()
# ``list_alerts`` runs two queries: count (scalar_one int) + select.
db = _mk_db([3, [_alert(user.tenant_id), _alert(user.tenant_id), _alert(user.tenant_id)]])
- response = await list_alerts(current_user=user, db=db, **_LIST_ALERTS_DEFAULTS)
+ response = await list_alerts(current_user=user, db=db, http_request=_http_request(), **_LIST_ALERTS_DEFAULTS)
assert response.total == 3
assert len(response.items) == 3
_assert_tenant_scoped(db.executed, user.tenant_id)
@@ -299,7 +324,7 @@ async def test_list_alerts_with_filters_keeps_tenant_scope() -> None:
"min_confidence": 70,
"confidence_label": "high",
}
- await list_alerts(current_user=user, db=db, **kwargs)
+ await list_alerts(current_user=user, db=db, http_request=_http_request(), **kwargs)
_assert_tenant_scoped(db.executed, user.tenant_id)
# Every alerts statement should mention tenant_id (count + select).
alerts_stmts = [(sql, params) for sql, params in db.executed if "alerts" in re.sub(r"\s+", " ", sql).lower()]
@@ -316,7 +341,7 @@ async def test_list_alerts_rejects_invalid_confidence_label() -> None:
db = _mk_db([])
kwargs = {**_LIST_ALERTS_DEFAULTS, "confidence_label": "urgent"}
with pytest.raises(HTTPException) as exc:
- await list_alerts(current_user=user, db=db, **kwargs)
+ await list_alerts(current_user=user, db=db, http_request=_http_request(), **kwargs)
assert exc.value.status_code == 400
@@ -421,6 +446,7 @@ async def test_update_alert_cross_tenant_returns_404() -> None:
request=AlertUpdateRequest(status="closed"),
current_user=tenant_a,
db=db,
+ http_request=_http_request(),
)
assert exc.value.status_code == 404
# Critical: no UPDATE statement should have run.
@@ -439,6 +465,7 @@ async def test_update_alert_same_tenant_scopes_select() -> None:
request=AlertUpdateRequest(status="resolved", tags=["triaged"]),
current_user=user,
db=db,
+ http_request=_http_request(),
)
assert resp.id == alert.id
# The SELECT must be tenant-scoped. The UPDATE-by-id WHERE clause
diff --git a/services/api/tests/test_bootstrap_admin.py b/services/api/tests/test_bootstrap_admin.py
index 1d7deb3a6..2863d4cd4 100644
--- a/services/api/tests/test_bootstrap_admin.py
+++ b/services/api/tests/test_bootstrap_admin.py
@@ -30,11 +30,12 @@ import pytest
import pytest_asyncio
from app.core.security import verify_password
from app.db.database import Base
+from app.models.audit import AuditLog
from app.models.tenant import Tenant, User
from app.scripts import bootstrap_admin as ba
from pydantic import BaseModel, EmailStr, ValidationError
from sqlalchemy import select
-from sqlalchemy.dialects.postgresql import JSONB
+from sqlalchemy.dialects.postgresql import INET, JSONB
from sqlalchemy.dialects.postgresql import UUID as PgUUID
from sqlalchemy.ext.asyncio import async_sessionmaker, create_async_engine
from sqlalchemy.ext.compiler import compiles
@@ -56,6 +57,11 @@ def _uuid_sqlite(_type_, _compiler_, **_kw_):
return "CHAR(36)"
+@compiles(INET, "sqlite")
+def _inet_sqlite(_type_, _compiler_, **_kw_):
+ return "TEXT"
+
+
class _LoginRequest(BaseModel):
"""The shape `POST /api/v1/auth/login` validates against."""
@@ -72,9 +78,21 @@ async def session_factory(monkeypatch):
"""
engine = create_async_engine("sqlite+aiosqlite:///:memory:")
async with engine.begin() as conn:
- # Only the two tables this touches. A whole-metadata create_all drags
+ # Only the tables this touches. A whole-metadata create_all drags
# in models using Postgres ARRAY, which SQLite cannot render.
- await conn.run_sync(Base.metadata.create_all, tables=[Tenant.__table__, User.__table__])
+ #
+ # `audit_log` joined the list when the script started recording the
+ # administrator it mints (issue #1246). The *chain* still cannot run
+ # here — `audit_chain_head` is raw SQL with no ORM table and
+ # `_ADVANCE_HEAD` calls `NOW()`, which SQLite has no equivalent for —
+ # so `emit_audit` takes its documented fallback, logs at ERROR and
+ # writes the row unchained. That is why the chained behaviour is
+ # asserted in `test_bootstrap_admin_is_audited.py` against the real
+ # migration chain, and only the account outcomes are asserted here.
+ await conn.run_sync(
+ Base.metadata.create_all,
+ tables=[Tenant.__table__, User.__table__, AuditLog.__table__],
+ )
factory = async_sessionmaker(engine, expire_on_commit=False)
monkeypatch.setattr(ba, "AsyncSessionLocal", factory)
yield factory
diff --git a/services/api/tests/test_bootstrap_admin_is_audited.py b/services/api/tests/test_bootstrap_admin_is_audited.py
new file mode 100644
index 000000000..b00d12286
--- /dev/null
+++ b/services/api/tests/test_bootstrap_admin_is_audited.py
@@ -0,0 +1,387 @@
+"""Minting the first administrator must leave a trace.
+
+The defect (issue #1246)
+------------------------
+``app/scripts/bootstrap_admin.py`` contained no occurrence of the word "audit"
+in 352 lines. ``AuditMiddleware`` is HTTP middleware, so a CLI run bypasses it
+entirely, and every other privileged identity operation in this service —
+``admin.users.role_added``, ``admin.users.disabled``, ``api_keys:create`` —
+emits through ``emit_audit``. The single most privileged act a deployment ever
+performs, creating the account that holds ``*`` over the tenant, was the one
+with no record at all, and ``--reset-password`` on that account was equally
+silent.
+
+Why a live database rather than the SQLite the sibling file uses
+-----------------------------------------------------------------
+``tests/test_bootstrap_admin.py`` builds its schema from ``Base.metadata``,
+which has no ``audit_chain_head`` table and none of the chain's triggers.
+``emit_audit`` is deliberately forgiving there: it catches a failed chain
+computation, writes the row *unchained*, and increments a counter. A SQLite
+run would therefore pass while proving only that a row was inserted — the
+hash link, the dense ``chain_index`` and the unique successor index would all
+be untested, and those are the properties that make the row evidence rather
+than a log line. So this runs the real migration chain.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import os
+import pathlib
+import socket
+import subprocess
+import sys
+import uuid
+from collections.abc import Iterator
+from urllib.parse import urlparse, urlunparse
+
+import asyncpg
+import pytest
+import pytest_asyncio
+from sqlalchemy import text
+from sqlalchemy.ext.asyncio import async_sessionmaker, create_async_engine
+
+SERVICE_ROOT = pathlib.Path(__file__).resolve().parents[1]
+
+_DSN = os.environ.get("DATABASE_MIGRATION_URL", "").strip() or os.environ.get("DATABASE_URL", "")
+_REQUIRED = os.environ.get("ALERT_AUDIT_PROOF_REQUIRED", "").strip() not in ("", "0", "false")
+
+
+def _postgres_is_listening() -> bool:
+ parsed = urlparse(_DSN.replace("postgresql+asyncpg://", "postgresql://"))
+ if not parsed.hostname:
+ return False
+ try:
+ with socket.create_connection((parsed.hostname, parsed.port or 5432), timeout=2):
+ return True
+ except OSError:
+ return False
+
+
+pytestmark = pytest.mark.skipif(
+ not ("postgres" in _DSN and _postgres_is_listening()) and not _REQUIRED,
+ reason=(
+ "needs a live PostgreSQL with the migration chain applied — on a schema built "
+ "from Base.metadata the audit chain degrades to an unchained row and the test "
+ "would pass without proving anything"
+ ),
+)
+
+#: A password that satisfies the script's own length rules and is obviously a
+#: fixture rather than anything anyone would deploy.
+FIXTURE_PASSWORD = "bootstrap-audit-fixture-pw"
+
+
+def _with_database(dsn: str, database: str) -> str:
+ parsed = urlparse(dsn)
+ return urlunparse(parsed._replace(path=f"/{database}"))
+
+
+async def _run_sql_outside_a_transaction(dsn: str, statement: str) -> None:
+ """CREATE/DROP DATABASE cannot run inside a transaction block."""
+ conn = await asyncpg.connect(_with_database(dsn, "postgres").replace("postgresql+asyncpg://", "postgresql://"))
+ try:
+ await conn.execute(statement)
+ finally:
+ await conn.close()
+
+
[email protected](scope="module")
+def scratch_database() -> Iterator[str]:
+ """A database of this module's own, carrying the full migration chain.
+
+ Not a shared one, because ``bootstrap()`` refuses to mint a second
+ administrator when an *active admin exists anywhere* — not in the tenant,
+ anywhere — which is the right behaviour for the command and makes its
+ precondition "a deployment with no administrator yet". A test database
+ other suites have written to cannot offer that, and the resulting failure
+ would depend on execution order rather than on the code under test.
+
+ Synchronous on purpose: pytest-asyncio gives every test its own event
+ loop, so a module-scoped async fixture would hand connections across
+ loops. ``asyncio.run`` here opens and closes its own.
+ """
+ name = f"aisoc_bootstrap_audit_{uuid.uuid4().hex[:12]}"
+ try:
+ asyncio.run(_run_sql_outside_a_transaction(_DSN, f'CREATE DATABASE "{name}"'))
+ except Exception as exc: # noqa: BLE001 - reported, not swallowed
+ if _REQUIRED:
+ pytest.fail(f"ALERT_AUDIT_PROOF_REQUIRED is set but a scratch database could not be created: {type(exc).__name__}: {exc}")
+ pytest.skip(f"cannot CREATE DATABASE on this server ({type(exc).__name__}) — runs in alert-audit-live.yml")
+
+ dsn = _with_database(_DSN, name)
+ migrate = subprocess.run( # noqa: S603 - fixed argv, no shell
+ [sys.executable, "-m", "app.scripts.run_migrations"],
+ cwd=SERVICE_ROOT,
+ env={**os.environ, "DATABASE_URL": dsn, "DATABASE_MIGRATION_URL": dsn},
+ capture_output=True,
+ text=True,
+ timeout=300,
+ check=False,
+ )
+ if migrate.returncode != 0:
+ asyncio.run(_run_sql_outside_a_transaction(_DSN, f'DROP DATABASE IF EXISTS "{name}"'))
+ pytest.fail(f"the migration chain did not apply to the scratch database:\n{migrate.stdout}\n{migrate.stderr}")
+
+ yield dsn
+ asyncio.run(_run_sql_outside_a_transaction(_DSN, f'DROP DATABASE IF EXISTS "{name}" WITH (FORCE)'))
+
+
+@pytest_asyncio.fixture
+async def bootstrap_env(monkeypatch, scratch_database):
+ """Point ``bootstrap_admin`` at a tenant of its own on the real schema.
+
+ Yields ``(maker, tenant_id, email)``. Users are cleared first so each test
+ sees the no-administrator precondition the command is written for; the
+ audit rows are left, because ``audit_log`` is append-only by database
+ trigger and every assertion below is scoped to this test's tenant anyway.
+ """
+ from app.scripts import bootstrap_admin as ba
+
+ engine = create_async_engine(scratch_database)
+ maker = async_sessionmaker(engine, expire_on_commit=False)
+
+ tenant_id = uuid.uuid4()
+ suffix = tenant_id.hex[:8]
+ async with maker() as db:
+ await db.execute(text("DELETE FROM users"))
+ await db.execute(
+ text("INSERT INTO tenants (id, name, slug) VALUES (:i, :n, :s)"),
+ {"i": tenant_id, "n": f"bootstrap-{suffix}", "s": f"bootstrap-{suffix}"},
+ )
+ await db.commit()
+
+ monkeypatch.setattr(ba, "AsyncSessionLocal", maker)
+ monkeypatch.setattr(ba, "DEFAULT_TENANT_ID", tenant_id)
+
+ yield maker, tenant_id, f"admin-{suffix}@example.com"
+ await engine.dispose()
+
+
+async def _audit_rows(maker, tenant_id: uuid.UUID) -> list[dict]:
+ async with maker() as db:
+ rows = (
+ (
+ await db.execute(
+ text(
+ """
+ SELECT action, resource, resource_id, actor_id, actor_email,
+ changes, metadata, prev_hash, entry_hash, chain_index
+ FROM audit_log WHERE tenant_id = :t
+ ORDER BY chain_index ASC NULLS LAST, created_at ASC
+ """
+ ),
+ {"t": tenant_id},
+ )
+ )
+ .mappings()
+ .all()
+ )
+ out = []
+ for row in rows:
+ record = dict(row)
+ for column in ("changes", "metadata"):
+ if isinstance(record[column], str):
+ record[column] = json.loads(record[column])
+ out.append(record)
+ return out
+
+
+class TestTheFirstAdministratorIsRecorded:
+ async def test_creating_one_writes_an_audit_row(self, bootstrap_env) -> None:
+ """The reproduction. Before the fix this table stayed empty."""
+ from app.scripts import bootstrap_admin as ba
+
+ maker, tenant_id, email = bootstrap_env
+
+ created_email, is_new = await ba.bootstrap(
+ email=email,
+ password=FIXTURE_PASSWORD,
+ username="admin",
+ reset_password=False,
+ )
+ assert (created_email, is_new) == (email, True)
+
+ rows = await _audit_rows(maker, tenant_id)
+ assert rows, (
+ "the first administrator — the account holding '*' over this tenant — was "
+ "created with no audit row at all. AuditMiddleware is HTTP middleware, so "
+ "nothing covers a CLI run."
+ )
+
+ async def test_the_row_names_the_account_it_created(self, bootstrap_env) -> None:
+ """A row saying only "a bootstrap happened" is the same gap one level
+ in: which address, under which name, with which role."""
+ from app.scripts import bootstrap_admin as ba
+
+ maker, tenant_id, email = bootstrap_env
+
+ await ba.bootstrap(email=email, password=FIXTURE_PASSWORD, username="first-admin", reset_password=False)
+
+ async with maker() as db:
+ user_id = (await db.execute(text("SELECT id FROM users WHERE email = :e"), {"e": email})).scalar_one()
+
+ rows = await _audit_rows(maker, tenant_id)
+ assert len(rows) == 1, f"expected exactly one row, got {[r['action'] for r in rows]}"
+ row = rows[0]
+
+ assert row["resource"] == "user"
+ assert row["resource_id"] == str(user_id)
+ assert row["changes"], "the row carries no changes payload"
+ assert row["changes"].get("email") == email
+ assert row["changes"].get("username") == "first-admin"
+ assert row["changes"].get("role") == "admin"
+
+ async def test_the_actor_is_recorded_as_unknown_rather_than_invented(self, bootstrap_env) -> None:
+ """A shell command has no platform principal, and naming one would be
+ a lie an investigator acts on.
+
+ Writing the new administrator's own address into ``actor_id`` /
+ ``actor_email`` would read as "this person signed in and created
+ themselves", which did not happen and is the opposite of useful on the
+ one account that holds ``*``. The honest record is no actor plus the
+ provenance that tells the reader where to look instead — the host's
+ shell history, not this table. ``autonomy_grants`` already writes an
+ actorless row for the same reason.
+ """
+ from app.scripts import bootstrap_admin as ba
+
+ maker, tenant_id, email = bootstrap_env
+
+ await ba.bootstrap(email=email, password=FIXTURE_PASSWORD, username="admin", reset_password=False)
+
+ row = (await _audit_rows(maker, tenant_id))[0]
+ assert row["actor_id"] is None
+ assert row["actor_email"] is None
+ assert row["changes"].get("invoked_via") == "bootstrap_admin CLI", f"the row does not say where it came from: {row['changes']}"
+
+ async def test_the_row_is_chain_linked(self, bootstrap_env) -> None:
+ """An unchained row is outside the tamper-evidence claim the audit log
+ makes, and ``emit_audit`` writes one rather than failing the caller —
+ so "a row exists" and "the chain covers it" are separate assertions."""
+ from app.scripts import bootstrap_admin as ba
+
+ maker, tenant_id, email = bootstrap_env
+
+ await ba.bootstrap(email=email, password=FIXTURE_PASSWORD, username="admin", reset_password=False)
+
+ row = (await _audit_rows(maker, tenant_id))[0]
+ assert row["entry_hash"], "the row was written unchained"
+ assert row["chain_index"] == 0
+ assert row["prev_hash"] is None, "the first row of a new tenant's chain has no predecessor"
+
+ async with maker() as db:
+ head = (
+ (
+ await db.execute(
+ text("SELECT head_hash, next_index FROM audit_chain_head WHERE tenant_id = :t"),
+ {"t": tenant_id},
+ )
+ )
+ .mappings()
+ .one()
+ )
+ assert head["head_hash"] == row["entry_hash"]
+ assert int(head["next_index"]) == 1
+
+ async def test_the_password_is_nowhere_in_the_row(self, bootstrap_env) -> None:
+ """``audit_log`` is immutable by database trigger and readable by every
+ tenant administrator. A secret written there cannot be taken back."""
+ from app.scripts import bootstrap_admin as ba
+
+ maker, tenant_id, email = bootstrap_env
+
+ await ba.bootstrap(email=email, password=FIXTURE_PASSWORD, username="admin", reset_password=False)
+
+ serialised = json.dumps(await _audit_rows(maker, tenant_id), default=str)
+ assert FIXTURE_PASSWORD not in serialised
+ assert "$2b$" not in serialised, "the bcrypt hash of the password reached the audit log"
+
+
+class TestAResetIsRecordedToo:
+ async def test_replacing_the_credential_writes_its_own_row(self, bootstrap_env) -> None:
+ """Taking over the administrator account is at least as interesting to
+ an investigator as creating it."""
+ from app.scripts import bootstrap_admin as ba
+
+ maker, tenant_id, email = bootstrap_env
+
+ await ba.bootstrap(email=email, password=FIXTURE_PASSWORD, username="admin", reset_password=False)
+ await ba.bootstrap(
+ email=email,
+ password=FIXTURE_PASSWORD + "-rotated",
+ username="admin",
+ reset_password=True,
+ )
+
+ rows = await _audit_rows(maker, tenant_id)
+ assert len(rows) == 2, f"the reset left no row of its own: {[r['action'] for r in rows]}"
+ assert rows[0]["action"] != rows[1]["action"], (
+ "creating an administrator and resetting its password are different events and "
+ f"must not share an action label: {rows[0]['action']}"
+ )
+ assert rows[1]["chain_index"] == 1
+ assert rows[1]["prev_hash"] == rows[0]["entry_hash"]
+
+
+class TestARunThatChangesNothingRecordsNothing:
+ """The other direction, and the one that keeps the trail readable.
+
+ ``make bootstrap`` is documented as safe to re-run. Auditing every
+ invocation would pad the log with rows for an operation that did not
+ happen, which is the same failure as the missing row wearing the opposite
+ sign: an auditor cannot tell the events apart from the noise.
+ """
+
+ async def test_a_second_run_adds_no_row(self, bootstrap_env) -> None:
+ from app.scripts import bootstrap_admin as ba
+
+ maker, tenant_id, email = bootstrap_env
+
+ await ba.bootstrap(email=email, password=FIXTURE_PASSWORD, username="admin", reset_password=False)
+ before = len(await _audit_rows(maker, tenant_id))
+
+ _email, is_new = await ba.bootstrap(
+ email=email,
+ password=FIXTURE_PASSWORD,
+ username="admin",
+ reset_password=False,
+ )
+ assert is_new is False, "the fixture is wrong: the second run created something"
+
+ after = len(await _audit_rows(maker, tenant_id))
+ assert after == before, f"a no-op re-run appended {after - before} audit row(s)"
+
+
+class TestTheAccountStillGetsCreated:
+ """A control.
+
+ The audit write shares the script's transaction, so a mistake in it does
+ not merely lose the row — it loses the administrator, on the one command a
+ new deployment cannot do without.
+ """
+
+ async def test_the_user_row_lands_with_the_audit_row(self, bootstrap_env) -> None:
+ from app.core.security import verify_password
+ from app.scripts import bootstrap_admin as ba
+
+ maker, tenant_id, email = bootstrap_env
+
+ await ba.bootstrap(email=email, password=FIXTURE_PASSWORD, username="admin", reset_password=False)
+
+ async with maker() as db:
+ row = (
+ (
+ await db.execute(
+ text("SELECT tenant_id, role, is_active, hashed_password FROM users WHERE email = :e"),
+ {"e": email},
+ )
+ )
+ .mappings()
+ .one()
+ )
+ assert row["tenant_id"] == tenant_id
+ assert row["role"] == "admin"
+ assert row["is_active"] is True
+ assert verify_password(FIXTURE_PASSWORD, row["hashed_password"])