Skip to main content
Tracecat comes with a build-in secrets manager. This allows you to store and retrieve sensitive data without exposing the value in plaintext. Secrets are encrypted at rest and stored in the database.

​
Storing secrets

Secrets are scoped to a workspace. To add a secret, navigate to the Credentials page and click on the Create Secret button.
  • Open credentials settings
  • Create secret
Select the settings icon in the top right corner of the page and click on Credentials.Credentials settings

​
SECRETS context

Secrets stored in the secrets manager can be accessed using the SECRETS context: ${{ SECRETS.<name>.<key> }}. For example: 
${{ SECRETS.virustotal.VIRUSTOTAL_API_KEY }}
Tracecat will automatically replace the expression with the secret value at runtime. Retrieved secrets are removed from memory, i.e. garbage collected, after the action is executed.

​
Integrations and secrets

Check out the integrations cheatsheet for a list of pre-built integrations and their required secrets.
Authentication with pre-built integrations is handled implicitly. Pre-built integrations are associated with specific secret names and keys. For example, the VirusTotal integration requires a secret with the name virustotal and the key VIRUSTOTAL_API_KEY. Different integrations may require different required and optional keys. For example, Tracecat’s AWS integration is configured with the following secret with optional keys, but with optional=False meaning at least one of the keys must be provided: 
aws_secret = RegistrySecret(
    name="aws",
    optional_keys=[
        # Access key-based authentication
        "AWS_ACCESS_KEY_ID",
        "AWS_SECRET_ACCESS_KEY",
        "AWS_REGION",
        # Role-based authentication
        "AWS_ROLE_ARN",
        "AWS_ROLE_SESSION_NAME",
        # Profile-based authentication
        "AWS_PROFILE_NAME",
    ]
    optional=False
)

​
OAuth secrets

Unlike regular secrets, OAuth secrets are not stored in the secrets manager. Instead, they are stored in the OAuth provider’s database. To access them use the following syntax: 
${{ SECRETS.<provider_id>_oauth.<prefix>_[SERVICE|USER]_TOKEN }}
For example, to access the GitHub user token, you would use the following expression: 
${{ SECRETS.github_oauth.GITHUB_USER_TOKEN }}
OAuth secrets are scoped to a provider. To add an OAuth secret, navigate to the Integrations page and click on the Create OAuth Secret button.

​
Multi-tenant secrets

A common use case is to have different sets of the same secret for different tenants. For example, an MDR provider will likely have different Crowdstrike tenant IDs for each customer. Tracecat supports multi-tenant secrets via the workflow’s environment configuration. Example
1

Create a multi-tenant secret

Create a multi-tenant secret for an integration by specifying the environment key. The secret name and keys (e.g. aws and AWS_ROLE_ARN) remain the same.If no environment key is specified, the environment key defaults to default.Specify environment for secret
2

Specify workflow environment

Click on the workflow canvas. You can specify the workflow’s environment under the Configuration section.Specify workflow environment
3

Trigger multi-tenant workflows

Let’s say you have multiple sets of AWS credentials, one for each account, and you want to retrieve GuardDuty detections for each account.You can do this easily in two-steps using a looped core.workflow.execute action.First, drag out a core.workflow.execute action, then specify a loop expression that iterates over a list of AWS account IDs:
${{ for var.aws_account_id in <some-list-of-account-ids> }}
Loop expressionThen configure the core.workflow.execute action with the following inputs:
trigger_inputs: <child-workflow-inputs>
workflow_alias: <child-workflow-alias>  # You can find this in the workflows page
environment: ${{ var.aws_account_id }}  # The secret environment
Execute child workflow with variable environment