Audit Trail

Agent Action Firewall maintains a comprehensive, tamper-evident audit trail of all agent actions, policy decisions, and approvals. This is critical for compliance, security investigations, and operational visibility.

Tamper-Evidence

Every audit event is cryptographically linked to the previous event using hash chaining:

Event N:
  hash = SHA256(event_data + prev_hash)
  prev_hash = hash of Event N-1

Event N+1:
  hash = SHA256(event_data + prev_hash)
  prev_hash = hash of Event N

This ensures that:

• No event can be modified without breaking the chain
• No event can be deleted without detection
• No event can be inserted retroactively
• The complete history is verifiable

Event Types

Event Schema

Each audit event contains:

{
  "id": "evt-abc123",
  "event_type": "action.executed",
  "timestamp": "2024-01-15T10:30:00Z",
  "org_id": "org-uuid",
  "actor_type": "agent",
  "actor_id": "agent-001",
  "action_request_id": "act-456",
  "payload": {
    "tool": "http",
    "operation": "POST",
    "url": "https://api.stripe.com/v1/charges",
    "response_status": 200
  },
  "prev_hash": "abc123...",
  "hash": "def456..."
}

Querying the Audit Trail

Basic Query

GET /api/v1/audit?limit=50&offset=0

Filter by Event Type

GET /api/v1/audit?event_type=action.executed

Filter by Time Range

GET /api/v1/audit?from=2024-01-01T00:00:00Z&to=2024-01-31T23:59:59Z

Filter by Agent

GET /api/v1/audit?agent_id=agent-001

Filter by Action

GET /api/v1/audit?action_request_id=act-456

Verifying Integrity

Verify the Hash Chain

import { verifyAuditChain } from '@aaf/sdk';

const events = await api.get('/audit?limit=1000');
const valid = verifyAuditChain(events);

if (!valid) {
  console.error('Audit chain integrity compromised!');
}

Via API

POST /api/v1/audit/verify
{
  "from": "2024-01-01T00:00:00Z",
  "to": "2024-01-15T23:59:59Z"
}

# Response
{
  "valid": true,
  "events_checked": 15234,
  "first_event": "evt-001",
  "last_event": "evt-15234"
}

Proof Packs

Export a self-contained proof pack for compliance or investigations:

POST /api/v1/proof-pack
{
  "action_request_id": "act-456"
}

A proof pack contains:

• The original action request
• The policy that was evaluated
• The complete Rego policy source
• All approval records
• The full audit trail for this action
• Hash chain verification data

Proof packs are exported as signed ZIP files.

SIEM Integration

Export audit events to your SIEM:

Webhook Export

await api.post('/integrations/siem', {
  type: 'webhook',
  endpoint: 'https://your-siem.example.com/api/events',
  auth: {
    type: 'bearer',
    token: 'your-api-key'
  },
  events: ['action.*', 'approval.*', 'dlp.detected'],
  batch_size: 100,
  max_delay_seconds: 60
});

Supported SIEMs

• Splunk (via HEC)
• Datadog
• Elastic/OpenSearch
• Sumo Logic
• Custom webhook

Retention

For compliance requirements, Enterprise plans support:

• Extended retention (7+ years)
• Cold storage archival
• Geographic data residency

Compliance Reports

Generate compliance reports:

POST /api/v1/audit/reports
{
  "type": "SOC2",
  "period": {
    "from": "2024-01-01",
    "to": "2024-03-31"
  },
  "include": [
    "action_summary",
    "approval_metrics",
    "policy_changes",
    "access_logs"
  ]
}

Report types:

• SOC 2 Type II
• GDPR Article 30
• HIPAA Audit Log
• Custom

Best Practices

Tip: Never disable audit logging. Even for testing environments, maintain audit logs to track what agents are doing.

Tip: Verify regularly. Run hash chain verification weekly or after any system maintenance.

Tip: Export for long-term. For compliance, export proof packs to external storage where they can't be modified by AAF.

Tip: Set up SIEM integration. Real-time event streaming enables faster incident detection.

Next Steps

• DLP Protection — Detect sensitive data in actions
• Proof Packs — Export compliance bundles