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(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.ymlnew file mode 100644index 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.yamlindex 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_getsecurity:- HTTPBearer: []@@ -629,6 +634,20 @@ paths:minimum: 1default: 25title: 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: severityin: queryrequired: false@@ -833,7 +852,12 @@ paths:tags:- alertssummary: 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__patchsecurity:- HTTPBearer: []diff --git a/services/api/app/api/v1/endpoints/alerts.py b/services/api/app/api/v1/endpoints/alerts.pyindex 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'tmatch either filter — that's intentional; analysts who care aboutconfidence 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.pyindex 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_IDfrom app.core.security import get_password_hashfrom app.db.database import AsyncSessionLocalfrom 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 = 24MIN_PASSWORD_LENGTH = 12MAX_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_activeuser.hashed_password = get_password_hash(password)user.is_active = Trueuser.is_verified = Trueuser.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, Truediff --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.pynew file mode 100644index 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"]) == 5diff --git a/services/api/tests/test_alert_patch_records_what_changed.py b/services/api/tests/test_alert_patch_records_what_changed.pynew file mode 100644index 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 >= 2024diff --git a/services/api/tests/test_alerts_tenant_isolation.py b/services/api/tests/test_alerts_tenant_isolation.pyindex 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 == 3assert 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 clausediff --git a/services/api/tests/test_bootstrap_admin.py b/services/api/tests/test_bootstrap_admin.pyindex 1d7deb3a6..2863d4cd4 100644--- a/services/api/tests/test_bootstrap_admin.py+++ b/services/api/tests/test_bootstrap_admin.py@@ -30,11 +30,12 @@ import pytestimport pytest_asynciofrom app.core.security import verify_passwordfrom app.db.database import Base+from app.models.audit import AuditLogfrom app.models.tenant import Tenant, Userfrom app.scripts import bootstrap_admin as bafrom pydantic import BaseModel, EmailStr, ValidationErrorfrom sqlalchemy import select-from sqlalchemy.dialects.postgresql import JSONB+from sqlalchemy.dialects.postgresql import INET, JSONBfrom sqlalchemy.dialects.postgresql import UUID as PgUUIDfrom sqlalchemy.ext.asyncio import async_sessionmaker, create_async_enginefrom 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 factorydiff --git a/services/api/tests/test_bootstrap_admin_is_audited.py b/services/api/tests/test_bootstrap_admin_is_audited.pynew file mode 100644index 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"])