Audit Logging

Every meaningful action in Sophon lands in the audit log: sign-ins, role changes, tool executions, approvals, workflow runs, connection configuration, memory writes and deletes, Node commands, admin operations. The log is immutable — you can read and export it but not modify it — and filterable across ~20 dimensions.

This page covers what gets logged, how to use the Dashboard, how to export, retention policies, and Enterprise-only streaming features.

What gets logged

Authentication

• Login (success + failure), logout, session revocation
• 2FA enrollment / disenrollment / failure
• SSO login (with IdP identity)
• API token create / revoke / use

Identity & RBAC

• User create / update / delete / suspend / reactivate
• Role create / update / delete / assign / unassign
• Permission grants (via direct role change or SSO group sync)

Resources

• Agent / Workflow / Skill / Document / Connection create / update / delete
• Memory write / forget / reindex
• Cron job create / pause / resume / fire / fail
• Webhook create / delete / delivery attempt
• Channel configure / test / disable
• Node pair / approve / revoke / scope change
• MCP server connect / disconnect / tool bridge

Execution

• Chat message sent / received
• Tool call (name, params-hash, result-hash, risk level, duration)
• Approval requested / approved / edited / rejected / timed-out
• Task queued / started / completed / failed / cancelled
• Plan generated / approved / executed

System & admin

• License install / rotate
• Tenant create / update / delete / user-assignment
• Settings changes (config file diff)
• Service start / stop / restart
• Cache flushed

Log entry schema

{
  "id": "audit_01HV4K...",
  "timestamp": "2026-04-22T10:15:23.847Z",
  "actor": {
    "userId": "usr_abc123",
    "email": "enes@example.com",
    "role": "Admin",
    "tenantId": "tenant_xyz"
  },
  "action": "workflow.update",
  "resource": {
    "type": "workflow",
    "id": "wf_morning_briefing",
    "name": "Morning Briefing"
  },
  "outcome": "success",
  "ip": "198.51.100.42",
  "userAgent": "Mozilla/5.0 ...",
  "changes": {
    "before": { "cronExpression": "0 8 * * *" },
    "after":  { "cronExpression": "0 9 * * MON-FRI" }
  },
  "metadata": { "source": "dashboard" }
}

All fields are indexed; changes is a JSON diff of before / after for mutating actions.

Viewing the log

Admin → Audit. Default view: last 25 entries, newest first.

Filters:

• Actor — user, role, IP
• Action — wildcard (workflow.*, memory.forget)
• Resource — type + ID
• Outcome — success / failure / denied
• Date range — preset or custom
• Free text — matches any field

Click an entry for full detail with expandable changes block.

Export

Dashboard

Admin → Audit → Export — pick format and date range:

• CSV — tabular, spreadsheet-friendly
• JSON — structured, one entry per line (JSONL)
• NDJSON — for piping directly into SIEM ingestion

CLI

sophon admin audit --since 2026-04-01 --until 2026-04-22 --format json > audit.jsonl
sophon admin audit --action "workflow.*" --user <id> --format csv > workflow-history.csv

REST

GET /api/admin/audit?from=2026-04-01&to=2026-04-22&format=json

Exports are rate-limited: 10 requests per 5 minutes, max 1 million entries per request.

Streaming (Enterprise)

For SIEM integration, Sophon can stream audit events to external sinks in near-real time:

Splunk

{
  "Sophon": {
    "Audit": {
      "Sinks": {
        "Splunk": {
          "Enabled": true,
          "Hec": {
            "Url": "https://splunk.example.com:8088",
            "Token": "{{vault:splunk_hec_token}}",
            "Index": "sophon_audit"
          }
        }
      }
    }
  }
}

Datadog / Elastic / syslog

Same shape — pick the sink, paste credentials in vault references, enable.

Generic webhook

{
  "Sinks": {
    "Webhook": {
      "Enabled": true,
      "Url": "https://siem.example.com/ingest",
      "Signed": true
    }
  }
}

Sinks receive one POST per event, with retry + backoff (see Webhooks).

Retention

Defaults by tier:

Configure in appsettings.json:

{
  "Sophon": {
    "Audit": {
      "Retention": "365.00:00:00"
    }
  }
}

A daily background job prunes entries older than retention. Prior to pruning, entries are optionally archived to cold storage (S3, Azure Blob) per sink config.

Immutability

The audit table is append-only. There's no UPDATE statement, no DELETE statement, anywhere in the code path. Pruning by retention runs at the database level with a system user, logged as a special audit.prune action that itself is audited — so a gap in the log has a reason.

Enterprise deployments can enable hash-chain immutability — each entry includes a SHA-256 of the previous entry's hash, detecting any tampering at the database level. Verify via:

sophon admin audit verify-chain --since 2026-01-01

Filtering out noise

Some actions fire very frequently (e.g., every tool call). If your SIEM doesn't need those, filter:

{
  "Sophon": {
    "Audit": {
      "Excluded": ["tool.execute", "memory.search", "insights.query"]
    }
  }
}

Excluded actions still land in the database (for the Dashboard audit view) but are not streamed to sinks.

Privacy considerations

• Parameter hashing — raw parameters for tool calls are SHA-256 hashed in the changes block to prevent accidental PII leaks. Full params available via authorized detail view with ViewAuditLogs permission.
• Token redaction — API tokens, OAuth tokens, credential content never appear in audit entries even in detail view.
• GDPR right-to-erasure — a deleted user's PII is redacted from audit entries (name / email replaced with [deleted]), but the entries themselves persist. The action trail is legally required retention.

Where to go next

• RBAC — controls who can view / export the log
• Compliance — using audit for compliance reports
• Webhooks — webhook sink configuration