Skip to main content
Tracecat’s security design rests on seven control areas:
  • Identity: SSO, SCIM provisioning, and role-based access control at organization and workspace level.
  • Data security: row-level tenant isolation, encrypted credentials, and encrypted workflow payloads.
  • AI agent security: default-deny tool policy, durable human approval, and token budgets.
  • Sandboxed execution: nsjail isolation for custom Python, agent-generated code, and local MCP servers.
  • Auditability: platform and organization audit webhooks, agent telemetry, and workspace MCP access records.
  • Change management: roll back custom integrations to any commit, and review and revert workspace configuration — workflows, agents, skills, tables, and case fields — in your own Git repository.
  • Dependencies: lockfile-pinned core registry dependencies, per-commit builds of custom registry dependencies, and sandboxed execution for both.
This page covers Tracecat Cloud and hardened self-hosted deployments. Tracecat runs customer-authored code and agents on multi-tenant infrastructure, so every execution path is sandboxed. That code then acts with privileged access to your systems, so credentials are encrypted at rest, resolved at execution time, and attached by trusted proxies rather than handed to a model.

​
Threat model

This threat model covers the complete Tracecat platform. It separates conventional platform threats from AI-specific threats.

​
Protected assets

  • Organization and workspace data.
  • Agent and automation configuration.
  • User and service-account identity.
  • API, OAuth, MCP, and LLM provider credentials.
  • External systems reachable through tools.
  • Control-plane and executor infrastructure.
  • Workflow and agent inputs and outputs.
  • Audit records and agent telemetry.

​
Within Tracecat boundary

​
Platform and application threats

Threat actors and untrusted sources include:
  • External attackers targeting API, authentication, OAuth, or MCP endpoints.
  • Compromised tenant accounts submitting code or workloads.
  • Compromised administrators, service accounts, personal access tokens, or OAuth grants.
  • Malicious packages, custom registry content, and local MCP processes.
  • Attackers targeting the control plane, executor, durable state, or object storage.
Custom code runs on shared infrastructure, so isolation cannot depend on that code being correct. A logic bug, a compromised dependency, and a compromised tenant account all produce the same class of outcome: a process reading another run’s data, reaching a platform service, or consuming shared capacity. The sandbox bounds all three identically, which is why the boundary does not rely on reviewing the workflow author’s intent.

​
AI threats

Threat actors and untrusted sources include:
  • Attackers who control prompts, alerts, email, cases, retrieved documents, or tool results.
  • Users who try to steer an agent beyond their intended task or authorization.
  • Compromised LLM, API, or remote MCP providers.
  • Unsafe LLM output, generated code, tool selection, or resource consumption.
Tracecat treats the LLM as an untrusted decision-maker. It can propose a tool call and generate code. It cannot grant itself a role, approve its own call, resolve a brokered secret, or change sandbox policy.

​
Outside Tracecat boundary

You own controls for systems that Tracecat does not operate. Use these references to harden systems outside Tracecat:

​
OWASP alignment

This page maps Tracecat controls to three OWASP risk lists: The mapping identifies relevant categories. It does not represent OWASP certification.

​
Identity

A01 A07 ASI03 Tracecat authenticates every API and MCP request before it resolves tenant context, so an unauthenticated caller never reaches a tenant lookup. Holding a valid credential establishes who you are; it does not decide what you can reach.

​
Single sign-on and provisioning

  • SAML and OIDC authenticate users against your identity provider. Basic auth is available for deployments that do not use one.
  • SCIM provisions and deprovisions accounts from the directory, so access is removed at the source when someone leaves.
  • SCIM also syncs directory groups to Tracecat groups, which is what makes group-based role assignment worth using.
See SAML SSO and OIDC for connection steps.

​
Role-based access control

A scope is one permission on one resource, named resource:action following OAuth 2.0 convention. The prefix carries the level: Roles bundle scopes:
  • Built-in roles cover the common cases: organization-owner, organization-admin, organization-member, workspace-admin, workspace-editor, workspace-viewer.
  • You can define custom roles, and custom scopes alongside the platform-defined set, when the built-in roles do not fit.
Roles are assigned to a group or directly to a user. Each assignment is either organization-wide or bound to a single workspace, and a user’s effective permission is the union of both. That means an organization-wide assignment applies in every workspace, while a workspace assignment grants nothing outside it. Service accounts are scoped directly rather than through roles, and are bounded two ways: they can only hold scopes from an allowlist for their kind, and nobody can grant a service account a scope they do not themselves hold.

