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 (Figure 2).
Creating a New Playbook
- To create a new Playbook, click the NEW button. The Create Playbook window will appear (Figure 3).
- 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.
Cloning, Exporting, and Deleting a Playbook or Playbook Component
NOTE: As stated in the Delete Playbook window, deleting a Playbook will delete return on investment (ROI) metrics related to that Playbook. See Playbooks: Return on Investment for more details on ROI metrics.
- To clone (copy) a Playbook or Component (this example uses a Playbook), click the Clone icon in the Options column for the Playbook in the Playbooks screen (Figure 2). The Clone Playbook window will appear (Figure 4). Click the YES button, and a copy of the Playbook will open.
- To export a Playbook or Component, click the Export icon in the Options column for the Playbook or Component in the Playbooks screen (Figure 2). The Export Playbook wizard will appear with the Encrypted tab selected (Figure 5).
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 6).
- 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, click the Delete icon in the Options column for the Playbook in the Playbooks screen (Figure 2). The Delete Playbook window will appear (Figure 7). Click the YES button to delete the Playbook.
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 red slider on the top right-hand side of the grid (Figure 8). Click on the Description text to expand and edit the Description. Click on the Playbook ROI text to collapse the Playbook ROI section. If the Auto display ROI slider is toggled to gray, the Playbook ROI section will be collapsed by default in all Playbooks that the user views. See Playbooks: Return on Investment for more details on the Playbooks ROI feature.
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. There are four Trigger categories, which may be viewed by collapsing the menus on the left-hand side of the page (Figure 9).
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 10 later in 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 10).
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 11).
- 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 8). To create an item, simply click on it from the left-hand side of the screen. For example, Figure 12 shows an Address Indicator Trigger.
- Double click inside the newly created Trigger to configure its details (Figure 13).
- Enter the name of the Trigger in the Trigger Name field. Click the NEXT button to configure the Action (Figure 14).
- 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 15).
- Select the Owner of the Address Indicator from the drop-down list. Multiple Owners may be selected. Then select the Action Type (that is, what action should be taken on the Address Indicator) from the drop-down menu (Figure 16).
- 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 17). 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 18).
- 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 19). 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 20). 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 21).
- To add an App, click the + APP button at the top left of the screen and choose an App from the drop-down lists. In this example, the Get VirusTotal Enrichment App was chosen (Figure 22).
- If desired, move the App box, and then double click inside the box to configure the App (Figure 23).
- Fill in the requested information to configure the App, and then click the SAVE button. Hover the cursor over the question-mark icon next to the name of the App to view a tooltip with information about what the App does, its parameters, and its inputs and outputs.
- Click the Menu icon in the upper right-hand corner of the App box to edit the App, set or change the log level, choose a remote environment on which the App is to be run, clone (copy) the App, or delete the App (Figure 24).
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 of all downstream Apps, indicating that the log level is the same for all of the Apps with the icon.
NOTE: The Environment option will appear only if a System Administrator has configured the App for remote execution and if an Environment Server has been configured and assigned to the ThreatConnect instance. 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 25). 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 26). 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 create an Operator, click the + OPERATOR button at the top left of the screen and choose an Operator from the drop-down list. In this example, the If/Else Operator was chosen (Figure 27).
- If desired, move the Operator box, and then double click inside the box to configure the Operator (Figure 28).
- 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 29).
- 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 30).
- 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 31), which include choosing a different user to run the Playbook as, choosing the log level for the Playbook, and setting ROI information for the Playbook. See Playbooks: Return on Investment for more details on ROI metrics.
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.
- Hover the cursor over the vertical ellipsis icon in the upper right-hand corner of the Playbook design pane 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 (Figure 32).
- Click the screen-mode icon to toggle to full-screen mode (Figure 33) 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 34). Note that active Playbooks may not be edited, except for their Name and Description. 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 main 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.
- 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 35).
- Click the red exclamation point icon to view a message listing the error(s) that prevented the Playbook from being activated (Figure 36).
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 37).
- 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 (not shown in Figure 37) 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 38).
- 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 39). 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.
ThreatConnect provides a set of Playbooks Templates that may be customized to a user’s specific needs. All available Templates are listed below a user’s Playbooks on the main Playbooks screen (Figure 40). As a shortcut, use the VIEW TEMPLATES button (Figure 2) to jump down to the list instead of scrolling.
- To import a Template, click the up-arrow button in the Options column for that Template. The Import Playbook wizard will appear with the Apps tab selected (Figure 41). The Apps tab verifies that all of the Apps needed to successfully run the Playbook are installed.
- Click the Next button to advance to the Variables tab (Figure 42), which verifies the existence of the Variables needed to successfully run the Playbook.
- Click the IMPORT button at the bottom right to complete the import process. The imported Playbook will appear in inactive mode in the Playbook Designer (Figure 43). The Playbook will also be available for editing from the list of user-owned Playbooks at the top of the main Playbooks screen.
- Users may upload Playbooks files (.pbx) saved on their computers by clicking the IMPORT button (Figure 2). 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.
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 in the 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).