Parts of a Playbook

Overview

Playbooks are composed of three main building blocks: Triggers, Apps, and Operators. These elements determine the Playbook’s logic and flow, from how the Playbook is activated to the actions that the Playbook takes and the decisions the Playbook makes. This article describes each Trigger, App, and Operator type and, when applicable, provides links to articles that contain more detailed information.

Before You Start

Playbook Designer

You can add Triggers, Apps, and Operators to a Playbook in the Playbook Designer in ThreatConnect^®. When you open the Playbook Designer, the Playbook design pane will be displayed in the middle of the screen, and a navigation bar with a variety of options, including ones for creating Triggers, Apps, and Operators, will be displayed on the left side of the screen (Figure 1).

To expand the side navigation bar of the Playbooks Designer and view labels for each icon, click Expandat the upper-left corner of the screen (Figure 2).

Triggers

A Trigger creates an event that initiates the actions defined within a Playbook. In order to be activated, a Playbook must have one, and only one, Trigger. There are five Trigger categories, which you can view by clickingTriggers on the side navigation bar of the Playbook Designer (Figure 2). To filter Triggers by name, use the search bar at the top of the Triggers pane.

The five Trigger categories are defined as follows:

• External: External Triggers are actions that occur outside of ThreatConnect. There are five External Trigger types:
  • WebHook: The WebHook Trigger creates an HTTPS endpoint that can process nearly any piece of information that can be sent via HTTP. This functionality can be useful for building integrations and getting disparate systems to interact via Playbooks. For example, a SIEM can post a series of Indicators to the URL provided by the WebHook Trigger, the Playbook can enrich the Indicators with additional context, and then the context can be sent back to the same URL. To view the endpoint, hover the cursor over theicon on the Trigger box, which will be displayed when the Trigger is added to the design pane of the Playbook Designer.
  • Mailbox: The Mailbox Trigger lets you create a mailbox to send information to a Playbook. The Trigger will fire whenever an email is received in the inbox you create. It can be used to parse Indicators from an email, send an attachment to a malware analysis tool, or coordinate communication across teams, among other things.
  • Timer: The Timer Trigger allows you to initiate execution of a Playbook on a set schedule (e.g., once a day; on the 15th of the month). It is useful for replicating the Jobs functionality in ThreatConnect. With a Timer Trigger, you can also perform advanced scheduling by entering a cron string.
  • UserAction: The UserAction Trigger allows you to run Playbooks on demand from the Details screen of Groups, Indicators, Intelligence Requirements, Tracks, and Victims. You can also run UserAction Trigger–based Playbooks for Indicators while using Threat Graph. This Trigger is contextually aware and user driven, and it allows a customized response (HTML or plain text).
  • Custom: A Custom Trigger is a type of Service Trigger that is not linked to a remote HTTP request. Instead, it is dependent on an external Trigger source to determine whether the Playbook executes, as defined by the App in its configuration.
