docs: overhaul security, isolation, and audit log documentation

docs/agents/secrets-variables.mdx

@@ -15,7 +15,7 @@ Preset agent tool calls go through a secure server-side proxy.
 The LLM only sees the raw expression placeholder (e.g. `${{ SECRETS.threatintel.API_KEY }}`). The actual secret values are injected server-side at the tool execution layer after the model responds, so the LLM never has access to your credentials.
 
 <Warning>
-`ai.action` and `ai.agent` actions do **not** support secure secrets injection. Secret and variable expressions are evaluated immediately in workflow action inputs and will be exposed to the LLM.
+Do not use `SECRETS` expressions — or any expression that resolves to a value you would not send to your LLM provider — in `ai.action` or `ai.agent` inputs. Use `ai.preset_agent` for secure secrets injection.
 </Warning>
 
 ## Secrets

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 gateway 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,18 @@
 ---
 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 AuditDeliveryBehavior from "/snippets/audit-delivery-behavior.mdx";
+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 changes, agent configuration drift, and approval decisions on agent tool calls.
+
 ## Connect a log collector
 
 <Steps>
@@ -23,11 +30,7 @@ You must be an organization administrator to configure the endpoint.
   <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 an
-    `organization_setting` event with a `SUCCESS` status.
+    certificate verification, then click **Save changes**.
   </Step>
 </Steps>
 
@@ -56,39 +59,115 @@ 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.
+
+A burst of `FAILURE` events from one `actor_id` or `ip_address` is a probing signal worth alerting on. An `ATTEMPT` with no matching terminal event is a weaker signal — the terminal event may have been shed or lost in delivery rather than the request failing.
+
+## 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` | Creation, rotation, and deletion 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 two detections: privilege grants outside a change window and non-human credential creation.
+
+## 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
+
+<AuditDeliveryBehavior />
+
+## 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.
+Events can continue to reach the old endpoint for up to 30 seconds after the change while cached settings expire.
+
 ## 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,110 @@
+---
+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 AuditDeliveryBehavior from "/snippets/audit-delivery-behavior.mdx";
+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, then click **Save changes**.
+  </Step>
+</Steps>
+
+Tracecat encrypts the webhook URL, custom headers, and custom payload at rest.
+
+Events can continue to reach the old endpoint for up to 30 seconds after an endpoint change while cached settings expire.
+
+## 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": null,
+  "created_at": "2026-01-15T14:03:12.123456Z"
+}
+```
+
+For platform settings updates, `data` is `null`, so the event tells you who made the change and whether it succeeded, but not which setting changed.
+
+<AuditEventFields />
+
+Platform events normally carry `null` `organization_id` and `workspace_id` because Tracecat emits them with a platform role.
+Organization-scoped sign-in is the exception: its `auth` `sign_in` event reaches both sinks, and the platform copy carries the organization's ID.
+
+Do not filter strictly on null scope to separate platform administration from tenant activity — that drops those sign-in events.
+Tag each stream with a custom payload instead when both reach the same index.
+
+## Delivery behavior
+
+<AuditDeliveryBehavior />
+
+## 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"
             ]
           }
         ]