docs: overhaul security, isolation, and audit log documentation - #3166
Conversation
topher-lo
added
docs
|
✅ No security or compliance issues detected. Reviewed everything up to f89d182. Security Overview
Detected Code Changes
|
|
Preview deployment for your docs. Learn more about Mintlify Previews.
💡 Tip: Enable Workflows to automatically generate PRs for you. |
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 516753e33e
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
516753e to
4f03180
Compare
4f03180 to
bb1edba
Compare
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: bb1edba07d
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
Add a platform audit log page and expand the organization audit page for detection engineers with attribution, scope, approval, and privacy detail. Rewrite the security architecture page to lead each control with the concrete threat it answers, and correct the Mermaid diagram: MCP access activity records inbound external MCP client calls, not outbound proxy calls. Section order is unchanged. Register agent logs and MCP access logs as work-in-progress stubs. Both depend on unmerged work (#2638, #2649, #2650) and will be written separately.
bb1edba to
5f40ee2
Compare
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 5f40ee2e0c
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
Add a Platform secrets section to the self-hosting security page covering the required cryptographic secrets, recommended storage per deployment target, and which secrets can be rotated. Add an Encryption keys section to the security architecture page linking the credential and Temporal payload keys to where they are provisioned, and note that TRACECAT__DB_ENCRYPTION_KEY has no re-encryption path. Cross-link the generate-secrets snippet to the new storage guidance.
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: a35985981a
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
Feature gap TODOsRecording what this PR's docs run ahead of, so it doesn't have to be re-derived from the review threads. In flight
Roadmapped for August
No owner yet
Note on terminology, since this PR documents both: Not a gap, and documented instead: workflows imported by workspace sync carry no registry lock and resolve actions against the target workspace's current registry versions. That is intended — publishing is what pins — and this PR adds a callout for it. |
|
Also worth flagging for whenever Two details matter for a security page specifically: content is redacted by default and only included if someone sets |
Remove or scope documented claims that did not match shipped behavior, and restructure change management around the two mechanisms it covers. Security architecture: - Drop the data-versus-instructions framing; no such separation exists. - Split change management into actions registry and workspace GitOps, leading with rollback and adding the promotion flow. - Scope the registry-lock guarantee to workflows published in Tracecat. Workspace sync imports carry no lock and resolve actions against the target workspace's current registry on every execution. - Split external secrets into workflow actions and agents. Workflow action sandboxes do receive secret values; agent sandboxes do not. - Name the trusted services that resolve credentials, rather than attributing resolution to the executor alone. - Add a dependencies section covering core lockfile pinning and customer-owned custom registry dependencies. - Name the agent telemetry component an OTLP gateway, and use OTel rather than OTEL in prose. Audit logs: - Remove the save-and-verify step. Audit settings are cached for 30 seconds without invalidation, so the save event cannot be observed at a newly configured collector. - Correct three retries to three total attempts. - Remove continuity-gap alerting and the attempt-to-terminal join, neither of which the event payload supports. - Remove the audit-sink-change detection. Grouped settings updates emit null data, so the event cannot identify which setting changed. - Correct the example payload to the data value actually emitted. - Document the org-scoped sign-in exception to null tenant scope on the platform sink. - Narrow credential detection to mutations. Secret reads are not audited. - Document duplicate delivery and the stale-endpoint window. - Extract the shared delivery behavior into a snippet. Self-hosting: - Replace the rotation bullets with a table covering overlap window, procedure, and blast radius per secret. - Correct the scope of USER_AUTH_SECRET and TRACECAT__SIGNING_SECRET. Agents: - Correct the secrets warning. Secret expressions in ai.action and ai.agent inputs are not exposed to the model.
![cubic-dev-ai[bot]](https://avatars.githubusercontent.com/in/1082092?s=60&v=4){kind=small}
There was a problem hiding this comment.
All reported issues were addressed across 12 files
Reply with feedback, questions, or to request a fix.
Re-trigger cubic
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: f89d182ad0
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
Split the run_python fallback log into two cases: nsjail disabled on purpose, and nsjail enabled but missing its binary or rootfs. These need different fixes. The old message advised setting TRACECAT__DISABLE_NSJAIL to false, which flips _is_nsjail_available() to true because the binary and rootfs ship in the image, so nsjail is then attempted and fails at runtime unless the container also has SYS_ADMIN, unconfined seccomp, unmasked system paths, and /dev/net/tun. Promote the message to a warning and emit it once per process. The previous guards were instance attributes on UnsafePidExecutor, which is rebuilt per call through SandboxService, so they fired on every invocation despite the intent. Drop the internal class name from the execution failure log. Mark PID-namespace isolation deprecated for removal before 1.0.0. It requires CAP_SYS_ADMIN so it rarely activates, it does not pass --mount-proc so /proc still lists other container processes, and its process-tree reaping is already covered by start_new_session with killpg in terminate_process_group.
Rename the self-hosting Execution sandboxing section to Isolation and replace the binary production callout with two levels, nsjail and none, plus coverage by code path. Without nsjail a custom registry action inherits the executor environment, which the previous text did not say. Add nsjail requirements, per-deployment enable steps for Docker Compose and Kubernetes, the log lines that reveal which level is running, best practices, and an isolation FAQ. Expand the Helm section with the rendered manifest diff for tracecat.sandbox.disableNsjail, cluster prerequisites for PodSecurity and the TUN device, the interaction where an ephemeral backend forces nsjail regardless of the flag, and the limits on customizing the profile. Add an Isolation subsection to the security architecture and name the isolation level for each deployment profile. Document TRACECAT__EXECUTOR_SANDBOX_ENABLED and the sandbox and agent sandbox timeout and memory variables.
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: ebe69f6298
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
Replace the grouped Event categories and Covered actions tables with one row per emitted event: 96 organization events and 22 platform events, each checked against its call site. Correct claims that did not match behavior. The Approval decisions section documented an agent_approval event that is never emitted, so it is removed; approvals persist to the approval table and surface through agent telemetry. user, organization_domain, and organization_tier were listed as organization events but are platform-only. workspace, workspace_invitation, tag, and organization delete were missing entirely. No rotate action exists for any secret type, and there are no read events at all. The platform table omitted five emitted resource types. Drop detection and alerting guidance from both pages. The event set still has coverage gaps, so recommending detections on it is premature. Give both pages the same six sections, and share the request options table as a snippet. Document why the payload attribute exists, since Splunk HTTP Event Collector requires each event wrapped in an event field. Drop the SIEM setup sections. Their vendor-specific guidance was not verified against behavior. Move the privacy approach into a callout on the security architecture page, scoped to what the metadata allowlist and credential-pattern dropping actually guarantee.
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: f6579d8c47
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| @@ -0,0 +1,15 @@ | |||
| | Field | Description | | |||
| | --- | --- | | |||
| | `organization_id` | Organization scope for an organization event. `null` for a platform event. | | |||
There was a problem hiding this comment.
Fresh evidence after the earlier null-scope finding was addressed: this shared table still states that every platform event has a null organization_id, even though the platform page now correctly documents that organization-scoped auth/sign_in copies retain the organization ID. Because this table renders on that same page, readers can still build a schema or filter that drops those events; qualify the field description with the sign-in exception.
AGENTS.md reference: docs/AGENTS.md:L52-L55
Useful? React with 👍 / 👎.
topher-lo
changed the title
The shared field table stated that organization_id is null on every platform event. The platform page documents the exception directly below it: an organization-scoped sign-in emits auth sign_in to both sinks, and the platform copy carries the organization ID. tracecat/auth/users.py:521-538 builds the audit role with organization_id set and emits to both sinks, so the flat claim was wrong. A reader could have built a schema or filter on null scope that silently drops those sign-in events.
Reverts the PID isolation deprecation and the isolation documentation rewrite. The code change is out of scope for a documentation PR, and the isolation pages enumerated what the sandbox does not cover, which does not belong in public customer docs. self-hosting/security keeps its existing Execution sandboxing section and backend table. The nsjail and executor backend configuration will be revisited separately. This reverts commit cdff1a8. This reverts commit ebe69f6.
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: b4ed520eb3
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
Drop the PID namespace isolation writeup. It described a fallback that is not a configuration anyone selects, and the claim that it prevents inspecting other processes via /proc was not accurate. State defaults per deployment target. The previous text gave the Docker Compose default as if it applied everywhere, while the Kubernetes page says the chart enables nsjail by default. Kubernetes defaults to nsjail, Docker Compose and AWS Fargate default to no isolation. Describe what running without isolation requires: it is a supported production configuration when you trust your own code, the dependencies your actions install, and the agents and tools you enable. Choose nsjail when you run code you have not reviewed.
Updates the inbound anchor in the TLS page, which was the only reference to the old heading.
1 participant
Summary
Splits audit logging into its own set of reference pages under Security, and rewrites the security architecture page for accuracy and concision.
Written:
audit-logs/platform(new) — platform-administrator webhook: setup, covered actions, payload schema with null org/workspace scope, delivery behavior, SIEM connection, and why the platform sink stays separate from organization sinks.audit-logs/organization(expanded) — detection-oriented detail: human vs service-account attribution, scope, theATTEMPT→SUCCESS/FAILURElifecycle,agent_approvalevents, event categories for detections, and explicit privacy boundaries.security/architecture(rewritten in place) — every control section now leads with the concrete attacker action before the boundary it enforces. Section order is byte-identical to the previous version.Work-in-progress stubs:
audit-logs/agentsandaudit-logs/mcp-accessare registered in navigation but left as stubs. Both describe unmerged work and will be written separately.Notable fixes
tools -. external MCP call .-> mcpActivity, implying MCP access logs record Tracecat's outbound proxy calls. They record inbound external client calls. Added anExternal MCP clientnode feeding the API and re-pointed the edge.snippets/audit-event-fields.mdxso the platform and organization pages cannot drift on the webhook schema.Dependencies
Content describing Agent OTel (#2638, #2649, #2650) and
agent_approvalaudit events (#3162) is not merged. The two affected pages are stubs; the architecture page references both features conceptually.LOC breakdown
docs.json)Validation
mint broken-links— no broken linksjq/json.toolondocs/docs.json— validgit diff --check— cleanmint dev: correct nav placement and order, correct "On this page" headings, Mermaid renders with no error (25 nodes / 32 edges), no console errorsSummary by cubic
Major overhaul of security docs: added platform and organization audit log pages, rewrote the architecture with a concrete threat model, documented platform secrets storage/rotation, and clarified sandbox isolation options and defaults. Navigation now groups all security content; added stubs for agent telemetry and MCP access logs.
New Features
organization_id/workspace_idarenullexcept org‑scoped sign‑ins; 30‑second stale‑endpoint window.user_agent; clearATTEMPT→SUCCESS/FAILURE; shared schema, delivery behavior, and request options.TRACECAT__DB_ENCRYPTION_KEYis non‑rotatable; cross‑linked fromsnippets/generate-secrets.mdx.nsjailand no‑isolation; defaults per target (Kubernetesnsjail; Docker Compose and AWS Fargate none); guidance on when to use each.Bug Fixes
agent_approval; corrected scopes (moveduser,organization_domain,organization_tierto platform; addedworkspace,workspace_invitation,tag,organizationdelete); confirmed no read/rotate events; shared request options and explained the payload attribute; documented delivery behavior (10‑second timeout, three total attempts, possible duplicates) and the 30‑second stale‑endpoint window; qualified theorganization_idexception in the shared fields table.TRACECAT__SIGNING_SECRET/USER_AUTH_SECRETscopes; adjusted agent secrets warning to avoid claiming exposure and recommendai.preset_agent.Written for commit 4f6b8ac. Summary will update on new commits.