• Group: Group Triggers correspond to all of the defined Groups on your ThreatConnect instance.
• Indicator: Indicator Triggers correspond to all of the defined Indicatorson your ThreatConnect instance.
  Note

  The MultipleIndicator Trigger enables you to select more than one Indicator type for a single Trigger so that any of the selected Indicator types will cause the Trigger to initiate the Playbook actions. The Indicator type that actually caused the Trigger to initiate is provided as one of the output variables (#trg.tc.type). See Adding a Trigger for more information on output variables for Triggers.
• Other: Other Triggers correspond to the Case, Intelligence Requirement, Track, and Victim objects.
• Service: Service Triggers are microservices that constantly run in the background.

Apps

An App is a tool that is used to act on data provided by a Trigger or another App within the Playbook. There are 15 App categories, which you can view by clickingApps on the side navigation bar of the Playbook Designer (Figure 2). To filter Apps by name, use the search bar at the top of the Apps pane.

The 15 App categories are defined as follows:

• Collaboration & Messaging: Collaboration & Messaging Apps send a customizable message via a client (e.g., email, meeting invitation, SMS).
• Component: Components are Apps that consist of modules of Playbook elements (Apps and Operators, with a single initial Trigger) that can be called from a Playbook.
• Data Enrichment: Data Enrichment Apps automate the enrichment of Indicators through ThreatConnect or third-party enrichment tools.
• Email Security: Email Security Apps automate email investigation and response actions based on senders, attachments, and folders.
• Endpoint Detection & Response: Endpoint Detection & Response Apps add, update, and remove Indicators from alerting and blocking lists on endpoint security tools.
• Identity & Access Management: Identity & Access Management Apps retrieve user information and update, activate, and block users.
• Incident Response & Ticketing: Incident Response & Ticketing Apps create a ticket, record, or issue for the Trigger in a third-party system such as Jira™, ServiceNow^®, or IBM Resilient Incident Response Platform^® (Resilient).
• IT Infrastructure: IT Infrastructure Apps investigate storage solutions and other infrastructures, such as Amazon Simple Storage Service (Amazon S3™) or Apache Kafka^®, to identify Indicators and security alerts.
• Malware Analysis: Malware Analysis Apps analyze a file artifact for maliciousness and automate actions to be taken on the resulting report data.
• Network Security: Network Security Apps add, update, and remove Indicators from alerting and blocking lists on network tools.
• SIEM & Analytics: SIEM & Analytics Apps add, update, and remove Indicators from alerting and blocking lists on SIEM tools.
• Threat Intelligence: Threat Intelligence Apps integrate with third-party products that typically use data in ThreatConnect. These integrations bring timely and relevant information into ThreatConnect so that users can make informed decisions.
• ThreatConnect: ThreatConnect Apps perform a task in ThreatConnect.
• Utility: Utility Apps perform data utility functions, like formatting dates, filtering regexes, and extracting data from a file of a given type (CSV, JSON, EML/MSG, RSS, or XPath).
• Vulnerability Management: Vulnerability Management Apps search for, retrieve, and prioritize vulnerabilities.

Operators

Operators are logic- or time-based links between Triggers and Apps. There are five Operators, which you can view by clickingOperators on the side navigation bar of the Playbooks Designer (Figure 2).

The five Operators are defined as follows:

• Merge: The Merge Operator enables upstream Apps to merge an operation into a single path, allowing a Playbook to guarantee an outcome in cases of path failures. The first path to hit a Merge Operator will force a continuation of the Playbook even if the other paths have not completed. This logic is distinct from that of an App, which will wait until all upstream paths are complete before it gets executed. For instance, an HTTP Client request might fail, but you may still want to continue a path regardless of success or failure. In general, the Merge Operator should be used with the Set Variable App to define a failure path. Once both failure and success have been defined, the Merge Operator can be used to continue the Playbook branch.
• If / Else: The If / Else Operator compares two variables in order to perform logical operations on the data. It can be used to determine whether an Indicator's threat rating is over a certain threshold, to see if a string of text exists in information returned by an integration, etc.
• Delay: The Delay Operator lets you specify an amount of time to wait before executing additional operations in the Playbook. It is useful when utilizing a third-party service that you know may take several seconds or minutes to return a response.
• Iterator: The Iterator Operator iterates through items in an input array or set of arrays, applies any logic available with Playbooks to each item, and returns the output to the Playbook. This capability expands Playbook applications beyond set-based use cases.
• Break Iterator: The Break Iterator Operator is used in the iteration loop of the Iterator Operator to define a break condition for the loop or break from the loop directly after an app failure.

ThreatConnect^® is a registered trademark of ThreatConnect, Inc.
Apache Kafka^® is a registered trademark of The Apache Software Foundation.
Amazon S3™ is a trademark of Amazon Technologies, Inc.
IBM Resilient Incident Response Platform^® is a registered trademark of IBM Corporation.
Jira™ is a trademark of Atlassian Corporation Plc.
ServiceNow^® is a registered trademark of ServiceNow, Inc.

20108-01 v.02.C