Audit Trail

Every guard() call generates an immutable audit event. These events are the foundation of Auditail's compliance and debugging story.

---

What Gets Logged

{
  "auditId": "aeg_1a2b3c_x9z4k7",
  "agentId": "financial-report-bot",
  "userId": "user_7291",
  "action": "send_email",
  "payload": {
    "to": "[email protected]",
    "subject": "Q3 Report",
    "body": "Please find the report attached."
  },
  "approved": false,
  "reason": "Blocked: sending email to an external domain requires human approval.",
  "matchedRule": "no-external-email",
  "tags": {
    "team": "finance",
    "feature": "automated-reporting"
  },
  "timestamp": "2025-01-15T10:30:00.123Z",
  "environment": "production",
  "sdkVersion": "0.1.0"
}

Every field is logged on every event — approved or blocked.

---

Audit Log Schema

Field	Type	Description
auditId	string	Unique ID for this event. Use this in incident reports.
agentId	string	The agent that attempted the action.
userId	string?	The user or session that triggered the agent.
action	string	The action name (e.g. send_email, execute_query).
payload	object	The full payload passed to guard().
approved	boolean	Whether the action was allowed.
reason	string?	Human-readable block reason, from the matching rule.
matchedRule	string?	Name of the rule that fired.
tags	object?	Custom key-value tags for filtering.
timestamp	ISO 8601	UTC timestamp of the decision.
environment	string	The environment label set in Auditail({ environment }).
sdkVersion	string	SDK version for compatibility tracking.

---

Querying the Audit Log

In the Dashboard (full SDK)

The Auditail dashboard at https://app.auditail.io provides:

• Full-text search across all events
• Filter by agentId, userId, action, approved, matchedRule, tags
• Time-range selection
• Export to CSV or JSON

In the Preview SDK

const events = aegis.getAuditLog();

// All blocked events
const blocked = events.filter(e => !e.approved);

// All events for a specific agent
const botEvents = events.filter(e => e.agentId === 'financial-report-bot');

console.log(blocked);

---

SOC2 Compliance Export (full SDK)

The Scale tier includes one-click SOC2 audit log export:

• Immutable logs — stored in append-only S3 with object-lock enabled
• Tamper-evident — each event is HMAC-signed
• Queryable — indexed by Elasticsearch for instant search
• Exportable — download as JSON for your auditor

---

Connecting auditId to Your Systems

Always store the auditId returned from guard(). It's your reference point for incident investigation:

const result = await aegis.guard({ ... });

// Store the auditId in your own database alongside the action
await db.agentActions.create({
  auditId: result.auditId,
  userId: currentUser.id,
  action: 'send_email',
  outcome: result.approved ? 'executed' : 'blocked',
});

When something goes wrong, you can look up the auditId in both Auditail's dashboard and your own system to get the full picture.

---

Data Retention

Tier	Retention
Hobby (free)	7 days
Pro	90 days
Scale	1 year (configurable)
Private Cloud	Unlimited (your storage)