Skip to content

Audit Logs

The Audit page provides a searchable, filterable view of all agent actions logged in your tenant. Audit logs form the compliance backbone of AegisAI — tamper-evident, exportable, and correlated with anomalies and policy decisions.

Audit Table

Column Description
Timestamp When the action occurred (UTC)
Agent Agent that performed the action
Action Operation type (e.g., read_data, delete_record)
Resource Target resource identifier
Risk Score 0.0–1.0 if assessed
Approved Whether the action was approved (HITL or policy)
Signature HMAC signature (when signing enabled)

Filtering

Filter audit logs by:

  • Agent — select from registered agents
  • Action — free-text action name
  • Date range — start and end timestamps
  • Risk threshold — minimum risk score

Filters are applied server-side via query parameters on GET /api/v1/audit.

Logging Actions

Agents log actions via the API or SDK:

curl -X POST http://localhost:8000/api/v1/audit/log \
  -H "X-API-Key: <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "<uuid>",
    "action": "query_database",
    "resource": "customer_records",
    "input": {"query": "SELECT name FROM customers LIMIT 10"},
    "output": {"rows": 10},
    "reasoning": ["User requested customer list", "Applied row limit"],
    "risk_score": 0.2,
    "is_approved": true
  }'

SDK Observer Pattern

async with client.observe("read_data", "customer_pii") as obs:
    obs.set_input({"fields": ["email", "name"]})
    result = await fetch_customer_data()
    obs.set_output({"records": len(result)})
    # Automatically checks policy and logs audit entry

Audit Signing

When AUDIT_SIGNING_ENABLED=true, each log entry receives an HMAC-SHA256 signature for integrity verification. Signatures are displayed in the audit table and included in exports.

Export

Export audit logs for compliance archives or external SIEM integration.

Synchronous Export

# CSV
curl "http://localhost:8000/api/v1/audit/export/csv?limit=1000" \
  -H "X-API-Key: <your-api-key>" \
  -o audit_export.csv

# JSON
curl "http://localhost:8000/api/v1/audit/export/json?limit=1000" \
  -H "X-API-Key: <your-api-key>" \
  -o audit_export.json

Async Export (Large Datasets)

For exports exceeding synchronous limits:

# Start export job
curl -X POST "http://localhost:8000/api/v1/audit/export/async?limit=50000" \
  -H "X-API-Key: <your-api-key>"

# Check status
curl "http://localhost:8000/api/v1/audit/export/status/<job_id>" \
  -H "X-API-Key: <your-api-key>"

# Download result
curl "http://localhost:8000/api/v1/audit/export/download/<job_id>" \
  -H "X-API-Key: <your-api-key>" \
  -o audit_export.jsonl
Status Meaning
pending Job queued
processing Export in progress
completed Ready for download
failed Export failed (check error message)

Permissions

Role Read Export
Viewer ✅ ❌
Developer ✅ ❌
Security Analyst ✅ ✅
Admin ✅ ✅
Super Admin ✅ ✅

Retention

Audit logs are stored in PostgreSQL with no automatic purge by default. Configure retention policies at the infrastructure level (see Backup).