Audit Trail

Every interaction with data is automatically tracked in an immutable audit trail, providing complete accountability and transparency.

What is the audit trail

The Audit Trail is a comprehensive, immutable record of every data access event and action taken within the Xase system.

Every audit entry captures:

— Who — Identity of the actor
— What — Action performed
— When — Precise timestamp
— Why — Purpose of the action
— Where — Source IP and geographic location
— How — Method and authentication used

This creates a chain of accountability that can be presented to regulators, auditors, or courts.

Tracked events

Access Events

Session creation and data access events:

{
  "event_id": "evt_a1b2c3d4",
  "event_type": "ACCESS_SESSION_CREATED",
  "timestamp": "2026-01-15T14:30:00Z",
  "actor": {
    "id": "user_123abc",
    "email": "researcher@ai-lab.com",
    "organization": "AI Research Lab"
  },
  "context": {
    "session_id": "sess_7f6e5d4c",
    "dataset_id": "dataset_medical_records",
    "purpose": "model-training",
    "ip_address": "203.0.113.42",
    "location": "New York, US",
    "auth_method": "mTLS",
    "user_agent": "Python/3.12 xase-client/1.4.2"
  }
}

Authorization Events

Policy evaluation and approval events:

{
  "event_id": "evt_b2c3d4e5",
  "event_type": "ACCESS_AUTHORIZED",
  "timestamp": "2026-01-15T14:28:45Z",
  "actor": {
    "id": "user_456def",
    "email": "data-admin@hospital.org",
    "organization": "Metropolitan Hospital"
  },
  "context": {
    "session_id": "sess_7f6e5d4c",
    "policy_id": "policy_medical_research",
    "policy_version": "1.2",
    "authorization_id": "auth_b2c3d4",
    "ip_address": "198.51.100.73",
    "location": "Chicago, US",
    "auth_method": "2FA",
    "mfa_verified": true
  }
}

Data Usage Events

Data operations and transformations:

{
  "event_id": "evt_c3d4e5f6",
  "event_type": "DATA_ACCESSED",
  "timestamp": "2026-01-15T15:12:27Z",
  "actor": {
    "id": "user_123abc",
    "email": "researcher@ai-lab.com",
    "session_id": "sess_7f6e5d4c"
  },
  "context": {
    "record_count": 1000,
    "operation": "stream_batch",
    "filter_applied": {"age": {"$gte": 18}},
    "data_fields": ["patient_id", "diagnosis", "symptoms"],
    "purpose": "model-training"
  }
}

Security Events

Security-related events and anomalies:

{
  "event_id": "evt_d4e5f6g7",
  "event_type": "ACCESS_DENIED",
  "timestamp": "2026-01-15T16:45:12Z",
  "actor": {
    "id": "user_789ghi",
    "email": "engineer@ai-lab.com",
    "organization": "AI Research Lab"
  },
  "context": {
    "dataset_id": "dataset_medical_records",
    "reason": "POLICY_VIOLATION",
    "details": "Model not in allowed list",
    "policy_id": "policy_medical_research",
    "ip_address": "203.0.113.55",
    "location": "New York, US"
  }
}

Administrative Events

System configuration and policy changes:

{
  "event_id": "evt_e5f6g7h8",
  "event_type": "POLICY_UPDATED",
  "timestamp": "2026-01-10T11:23:54Z",
  "actor": {
    "id": "user_456def",
    "email": "data-admin@hospital.org",
    "organization": "Metropolitan Hospital"
  },
  "context": {
    "policy_id": "policy_medical_research",
    "old_version": "1.1",
    "new_version": "1.2",
    "changes": [
      {
        "field": "allowed_models",
        "old": ["model_diagnostic_v1"],
        "new": ["model_diagnostic_v1", "model_diagnostic_v2"]
      }
    ],
    "ip_address": "198.51.100.73",
    "location": "Chicago, US"
  }
}

Working with the audit trail

Querying Audit Logs

Access audit events programmatically:

import xase

client = xase.Client(api_key="sk_...")

# Query audit logs
logs = client.audit.list(
    session_id="sess_7f6e5d4c",
    event_types=["ACCESS_SESSION_CREATED", "DATA_ACCESSED"],
    start_time="2026-01-15T00:00:00Z",
    end_time="2026-01-16T00:00:00Z",
    limit=100
)

for event in logs:
    print(f"Event: {event.event_type}")
    print(f"Time: {event.timestamp}")
    print(f"Actor: {event.actor.email}")

Audit Reports

Generate audit reports for compliance:

# Generate session audit report
report = client.audit.report(
    session_id="sess_7f6e5d4c",
    format="pdf",  # or "json", "csv"
    include_evidence=True
)

# Download report
report.download("./session_audit_report.pdf")

# For compliance reporting periods
monthly_report = client.audit.report(
    dataset_id="dataset_medical_records",
    start_time="2026-01-01T00:00:00Z",
    end_time="2026-01-31T23:59:59Z",
    format="csv"
)

monthly_report.download("./january_audit_report.csv")

Automated Notifications

Configure notifications for important events:

# Set up audit event notifications
client.audit.create_notification(
    name="access-denied-alert",
    event_types=["ACCESS_DENIED"],
    destination="security-team@company.com",
    channel="email"
)

# Webhook for security events
client.audit.create_notification(
    name="security-events-webhook",
    event_types=["ACCESS_DENIED", "ANOMALY_DETECTED"],
    destination="https://security.company.com/webhooks/xase",
    channel="webhook",
    include_full_event=True
)

Security and retention

Immutability

Audit logs are append-only and cryptographically protected against tampering. Modifications are impossible, even by administrators.

Retention

Audit logs are retained for 7 years by default. Custom retention policies can be configured to meet regulatory requirements.

Access Controls

Audit logs have strict access controls. Only authorized personnel with explicit audit permissions can view them.

Cryptographic Protection

All audit events are signed and can be verified using the same mechanisms as evidence bundles.

Next steps

VerificationLearn how to verify evidence bundles

Usage MeteringLearn how usage is measured and billed