Action Templates are custom integrations built on Tracecat’s YAML-based DSL (domain specific language). A template comprises of the following elements:

  • A unique title, description, and display group
  • A namespace (e.g. tools.falconpy) and name (e.g. call_command) for the action
  • Inputs defined in the expects section
  • Steps defined in the steps section
  • An optional secrets section

Steps consist of 1-2 commonly used actions, such as core.http_request, configured to call an external API. These steps are also parameterized with the inputs defined in the expects section.

Only data specified in the returns field of the template is logged in Tracecat workflows. Outputs between steps are not logged unless specified in returns.

Every template follows the same structure:

type: action
definition:
  title: <title>
  description: <description>
  display_group: <display_group>
  doc_url: <doc_url>
  namespace: <namespace>
  name: <name>
  secrets:  # Secrets are optional
    - name: <secret_name>
      keys:
        - <key_name>
      optional_keys:
        - <key_name>
  expects:
    <param_name>:
      type: <type>
      description: <description>
      default: <default_value>  # Optional
  steps:
    - ref: <step_id>
      action: <action_namespace>.<action_name>
      args:
        <param_name>: <param_value>
  returns: <returns>

​
Actions in templates

Templates support all actions defined in the Tracecat Registry. Actions, such as core.http_request and tools.falconpy.call_command, can all be used in templates by specifying the steps.action field.

​
Expressions in templates

Templates support the following expressions:

  • inputs: Reference inputs into the action as defined in the expects section.
  • steps: Reference results from previous steps in the same template.
  • SECRETS: Reference secrets.
  • FN: Reference functions.

inputs and steps are expressions specific to templates. SECRETS and FN are used in the same way as in workflows.

This means that templates have full support for Tracecat’s powerful inline functions. For example:

${{ FN.to_isoformat(inputs.start_time) }}
${{ FN.strip(FN.to_base64url(inputs.url), "=") }}

​
Secrets in templates

Secrets used in templates must be defined in the secrets section. You must specify the secret’s name, key, and (if applicable) optional_keys.

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.

​
OAuth 2.0 Authentication

Use Action Templates to securely call external APIs that use OAuth 2.0 for authentication. There are two steps to calling REST APIs that use OAuth 2.0 authentication:

  1. Retrieve a token given a client ID and client secret
  2. Use the token to make a request to the API

Action Templates provide a secure way to retrieve OAuth 2.0 tokens without exposing the secret in Tracecat logs. The first step of the template is a Python UDF action, such as tools.microsoft_graph.get_access_token, which retrieves the token. The second step is then typically a core.http_request action that uses the token to make a request to the API.

We recommend using a Python UDF to handle the process of retrieving and refreshing OAuth 2.0 tokens.

Check out Tracecat’s Wiz, Microsoft Graph, and Jamf get_access_token Python integrations on GitHub for examples.

One reason for using Python UDFs is many vendors, such as Microsoft Graph and Google APIs, have official Python client libraries. These clients are more reliable than trying to implement OAuth 2.0 flows manually using core.http_request.

Even if a client library is not available, different vendors implement OAuth 2.0 flows slightly differently. A Python UDF allows you to abstract the underlying implementation details of the OAuth 2.0 flow.

Was this page helpful?