docs: overhaul security, isolation, and audit log documentation

docs/audit-logs/agents.mdx

@@ -0,0 +1,14 @@
+---
+title: "Organization agent logs"
+description: "Export OpenTelemetry metrics, log events, and traces for agent runs to your observability backend."
+---
+
+This page is a work in progress.
+
+Agent runs export OpenTelemetry signals to your observability backend. Configure the exporter under Organization settings, then open **Agent OTel**.
+
+## Related pages
+
+- See [Organization audit logs](/audit-logs/organization) to stream user and service-account activity to your SIEM.
+- See [Platform audit logs](/audit-logs/platform) to capture administration above the organization boundary.
+- See [Architecture](/security/architecture) for the sandbox and relay boundaries that agent telemetry crosses.

docs/audit-logs/mcp-access.mdx

@@ -0,0 +1,14 @@
+---
+title: "MCP access logs"
+description: "Review OAuth connections, personal access tokens, and external MCP client activity in a workspace."
+---
+
+This page is a work in progress.
+
+External MCP clients connect to Tracecat and call tools as a real user. Review their connections, tokens, and activity from the workspace sidebar under **MCP access**.
+
+## Related pages
+
+- See [Organization audit logs](/audit-logs/organization) to stream token issuance and revocation to your SIEM.
+- See [Platform audit logs](/audit-logs/platform) to capture administration above the organization boundary.
+- See [Architecture](/security/architecture) for the permission model behind MCP connections.

docs/audit-logs/organization.mdx

@@ -1,11 +1,17 @@
 ---
 title: "Organization audit logs"
 description: "Stream organization audit events to an HTTPS webhook and shape each request for your log collector."
+keywords: ["organization audit", "detection", "audit webhook", "SIEM", "approval"]
 ---
 
+import AuditEventFields from "/snippets/audit-event-fields.mdx";
+
 Send organization audit events to an external log collector over HTTPS.
 You must be an organization administrator to configure the endpoint.
 
+Each event answers one question: which identity changed which resource, from where, and did it work.
+Use the stream to detect privilege changes, credential access, agent configuration drift, and approval decisions on agent tool calls.
+
 ## Connect a log collector
 
 <Steps>
@@ -56,39 +62,125 @@ An audit event contains the actor, affected resource, action, result, and scope.
   "actor_id": "00000000-0000-4000-8000-000000000003",
   "actor_label": "avery@example.com",
   "ip_address": "192.0.2.10",
+  "user_agent": "Mozilla/5.0",
   "resource_type": "workflow",
   "resource_id": "00000000-0000-4000-8000-000000000004",
   "action": "update",
   "status": "SUCCESS",
