feat(audit): implement audit logging functionality with middleware

[romariohornburg]

Audit Logs Implementation (Closes #82)

Summary

This PR implements headless, asynchronous audit logging across the Tron platform. It captures structured events for every significant request and exports them directly to external SIEMs (Elasticsearch, Splunk, Datadog) via HTTP. The design is fail-open and configured exclusively via environment variables (no UI).

Audit Event Structure

Each log entry contains:

• timestamp: ISO 8601 (when the action occurred)
• actor: Email/ID of the authenticated user or anonymous
• action: READ, CREATE, UPDATE, EXEC, DELETE (mapped from HTTP method)
• resource: Affected resource (e.g., instances/abc-123, organizations/xyz/members)
• status: Success/Failure + HTTP status code
• source_ip: Client IP (with support for X-Forwarded-For behind proxies)

For EXEC events (pod command execution), the following are also included:

• exec_request: Command and container name
• exec_response: stdout, stderr, return_code (truncated at 4096 chars to avoid huge payloads)

Architecture

• AuditMiddleware intercepts requests at the FastAPI layer
• After the response is returned, builds the audit payload and sends it via asyncio.create_task() (non-blocking)
• Auth dependency sets request.state.audit_actor on successful authentication
• If the SIEM endpoint is offline or times out, the platform continues normally (fail-open)

File Structure

api/app/
├── audit/
│   ├── core/
│   │   ├── audit_config.py      # Config from env
│   │   ├── audit_event.py       # Event schema and mapping
│   │   └── audit_sender.py      # Async HTTP send (fail-open)
│   └── __init__.py
├── shared/
│   └── middleware/
│       └── audit_middleware.py  # FastAPI middleware
└── main.py                      # Middleware registration

Configuration

Environment variables (add to .env):

• AUDIT_LOG_ENABLED (default: false) – enables/disables audit logging
• AUDIT_SIEM_URL – SIEM endpoint URL (e.g., https://logs.example.com/ingest)
• AUDIT_SIEM_TOKEN (optional) – Bearer token for authentication
• AUDIT_SIEM_TIMEOUT (default: 5) – HTTP timeout in seconds

The middleware is only registered when AUDIT_LOG_ENABLED=true and AUDIT_SIEM_URL is set.

Changes

• Added audit module with config, event builder, and async sender
• Added AuditMiddleware to capture request/response metadata
• Integrated with auth to capture actor (user email or token name)
• EXEC handlers (workers, webapps) now populate audit_exec_payload with command and output
• Updated docker-compose.yaml to pass audit env vars to the API container
• Updated docker/.env.example with audit variables

Tests

• Unit tests for audit_config, audit_event, and audit_sender (including fail-open behavior)
• All unit tests pass (update the count here after running pytest tests/unit if you want it exact)

Compliance

• Small functions, clear names, no duplication
• Fail-open: send errors never block the response
• Configuration via env vars only, no UI
• Pre-commit: ruff check, ruff format, pytest tests/unit