​
Data security

A04

​
Tenant isolation

Tenant scope is enforced in the application layer and again by PostgreSQL row-level security on tenant-owned tables. The second layer is the one that matters under failure: a missed application check does not by itself return another tenant’s rows.

​
Credentials and sensitive settings

Tracecat presents stored credentials to external systems at execution time, so credential storage has to be reversible. Anything that never needs replaying is stored one-way instead. Reversible encryption uses Fernet, which is AES-128-CBC with an HMAC-SHA256 authentication tag, keyed by TRACECAT__DB_ENCRYPTION_KEY. Ciphertext is authenticated, so tampering fails to decrypt rather than yielding altered plaintext. It covers:
  • Workspace, organization, and platform secrets.
  • OAuth and integration credentials, including access tokens, refresh tokens, and client secrets.
  • Remote MCP server headers and stdio MCP environment variables.
  • Custom LLM provider credentials and Slack agent-channel credentials.
  • Organization and platform settings marked sensitive, including the audit webhook URL, its headers, and its custom payload.
API tokens are not encrypted, because Tracecat never needs to read one back:
  • Service account API keys, MCP personal access tokens, and webhook API keys are stored as a salted BLAKE2b digest. Tracecat verifies a presented token in constant time and cannot recover the original.
  • The raw token is returned exactly once, at creation. Only a short preview prefix is kept so you can identify it later.
  • A lost token is replaced by rotation, never by retrieval.
Credentials in MCP commands and URLs are stored in cleartextThe stdio MCP command and its arguments, and the remote MCP server URI, are not encrypted. Put credentials in environment variables or headers, which are, rather than inline in an argument or a query string.

​
Workflow payloads and durable state

Temporal persists workflow and agent inputs and outputs for the life of an execution history, so payload protection is separate from database encryption.
  • Payloads are encrypted with AES-256-GCM by a Tracecat-side codec before Temporal stores anything, so Temporal only ever holds ciphertext.
  • Each workspace gets a distinct key, derived with HKDF-SHA256 from a versioned root secret using the workspace ID as derivation context. One workspace’s key does not decrypt another’s payloads.
  • The keyring is versioned. Rotation issues a new key ID, and existing histories stay readable under the ID they were written with.
  • Secret values are masked as *** in action results, and masking runs before the result is persisted, so history holds the masked form.
  • Large triggers and action results move to object storage automatically. Workflow state keeps a scoped reference, which bounds how much data one run pushes through durable history.
Two limits are worth knowing. Masking is literal substring replacement, so an encoded or otherwise transformed copy of a secret is not caught. Payload encryption is a deployment setting (TEMPORAL__PAYLOAD_ENCRYPTION_ENABLED) that is off by default — enable it wherever Temporal history can hold sensitive data.

​
Encryption keys

Tracecat generates no key material of its own. You provision two things and supply them to the deployment: TRACECAT__DB_ENCRYPTION_KEY, the Fernet key behind credential encryption, and the Temporal payload keyring behind workflow history encryption. Store both in the secret manager your platform already provides, and keep them out of application configuration and version control. On Kubernetes, the recommended production deployment, use a Kubernetes Secret synced from your own secret manager by External Secrets Operator rather than one created by hand. On AWS Fargate, use AWS Secrets Manager: ECS injects the core secrets into the container at task launch, and the task role fetches the keyring at runtime so it never appears in a task definition. On Docker Compose, treat the .env file as the sensitive artifact: restrict it to the service account that runs Tracecat and keep it out of version control. Move to Kubernetes for a managed secret store and the full sandbox boundary.
TRACECAT__DB_ENCRYPTION_KEY cannot be rotatedTracecat encrypts under a single Fernet key and has no re-encryption path. Changing or losing the key makes every stored credential unrecoverable. Back it up, and restrict access to it at least as tightly as the credentials it protects.
See Platform secrets for per-deployment storage and rotation, and Secrets management for the Helm wiring.

​
External secrets

A04 LLM02 ASI03 The subsections above cover how credentials are stored. This one covers how a value reaches running code, and the boundary differs between workflow actions and agents. Tracecat stores credential metadata and resolves values at execution time, in trusted services only:
  • The executor, for the secrets a workflow action declares.
  • The agent tool runner, for secret expressions in tool arguments.
  • The trusted MCP server, which resolves remote HTTP MCP headers per call.
  • The LLM gateway, which attaches provider credentials per request.
  • The preset service, for stdio MCP environment values.
