feat(audit): implement audit logging functionality with middleware an…

[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 221 unit tests pass

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

[github-actions]

👋 Welcome to Tron! Thanks for your first pull request.

A maintainer will review it soon. Here's what to expect:

1. ✅ Automated tests will run on your changes
2. 👀 A maintainer will review your code
3. 💬 You may receive feedback or requests for changes
4. 🎉 Once approved, your PR will be merged!

While you wait:

• Make sure all tests pass
• Check that your PR follows the contribution guidelines
• Feel free to ask questions if you need help

Thank you for contributing to Tron! 🚀

[codecov-commenter]

Welcome to Codecov 🎉

Once you merge this PR into your default branch, you're all set! Codecov will compare coverage reports and display results in all future pull requests.

ℹ️ You can also turn on project coverage checks and project coverage reporting on Pull Request comment

Thanks for integrating Codecov - We've got you covered ☂️

[digmunhoz]

Please close and reopen the pull request to re-read the labeler job permission.