From 8f0b3c4fa678143bde4acb9bc8dbb7f159b7557e Mon Sep 17 00:00:00 2001 From: Manish Kumar Date: Fri, 7 Aug 2026 21:52:06 -0500 Subject: [PATCH] docs: document the DB sink + query API that already ship, add endpoints - Architecture diagram's "Future Sink Layer (DB / S3 / OpenSearch)" undersold reality: worker/main.py + consumers/sink.py already write into a MySQL-backed store (db/models.py, Alembic-migrated, AUDIT_DATABASE_URL), and GET /audit/events already queries it, platform-admin-gated. Updated the diagram and the Roadmap's "OpenSearch / PostgreSQL sink | Planned" line, which read as if no sink existed at all -- it's specifically additional backends beyond the MySQL one that are still open. - New "API Endpoints" section: /health, /audit/test (no auth today), and /audit/events (platform_admin-gated, with its real query params) -- the "Running" section only showed a health-check curl example before, despite the Authentication section already referencing "audit query/search endpoints" that were never documented anywhere. - Added the three DB/consumer env vars (AUDIT_DATABASE_URL, AUDIT_CONSUMER_GROUP, AUDIT_CONSUMER_NAME) that back the sink layer, missing from the Environment Variables table. Co-Authored-By: Claude Sonnet 5 --- README.md | 32 +++++++++++++++++++++++++++++--- 1 file changed, 29 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index b80ded4..4ca08aa 100644 --- a/README.md +++ b/README.md @@ -36,10 +36,20 @@ Services (Auth / IAM / Policy / TES) │ ┌───────┴────────┐ ▼ ▼ -Stream Consumers Future Sink Layer -(processors) (DB / S3 / OpenSearch) +Stream Consumers Sink Layer (implemented today) +(processors) worker/main.py + consumers/sink.py write into a + MySQL-backed store (db/models.py, Alembic-migrated) + │ + ▼ + GET /audit/events — platform-admin-gated query API + (see "API Endpoints" below) ``` +A DB sink and a queryable read API already exist — "Future Sink Layer" +in earlier revisions of this diagram undersold what's shipped; the +Roadmap's remaining "OpenSearch / additional sink backends" item is +about backends *beyond* MySQL, not the first one. + --- ## Authentication @@ -178,6 +188,18 @@ curl http://localhost:8004/health # {"status": "ok"} ``` +### API Endpoints + +| Endpoint | Method | Auth | Description | +|----------|--------|------|-------------| +| `/health` | GET | — | Health check | +| `/audit/test` | GET | none today | Write-side ingestion smoke test | +| `/audit/events` | GET | `platform_admin` role | Query audit events — `page`/`page_size`, plus optional `user_id`/`service`/`event_type`/`decision`/`from_timestamp`/`to_timestamp` filters | + +`/audit/events` is deliberately a separate router from `/audit/test` — +the former is the platform-admin-gated read API (see "Platform admin +authentication" above), the latter has no auth at all today. + ### Environment variables | Variable | Default | Description | @@ -186,6 +208,9 @@ curl http://localhost:8004/health | `AUDIT_STREAM` | `audit:events` | Stream name | | `SERVICE_NAME` | `omnibioai-security-audit` | Service identifier | | `AUDIT_MAXLEN` | `1000000` | Max stream length | +| `AUDIT_DATABASE_URL` | `mysql+pymysql://root:root@localhost:3306/omnibioai_audit` | Durable audit-event store the consumer writes into and `/audit/events` queries | +| `AUDIT_CONSUMER_GROUP` | `audit-workers` | Redis Streams consumer group name | +| `AUDIT_CONSUMER_NAME` | `worker-{pid}` | Per-process consumer identity within the group | --- @@ -321,7 +346,8 @@ This service integrates with: | Fail-open design | ✓ Stable | | Distributed trace ID support | ✓ Stable | | 99% test coverage | ✓ Stable | -| OpenSearch / PostgreSQL sink | Planned | +| MySQL sink + queryable read API (`worker/`, `db/`, `/audit/events`) | ✓ Stable | +| OpenSearch / additional sink backends | Planned | | Real-time security dashboard | Planned | | AI-based anomaly detection | Planned v0.5 | | Compliance reporting engine | Planned v0.5 |