None of these services runs inside the agent sandbox, and no credential value is persisted in workflow state. You can keep workspace and integration credentials in AWS Secrets Manager instead of Tracecat.

​
Workflow actions

An action receives the secrets it declares or references, injected into its sandbox at dispatch. The sandbox bounds what the action can reach — the host, the database, other runs — rather than hiding the credential from code that needs it. core.script.run_python receives no ambient workspace secrets. Your script sees only what you pass through env_vars or Action inputs. See Secrets for how actions declare and reference secrets.

​
Agents

Agent-controlled code runs in the same sandbox as the agent, so any credential placed inside that sandbox is readable by whatever the model generates. Tracecat keeps credential values out of the agent sandbox.
  • The sandbox receives short-lived JWTs scoped to the run, workspace, model, and allowed tools.
  • Trusted services validate those claims before resolving a provider credential.
  • Trusted proxies attach credentials to API, LLM, and remote HTTP MCP calls outside the sandbox.
  • The LLM receives typed interfaces and results; Tracecat never places a stored credential value into model context. Secret expressions in tool arguments resolve outside the sandbox, after the model responds.
Local stdio MCP is the exception. Its credentials enter the shared sandbox, so treat them as readable by agent-controlled code.

​
Agent and MCP control plane

​
Default-deny tool policy

A01 LLM06 ASI02 Hostile instructions hidden in an alert, email, case, or tool result can redirect an agent toward a tool the operator never intended it to call. Tool selection is therefore not the model’s decision to make. Agents discover only the tools allowed by identity and workspace scope, and agent configuration narrows that set further. An explicit deny overrides an allow. Every policy decision resolves to one of three outcomes:
  • Allow: Run the tool through the trusted proxy or stdio process.
  • Deny: Block the call before credentials resolve or side effects occur.
  • Require approval: Create a durable request and pause before execution.
The trusted proxy rechecks Tracecat and remote HTTP MCP calls before executing them, so a request the agent fabricates is rejected outside the sandbox rather than trusted because it arrived. Local stdio MCP is checked against the captured inventory only and does not get this second check.

​
Token budget

LLM10 ASI08 An agent stuck in a reasoning loop, or steered into one, can issue model requests until it exhausts your inference budget. A fixed cap on LLM requests or tool calls does not contain this, because legitimate multi-step work has no predictable call count. Tracecat bounds consumption by tokens instead:
  • Total token budget: Caps cumulative LLM token usage for the run.
  • Token burn-rate limit: Caps how fast the run consumes that budget, which stops runaway loops before the total is spent.
Sandbox wall-time and resource limits contain execution independently, and tool policy and approval continue to govern side effects.

​
Durable human approval

A01 A06 LLM06 ASI02 ASI09 An approval gate only holds if the decision survives worker restarts and retries, and if no other path can resume the tool without a recorded decision. Temporal persists the agent at the approval boundary and the tool waits for an authorized acceptance. The decision stays attached to the run and tool call across retries and worker restarts, and Tracecat authorizes the call only when the recorded decision permits it. Each authenticated accept or reject emits one audit event identifying the approver, the tool, and the outcome. Tool arguments, override values, prompts, and tool outputs are never included.

​
External MCP connections

External MCP clients such as coding agents authenticate to Tracecat and call tools with a real user’s authority, which makes connection sprawl an access-review problem.
  • OAuth connections inherit the user’s effective Tracecat permissions.
  • Personal access tokens remain workspace-scoped.
  • The MCP access page groups connections, tokens, and external tool calls by user.
  • Per-profile scope reduction below user permissions is planned.

​
Trusted agent execution

A05 A06 ASI05 ASI08 Custom Python actions, agents, agent-generated code, and local MCP processes all execute code that Tracecat did not write, on infrastructure shared between tenants. Containment therefore cannot depend on that code being correct. nsjail is the boundary. It runs by default on full-isolation profiles and applies to tenant code, third-party packages, and generated output alike. The sandbox exposes only the files and broker interfaces the run needs. General automation actions use their configured executor network policy instead. These controls bound the blast radius of compromised output or third-party code. They do not make untrusted code safe outside a supported sandbox profile.

​
Sandboxed MCP

