The Playbooks feature allows ThreatConnect® users to automate cyberdefense tasks via a drag-and-drop interface. The interface uses Triggers (e.g., a new IP address Indicator, a phishing email sent to an inbox) to pass data to Apps, which perform a variety of functions, including data enrichment, malware analysis, and blocking actions. Once enabled, Playbooks run in real time and provide users with detailed logs of each execution. Playbooks may also be saved for use as Components (i.e., modules) within other Playbooks. See Playbook Components for more details.
The Playbooks Screen
On the top navigation bar (Figure 1), click PLAYBOOKS to display the Playbooks screen. If no Playbooks have been created, the Playbooks screen will look like the one in Figure 2.
If there are Playbooks available to the user, the Playbooks screen will look like the one in Figure 3.
This screen contains up to four tabs at the top left: Playbooks, Templates, Activity, and Environments. This article covers the Playbooks tab. See Playbook Templates, Playbook Activity, and Playbook Environments for information on the Templates, Activity, and Environments tabs, respectively.
NOTE: The Activity and Environments tabs will be visible only for Organization Administrators and higher.
The Playbooks tab is organized into 7 columns:
- Type: This column displays icons that illustrate the type of item in each row. indicates that the item is a Playbook. indicates that the item is a Playbook Component . A green checkmark above the icon (as demonstrated by the Block IP Address Component and the Deploy Related Indicators to SIEM Playbooks in Figure 3) indicates that the Component or Playbook is active. See Step 29 of the “Designing a Playbook” section of this article for more information about activating a Playbook and the “Playbook Execution and Logging” section of this article for more information about activating and executing Playbooks.
- Name: This column displays the name of the Playbook or Component in blue. Click on the name to open the Playbook. If there is a HttpLink or Mailbox Trigger in the Playbook (see “Triggers” later in this article), the URL endpoint of the Trigger will be displayed under the name. Components do not have URL endpoints associated with them. If a creator or editor has provided a description of the Playbook or Component, the description will appear below the endpoint (or directly below the name if no endpoint is available).
NOTE: Hovering the cursor over any part of a row containing an active Playbook with a URL endpoint will cause two icons to appear to the right of the endpoint. Clicking the copy icon will copy the URL endpoint to the clipboard. Clicking the execute-endpoint icon will execute the Playbook’s endpoint. These icons will not appear for Components.
- Trigger: This column displays the type of Trigger that initiates execution of the Playbook. See the “Triggers” sub-section of the “Designing a Playbook” section for more information. If the item is a Component, then “Component” will be displayed in this column. If the Playbook does not have a Trigger (e.g., if it is not yet fully designed and configured), then this column will be blank.
- Labels: This column displays any labels that have been applied to the Playbook or Component. Labels are keywords that are used to classify Playbooks and Components. For example, labels such as “In Design” and “QA” can be used to track the development or status of Playbooks, and labels such as “Enrichment” and “Reporting” can be used to make filtering by Playbook type more manageable.
- Log Level: This column displays the log level for the Playbook. Components will not have log levels displayed.
- Updated: This column displays the date and time at which the Playbook or Component was last updated.
- ROI: Clicking on the graph icon in the ROI column will cause a window containing return on investment (ROI) metrics for the Playbook to appear. See Playbooks: Return on Investment for more details on ROI metrics. Components do not have ROI metrics associated with them.
- Vertical ellipsis menu: Clicking the vertical ellipsis icon for an item provides a menu with options for cloning, deleting, and exporting the Playbook or Component. See the “Cloning, Exporting, and Deleting a Playbook or Playbook Component” section for more information.
The Playbooks and Components listed on the Playbooks tab can be sorted and filtered by using the menus above the table:
- Name: Enter a search string in the box to search for a Playbook or Component by name. As letters are entered, the screen will narrow down the selections to ones that contain the entered characters.
- Status: Use the Status dropdown menu to display only Playbooks and Components that are Active or that are Inactive.
- Type: Use the Type dropdown menu to display a multi-select list of Trigger types: HttpLink, Component, Timer, Mailbox, and UserAction. Selecting one or more Trigger types will cause only Playbooks with those types of Triggers to be displayed. Selecting the Component option will cause all Playbook Components to be displayed. See the “Triggers” sub-section of the “Designing a Playbook” section for more information about Triggers.
- Label: Use the Label dropdown menu to display a scrollable multi-select list of available labels. Selecting one or more labels will cause only Playbooks and Components with those labels to be displayed.
Creating a New Playbook
- To create a new Playbook, click the + NEW button. A menu with two options will appear (Figure 4).
- Click the New option. The Create Playbook window will appear (Figure 5).
- Make sure the Playbook radio button is selected. See Playbook Components for more information about creating and using Playbook Components.
- Enter the Name of the new Playbook and an optional Description of the Playbook, and then click the SAVE button.
- See the “Designing a Playbook” section for information on how to design a Playbook once it has been created.
Importing a Playbook
Users may upload Playbooks files (.pbx) saved on their computers by importing the files.
- To import a Playbook, click the + NEW button. A menu with two options will appear (Figure 4).
- Click the Import option. Select a .pbx file from the browser window that appears. The Playbook will appear on the Playbooks screen.
NOTE: If a Playbook being imported contains Components, all Components that do not already exist in the importing user’s instance will be imported as well. If a Component with the same name as a Component in the import file already exists, the Component in the import file will not be imported, and the existing Component will be called by the Playbook when the Playbook is run. See Playbook Components for more information about Components.
NOTE: Imported Playbooks and Components will never override existing Playbooks or Components of the same name. If a Playbook is being imported and a Playbook of the same name already exists on the user’s instance, the imported Playbook will be imported with a “1” at the end of its name. For example, a Playbook called “Basic Email Ingest” will be imported with the name “Basic Email Ingest 1”. The same principle applies to Components that are imported on their own (i.e., not as part of a Playbook).
Cloning, Exporting, and Deleting a Playbook or Playbook Component
Clicking on the vertical ellipsis icon to the right of each row of the table on the Playbooks tab causes a menu with Clone, Delete, and Export options to appear (Figure 6).
- To clone (copy) a Playbook or Component (this example uses a Playbook), select the Clone option in the vertical ellipsis menu. The Clone Playbook? window will appear (Figure 7). Click the CLONE button, and a copy of the Playbook will open.
- To export a Playbook or Component, select the Export option in the vertical ellipsis menu. The Export Playbook wizard will appear with the Encrypted tab selected (Figure 8).
NOTE: When exporting a Playbook, all Components called in the Playbook will be exported as well. The Playbook and all of the Components will be downloaded in a single .pbx file.
- Review any displayed encrypted parameters, and then click the Next button. The Review tab will appear (Figure 9).
- Review the provided information, and then click the EXPORT button, and the Playbook will be downloaded to the user's computer.
- To delete a Playbook or Component, select the Delete option in the vertical ellipsis menu. The Delete Playbook? window will appear (Figure 10). Click the DELETE button to delete the Playbook.
NOTE: As stated in the Delete Playbook? window, deleting a Playbook will delete ROI metrics related to that Playbook. See Playbooks: Return on Investment for more details on ROI metrics.
Designing a Playbook
When a new Playbook is created or when the user clicks on an existing Playbook, the Playbook Designer will open in Design Mode, as designated by the orange slider at the top right-hand side of the grid (Figure 11).
The top part of the Playbook Designer displays the Playbook Metadata card. On the left-hand side is the Playbook ROI section. See Playbooks: Return on Investment for more details.
A description of the Playbook may be provided in the Description section. Click on the pencil icon, and a text box will appear (Figure 12). Enter a description in the box, and then click the checkmark icon to save it.
Labels for the Playbook may be provided in the Labels section. Click on the pencil icon, and a text box will appear (Figure 13). Enter a description in the box. As letters are entered, labels that already exist will appear in a dropdown menu. Select one of the labels from the menu or finish entering the label manually, and then click the plus sign icon to save it. Multiple labels may be entered.
To hide the Playbook Metadata card, click the gray box with the “Playbook Metadata” text at the top right-hand side. The arrow next to it will point down, and the card will be hidden, Click the gray box again to show the Playbook Metadata card. If the Auto display Metadata slider is toggled to gray, the Playbook Metadata section will be collapsed by default in all Playbooks that the user views.
Parts of a Playbook
Playbooks are composed of three main building blocks: Triggers, Apps, and Operators. The Playbook Designer opens with the Trigger options provided on the left-hand side of the screen. To toggle between Triggers, Apps, and Operators, click the associated buttons on the top left of the screen. To collapse the left-hand sidebar, click on the double left-arrow icon on the top left of the grid.
NOTE: When a new Playbook is created, the Active slider at the top right of the screen will be displayed in gray, indicating that the Playbook is inactive.
A Trigger is a tool that creates an event that initiates the actions defined within a Playbook to occur. In order to be activated, a Playbook must have one, and only one, Trigger. There are four Trigger categories, which may be viewed by collapsing the menus on the left-hand side of the page (Figure 14).
Click on the down arrow to the right of each list item to expand the list of the Triggers of that type. There are four External Triggers:
- HttpLink: The HttpLink Trigger creates an HTTP 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 HttpLink Trigger, the Playbook can enrich the Indicators with additional context, and then the context can be sent back to the same URL. The endpoint can be viewed by hovering the cursor over the “i” icon on the Trigger item.
- Mailbox: The Mailbox Trigger lets users create a mailbox to send information to a Playbook. The Trigger will fire whenever an email is received in the inbox the user creates. 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 users to Trigger a Playbook on a set schedule (e.g., once a day; on the 15th of the month). It is useful for replicating the existing “jobs” functionality.
- UserAction: The UserAction Trigger allows users to run Playbooks on demand from the Details page of Indicators, Groups, Tracks, or Victims. This Trigger is contextually aware and user driven, and it allows a customized response (HTTP or PlainText.). See Playbooks: The UserAction Trigger for further information.
The Group and Indicator Triggers are simply all of the defined Groups and Indicators, respectively, in the user’s instance of ThreatConnect, and the Other Triggers are the Track and Victim resources.
NOTE: The MultipleIndicator Trigger enables users 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 Step 11 of the "Designing a Playbook" section of this article for more information on output variables.
Triggers may be selected directly from the lists, or they may be entered in the search bar above the lists, which will cause the lists to show all potential matches as each letter is added to the search. The search bar works similarly for 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 12 App categories, which may be viewed by collapsing the menus on the left-hand side of the page after toggling the + APP button (Figure 15).
Click on the down arrow to the right of each list item to expand the list of the Apps of that type. The 12 types are defined as follows:
- Client Apps send a customizable message via a client (e.g., Email, Slack).
- 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. See Playbook Components for more information.
- Endpoint Apps add, update, and remove Indicators from alerting and blocking lists on endpoint security tools.
- Enrichment Apps automate ThreatConnect or third-party enrichment of Indicators.
- Malware Analysis Apps analyze a file artifact for maliciousness and automate actions to be taken on the resulting report data.
- Network Apps add, update, and remove Indicators from alerting and blocking lists on network tools.
- Parser Apps extract data from a file of a given type (CSV, Json, RSS, or XPath).
- SIEM Apps add, update, and remove Indicators from alerting and blocking lists on SIEM tools.
- Static Analysis Apps consist of two separate apps: Extract OLE Streams extracts streams and content from OLE files. Yara Analyze runs YARA rules against a file.
- ThreatConnect Apps perform a task in ThreatConnect.
- Ticketing Apps create a ticket, record, or issue for the Trigger in a third-party system.
- Utility Apps perform data utility functions, like formatting dates and filtering regexes.
Operators are logic- or time-based links between Triggers and Apps. There are three operators (Figure 16).
- Merge: The Merge Operator allows Playbooks to guarantee an outcome in cases of path failures. For instance, an HTTP Client request might fail, but the analyst 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 the user specify an amount of time to wait before executing additional operations in the Playbook. It is useful when using a third-party service that the user knows may take several seconds or minutes to return a response.
- Each Trigger, App, and Operator that is created in a Playbook is represented visually in the Playbook design pane—that is, the grid on the right-hand side of the Playbook Designer (Figure 11). To create an item, simply click on it from the left-hand side of the screen. For example, Figure 17 shows an Address Indicator Trigger.
- Double click inside the newly created Trigger to configure its details (Figure 18).
- If desired, toggle the Display Notes slider at the top right of the Edit section to view information about the Trigger, including a description, its input parameters, and its output variables (Figure 19).
- Enter the name of the Trigger in the Trigger Name field. The Type field is pre-populated with the relevant object type (in this case, Address, because the Trigger is an Address Trigger) and cannot be edited. Click the NEXT button to configure the Action (Figure 20).
- The red exclamation point icon indicates that necessary information is missing. Hover the mouse cursor over the icon to get details on the missing information (Figure 21).
- Select the Owner of the Address Indicator from the dropdown list in the Edit section. Multiple Owners may be selected. Then select the Action Type (that is, what action should be taken on the Address Indicator) from the dropdown menu (Figure 22).
- Depending on the Action Type chosen, further selections may appear at the bottom of the Action section. For example, selecting Action Type Create causes a Fire on Duplicate checkbox to appear (Figure 23). Check this box to specify that the Trigger should create an Address Indicator even when that Indicator already exists in ThreatConnect.
- Click the NEXT button to configure the Filters details (Figure 24).
- Select up to five filters (the number of available filters depends on the choice of Action) from the dropdown menu. For each selected filter, use the dropdown menu and text box below it to configure the value that will cause the Action Type selected in the previous step to occur (Figure 25). Check the box above the filter selection menu if the “OR” operator is to be applied to all selected filters.
- Click the SAVE button.
- Hover the mouse cursor over the hashtag in the upper left corner of the Trigger box to view all available output variables (Figure 26). Output variables are values that a Trigger or App can send to other Playbook Triggers, Apps, and Operators. For example, #trg.tc.weblink is a hyperlink to the Address. It could be used in an Attribute, the body of an email, etc.
- Click the Menu icon in the upper right-hand corner of the Trigger box to edit or delete the Trigger (Figure 27).
- To add an App, click the + APP button at the top left of the screen and choose an App from the dropdown lists. In this example, the Get CAL Enrichment App was chosen (Figure 28).
- If desired, move the App box, and then double click inside the box to configure the App (Figure 29).
- If desired, toggle the Display Notes slider at the top right of the Edit section to view information about the App, including a description, its input parameters, and its output variables (Figure 30).
- Fill in the requested information to configure the App, and then click the SAVE button.
- Click the Menu icon in the upper right-hand corner of the App box to edit the App, set or change the log level, clone (copy) the App, or delete the App (Figure 31).
NOTE: When setting or changing the log level, if the Apply to all 'downstream' apps option is selected, then a log icon will appear at the bottom right of all downstream Apps, indicating that the log level is the same for all of the Apps with the icon.
- If a System Administrator has configured an App for remote execution, then an Environment option will appear in the menu (Figure 32). Choosing this option will allow the user to select an Environment Server on which to execute the App. Once an Environment Server has been selected, an Environment icon will be displayed at the top left of the App. See Multi-Environment Orchestration: Executing Playbook Apps Through a Firewall for more information.
- Some Apps, such as Report False Positive and Report Observation, have a Run As option in their menu (Figure 33). This option allows the App to be run by a selected API user rather than the user who is running the rest of the Playbook so that the false positive or observation is reported by the correct user.
- Click the blue and/or orange dots and drag the lines that appear to connect the Trigger and the App (Figure 34). The Playbook will follow the path from the blue dot if the result of the App, Trigger, or Operator it starts from is successful, and it will follow the path from the orange dot if the result is failure.
- To delete a connection, double click on the blue or orange arrow. The Delete Connection window will appear (Figure 35). Click the YES button to delete the connection.
NOTE: As stated in the window, deleting a connection may break downstream variable references.
- To create an Operator, click the + OPERATOR button at the top left of the screen and choose an Operator from the dropdown list. In this example, the If/Else Operator was chosen (Figure 36).
- If desired, move the Operator box, and then double click inside the box to configure the Operator (Figure 37).
- Fill in the requested information to configure the Operator, and then click the SAVE button.
- Click the Menu icon in the upper right corner of the Operator box (or, for the If/Else Operator, at the top of the diamond) to edit the Operator, set or change the log level, or delete the Operator (Figure 38).
- Add more Apps, Operators, or Triggers, and click the blue and/or orange dots and drag the lines that appear to connect the various boxes to configure the Playbook to function as desired (Figure 39).
- To select and move multiple Triggers, Apps, and/or Operators at one time, click on the lasso tool at the top right of the design pane. Then use the cursor to drag and select the items and move them as a unit.
- Click on the Settings icon in the upper right-hand corner of the Playbook design pane to configure Playbook Settings (Figure 40), which include choosing a different user to run the Playbook as, choosing the log level for the Playbook, choosing a Playbook Server on which to run the Playbook (see Playbook Activity for more information on Playbook Servers), choosing a priority level for the Playbook, and setting ROI parameters for the Playbook (see Playbooks: Return on Investment for more information).
NOTE: It is recommended to set the Playbook Log Level to INFO or WARN, as higher log levels take up large amounts of memory. Specific Apps and Operators may be set to DEBUG or TRACE if desired.
NOTE: If a Private Server is available to the user’s Organization, it will display a lock icon next to the Server’s name in the list of Playbook Servers in the Settings menu. In a multi-tenant instance of ThreatConnect, Private Servers are dedicated instances on which users in an Organization can run a Playbook rather than have the Playbook execute through the queue of the pool of Public Servers (i.e., the Default Server Pool). Private Servers should be used for Playbooks of priority or performance requirements that necessitate their execution outside of the Default Server Pool.
NOTE: Playbook priority level is used to influence a Playbook’s position in the execution queue. When all Playbooks in the execution queue (either in the Default Server Pool or on a Private Server) have the same priority level, they will go through the queue on a first-in, first-out (FIFO) basis. When a Playbook of higher priority enters the queue, its execution will take precedence over any lower-priority Playbooks waiting in the queue, regardless of existing queue order. When multiple Playbooks of a given priority level are in the queue, they will execute on a FIFO basis within their priority level. For example, if there are two high-priority Playbooks, three medium-priority Playbooks, and four low-priority playbooks in the queue, the two high-priority Playbooks will execute first, in the order in which they were entered in the queue (i.e., FIFO), the three medium-priority Playbooks will execute next in FIFO order, and then the four low-priority Playbooks will execute last in FIFO order. If, while the medium-priority Playbooks are executing, another high-priority Playbook enters the queue, the high-priority Playbook will execute after the current execution completes, and then the queue will go back to executing the medium-priority Playbooks. The default priority level for a Playbook is Medium.
- Hover the cursor over the vertical ellipsis icon in the upper right-hand corner of the Playbook design pane (Figure 41) to clone (copy) the Playbook, clone the Playbook as a Component (for more information, see Playbook Components), delete the Playbook, export the Playbook, or reset the logging level for all Apps in the Playbook to the Playbook default.
- Click the screen-mode icon to toggle to full-screen mode (Figure 42) if desired. Full-screen mode hides the title, description, and ROI information at the top of the Playbooks screen so that the user can have more screen space for working with the Playbook itself. To exit full-screen mode, click the screen-mode icon again.
- Toggle the Active switch in the top right-hand corner of the Playbook Designer. It will turn orange, indicating that the Playbook is active. The Playbook Designer will switch from Design Mode to Execution Mode, as indicated by the Design Mode switch at the top right of the Playbook design pane, which will change in color from orange to gray (Figure 43). Note that active Playbooks may not be edited, except for their Name. To edit a Playbook, toggle the Active switch back to gray (indicating that the Playbook is now inactive), which will automatically toggle the Design Mode switch back to orange (indicating that Design Mode is now on). Toggling the Design Mode switch to orange while a Playbook is active will allow the user to view the details of the Playbook as they appear in Design Mode, but it will be impossible to make changes to the Playbook; that is, double clicking on or attempting to create a Trigger, App, or Operator will not be possible.
NOTE: Only Organization Administrators and higher may activate and de-activate Playbooks.
NOTE: From the Playbooks tab on the Playbooks screen, active Playbooks open in Execution Mode, and inactive Playbooks open in Design Mode. Components always open in Design Mode, as there is no Execution Mode for Components, but they may not be edited until they are inactivated.
- Errors may occur when an attempt is made to activate a Playbook that is not configured properly. If an error occurs, a red warning message will appear for several seconds in the upper right-hand corner of the screen (Figure 44).
- Click the red exclamation point icon at the top right of the screen, which will turn gray and white when clicked, to view a message listing the error(s) that prevented the Playbook from being activated (Figure 45).
Playbook Execution and Logging
When a Playbook is active, details about the Playbook's executions, including execution logs for each app, may be viewed in Execution Mode.
- Open or view an active Playbook in Execution Mode (Figure 46).
- The Execution Mode screen shows the list of executions on the left-hand side. A green circle to the left of an execution indicates a fully successful execution. An orange circle indicates a partially failed execution (that is, one or more pathways failed, while others ran successfully). A red circle indicates complete failure of the Playbook (that is, all pathways failed). Click on an execution to see a list of all of the steps in the execution and their respective results. The grid on the right-hand side of the screen will visually depict the path the execution took by showing in color the steps that executed, regardless of the result, and graying out the steps that were not taken (Figure 47).
- Click on an item in the Steps list on the left or a Trigger, App, or Operator icon in the grid on the right. Details on the execution for that Trigger, App, or Operator will appear at the bottom of the screen (Figure 48). The Details section will contain up to five tabs, depending on the Trigger, App, or Operator that has been chosen.
- Trigger or Jobs: For a Trigger, this tab displays the name of the Trigger and the execution status of the Trigger (e.g., Executed). For Apps and Operators, this tab displays details about the Job that executed.
- Inputs: This tab displays the names and values of all inputs passed to the App or Operator. Triggers do not take inputs, so a Trigger will not display this tab. Inputs are recorded only when the log level for the App or Operator has been set to DEBUG or TRACE.
- Outputs: This tab displays the names and values of all outputs from the Trigger, App, or Operator. Outputs are recorded only when the log level for the Trigger, App, or Operator has been set to DEBUG or TRACE.
- App Logs: This tab displays the logs for an App. The information it provides is dependent on the logging level assigned to the App. A search bar is also provided so that the logs can be searched for an entered term. The logs can be downloaded into a .csv file.
- OS Logs: This tab displays the logs generated on the server side of the Playbook execution. It also provides the capability to download all OS logs (e.g., standard error, standard output, logs particular to the given App). Note that the logs must be downloaded together as a single .zip file. They cannot be downloaded individually. Also note that some Apps do not support OS logs, so no OS Log tab will be available for those Apps.