Audit Trail¶

The ARX audit trail is the foundational compliance component of the platform (INV-001). Every agent action, connector call, policy evaluation, approval decision, and administrative change produces an immutable audit log entry. The audit trail is append-only by design: no entry can be modified or deleted after creation, and this constraint is enforced at the database schema level.

Architecture¶

Append-Only Guarantee¶

The audit trail is stored in the audit_log table in the platform database. Schema-level enforcement prevents any modification or removal of existing records:

REVOKE UPDATE -- The database role used by the application has no UPDATE privilege on the audit_log table. The single exception is a one-way status transition that appends an outputs_hash and marks an in-progress entry as success or error. Status transitions are strictly one-directional and cannot be reversed.
REVOKE DELETE -- The database role has no DELETE privilege on the audit_log table. No application code path can remove an audit entry.
Row-Level Security (RLS) -- Supabase RLS policies enforce tenant isolation. Queries against the audit trail always include org_id, ensuring that organizations can only access their own audit data.

These constraints are enforced at the PostgreSQL level, not in application code. Even if application logic were compromised, the database would reject any attempt to alter or remove audit records.

Write Failure Semantics¶

The audit logger follows a strict fail-closed rule: if the audit log write fails, the triggering action also fails. This ensures that no agent action can execute without a corresponding audit record. The AuditLogger.log() method re-raises any database exception, causing the calling operation to abort and return an error to the client.

This is a deliberate trade-off. The platform prioritizes compliance completeness over availability. An agent action that cannot be audited is treated as an action that did not happen.

Event Schema¶

Every audit log entry captures the following fields:

Field	Type	Description
`id`	`UUID`	Unique identifier for the audit entry.
`org_id`	`UUID`	Organization that owns this entry. Used for RLS tenant isolation.
`agent_id`	`UUID`	Agent that performed the action. Null for administrative actions.
`user_id`	`UUID`	User who initiated the action. Null for automated agent actions.
`action_type`	`string`	Structured action identifier. Examples: `agent.deployed`, `connector.called`, `policy.created`, `approval.reviewed`, `drift.detected`.
`connector`	`string`	Connector type involved in the action. Examples: `crowdstrike`, `splunk`, `jira`. Null for non-connector actions.
`target_resource`	`string`	The specific resource or operation targeted. Examples: `detections:read`, `hosts:contain`.
`inputs_hash`	`string`	SHA-256 hash of the action inputs. Raw input data is never stored in the audit trail.
`outputs_hash`	`string`	SHA-256 hash of the action outputs. Raw output data is never stored in the audit trail.
`policy_verdict`	`string`	The policy engine decision for this action: `PERMIT`, `ESCALATE`, or `DENY`.
`risk_score`	`integer`	Dynamic risk score assigned by the policy engine (0--100). Stored in `metadata`.
`duration_ms`	`integer`	Execution duration in milliseconds.
`status`	`string`	Outcome of the action: `success`, `error`, or `blocked`.
`metadata`	`JSON`	Structured metadata specific to the action type. May include `risk_score`, `policy_id`, `operation`, version numbers, or error details.
`created_at`	`timestamp`	UTC timestamp when the entry was created.

Data Privacy by Design¶

The audit trail stores hashes of inputs and outputs, never raw values. The hash_value() function computes a SHA-256 digest of the serialized input or output data. This design ensures that:

Sensitive data (API responses, query results, credentials) is never persisted in the audit trail.
Hashes can be used to verify that a specific input produced a specific output.
Compliance reviewers can confirm that audit records exist for every action without accessing the underlying data.

Secret values are excluded from audit entries entirely. The AuditLogger never receives raw credentials, API keys, or tokens.

Querying the Audit Trail¶

The audit trail is queryable through the REST API. All queries are scoped to the authenticated user's organization via RLS.

List Audit Entries¶

GET /v1/audit

Supported query parameters:

Parameter	Type	Description
`agent_id`	`UUID`	Filter entries by agent.
`action_type`	`string`	Filter by action type (e.g., `connector.called`).
`connector`	`string`	Filter by connector type (e.g., `crowdstrike`).
`status`	`string`	Filter by status: `success`, `error`, `blocked`.
`limit`	`integer`	Number of entries to return (1--1000, default 100).
`offset`	`integer`	Pagination offset (default 0).

Results are ordered by created_at descending (most recent first). The response includes a total count for pagination.

Get Single Entry¶

GET /v1/audit/{entry_id}

Returns a single audit log entry by ID. Returns 404 if the entry does not exist or belongs to a different organization.

Export¶

The audit trail can be exported in two formats for external consumption.

CSV Export¶

GET /v1/audit/export?format=csv

Produces a CSV file with columns: created_at, action_type, connector, target_resource, policy_verdict, status, user_name, duration_ms. User IDs are resolved to human-readable names (full name or email) for auditor convenience. The CSV export supports up to 50,000 entries per request.

JSON Export¶

GET /v1/audit/export?format=json

Produces a JSON array of full audit log entries with all fields. Suitable for programmatic ingestion by external systems.

Both export endpoints accept an optional agent_id query parameter to scope the export to a single agent, and a limit parameter (default 10,000, max 50,000).

SIEM Integration¶

ARX supports real-time fan-out to SIEM platforms. When a SIEM integration is configured for an organization, every new audit log entry is automatically forwarded to all enabled SIEM endpoints. SIEM delivery is asynchronous and non-blocking: it runs in the background after the audit entry is persisted. Failures in SIEM delivery are logged and tracked (error counts and last error messages are recorded on the integration), but they never block the audit write or the triggering action.

Supported SIEM targets include Splunk, Microsoft Sentinel, Elastic Security, and any platform that accepts structured JSON events over HTTPS. SIEM integrations are configured per organization in the siem_integrations table with type-specific configuration (endpoint URLs, authentication tokens, index names).

Retention¶

Audit log entries are retained according to the organization's plan:

Plan	Retention Period
Starter	90 days
Professional	1 year
Enterprise	7 years (configurable)

Retention policies are enforced by a scheduled background job that removes entries older than the configured retention window. Because the audit_log table does not permit application-level deletes, retention is managed by a privileged database role that runs outside the application.

Organizations on the Enterprise plan can configure custom retention periods up to 7 years to meet regulatory requirements (e.g., SEC Rule 17a-4, HIPAA, SOX). Exported audit data (CSV, JSON) is not subject to platform retention limits and should be archived according to the organization's own data retention policies.

Compliance Significance¶

The audit trail directly supports multiple SOC 2 Trust Service Criteria:

CC6.1 (Logical Access) -- Every access to external systems through connectors is logged with the connector type, operation, and policy verdict.
CC7.1 (Monitoring) -- The audit trail provides continuous monitoring of all agent activity, including behavioral drift detection events.
CC7.2 (Anomaly Detection) -- Blocked actions, escalated approvals, and drift events are recorded with full context for incident investigation.
CC8.1 (Change Management) -- Agent deployments, configuration changes, policy modifications, and version rollbacks are tracked with the identity of the user who initiated the change.

The audit trail is the primary evidence source for compliance packages generated by the platform. When a compliance package is created, the execution graph, control mappings, and vendor security questionnaire responses are all derived from audit trail data.