Working with Interfaces

Overview

This section of the Turbine User Guide describes the interfaces available in Turbine Solutions. Interfaces are standard data formats that enable components to work together seamlessly. Use interfaces to standardize data transformation across security operations workflows.

When you apply an interface to a component, it automatically configures the component's input and output data structures. This standardization allows you to easily swap components in your playbooks without manual re-configuration, as long as they use the same interface.

This guide covers:

What interfaces are and how they work

How to use interfaces when building components

Available interface catalogs for SOC, AI SOC, and VRM workflows

Best practices for working with interfaces

Interface catalogs

Full interface contracts for each solution area live in these guides:

SOC InterfacesSOC Interfaces — 22 Classic SOC interface contracts

AI SOC InterfacesAI SOC Interfaces — 4 AI SOC interface contracts

VRM InterfacesVRM Interfaces — 6 VRM interface contracts

For complete data model field definitions, see Turbine Schema Reference (Classic SOC)Turbine Schema Reference (Classic SOC), Turbine Schema Reference (AI SOC)Turbine Schema Reference (AI SOC), and Turbine Schema Reference (VRM)Turbine Schema Reference (VRM).

What Are Interfaces?

An interface defines the data structure that a component expects to receive (inputs) and the data structure it produces (outputs). Think of it as a standard template that ensures components can work together seamlessly.

Key Concepts

Component: A reusable automation flow that performs a specific task. Components are used within playbooks to build automation workflows.

Interface: A standard data format that components can use. When multiple components use the same interface, they can easily be swapped with each other because they all accept and produce data in the same format.

Input Schema: Defines what data your component needs to receive to work properly.

Output Schema: Defines what data your component will produce when it runs.

Example

Imagine you have multiple threat intelligence enrichment components:

Enrich via VirusTotal

Enrich via Recorded Future

Enrich via URLHaus

If they all use the same "Simple Observable to Enrichment" interface, they all:

Accept the same input format (an observable like an IP address)

Produce the same output format (enriched observable data)

This means you can swap between these components in your playbook without changing any other parts of your workflow.

Note: You can still create components without applying an interface, but they will not benefit from standardization and easy swapping.

Benefits of Using Interfaces

Interfaces provide powerful benefits that make your automation workflows more flexible and easier to manage:

Easy Component Swapping: Components that use the same interface can be swapped in and out of playbooks with a single click. No manual re-configuration or re-mapping of data needed.

Search by Functionality: You can search for components based on what they do, regardless of which vendor technology they use. For example, find all enrichment components that work with observables, even if they use different threat intelligence sources.

Guaranteed Compatibility: Components built with interfaces are guaranteed to work seamlessly with playbooks and other components that use the same interface.

Standardized Data Flow: Interfaces ensure that data flows correctly between components, reducing errors and making your playbooks more reliable.

Vendor Flexibility: You can easily switch between different vendor technologies (such as VirusTotal, Recorded Future, or URLHaus) without changing your playbook structure, as long as the components use the same interface.

How to Use Interfaces

Interfaces are available in Turbine Canvas when building components. When you create or edit a component:

Open the component builder in Turbine Canvas

Navigate to the "Data" tab in the side panel

Select an interface from the dropdown list of available interfaces

The interface automatically configures the component's input and output schemas

Once an interface is applied, your component will have standardized inputs and outputs that match other components using the same interface, making them easily swappable in playbooks.

Understanding Interface Schemas

Each interface defines two key parts:

Input Schema: Specifies what data your component expects to receive

Output Schema: Specifies what data your component will produce

When you apply an interface to a component, these schemas are automatically configured, ensuring your component accepts and produces data in the correct format.

Usage Patterns

Pattern 1: Data Ingestion Pipeline

Source Data → Ingestion Interface → Normalized Data → Processing Interface → Output

Example:

Email → Email to Email → Processed Email → Extract Observables → Observable Array

Pattern 2: Enrichment Workflow

Observable → Simple Observable to Enrichment → Enriched Observable → Alert Creation

Pattern 3: Remediation Workflow

Vulnerability Finding → Remediation Item to Ticket → Ticket Created → Remediation Item Check → Status Updated

Pattern 4: Bulk Processing

Array of Objects → Array to Array Interface → Normalized Array → Individual Processing

Best Practices

Follow these guidelines when working with interfaces:

Use the latest version: Always use the latest version of interfaces when available. Check the version field to ensure compatibility.

Include required fields: Include all required fields in input schemas. Missing required fields cause transformation failures.

Validate data before transformation: Validate input data against the interface schema before transformation to catch errors early.

Handle errors: Implement error handling for transformation failures, especially in automated workflows.

Choose the right interface: Select interfaces that match your data flow:

Use "to None" interfaces for ingestion and logging

Use transformation interfaces for data conversion

Use remediation interfaces for automated actions

Extract observables from text: Use "Text to Array of Observables" to extract IOCs from unstructured text.

Process bulk data efficiently: Use array interfaces to process multiple items efficiently.

Validate remediation actions: Validate action parameters before executing remediation actions to prevent unintended consequences.

Playbook Integration

How Interfaces Work in Playbooks

Interfaces define the input and output schemas for playbook transformations. When you create a playbook component using a BuilderIntent interface:

Input schema: Defines what data the playbook expects

Output schema: Defines what data the playbook produces

Validation: Ensures data matches schemas at runtime

