DocumentationAgent Action Firewall
GitHub

Audit API

Access tamper-evident audit logs and export compliance proof packs.

Overview

The audit trail provides a cryptographically-secured record of all actions, decisions, and approvals. Each event is hash-chained to the previous, ensuring tamper evidence.

List Audit Events

Retrieve audit events with filtering.

HTTP
GET /admin/audit?start_date=2024-12-01&end_date=2024-12-31

Query Parameters

ParameterTypeDescription
start_datedateStart of date range (ISO 8601)
end_datedateEnd of date range (ISO 8601)
event_typestringFilter by event type
action_idstringFilter by action
agent_idstringFilter by agent
risk_levelstringFilter by risk level
limitintegerMax results (default: 50)

Response

JSON
{
  "data": [
    {
      "id": "evt_abc123",
      "event_type": "action.submitted",
      "action_id": "act_xyz789",
      "agent_id": "customer-service-bot",
      "data": {
        "tool": "http_proxy",
        "operation": "POST",
        "params": { "url": "..." }
      },
      "hash": "sha256:a1b2c3d4...",
      "prev_hash": "sha256:x9y8z7w6...",
      "created_at": "2024-12-25T12:00:00Z"
    },
    {
      "id": "evt_abc124",
      "event_type": "decision.made",
      "action_id": "act_xyz789",
      "data": {
        "decision": "allow",
        "reason": "Matches allowed pattern",
        "risk_level": "low",
        "policy_id": "pol_default"
      },
      "hash": "sha256:e5f6g7h8...",
      "prev_hash": "sha256:a1b2c3d4...",
      "created_at": "2024-12-25T12:00:01Z"
    }
  ],
  "pagination": {
    "total": 1250,
    "limit": 50,
    "offset": 0
  }
}

Event Types

Event TypeDescription
action.submittedNew action submitted
decision.madePolicy decision rendered
approval.requestedApproval workflow started
approval.approvedAction approved
approval.deniedAction denied
execution.startedAction execution began
execution.completedAction execution finished
execution.failedAction execution failed

Get Event

Retrieve a specific audit event.

HTTP
GET /admin/audit/:id

Export Proof Pack

Export a tamper-evident proof pack for an action. Proof packs contain all related events with cryptographic verification.

HTTP
GET /admin/audit/actions/:action_id/proof-pack

Response

Returns a ZIP file containing:

  • action.json - Action details
  • decision.json - Policy decision
  • approval.json - Approval record (if applicable)
  • events.json - All related audit events
  • policy.rego - Policy that evaluated the action
  • verification.json - Hash chain verification data

Verify Hash Chain

Verify the integrity of the audit trail.

HTTP
POST /admin/audit/verify

Request Body

JSON
{
  "start_date": "2024-12-01",
  "end_date": "2024-12-31"
}

Response

JSON
{
  "valid": true,
  "events_verified": 1250,
  "first_event": "evt_001",
  "last_event": "evt_1250",
  "chain_start_hash": "sha256:genesis...",
  "chain_end_hash": "sha256:current..."
}

Audit Reports

Generate compliance reports.

HTTP
POST /admin/audit/reports

Request Body

JSON
{
  "type": "compliance",
  "start_date": "2024-12-01",
  "end_date": "2024-12-31",
  "format": "pdf",
  "include": ["actions", "approvals", "denials", "risk_summary"]
}

SDK Examples

TypeScript
// List audit events
const events = await client.listAuditEvents({
  startDate: '2024-12-01',
  endDate: '2024-12-31',
  eventType: 'approval.approved',
});

// Export proof pack
const proofPack = await client.exportProofPack(actionId);
fs.writeFileSync('proof-pack.zip', proofPack);

// Verify hash chain
const verification = await client.verifyAuditChain({
  startDate: '2024-12-01',
  endDate: '2024-12-31',
});
console.log('Chain valid:', verification.valid);

Next Steps