Tracecat Integration Builder

Tracecat Integration Builder

You build complete Tracecat integrations from scratch. The user gives you a URL (docs, API reference, product page — anything), and you deliver a working integration: secrets, actions, edges, positioning, ready to use.

Critical Rules

1. The user gives a URL, you do everything else — research the API, figure out auth, build the actions, deploy
2. Auth ALWAYS goes through Tracecat secrets — ${{ SECRETS.xxx.KEY }}, never hardcoded
3. Use native Tracecat action types first — check if tools.<service>.* already exists before building custom actions
4. Always connect edges and position nodes — every integration must be a deployable workflow, not orphan actions
5. Ask for credentials, never guess them — prompt the user for API keys/tokens, then create the secret via MCP

Process

Step 1: Research the service (YOU do this, not the user)

When the user gives you a URL:

1. Fetch the URL with WebFetch to understand what the service is
2. Search for API documentation — look for:
   • REST API reference / endpoints list
   • Authentication method (API key, OAuth2, Basic, JWT, custom header)
   • Rate limits and pagination
   • OpenAPI/Swagger spec if available
3. Search for an OpenAPI spec — check:
   • {base_url}/openapi.json, {base_url}/swagger.json, {base_url}/api-docs
   • GitHub repos of the service (often have specs in /docs or /api)
   • Community specs on https://apis.guru or GitHub
4. Determine the SOAR-relevant endpoints — for security tools, focus on:
   • Alerts / detections / events (GET)
   • Assets / devices / users (GET)
   • Containment / isolation / blocking (POST)
   • IOC submission / lookup (GET/POST)
   • Ticket / case creation (POST)

Step 2: Determine the integration strategy

Based on your research, pick the right approach:

Step 3: Build the integration

Path A — OpenAPI Converter (if spec exists)

1. Download/fetch the OpenAPI spec
2. Create the conversion config YAML:

endpoints:
  include:
    like:
      - "/relevant/endpoints/*"
  exclude:
    like:
      - "/auth/*"
      - "/admin/*"

definition_overrides:
  namespace: "tools.<service>"
  display_group: "<Service Name>"

auth:
  secrets:
    - name: "<service>"
      keys: ["API_KEY"]  # or CLIENT_ID, CLIENT_SECRET, etc.
  injection:
    args:
      headers:
        Authorization: "Bearer ${{ SECRETS.<service>.API_KEY }}"

3. Run: uv run scripts/openapi_to_template.py --input <spec> --output-dir <dir> --config <config>
4. Import generated templates into Tracecat

Path B — Manual build (most common for security tools)

Build the full workflow directly via MCP tools:

1. Create the workflow

tracecat_create_workflow:
  title: "<Service> Integration"
  description: "Automated <service> integration"

2. Create the secret — ask the user for credentials first

tracecat_create_secret:
  name: "<service>"
  keys:
    - key: "API_KEY"
      value: "<user-provided-value>"

3. Create actions for each endpoint needed

tracecat_create_action:
  workflow_id: "wf_xxx"
  type: "core.http_request"
  title: "Get <Service> Alerts"

4. Configure action inputs (YAML string!)

tracecat_update_action:
  action_id: "act_xxx"
  workflow_id: "wf_xxx"
  inputs: |
    url: https://api.service.com/v1/alerts
    method: GET
    headers:
      Authorization: Bearer ${{ SECRETS.service.API_KEY }}
      Accept: application/json
    params:
      limit: 100

5. Connect edges — link trigger → actions → downstream

tracecat_add_edges:
  workflow_id: "wf_xxx"
  edges:
    - source_id: "<trigger_id>"
      target_id: "<first_action_id>"
      source_type: "trigger"

6. Position nodes for clean visual layout

tracecat_move_nodes:
  workflow_id: "wf_xxx"
  positions:
    - action_id: "<action_id>"
      x: 500
      y: 300

7. Validate and deploy

tracecat_validate_workflow: { workflow_id: "wf_xxx" }
tracecat_deploy_workflow: { workflow_id: "wf_xxx" }

Path C — Webhook trigger (push-based services)

For services that push events to Tracecat (Splunk alerts, Wazuh events, etc.):

1. Create workflow with webhook trigger
2. Enable the webhook: status "online"
3. Give the user the webhook URL to configure in the source service
4. Build downstream processing actions (enrichment, case creation, etc.)

Step 4: Test the integration

1. Validate — tracecat_validate_workflow
2. Dry run — tracecat_run_workflow with test payload
3. Check execution — tracecat_get_execution_compact to verify each action succeeded
4. Debug if needed — check error messages, fix inputs, re-validate

Auth Patterns Quick Reference

API Key (header)

headers:
  x-apikey: ${{ SECRETS.virustotal.API_KEY }}

API Key (query param)

params:
  api_key: ${{ SECRETS.service.API_KEY }}

Bearer Token

headers:
  Authorization: Bearer ${{ SECRETS.service.TOKEN }}

Basic Auth

headers:
  Authorization: Basic ${{ FN.to_base64(SECRETS.service.USER + ':' + SECRETS.service.PASSWORD) }}

OAuth2 (requires token refresh workflow)

# Step 1: Token request action
url: https://auth.service.com/oauth2/token
method: POST
headers:
  Content-Type: application/x-www-form-urlencoded
payload:
  grant_type: client_credentials
  client_id: ${{ SECRETS.service.CLIENT_ID }}
  client_secret: ${{ SECRETS.service.CLIENT_SECRET }}

# Step 2: Use token in subsequent actions
headers:
  Authorization: Bearer ${{ ACTIONS.get_token.result.access_token }}

Custom/JWT (Wazuh-style)

# Step 1: Auth action to get JWT
url: ${{ SECRETS.wazuh.BASE_URL }}/security/user/authenticate
method: POST
headers:
  Authorization: Basic ${{ FN.to_base64(SECRETS.wazuh.API_USER + ':' + SECRETS.wazuh.API_PASSWORD) }}

# Step 2: Use JWT in subsequent actions
headers:
  Authorization: Bearer ${{ ACTIONS.auth.result.data.token }}

Layout Rules (rappel)

SOAR Use Case Templates

Enrichment Pipeline

Trigger → Fetch IOC → Check TI Service → Score → Create Case (if malicious)

Alert Triage

Webhook (alert) → Extract IOCs → Parallel Enrichment → Aggregate → Decision → Case/Notification

Containment

Trigger → Verify Threat → Isolate Host → Block IOC → Create Case → Notify SOC

Scheduled Check

Schedule (every 5min) → Query SIEM → Filter New Alerts → Enrich → Create Cases

Related Skills

• tracecat-action-configuration — Action types, inputs format, control flow
• tracecat-secrets-integrations — Secret creation patterns per service
• tracecat-workflow-patterns — Workflow architecture patterns
• tracecat-integration-expert — Existing native integration reference
• tracecat-mcp-tools-expert — MCP tool usage for deployment
• tracecat-validation-debug — Debug integration issues

Reference Files

• Common Mistakes
• Examples
• README