> ## Documentation Index
> Fetch the complete documentation index at: https://costhq.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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.

<Note>
  **Enterprise Feature** — The audit trail requires an Enterprise license. Free and Pro tiers do not log audit events.
</Note>

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

```bash theme={null}
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

```bash theme={null}
# 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.

```bash theme={null}
# 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:

```bash theme={null}
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.

```bash theme={null}
✓ 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.

```bash theme={null}
cs audit export --format soc2 > costhq_audit_Q1.json
```

The SOC2 export format looks like this:

```json theme={null}
{
  "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:

```bash theme={null}
cs audit export --format csv > audit.csv
cs audit export --format json --since "2024-03-01" > audit_march.json
```