Type Safety: Provides type information for the UI

Creating a Playbook with an Interface

Example Playbook YAML:

schema: playbook/2
name: observable-enrichment-playbook
title: Observable Enrichment Playbook
description: Enriches observables with threat intelligence

# Reference to the interface schema
inputSchemaReferenceId: simple-observable-to-enrichment-v1-0-2-06fbe

actions:
  enrich_observable:
    actionType: jsonata
    inputs:
      expression: |
        {
          "observable": $.observable,
          "enrichment": {
            "enrichment_type": "reputation",
            "enrichment_provider": "threat-intel",
            "enrichment_verdict": "malicious",
            "enrichment_timestamp": $now(),
            "enrichment_context": "Enriched via playbook"
          }
        }
      data:
        observable:
          observable_type: string
          observable_value: string

publish:
  enrichment: $.enrich_observable.enrichment

Connecting Multiple Interfaces

You can chain multiple interfaces together in a playbook:

actions:
  # Step 1: Extract observables from text
  extract_observables:
    actionType: jsonata
    inputs:
      expression: |
        {
          "observables": $split($.text_value, " ")
        }
      data:
        text_value: string
  
  # Step 2: Enrich each observable
  enrich_observable:
    actionType: jsonata
    next: create_alert
    inputs:
      expression: |
        {
          "enrichment": {
            "enrichment_type": "reputation",
            "enrichment_provider": "threat-intel",
            "enrichment_verdict": "suspicious"
          }
        }
      data:
        observable: object
  
  # Step 3: Create alert from enriched observable
  create_alert:
    actionType: jsonata
    inputs:
      expression: |
        {
          "alert": {
            "alert_title": "Threat Detected",
            "alert_severity": "high",
            "observables": [$.enrich_observable.observable]
          }
        }
      data:
        enrichment: object

Troubleshooting and Common Pitfalls

Issue 1: Schema Validation Failures

Symptom: Transformation fails with validation error

Causes:

Missing required fields

Wrong data types

Invalid enum values

Extra fields not in schema (if additionalProperties: false)

Solution:

Validate input data against schema before transformation

Use schema validation tools

Check interface documentation for required fields

Remove or map extra fields

Example Fix:

// Before (fails validation)
{
  "observable": {
    "type": "ip",  // Wrong field name
    "value": "192.168.1.1"  // Wrong field name
  }
}

// After (passes validation)
{
  "observable": {
    "observable_type": "ip",  // Correct field name
    "observable_value": "192.168.1.1"  // Correct field name
  }
}

Issue 2: Transformation Timeouts

Symptom: Transformation fails with timeout error

Causes:

External API calls taking too long

Large data processing

Network latency

Insufficient timeout configuration

Solution:

Increase timeout for slow operations

Optimize transformation logic

Use async processing for long operations

Implement retry logic with exponential backoff

Issue 3: Incorrect Interface Selection

Symptom: Data does not match expected format

Causes:

Using wrong interface for data type

Confusing similar interfaces

Version mismatch

Solution:

Review interface documentation

Check input/output schemas

Verify interface version compatibility

Test with sample data first

Example:

// Wrong: Using "Simple Observable to Enrichment" for array
// Correct: Use "Array of Simple Observable to None" or process individually

Issue 4: Remediation Action Failures

Symptom: Remediation actions return error messages

Causes:

Invalid action parameter

System permissions

Target system unavailable

Invalid observable format

Solution:

Validate action parameters before execution

Check system connectivity

Verify permissions

Review error messages for specific issues

Example:

// Invalid action
{
  "action": "ban"  // Should be "block" or "unblock"
}

// Valid action
{
  "action": "block"
}

Issue 5: Data Type Mismatches

Symptom: Numbers passed as strings, dates in wrong format

Causes:

Data source provides wrong types

Missing type conversion

Schema expects specific format

Solution:

Convert data types before transformation

Use transformation functions for type conversion

Validate data types match schema

Example:

// Before (may fail)
{
  "alert": {
    "alert_risk_score": "85"  // String
  }
}

// After (correct)
{
  "alert": {
    "alert_risk_score": 85  // Integer
  }
}

Frequently Asked Questions

Where Can I See a List of Available Interfaces That I Can Use?

Currently, the only way to view the list of available interfaces would be through the component builder in Turbine Canvas. You can select a component or create a new one, go to the "Data" tab in the side panel, and use the dropdown there to view the list of supported interfaces.

Can I Create My Own Interfaces?

No, currently you can only use the available interfaces that Swimlane provides. Custom interface creation is on the roadmap as a future feature enhancement.

How Do I Know Which Interface to Use for My Component?

Choose an interface that matches your component's purpose:

Ingestion components: Use interfaces that end with "to None" (such as "Alert to None")

Enrichment components: Use interfaces like "Simple Observable to Enrichment"

Transformation components: Use interfaces that transform one data type to another (such as "Email to Email")

Remediation components: Use remediation action interfaces (such as "Block/Unblock Observable Remediation Action")

What Happens if I Do Not Use an Interface?

You can still create components without applying an interface. However, you will need to manually configure inputs and outputs, and the component will not benefit from standardization or easy swapping with other components that use the same interface.

Can I Use Multiple Interfaces on the Same Component?

No, each component can only have one interface applied to it. The interface defines both the input and output schemas for that component.

References

JSON Schema Specification

MITRE ATT&CK Framework