Audit Log

Open Astra maintains a tamper-proof audit trail of every significant action. Entries are chained with SHA-256 hashes so any modification to historical records can be detected. The audit log supports querying, CSV export, real-time streaming, and integrity verification.

Events logged

Event	Severity	Source
`tool.executed`	Low	Every tool execution
`memory.written`	Low	Every memory write
`agent.spawned`	Low	Sub-agent spawn events
`inference.request`	Low	Every inference call
`security.token_replay`	Critical	Replayed JWT detected
`security.token_revoked`	Medium	Token revocation

Critical and high severity events automatically fire a webhook to SECURITY_WEBHOOK_URL if configured.

Querying the log

bash

# Query audit log with filters (owner only)
curl "http://localhost:3000/audit?event=tool.executed&limit=50&offset=0" \
  -H "Authorization: Bearer ${JWT_TOKEN}"

# Response
{
  "entries": [
    {
      "id": "aud_abc123",
      "event": "tool.executed",
      "uid": "uid_alice",
      "agent_id": "code-agent",
      "action": "file_write",
      "session_id": "sess_abc123",
      "details": { ... },
      "metadata": { ... },
      "timestamp": "2026-03-07T12:00:00.000Z"
    }
  ],
  "limit": 50,
  "offset": 0
}

Parameter	Default	Max	Description
`from`	—	—	ISO 8601 start timestamp
`to`	—	—	ISO 8601 end timestamp
`event`	—	—	Filter by event type
`limit`	100	1000	Page size
`offset`	0	—	Pagination offset

CSV export

bash

# Export audit log as CSV
curl "http://localhost:3000/audit/export.csv?from=2026-03-01&to=2026-03-07" \
  -H "Authorization: Bearer ${JWT_TOKEN}" > audit.csv

Hash chain verification

Each audit entry contains a SHA-256 hash computed from the previous entry's hash and the current entry's event, uid, and metadata. Verification walks the chain and confirms each hash matches.

bash

# Verify hash chain integrity (detect tampering)
curl http://localhost:3000/audit/verify \
  -H "Authorization: Bearer ${JWT_TOKEN}"

# Response — chain is valid
{ "valid": true, "checkedCount": 1842 }

# Response — chain is broken (tampered)
{ "valid": false, "brokenAt": "aud_def789", "checkedCount": 1842 }

Real-time streaming

Subscribe to audit events in real-time via Server-Sent Events.

bash

# Stream audit events in real-time (SSE)
curl -N http://localhost:3000/audit/stream \
  -H "Authorization: Bearer ${JWT_TOKEN}"

# Events arrive as SSE:
# data: {"event":"tool.executed","payload":{...},"timestamp":1741363200000}

Workspace-scoped audit

For workspace-level queries with agent and action filtering:

bash

# Workspace-scoped audit with agent and date filters
curl "http://localhost:3000/workspace-audit?agentId=code-agent&from=2026-03-01T00:00:00Z" \
  -H "Authorization: Bearer ${JWT_TOKEN}"

# Aggregated audit summary
curl "http://localhost:3000/workspace-audit/summary?from=2026-03-01T00:00:00Z" \
  -H "Authorization: Bearer ${JWT_TOKEN}"

Payload sanitization

Metadata strings longer than 500 bytes are replaced with a SHA-256 hash prefix ([sha256:xxxxxxxx***]) to prevent sensitive data from being stored in the audit log.