A03 A08 LLM03 ASI04 A third-party MCP server is untrusted code with a tool description attached. Where it runs decides what it can reach. Remote MCP servers run outside the agent sandbox, and the trusted proxy authenticates each call and returns the result. stdio MCP servers run as child processes inside the agent sandbox and inherit its filesystem, network, time, resource, and identity boundaries. Local MCP is a containment boundary, not a policy boundary. Agent-generated code inside the sandbox can invoke a local server’s executable directly. Use remote HTTP MCP when every call must be rechecked at the trusted proxy.
stdio MCP limitations
  • Approval gates do not support stdio tools. Use remote HTTP MCP for approved calls.
  • Enabling stdio requires network access for the whole agent sandbox.
  • The agent and stdio process share one execution identity.
  • stdio credentials enter the shared sandbox.

​
Trusted API and LLM gateways

A credential pasted into a prompt is a credential in model context, in provider logs, and in any telemetry that captures prompts. Tracecat resolves secrets referenced by preset-agent Expressions only after a request passes policy, and adds API, OAuth, MCP, and LLM credentials at the proxy outside the sandbox. The agent receives the typed result rather than the credential. You can use the managed LLM gateway, an OpenAI-compatible provider, or route LLM traffic through your own proxy.
Keep credentials out of agent inputs
  • Do not place credentials directly in prompts or agent inputs.
  • Use Tracecat Expressions to reference secrets in preset-agent instructions.
See Secrets and variables to learn how to pass secrets securely to preset agents through Expressions.

​
Audit logs

A09 Tracecat separates audit signals by administrative scope and runtime source.
Audit events record operations, not content.
  • data carries only stable identifiers, changed-field names, boolean state flags, counts, and a small set of operation discriminators. Tracecat drops unrecognized keys, and drops an allowed field when its value matches a credential pattern.
  • Prompts, tool arguments, tool outputs, credentials, and resource contents never appear in an audit event.
  • actor_label, ip_address, and user_agent are modeled as separate fields, so you can apply your own retention policy to them.
  • Use Organization agent logs when you need prompt, tool, or model-level detail.

​
Change management

A08 LLM03 ASI04 A configuration change persists beyond the session that made it, so an account compromise can outlive the access that caused it.

​
Actions registry

A custom registry rolls back to any commit: each sync creates an immutable version identified by the source commit, and you can sync to any commit or promote any earlier version from the UI or the API. Tracecat blocks deletion of a version that published workflows still reference. Rollback is predictable for workflows you publish in Tracecat. Publishing records a registry lock mapping each registry origin to the version current at publish time, and every execution resolves actions from that lock, so neither a sync nor a rollback changes what the published workflow runs. Workflows imported through workspace sync carry no registry lock, so every execution resolves their actions against the current registry version. Republish an imported workflow in Tracecat to pin it.
Republish a workflow to adopt newly synced actions, even when the workflow itself has not changed. Imported workflows are not pinned until you republish them.
The core registry tracks the Tracecat release version and updates when you upgrade Tracecat. Earlier core versions stay available to workflows that pinned them. See Custom registry for repository setup, sync, and commit selection.

​
Workspace GitOps

Workspace sync exports workflows, agent presets, skills, tables, case tags, case fields, case dropdowns, case durations, and variables to a GitHub or GitLab repository you own. Secrets sync as key names only — values never leave Tracecat.
  • Build and test in a staging workspace, then export the workspace as a pull request.
  • Review in your Git repository, where branch protection and signing apply.
  • Merge to your default branch.
  • Pull that commit into the production workspace.
  • Use workspace-level RBAC so the people who author in staging are not the people who pull into production.
Every pull targets an explicit commit, so imports are reproducible and rollback is a pull of an earlier commit. Tracecat does not pull in the background — to automate promotion, call the sync API from your CI/CD pipeline with a service account.
A pull reproduces workspace configuration, not action versions. Imported workflows carry no registry lock, so each execution resolves actions against the target workspace’s current core and custom registry versions until you publish the workflow there.

​
Dependencies

A03 A08 LLM03 ASI04 Core registry dependencies resolve from a committed lockfile that pins exact versions, and the executor runs that resolved set. The same dependency tree runs on every executor. Custom registry dependencies are yours. Tracecat resolves them from your repository’s pyproject.toml at sync time and builds the result into the version artifact for that commit — it does not pin, scan, or review them on your behalf. Custom registry code runs in the same sandbox as core actions, at sync and at execution. The sandbox bounds what a compromised dependency can reach without making it safe. Pin your dependencies, review changes in the registry repository, and apply the same branch protection you use for production code. See Custom registry for how to declare dependencies in your registry repository’s pyproject.toml.

​
Deployment profiles