-  "data": null,
+  "data": {
+    "changed_fields": ["title"]
+  },
   "created_at": "2026-01-15T14:03:12.123456Z"
 }
 ```
 
-| Field | Description |
-| --- | --- |
-| `organization_id` | Organization that owns the event. |
-| `workspace_id` | Workspace that owns the resource, when applicable. |
-| `actor_type` | `USER` or `SERVICE_ACCOUNT`. |
-| `actor_id` | ID of the user or service account that performed the action. |
-| `actor_label` | User email or service account name, when available. |
-| `ip_address` | Source IP address, when available. |
-| `resource_type` | Type of resource affected by the action. |
-| `resource_id` | ID of the affected resource, when available. |
-| `action` | Operation performed on the resource. |
-| `status` | `ATTEMPT`, `SUCCESS`, or `FAILURE`. |
-| `data` | Additional event-specific context, when available. |
-| `created_at` | UTC timestamp for the event. |
+<AuditEventFields />
+
+### Attribution
+
+`actor_type` distinguishes a human from automation.
+`USER` events carry the account's email in `actor_label`, and `SERVICE_ACCOUNT` events carry the service account's name.
+
+Alert on service accounts performing actions that only humans should perform, such as `create` on `rbac_user_assignment` or on `service_account_api_key`.
+Treat `actor_id` as the stable join key; `actor_label` is a display value that changes when a user's email changes.
+
+### Scope
+
+`organization_id` identifies the tenant and `workspace_id` identifies the workspace that owns the affected resource.
+Organization-level resources such as `organization_member` and `rbac_role` have no workspace, so `workspace_id` is `null`.
+
+If you index platform and organization events together, filter on `organization_id` being non-null to isolate tenant activity.
+
+### Status lifecycle
 
 Most audited changes emit an `ATTEMPT` event followed by `SUCCESS` or `FAILURE`.
-Your endpoint should return a successful response within 10 seconds; delivery failures do not block the audited action.
+
+The pair is what makes failed activity detectable.
+An `ATTEMPT` with no matching terminal event points at a request that died mid-flight, and a burst of `FAILURE` events from one `actor_id` or `ip_address` is a probing signal worth alerting on.
+
+Join the pair on `actor_id`, `resource_type`, `resource_id`, and adjacent `created_at` values.
+
+## Approval decisions
+
+Accepting or rejecting an agent tool call emits one `agent_approval` event per tool decision.
+Only authenticated Tracecat UI and API decisions are attributed this way.
+
+Each event records the approver as the actor, along with the decision time, the decision source, the tool identifiers, the outcome, whether the arguments were overridden, and an optional sanitized denial reason.
+
+These events tell you who authorized a side effect and when.
+Alert on approvals of high-impact tools, on a single approver clearing an unusual volume of calls, and on overridden arguments.
+
+## Event categories for detections
+
+| Category | Representative resource types | Why it matters |
+| --- | --- | --- |
+| Identity and access | `user`, `auth`, `organization_member`, `organization_session`, `organization_invitation` | Account lifecycle, sign-in, and membership changes. |
+| Privilege | `rbac_role`, `rbac_group`, `rbac_group_member`, `rbac_assignment`, `rbac_user_assignment`, `rbac_scope` | Grants and revocations that change what an identity can do. |
+| Non-human identity | `service_account`, `service_account_api_key`, `mcp_personal_access_token`, `webhook_api_key` | Credentials that act without a human session. |
+| Secrets | `secret`, `organization_secret`, `workspace_variable` | Access to and rotation of stored credentials. |
+| Agent configuration | `agent_preset`, `agent_catalog`, `agent_model_access`, `agent_custom_provider`, `agent_session` | Changes to what agents may call and which models they reach. |
+| Automation | `workflow`, `workflow_execution`, `schedule`, `webhook`, `case_trigger` | Changes to what runs, when, and on whose behalf. |
+| Configuration | `organization_setting`, `organization_domain`, `organization_tier` | Tenant-wide settings, including this audit sink. |
+| Case data | `case`, `case_comment`, `table`, `table_column` | Access to and modification of investigation data. |
+
+Start with three detections: privilege grants outside a change window, non-human credential creation, and any `update` to `organization_setting` that touches the audit webhook.
+
+## Privacy boundaries
+
+Audit events describe operations, not content.
+Tracecat drops unrecognized metadata keys and also drops an otherwise allowed field when its value matches a credential pattern.
+
+Audit events never include:
+
+- Prompts or agent instructions.
+- Tool call arguments, override values, or tool outputs.
+- Credentials, tokens, or secret values.
+- Arbitrary resource contents, names, or descriptions.
+- Request or response bodies, headers, or before-and-after snapshots.
+
+The `data` object carries only stable `*_id` and `*_ids` identifiers, `changed_fields` names, boolean state flags, numeric counts, and a small set of operation discriminators.
+This means you can tell that a secret was rotated and which fields changed, but not what the value was.
+
+`actor_label`, `ip_address`, and `user_agent` are the fields that carry PII and client metadata.
+They are modeled separately from `data` so you can reason about them under your own retention policy.
+
+If you need prompt, tool, or model-level detail, use [Organization agent logs](/audit-logs/agents) instead.
+That signal is disabled by default and has its own privacy controls.
+
+## Delivery behavior
+
+Tracecat posts each event as a JSON `POST` request and never blocks the audited action on the result.
+
+- Delivery runs in the background, so a failing or slow collector does not prevent a user's change from completing.
+- Each request times out after 10 seconds.
+- Tracecat retries up to three times with exponential backoff on `429`, `500`, `502`, `503`, `504`, and transport errors. Other `4xx` responses are terminal.
+- Under sustained backpressure Tracecat sheds events rather than buffering without bound.
+
+Delivery is best-effort.
+Treat the stream as a detection source rather than a guaranteed-complete ledger, and monitor for continuity gaps if you need to catch a silently failing sink.
+
+## Ingest into a SIEM
+
+Point the webhook directly at an HTTPS ingest endpoint, or at a collector you control.
+
+Send directly when your SIEM accepts authenticated JSON over HTTPS and you do not need transformation.
+Set the vendor's auth header as a custom header, and use the payload attribute when the vendor expects a wrapper key such as `event`.
+
+Put a collector in front when you need queuing and replay across SIEM outages, field normalization to a schema such as OCSF or ECS, routing to more than one destination, or an audit trail of what was forwarded.
+
+Tag the source with a custom payload when several Tracecat streams land in one index, for example `{"tracecat_sink": "organization"}`.
 
 ## Update or disconnect the endpoint
 
 Return to **Organization → Audit Logs** to update the request settings.
 Click the disconnect button to stop sending new organization audit events.
 
+Changing the endpoint is itself an audited `organization_setting` update, so your existing collector records the change before the stream moves.
+
 ## Related pages
 
-- See [Security architecture](/security/architecture) for the platform, agent, approval, and telemetry boundaries around audit events.
+- See [Platform audit logs](/audit-logs/platform) to capture administration above the organization boundary.
+- See [Organization agent logs](/audit-logs/agents) to export telemetry for agent runs.
+- See [MCP access logs](/audit-logs/mcp-access) to review external MCP clients acting as your users.
+- See [Architecture](/security/architecture) for the platform, agent, approval, and telemetry boundaries around audit events.
 - See [Security](/self-hosting/security) for deployment hardening guidance.

docs/audit-logs/platform.mdx

@@ -0,0 +1,118 @@
+---
+title: "Platform audit logs"
+description: "Stream platform administrator actions to an HTTPS webhook and separate them from organization audit events."
+keywords: ["platform audit", "superuser", "audit webhook", "SIEM"]
+---
+
+import AuditEventFields from "/snippets/audit-event-fields.mdx";
+
+<Badge icon="lock" color="blue" size="lg" shape="pill">Enterprise Edition</Badge>
+
+Platform audit logs record what platform administrators do above the organization boundary.
+Use them to detect changes that no organization audit stream can see, such as a new organization, a promoted superuser, or a rewritten platform setting.
+
+You must be a platform superuser to configure the endpoint. These events go to their own sink, separate from every organization webhook.
+
+## Connect a log collector
+
+<Steps>
+  <Step title="Open platform administration">
+    Open **Admin**, then select **Audit Logs** under **Platform**.
+  </Step>
+  <Step title="Connect the endpoint">
+    Click **Connect** and enter the HTTPS URL that accepts your audit events.
+  </Step>
+  <Step title="Configure the request">
+    Add any headers your collector requires. You can also merge custom JSON into every event, wrap the payload under a key such as `event`, and control TLS certificate verification.
+  </Step>
+  <Step title="Save and verify delivery">
+    Click **Save changes**, then confirm that your collector receives a `platform_setting` event with a `SUCCESS` status.
+  </Step>
+</Steps>
+
+Tracecat encrypts the webhook URL, custom headers, and custom payload at rest.
+
+## Covered actions
+
+Platform events cover administration performed through the platform boundary.
+
+| Resource type | Actions | What it tells you |
+| --- | --- | --- |
+| `platform_setting` | `update` | A platform-wide setting changed, including the audit sink itself. |
+| `user` | `create`, `delete`, `promote`, `demote` | A platform account was created or removed, or superuser access was granted or withdrawn. |
+| `organization` | `create`, `update`, `delete` | A tenant was provisioned, reconfigured, or removed. |
+| `organization_tier` | `update` | An organization's tier assignment changed. |
+| `tier` | `create`, `update`, `delete` | A tier definition changed, altering limits for every organization on it. |
+| `platform_registry` | `sync` | Registry content was synchronized, which changes the integration code available to tenants. |
+
+Treat `user` `promote` and `platform_setting` `update` as your highest-signal events.
+Promotion grants access above every tenant boundary, and a settings update can redirect this audit stream.
+
+## Event payload
+
+A platform event uses the same schema as an organization event, with platform-scope identifiers left null.
+
+```json
+{
+  "organization_id": null,
+  "workspace_id": null,
+  "actor_type": "USER",
+  "actor_id": "00000000-0000-4000-8000-000000000003",
+  "actor_label": "admin@example.com",
+  "ip_address": "192.0.2.10",
+  "user_agent": "Mozilla/5.0",
+  "resource_type": "platform_setting",
+  "resource_id": null,
+  "action": "update",
+  "status": "SUCCESS",
+  "data": {
+    "changed_fields": ["audit_webhook_url"]
+  },
+  "created_at": "2026-01-15T14:03:12.123456Z"
+}
+```
+
+<AuditEventFields />
+
+Platform administrators act outside any tenant, so `organization_id` and `workspace_id` are `null` on platform events.
+Filter on that pair to separate platform administration from tenant activity when both streams reach the same index.
+
+Some actions carry no single affected row, so `resource_id` can be `null`.
+Correlate those events on `actor_id`, `resource_type`, and `created_at` instead.
+
+## Delivery behavior
+
+Tracecat posts each event as a JSON `POST` request and does not block the audited action on the result.
+
+- Delivery runs in the background. A failing or slow collector never prevents an administrator's change from completing.
+- Each request times out after 10 seconds.
+- Tracecat retries up to three times with exponential backoff on `429`, `500`, `502`, `503`, `504`, and transport errors. Other `4xx` responses are terminal.
+- Under sustained backpressure Tracecat sheds events rather than buffering without bound.
+
+Delivery is best-effort, so treat the stream as a detection source rather than a guaranteed-complete ledger.
+Alert on gaps in `created_at` continuity if you need to catch a silently failing sink.
+
+## Send events to a SIEM
+
+Point the webhook at an HTTPS ingest endpoint and authenticate with custom headers.
+
+- Splunk HTTP Event Collector: set `Authorization: Splunk <token>` and wrap the payload under `event`.
+- Elastic and OpenSearch: post to a data-stream ingest endpoint and set `Authorization` to your API key.
+- Datadog: set `DD-API-KEY` and post to the logs intake endpoint.
+- Collector in front of a SIEM: post to your own HTTPS listener when you need queuing, replay, or enrichment that a direct sink cannot provide.
+
+Use a custom payload to tag the source when several Tracecat streams land in one index, for example `{"tracecat_sink": "platform"}`.
+
+## Keep the platform sink separate
+
+The platform sink is configured independently and is never derived from an organization's settings.
+Organization administrators cannot read it, change it, or receive its events.
+
+Keep the two streams separate in your SIEM as well.
+Platform events describe changes to the tenancy boundary itself, so an organization administrator who could see or alter them would gain visibility above their own tenant.
+
+## Related pages
+
+- See [Organization audit logs](/audit-logs/organization) to stream user and service-account activity inside an organization.
+- See [Architecture](/security/architecture) for the boundaries that platform audit events record.
+- See [Self-hosted security](/self-hosting/security) for deployment hardening guidance.

docs/docs.json

@@ -96,13 +96,6 @@
               "agents/secrets-variables"
             ]
           },
-          {
-            "group": "Security",
-            "icon": "shield-check",
-            "pages": [
-              "security/architecture"
-            ]
-          },
           {
             "group": "Building custom actions",
             "icon": "blocks",
@@ -136,10 +129,14 @@
             ]
           },
           {
-            "group": "Audit logs",
-            "icon": "logs",
+            "group": "Security",
+            "icon": "shield-check",
             "pages": [
-              "audit-logs/organization"
+              "security/architecture",
+              "audit-logs/platform",
+              "audit-logs/organization",
+              "audit-logs/agents",
+              "audit-logs/mcp-access"
             ]
           }
         ]