Security

Infrastructure credentials

The default configuration ships with weak, well-known passwords for PostgreSQL, MinIO, and Redis. Replace them with strong, unique values before exposing Tracecat to production traffic.

# PostgreSQL
TRACECAT__POSTGRES_USER=tracecat
TRACECAT__POSTGRES_PASSWORD=<strong random password>

# Temporal PostgreSQL
TEMPORAL__POSTGRES_USER=temporal
TEMPORAL__POSTGRES_PASSWORD=<strong random password>

# MinIO / S3
MINIO_ROOT_USER=<strong random user>
MINIO_ROOT_PASSWORD=<strong random password>

# Redis — add a password and update the URL
REDIS_URL=redis://:<strong random password>@redis:6379

For Redis, you also need to pass the password to the container. Add a command override in your docker-compose.yml:

services:
  redis:
    command: ["redis-server", "--requirepass", "<same password as above>"]

In production, consider replacing self-hosted PostgreSQL and Redis with managed services (e.g., Amazon RDS, ElastiCache) that handle encryption at rest, automated backups, and credential rotation.

Platform secrets

Tracecat requires four cryptographic secrets, plus an optional keyring if you enable Temporal payload encryption.

Secret	Protects
`TRACECAT__DB_ENCRYPTION_KEY`	Fernet key for credentials and sensitive settings stored in PostgreSQL.
`TRACECAT__SERVICE_KEY`	Service-to-service JWT signing.
`TRACECAT__SIGNING_SECRET`	Webhook URL signing and HMAC operations.
`USER_AUTH_SECRET`	Password reset tokens, email verification, OAuth state, the MCP OIDC issuer keypair, and the internal OIDC client secret.
`TEMPORAL__PAYLOAD_ENCRYPTION_KEYRING`	Versioned keyring for Temporal payload encryption. Optional, and only read when `TEMPORAL__PAYLOAD_ENCRYPTION_ENABLED` is true.

Where to store them

Keep these out of your application configuration and out of version control. Use the mechanism your platform already provides.

Deployment	Recommended storage
AWS ECS Fargate	AWS Secrets Manager. Pass secret ARNs to Terraform; values are resolved at task launch and never appear in your `.tfvars`.
Kubernetes	External Secrets Operator syncing from your secret manager, or an existing Kubernetes Secret you create out of band.
Docker Compose	A `.env` file on the host. Restrict it to the service account that runs Tracecat and exclude it from version control.

On Kubernetes, prefer External Secrets Operator over a hand-created Secret. Your secret manager stays the source of truth, values are re-synced rather than copied, and no plaintext passes through a shell history or a manifest. Reserve chart-managed secret templates for pipelines that encrypt values at rest with Sealed Secrets or SOPS.

Rotation

Rotation support differs by secret, and the differences matter before you plan a rotation window.

TRACECAT__DB_ENCRYPTION_KEY cannot be rotatedTracecat encrypts under a single Fernet key with no re-encryption path. Changing it makes every stored credential unrecoverable, and there is no migration to re-key existing rows. Treat this key as permanent for the life of the deployment: back it up, and control access to it at least as tightly as the credentials it encrypts.

Secret	Overlap window	Rotation procedure	Blast radius
`TEMPORAL__PAYLOAD_ENCRYPTION_KEYRING`	Yes	Add a key and point `current_key_id` at it. Keep retired keys as long as their histories are retained.	None. Existing histories stay readable under the key they were written with.
`TRACECAT__SIGNING_SECRET`	No	Rotate, then reissue every affected URL.	Every webhook URL and agent channel endpoint URL. Breaks in-flight Slack OAuth installs, and pending Slack approval buttons for up to 24 hours.
`TRACECAT__SERVICE_KEY`	No	Restart every service that holds it in one window, including `ui`, which uses it for the SAML ACS proxy.	While services disagree, in-flight agent turns fail their next tool or LLM call, executor calls fail, and service-to-service requests return `401`. Miss `ui` and SSO login breaks.
`USER_AUTH_SECRET`	No	Restart `api` and `mcp` together.	Active MCP access tokens (1-hour lifetime), and in-flight password reset and verification links. Sessions are database-backed, so users are not logged out. MCP refresh tokens are hashed and survive.

Isolation

Tracecat executes user-defined Python scripts, custom actions, and agents inside the executor service. You choose between nsjail isolation and no isolation. Defaults differ by deployment target.

Deployment	Default
Kubernetes	nsjail sandbox. The chart applies the required security context to the executor pods.
Docker Compose	No isolation. `TRACECAT__DISABLE_NSJAIL=true` with the `direct` backend.
AWS Fargate	No isolation. Fargate cannot grant the capabilities nsjail requires.

nsjail sandbox (recommended for production)

For production, enable nsjail — a process isolation tool from Google that enforces:

Filesystem isolation — scripts can only access their job directory and explicitly mounted paths. The host filesystem is not visible.
Resource limits — CPU time, memory, file size, and process count are capped per execution. A runaway script cannot starve the host.
User namespace separation — scripts run as unprivileged users even when the container runs as root.
Network access — network is allowed (scripts need to reach databases, APIs, and S3) but constrained to the container’s network namespace.

To enable nsjail, set the following in your .env:

TRACECAT__DISABLE_NSJAIL=false
TRACECAT__EXECUTOR_BACKEND=ephemeral

nsjail requires:

Linux with kernel 4.6+
Docker privileged mode or CAP_SYS_ADMIN capability on the executor container
The nsjail binary and sandbox rootfs (included in Tracecat images)

nsjail is not supported on macOS or Windows. Use the direct backend on those platforms.

No isolation

Without nsjail, scripts, custom actions, and agents run as regular subprocesses in the executor. This is a supported production configuration when you trust everything that runs. That means your own workflow and custom registry code, the third-party dependencies those actions install, and the agents, tools, and MCP servers you enable. Review that code and pin those dependencies as you would any code with direct access to your systems. Choose nsjail instead when you run code you have not reviewed, such as untrusted third-party packages or agents that generate and execute their own code.

Choosing a backend

Backend	Isolation	Latency	Use case
`direct`	None	~50ms	Trusted code, dependencies, and agents
`ephemeral`	nsjail sandbox (cold per action)	~4000ms	Untrusted code, dependencies, and agents

Authentication

Docker Compose deployments default to basic email/password authentication. For production, configure OIDC or SAML SSO.

TLS

Never run production traffic over plain HTTP. See TLS and certificates for Caddy-based automatic TLS setup, custom certificates, and trusting internal CAs.

See Architecture for the platform and AI agent trust model.

Overview

Building automations

Building agents

Building custom actions

Self-hosting

Authentication

Security

Infrastructure credentials

Platform secrets

Where to store them

Rotation

Isolation

nsjail sandbox (recommended for production)

No isolation

Choosing a backend

Authentication

TLS

​Infrastructure credentials

​Platform secrets

​Where to store them

​Rotation

​Isolation

​nsjail sandbox (recommended for production)

​No isolation

​Choosing a backend

​Authentication

​TLS

​Related pages

Infrastructure credentials

Platform secrets

Where to store them

Rotation

Isolation

nsjail sandbox (recommended for production)

No isolation

Choosing a backend

Authentication

TLS

Related pages