Enterprise Audit Trail & SOC2 Compliance

SOC2 compliance for AI agents. Tamper-evident audit logging for LLM usage with chained SHA-256 checksums and team identity tagging.

Enterprise Feature — The audit trail requires an Enterprise license. Free and Pro tiers do not log audit events.

CostHQ Enterprise provides an append-only, tamper-evident audit log of all cost-sensitive operations. This ensures that every AI usage event, session lifecycle change, policy update, or data deletion is tracked and verifiable, making CostHQ suitable for SOC2-compliant environments.

Checksum Chain Integrity

To prevent tampering, CostHQ uses a chained SHA-256 checksum architecture.

Each event’s checksum is generated by hashing the payload together with the checksum of the previous event:

current_checksum = SHA-256(previous_checksum + JSON(payload))

This creates an unbroken cryptographic chain starting from a genesis hash (00...00). If a single record is inserted, modified, or deleted, every subsequent checksum in the chain will be invalidated, making tampering mathematically impossible to hide.

Team Identity

In a multi-user or automated environment, audit logs are most useful when events are tagged with specific identities. You can configure a machine’s team identity so that all subsequent audit events are tagged with that user/role.

Setting Identity

cs team set --name "Platform Engineering" --member "alice.smith" --role "Lead Developer" --department "Backend"

Once set, all audit events will include this identity alongside the standard machine info (hostname, OS user).

Managing Identity

# Show current identity
cs team show

# Clear identity (revert to just hostname/OS user)
cs team clear

Viewing the Audit Log

You can view the audit log directly from the CLI or via the Command Center dashboard.

# View the last 20 events
cs audit log

# View 50 events
cs audit log --limit 50

# Filter by date (ISO format)
cs audit log --since "2024-01-01T00:00:00Z"

# Filter by event type
cs audit log --type "ai.usage"

# Output as JSON
cs audit log --json

Event Types

The following events are logged:

Event Type	Triggered By
session.start	Starting a new session (cs start, cs run)
session.end	Ending a session (cs end)
ai.usage	Logging token usage (cs log-ai, proxy requests)
policy.change	Modifying the Spend Firewall rules
config.change	Modifying CLI configuration or settings
data.export	Exporting session data
data.reset	Wiping the local database (cs proxy clear / cs db reset)
license.activate	Adding a license key
license.deactivate	Removing a license key
local_model.add	Registering a local model
local_model.remove	Removing a local model

Verifying Integrity

You can mathematically prove the integrity of the local audit log at any time:

cs audit verify

This command walks the entire database, recalculates every checksum in the chain, and confirms whether the log is fully intact or if tampering has occurred.

✓ All 1,402 audit events verified. Chain integrity intact.

If tampering is detected, it will report the exact ID where the chain is broken.

SOC2-Compliant Export

For compliance audits, you can export the audit trail in a structured, SOC2-friendly JSON format that includes the chain verification status.

cs audit export --format soc2 > costhq_audit_Q1.json

The SOC2 export format looks like this:

{
  "exportedAt": "2024-04-01T12:00:00.000Z",
  "format": "costhq-audit-soc2-v1",
  "compliance": {
    "standard": "SOC2 Type II",
    "scope": "AI cost tracking and access control",
    "chainIntegrity": true,
    "chainVerification": "All 1402 audit events verified. Chain integrity intact.",
    "totalEvents": 1402,
    "verifiedEvents": 1402
  },
  "exportMetadata": {
    "tool": "CostHQ",
    "hostname": "workstation-01",
    "platform": "darwin"
  },
  "events": [
    {
      "id": 1,
      "timestamp": "2024-01-01T09:00:00.000Z",
      "eventType": "session.start",
      "actor": "alice.smith@Platform Engineering (workstation-01/darwin)",
      "details": { "sessionId": 100, "name": "Refactoring Auth" },
      "teamId": "Platform Engineering",
      "checksum": "a1b2c3d4...",
      "chainPosition": 1
    }
  ]
}

You can also export to standard json or csv formats:

cs audit export --format csv > audit.csv
cs audit export --format json --since "2024-03-01" > audit_march.json