Skip to content

docs: document the DB sink + query API that already ship, add endpoints #1

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
man4ish merged 1 commit into from
Aug 8, 2026
Merged

docs: document the DB sink + query API that already ship, add endpoints #1

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
32 changes: 29 additions & 3 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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 |
Expand All @@ -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 |

---

Expand Down Expand Up @@ -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 |
Expand Down
Loading