Turbine Solutions 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 and vulnerability management 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 interfaces for soc and vulnerability management workflows best practices for working with interfaces 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 soc solutions bundle interfaces the soc solutions bundle includes 20 interfaces for security operations center workflows use these interfaces for alert triage, observable enrichment, email processing, and remediation actions alert to none v1 0 2 purpose processes an alert object without producing output use this interface for alert ingestion workflows where you process alerts without transforming them input schema field type required description alert object yes alert object alert alert categories array of strings no alert categories alert alert created timestamp string no when the alert was created alert alert description string no alert description alert alert end timestamp string no alert end time alert alert impacted hostnames array of strings no affected hostnames alert alert impacted ip addresses array of strings no affected ip addresses alert alert impacted usernames array of strings no affected usernames alert alert ingested timestamp string no when alert was ingested alert alert mitre attack tactic technique array of objects no mitre att\&ck mappings alert alert mitre attack tactic technique tactics array no tactic information alert alert mitre attack tactic technique technique object no technique details with name , uid alert alert mitre attack tactic technique technique name string no technique name alert alert mitre attack tactic technique technique uid string no technique uid alert alert mitre attack tactic technique version string no att\&ck version alert alert organization string no organization identifier alert alert originating files array of objects no files associated with alert alert alert originating files content object no file content (base64 or turbine attachment) alert alert originating files file hashes array no hash information alert alert originating files observables array no observable data alert alert permalink string no link to alert details alert alert provider string no alert source provider alert alert risk score integer no risk score alert alert rules array no rules that triggered the alert alert alert severity string no alert severity level alert alert start timestamp string no alert start time alert alert title string no alert title alert alert uid string no unique alert identifier alert observables array no observable entities alert raw alert object no raw alert data output schema empty object (no output) use cases alert ingestion pipelines alert logging and archival alert forwarding without transformation array of alerts to none v1 0 2 purpose processes an array of alerts without producing output use this interface for bulk alert processing input schema field type required description alerts array of alert objects yes array of alert objects to process output schema empty object (no output) use cases bulk alert ingestion alert batch processing alert archival workflows array of simple observable to none v1 0 2 purpose processes an array of simple observable objects without producing output input schema field type required description observables array of objects yes array of simple observable objects observables\[] observable type string yes type of observable observables\[] observable value string yes observable value output schema empty object (no output) use cases bulk observable ingestion observable logging observable forwarding simple observable to none v1 0 2 purpose processes a simple observable without producing output input schema field type required description observable object no observable object observable observable type string no type of observable observable observable value string no observable value output schema empty object (no output) use cases observable logging observable ingestion observable forwarding phishing email report to none v1 0 2 purpose processes phishing email report objects without producing output input schema field type required description phishing email report object no phishing email report data output schema empty object (no output) use cases phishing report ingestion phishing report logging phishing report archival alert triage ingestion to array of alert v1 0 2 purpose converts triage ingestion data into an array of standardized alert objects input schema triage ingestion format (specific structure) output schema field type required description alerts array of alert objects no array of standardized alert objects that match the alert schema use cases bulk alert ingestion alert normalization from multiple sources alert triage workflows simple observable to enrichment v1 0 2 purpose converts a simple observable into an enrichment object that includes threat intelligence data input schema field type required description observable object yes observable object observable observable metadata object no additional metadata observable observable type string yes type of observable (such as "ip", "domain", or "hash") observable observable value string yes the observable value output schema field type required description enrichment object no enrichment object enrichment enrichment context string no context information enrichment enrichment permalink string no link to enrichment details enrichment enrichment provider string no enrichment data provider name enrichment enrichment raw data string no raw enrichment data enrichment enrichment timestamp string no when enrichment was retrieved enrichment enrichment type string no type of enrichment (such as "location" or "reputation") enrichment enrichment verdict string no reputation verdict use cases threat intelligence enrichment observable reputation checking security context gathering simple observable to observable v1 0 2 purpose converts a simple observable into a full observable object with enrichment capabilities input schema field type required description observable object no observable object observable observable type string no type of observable observable observable value string no observable value observable observable metadata object no additional metadata output schema field type required description observable object no full observable object with enrichment fields use cases observable normalization observable enrichment preparation data structure standardization text to array of observables v1 0 2 purpose extracts observables from text content and returns them as an array input schema field type required description text value string yes text content to parse for observables output schema field type required description observables array of objects no array of extracted observables observables\[] observable type string no type of extracted observable observables\[] observable value string no the extracted value use cases email body parsing log file analysis text extraction from documents ioc extraction from reports object to alert v1 0 2 purpose converts a generic object into a standardized alert object input schema field type required description object object no generic object with alert related fields output schema field type required description alert object no standardized alert object matching alert schema use cases alert normalization from various sources custom alert format conversion alert standardization error to enrichment v1 0 2 purpose converts error information into an enrichment object for error tracking and analysis input schema field type required description error object no error information output schema field type required description enrichment object no enrichment object containing error context use cases error tracking error enrichment error analysis workflows email to email v1 0 2 purpose converts email objects while preserving the email structure used for email processing workflows input schema field type required description email object yes email object email email bcc addresses array of strings no bcc recipients email email body string no email body content email email cc addresses array of strings no cc recipients email email delivery timestamp string no delivery timestamp email email from address string no sender address email email headers array of objects no email headers email email headers\[] header key string no header name email email headers\[] header value string no header value email email html body string no html body content email email message id string no message id email email mime parts array of objects no mime parts email email mime parts\[] content object no content (base64 or turbine attachment) email email mime parts\[] file name string no file name email email mime parts\[] is attachment boolean no whether it is an attachment email email mime parts\[] mime type string no mime type email email organization string no organization identifier email email origination timestamp string no origination time email email reply to addresses array of strings no reply to addresses email email subject string no email subject email email text body string no plain text body email email to addresses array of strings no to recipients email observables array no observable entities extracted from email email raw email string no raw email content output schema field type required description email object no transformed email object with same structure use cases email processing workflows email transformation email forwarding email analysis turbine attachment to email v1 0 2 purpose converts a turbine attachment object into an email object format input schema field type required description turbine attachment object no turbine attachment object output schema field type required description email object no email object structure use cases attachment to email conversion email reconstruction from attachments email processing workflows file to file v1 0 2 purpose converts file objects while preserving file structure input schema field type required description file object no file object with file metadata and content output schema field type required description file object no transformed file object use cases file processing workflows file transformation file forwarding header to header v1 0 2 purpose converts header objects (email or http headers) input schema field type required description header object no header object output schema field type required description header object no transformed header object use cases header processing header transformation header analysis mime part to mime part v1 0 2 purpose converts mime part objects while preserving structure input schema field type required description mime part object no mime part object output schema field type required description mime part object no transformed mime part object use cases mime part processing email attachment handling content extraction phishing triage email ingestion to array of phishing email report v1 0 2 purpose converts phishing triage email ingestion data into an array of phishing email reports input schema phishing triage ingestion format output schema field type required description phishing email reports array of objects no array of phishing email report objects use cases bulk phishing email processing phishing triage workflows phishing report generation block/unblock observable remediation action purpose performs block or unblock actions on observables (such as ips and domains) in security systems input schema field type required description observable string yes the observable value to block or unblock observable type string yes type of observable (such as "ip" or "domain") action string yes action to perform ("block" or "unblock") output schema field type required description block message string no response message from the remediation action use cases ip address blocking/unblocking domain blocking threat containment workflows security control automation enable/disable user account remediation action purpose enables or disables user accounts in identity management systems input schema field type required description user account string yes the user account identifier to enable or disable action string yes action to perform ("enable" or "disable") output schema field type required description response message string no response message from the account action use cases account remediation incident response access control automation user account management isolate/rejoin hosts remediation action purpose isolates or rejoins hosts in network security systems input schema field type required description host string yes host identifier to isolate or rejoin action string yes action to perform ("isolate" or "rejoin") output schema field type required description response message string no response message from the remediation action use cases host isolation during incidents network containment incident response automation security control workflows vulnerability case management interfaces the vulnerability case management bundle contains 6 interfaces designed for vulnerability management workflows, including vulnerability finding processing, remediation tracking, and ticket management vulnerability finding to vulnerability finding v1 0 0 purpose converts vulnerability finding objects while preserving all vulnerability data used for vulnerability data normalization and processing input schema field type required description vulnerability finding object yes vulnerability finding object vulnerability finding vulnerability id string no cve or vulnerability identifier vulnerability finding vulnerability description string no description of the vulnerability vulnerability finding vulnerability status string no current status vulnerability finding vulnerability published date string no publication date vulnerability finding vulnerability last modified date string no last modification date vulnerability finding vulnerability cvss base score integer no cvss base score vulnerability finding vulnerability cvss version string no cvss version vulnerability finding vulnerability cvss vector string string no cvss vector string vulnerability finding vulnerability cvss temporal threat score integer no temporal or threat score vulnerability finding vulnerability epss score integer no epss score vulnerability finding vulnerability epss percentile integer no epss percentile vulnerability finding vulnerability references string no reference links vulnerability finding vulnerability weaknesses (cwes) string no cwe identifiers vulnerability finding vulnerability related attack patterns string no related attack patterns vulnerability finding vulnerability exploits string no exploit information vulnerability finding vulnerability public exploit found string no public exploit flag vulnerability finding vulnerability commercial exploit found string no commercial exploit flag vulnerability finding vulnerability weaponized exploit found string no weaponized exploit flag vulnerability finding vulnerability reported exploited string no reported exploitation flag vulnerability finding vulnerability reported exploitation string no exploitation details vulnerability finding vulnerability reported exploited by threat actors string no threat actor exploitation vulnerability finding vulnerability reported exploited by ransomware string no ransomware exploitation vulnerability finding vulnerability reported exploited by botnets string no botnet exploitation vulnerability finding vulnerability exploits trending on github string no github trending flag vulnerability finding vulnerability first exploit published string no first exploit publication date vulnerability finding vulnerability max exploit maturity string no maximum exploit maturity vulnerability finding vulnerability in known exploited vulnerabilities string no kev list flag vulnerability finding vulnerability finding unique id string no unique finding identifier vulnerability finding vulnerability finding grouping id string no grouping identifier vulnerability finding vulnerability finding summary string no finding summary vulnerability finding vulnerability finding primary asset identifier string no primary asset id vulnerability finding vulnerability finding primary asset type string no primary asset type vulnerability finding vulnerability finding hostnames array of strings no affected hostnames vulnerability finding vulnerability finding ip addresses array of strings no affected ip addresses vulnerability finding vulnerability finding mac addresses array of strings no affected mac addresses vulnerability finding vulnerability finding sources array of strings no finding sources vulnerability finding vulnerability finding scan id string no scan identifier vulnerability finding vulnerability finding scan type string no scan type vulnerability finding vulnerability finding raw risk score integer no raw risk score vulnerability finding vulnerability finding turbine risk score integer no turbine risk score vulnerability finding vulnerability finding remediation status string no remediation status vulnerability finding vulnerability finding remediation string no remediation details vulnerability finding vulnerability finding remediation owner string no remediation owner vulnerability finding vulnerability finding exception reference array of strings no exception references vulnerability finding vulnerability finding exception reason string no exception reason vulnerability finding vulnerability finding last ingested string no last ingestion timestamp vulnerability finding vulnerability finding last enriched string no last enrichment timestamp vulnerability finding vulnerability finding raw json string no raw json data vulnerability finding asset reference array of strings no asset references vulnerability finding asset zone string no asset zone vulnerability finding merged risk scores string no merged risk score information vulnerability finding vulnerability finding mitre attack techniques string no mitre att\&ck techniques output schema field type required description vulnerability finding object no transformed vulnerability finding with same structure use cases vulnerability data normalization vulnerability finding processing vulnerability data transformation cross platform vulnerability data exchange enriched vulnerability finding to enriched vulnerability finding v1 0 0 purpose converts enriched vulnerability finding objects with additional threat intelligence and context data input schema field type required description enriched vulnerability finding object no enriched vulnerability finding object output schema field type required description enriched vulnerability finding object no transformed enriched finding use cases enriched vulnerability processing threat intelligence integration vulnerability enrichment workflows array of object to array of vulnerability finding v1 0 0 purpose converts an array of generic objects into an array of standardized vulnerability finding objects input schema field type required description objects array of objects no array of generic objects output schema field type required description vulnerability findings array of objects no array of standardized vulnerability finding objects use cases bulk vulnerability ingestion vulnerability data normalization multi source vulnerability aggregation asset to tracking id v1 0 0 purpose extracts or generates tracking identifiers from asset objects input schema field type required description asset object no asset object output schema field type required description tracking id string no tracking identifier for the asset use cases asset tracking asset identification asset management workflows remediation item to ticket v1 0 0 purpose creates or updates tickets in itsm systems based on remediation item data input schema field type required description remediation owner string yes party responsible for remediation remediation channel string yes channel to reach remediation owner remediation item tracking id string yes tracking id of remediation item outbound message string yes message to attach to ticket output schema field type required description ticket id string no ticket id from itsm system ticket status string no ticket status (open, closed, error) ticket opened string no timestamp when ticket was opened ticket status updated string no timestamp of last status update ticket status message string no status message about ticket creation use cases itsm integration remediation workflow automation ticket creation from vulnerability findings remediation tracking remediation item check v1 0 0 purpose checks the status of remediation items and associated itsm tickets input schema field type required description remediation owner string yes remediation owner identifier remediation channel string yes remediation channel remediation item tracking id string yes tracking id of remediation item itsm ticket id string yes itsm ticket id to check output schema field type required description ticket status string no current ticket status ticket status updated string no timestamp of last status check or update inbound messages string no replies or inbound messages from itsm use cases remediation status monitoring ticket status synchronization remediation workflow tracking itsm integration status checks common data structures observable object observables represent security relevant entities such as ip addresses, domains, and file hashes { "observable type" "ip", "observable value" "192 168 1 1", "observable metadata" {}, "observable primary context" "context", "observable primary permalink" "https // ", "observable primary provider" "provider", "observable primary timestamp" "2024 01 01t00 00 00z", "observable primary verdict" "malicious", "observable enrichments" \[ { "enrichment type" "reputation", "enrichment provider" "provider", "enrichment context" "context", "enrichment permalink" "https // ", "enrichment timestamp" "2024 01 01t00 00 00z", "enrichment verdict" "malicious", "enrichment raw data" " " } ] } alert object alerts represent security events and incidents { "alert uid" "unique id", "alert title" "alert title", "alert description" "description", "alert severity" "high", "alert risk score" 85, "alert categories" \["malware", "phishing"], "alert start timestamp" "2024 01 01t00 00 00z", "alert end timestamp" "2024 01 01t01 00 00z", "alert created timestamp" "2024 01 01t00 00 00z", "alert ingested timestamp" "2024 01 01t00 00 00z", "alert provider" "security tool", "alert organization" "org id", "alert permalink" "https // ", "alert impacted hostnames" \["host1 example com"], "alert impacted ip addresses" \["192 168 1 1"], "alert impacted usernames" \["user1"], "alert rules" \[ { "rule id" "rule 123", "rule name" "rule name", "rule type" "detection", "rule description" "description" } ], "alert mitre attack tactic technique" \[ { "technique" { "uid" "t1189", "name" "drive by compromise" }, "tactics" \[ { "uid" "ta0001", "name" "initial access" } ], "version" "v12" } ], "alert originating files" \[], "observables" \[], "raw alert" {} } email object email objects represent email messages with full metadata { "email message id" "message id", "email from address" "sender\@example com", "email to addresses" \["recipient\@example com"], "email cc addresses" \[], "email bcc addresses" \[], "email reply to addresses" \[], "email subject" "subject", "email body" "body text", "email text body" "plain text body", "email html body" "\<html> \</html>", "email origination timestamp" "2024 01 01t00 00 00z", "email delivery timestamp" "2024 01 01t00 00 00z", "email organization" "org id", "email headers" \[ { "header key" "from", "header value" "sender\@example com" } ], "email mime parts" \[ { "mime type" "text/plain", "file name" "attachment txt", "is attachment" true, "content" { "base64" " ", "turbine attachment" {} } } ], "observables" \[], "raw email" " " } vulnerability finding object vulnerability findings represent discovered security vulnerabilities key fields include vulnerability identification (cve, description) scoring (cvss, epss) exploit information asset information remediation status risk scores see the "vulnerability finding to vulnerability finding" interface for complete schema 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 common issues and solutions 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 https //json schema org/ https //attack mitre org/