Plugins
Audit Trail Plugin
The Audit Trail plugin creates an immutable, HMAC-signed record of every authorization decision. Records are stored in PostgreSQL and optionally streamed to an S3-compatible bucket for long-term retention.
Record Structure
JSON
{
"trace_id": "01HZJ4P7K2G...",
"timestamp": "2025-01-15T12:34:56Z",
"agent_id": "gpt-4-agent",
"action": "delete_user",
"confidence": 0.82,
"decision": "require_review",
"reviewer": "alice@company.com",
"final_decision": "allow",
"policy_version": "v2.3.1",
"hmac": "sha256:a3f9b1..."
}S3 Export
Configure the S3 sink to stream audit records to any S3-compatible storage (AWS S3, MinIO, Cloudflare R2).
Environment variables
# Enable S3 export AUDIT_S3_ENABLED=true AUDIT_S3_BUCKET=my-audit-bucket AUDIT_S3_REGION=us-east-1 AUDIT_S3_PREFIX=lelu/audit/ # Credentials (or use IAM roles in AWS) AWS_ACCESS_KEY_ID=... AWS_SECRET_ACCESS_KEY=... # For MinIO / Cloudflare R2 AUDIT_S3_ENDPOINT=https://my-minio:9000
Querying Audit Records
Use the Platform REST API to query audit records by trace ID or time range.
curl
# Get by trace ID curl -H "Authorization: Bearer $LELU_API_KEY" \ http://localhost:9090/api/v1/audit?trace_id=01HZJ4P7K2G # Get last 100 records curl -H "Authorization: Bearer $LELU_API_KEY" \ "http://localhost:9090/api/v1/audit?limit=100&order=desc"
HMAC Verification
Each record includes an HMAC-SHA256 signature to detect tampering. Verify with the AUDIT_HMAC_SECRET environment variable.
Python
import hmac, hashlib, json
def verify_record(record: dict, secret: str) -> bool:
expected = record.pop("hmac")
payload = json.dumps(record, sort_keys=True).encode()
actual = "sha256:" + hmac.new(
secret.encode(), payload, hashlib.sha256
).hexdigest()
return hmac.compare_digest(expected, actual)