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 five tabs at the top left: Activity, Apps, Environments, Playbooks, and Templates. This article covers the Playbooks tab. See Playbook Activity, App Builder, Playbook Environments, and Playbook Templates for information on the Activity, Apps, Environments, and Templates tabs, respectively.
NOTE: The Activity and Environments tabs will be visible only to Organization Administrators and higher whose Organization has permissions enabled for the app build functionality.
The Playbooks tab is organized into 8 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 “Basic Email Ingest” Playbook, the “Block IP Address” Component, and the “Deploy Related Indicators to SIEM” Playbook in Figure 3) indicates that the Component or Playbook is active. See the “Activating a Playbook” section for more information about activating a Playbook, and see the “Playbook Execution and Logging” section for more information about 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 be displayed 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.
- Version: This column displays the version number of the Playbook or Component. See Playbook Versions for more information.
- Trigger: This column displays the type of Trigger that initiates execution of the Playbook. See the “Triggers” 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 be displayed. See Playbooks: Return on Investment for more details on ROI metrics. Components do not have ROI metrics associated with them.
- Administrative Options Menu: Clicking the vertical ellipsis icon for an item provides a menu with the following administrative options: Clone, Delete, Export, and Import New Version. See the “Playbook Administrative Options” 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 only Playbook Components to be displayed. See the “Triggers” 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, hover the cursor over the New button at the top left of the screen. A menu with two options will be displayed (Figure 4).
- Click the Create Playbook option. The Create Playbook window will be displayed (Figure 5).
- Ensure that 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 “The Playbook Designer” 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, hover the cursor over the New button at the top left of the screen. A menu with two options will be displayed (Figure 4).
- Click the Import Playbook option. Select a .pbx file from the browser window that appears. The Playbook will be displayed 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).
Playbook Administrative Options
Clicking on the vertical ellipsis icon to the right of each row of the table on the Playbooks tab causes a menu with the following administrative options to be displayed (Figure 6): Clone, Delete, Export, and Import New Version.
To clone (copy) a Playbook or Component (this example uses a Playbook), select the Clone option in Figure 6. The Clone Playbook? window will be displayed (Figure 7).
Click the CLONE button, and a copy of the Playbook will open in the Playbook Designer with the name “Copy of <original Playbook name>.” If a Playbook with that name already exists (i.e., the Playbook has been cloned previously), then a number will be added to the end of the name (e.g., if “Copy of My Playbook” already exists, then the new Playbook will be named “Copy of My Playbook 1”; if “Copy of My Playbook 1” already exists, then the new Playbook will be named “Copy of My Playbook 2,” etc.).
To delete a Playbook or Component, select the Delete option in Figure 6. The Delete Playbook window will be displayed (Figure 8).
Click the YES 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.
To export a Playbook or Component, select the Export option in Figure 6. The Export Playbook screen will be displayed with the Encrypted tab selected (Figure 9).
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 be displayed (Figure 10).
Review the provided information, and then click the EXPORT button. The Playbook will be downloaded to the user’s computer.
Import New Version
To import a new major version of a Playbook or Component, select the Import New Version option in Figure 6. Choose a .pbx file from the browser window that appears. The file will be imported as a new major version. See Playbook Versions for more information.
The Playbook Designer
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 design pane—that is, the grid on the right-hand side of the Playbook Designer (Figure 11).
The name of the Playbook is displayed at the top left of the screen. To change the name, click on the pencil icon and enter a new name for the Playbook. The version number of the Playbook is displayed next to the name. See Playbook Versions for more information.
When the Active slider at the top right of the screen is toggled to gray (off), the Playbook is inactive. When the slider is toggled to orange (on), the Playbook is active. See the “Activating a Playbook” section for more information.
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 be displayed (Figure 12). Enter or edit the 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 be displayed (Figure 13). Enter a label 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 display the Playbook Metadata card if desired.
If the Auto display Metadata slider is toggled to gray (off), the Playbook Metadata section will be collapsed by default in all Playbooks that the user views. If the slider is toggled to orange (on), the Playbook Metadata section will be displayed 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 design pane.
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 clicking the + TRIGGER button in Figure 11 and 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 icon on the Trigger box, which will appear when the Trigger is added to the Playbook design pane. See the “Adding and Configuring Triggers” section for more information.
- 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 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.
- 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 more information.
The Group and Indicator Triggers are simply all of the defined Groups and Indicators, respectively, in the user’s instance of ThreatConnect. The Other Triggers are the Track and Victim objects.
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 12 of the "Adding and Configuring Triggers" section for more information on output variables for Triggers.
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 display all potential matches as each letter is added to the search.
An App is a tool that is used to act on data provided by a Trigger or another App within the Playbook. There are 13 App categories, which may be viewed by clicking the + APP button in Figure 11 and collapsing the menus on the left-hand side of the page (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 13 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.
- Data Ingest Apps ingest data into third-party products that typically use data from ThreatConnect.
- 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, EML/MSG, 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. These Apps examine an executable file without viewing the actual instructions, which can confirm whether a file is malicious.
- ThreatConnect Apps perform a task in ThreatConnect.
- 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).
- Utility Apps perform data utility functions, like formatting dates and filtering regexes.
Apps may be selected directly from the lists, or app names or labels may be entered in the search bar above the lists, which will cause the lists to display all potential matches as each letter is added to the search.
Operators are logic- or time-based links between Triggers and Apps. There are five operators, which may be viewed by clicking the + OPERATOR button in Figure 11 (Figure 16).
- 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 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.
- 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. See Playbooks Iterator Operator for more information.
- 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. See Playbooks Iterator Operator for more information.
Designing a Playbook
Each Trigger, App, and Operator that is created in a Playbook is represented visually in the Playbook design pane (Figure 11). To add an item, simply click on it from the left-hand side of the screen.
Adding and Configuring Triggers
NOTE: Scroll down the Output Variables bubble to see all of the listed output variables.
- To add a Trigger, click the + TRIGGER button at the top left of the Playbook Designer. All available Triggers will be displayed to the left of the design pane (Figure 17). To narrow down the results, collapse the sub-menus, or type the name of the desired Trigger in the search bar.
- Click on a Trigger, and it will be added to the design pane. For example, in Figure 18, an Address Indicator Trigger was added.
- Double click inside the Trigger to configure it (Figure 19).
- If desired, toggle the Display Notes slider at the top right of the Edit pane to view information about the Trigger, including a description, its input parameters, and its output variables (Figure 20).
- 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 21).
- The red exclamation point icons at the bottom left corner of the Trigger box and on the Action step in the Edit pane indicate that required information is missing. Hover the cursor over the icon on the Trigger box to get details on the missing information (Figure 22).
- Select the Owner of the Address Indicator from the dropdown list in the Edit pane. Multiple Owners may be selected. Then select the Action Type (i.e., the action to be taken on the Address Indicator) from the dropdown menu (Figure 23).
- Depending on the Action Type chosen, further selections may be displayed at the bottom of the Action section. For example, selecting Create for the Action Type causes a Fire on Duplicate checkbox to appear (Figure 24). 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 25).
- Select up to five filters (the number of available filters depends on the Action chosen) 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 26). Select the checkbox above the filter selection menu to use “OR” logic with multiple filters.
- Click the SAVE button.
- Hover the mouse cursor over the hashtag in the upper left corner of the Trigger box in the design pane to view all available output variables (Figure 27). Output variables are values that a Trigger, App, or Operator 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 28).
Adding and Configuring Apps
NOTE: To get the latest version of an App, please contact your System Administrator.
NOTE: Scroll down the Output Variables bubble to see all of the listed output variables.
- To add an App, click the + APP button at the top left of the Playbook Designer. All available Apps will be displayed to the left of the design pane (Figure 29). To narrow down the results, collapse the sub-menus, or type the name of the desired App in the search bar.
- Click on an App, and it will be added to the design pane (Figure 30).
- If desired, move the App, and then double click inside the App to configure the it (Figure 31).
- If desired, toggle the Display Notes slider at the top right of the Edit pane to view information about the App, including its version, a description, its input parameters, and its output variables (Figure 32).
- Fill in the requested information to configure the App, and then click the SAVE button.
- Hover the mouse cursor over the hashtag in the upper left corner of the App to view all available output variables (Figure 33). Output variables are values that a Trigger, App, or Operator can send to other Triggers, Apps, and Operators. For example, #cal.indicators.success is an array containing the Indicators for which CAL was successfully queried. These Indicators could be passed to another App that will perform an action on them, such as modifying their data in ThreatConnect or reporting them to a SIEM.
- 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 34).
NOTE: When setting or changing the log level, if the Apply to all 'downstream' apps option is selected, then a log icon will be displayed 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 be displayed in the menu (Figure 35). 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 36). This option allows the App to be run by a selected 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 dot on the Trigger and drag the line that appears to connect the Trigger and the App (Figure 37). Apps and Operators (see the "Adding and Configuring Operators" section) have blue and orange dots. The Playbook will follow the path from the blue dot if the result of the App or Operator it starts from is successful. It will follow the path from the orange dot if the result is failure.
- To delete a connection, click on the blue or orange arrow. The Delete Connection window will be displayed (Figure 38). Click the YES button to delete the connection.
NOTE: As stated in the window, deleting a connection may break downstream variable references.
Adding and Configuring Operators
NOTE: Scroll down the Output Variables bubble to see all of the listed output variables.
- To add an Operator, click the + OPERATOR button at the top left of the Playbook Designer. All available Operators will be displayed to the left of the design pane (Figure 39). See Playbooks Iterator Operator for more information about the Iterator and Break Iterator Operators.
- Click on an Operator, and it will be added to the design pane (Figure 40).
- If desired, move the Operator, and then double click inside the Operator to configure it (Figure 41).
- If desired, toggle the Display Notes slider at the top right of the Edit pane to view information about the Operator, including a description, its input parameters, and its output variables (Figure 42).
- Fill in the requested information to configure the Operator, and then click the SAVE button.
- The Merge and Iterator Operators are the only Operators that have output variables, which are values that a Trigger, App, or Operator can send to other Triggers, Apps, and Operators. For these Operators, these variables do not automatically exist, but must be configured by the user. See Playbooks Iterator Operator for more information regarding the Iterator Operator. For the Merge Operator, once it is connected to a calling App (i.e, an App directly upstream), output variables from that App become available to the Merge Operator. In the Output Variables section of the Edit pane for the Merge Operator, create output variables by entering key/value pairs. In the Key field, enter a name for the output variable being created. In the Value field, enter a hashtag (#) to display a list of variables available from the upstream App, and then select a value from the list. Click the Plus button to accept them into the Output Variables table. To view all available output variables for an Operator, hover the mouse cursor over the hashtag in the upper left corner of the Operator (Figure 43).
- Click the Menu icon in the upper right corner of the Operator (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 44).
Formatting a Playbook
Add more Apps, Operators, or Triggers, and click the blue and/or orange dots and drag the lines that appear to connect the boxes to configure the Playbook logic (Figure 45).
The top three icons on the vertical gray panel on the right of the design pane provide options for formatting the view in the Playbook Designer:
- Zoom-to-fit icon: Click this icon to resize the Playbook elements so that all elements fit fully on the screen at one time.
- Zoom-in icon: Click this icon to increase the size of the Playbook elements.
- Zoom-out icon: Click this icon to decrease the size of the Playbook elements.
The Auto-layout icon on the vertical gray panel on the right of the design pane redistributes the Playbook elements to best represent the flow of Playbook logic. For example, the layout Playbook in Figure 46 is jumbled and confusing.
To arrange the elements in the most optimal configuration, click the Auto-layout icon. The Confirm Auto-layout window will be displayed (Figure 47).
NOTE: The auto-layout operation cannot be undone.
Click the YES button. The Playbook elements will redistribute (Figure 48).
The Bulk Selection icon on the vertical gray panel on the right of the design pane allows multiple Playbook elements to be selected and then deleted at one time. Click the icon and then drag and drop the cursor in the design pane to select the group of elements to be deleted. The outline of each selected element will change to red dashes (Figure 49).
A trash icon will appear in the vertical gray panel (Figure 50).
Click the trash icon, and the Delete window will be displayed (Figure 51). Click the YES button to confirm the deletion.
Click on the Settings icon in the upper right-hand corner of the Playbook Designer to configure the settings for the Playbook (Figure 52).
Use the dropdown menu to select the name of the user under which the Playbook should execute. This menu will be disabled if the Run as current user checkbox was enabled for a UserAction Trigger in the Playbook. See Playbooks: The UserAction Trigger for more information.
Use the dropdown menu to select the log level for the Playbook. Table 1 describes each log level, from least to most granular.
|ERROR||The ERROR log level will record only serious issues, such as a failure of an important process within the execution of a Playbook or Playbook App. The Playbook or Playbook App will still be able to run, but the problem, such as a dropped database connection or the inability to access a file or service, will require remediation in the near future.|
|WARN||The WARN log level will record unexpected and unusual, but not necessarily serious, problems in the execution of a Playbook or Playbook App, such as an attempt to invoke a service that resulted in failures before a successful connection on an automatic retry. It is unknown whether the issue will persist or recur. Warnings should be investigated, but are typically not urgent.|
|INFO||The INFO log level will record normal behavior and milestones for the execution of a Playbook or Playbook App, such as the start or exit of an App or the submission of an Indicator to a SIEM.|
|DEBUG||The DEBUG log level records detailed diagnostic information about the execution of a Playbook or Playbook App. For example, an App with this logging level may provide additional telemetry about a network or proxy connection.|
|TRACE||The TRACE log level records very detailed diagnostic information about the execution of a Playbook or Playbook App. This log level provides the most granular information and is used to capture every possible detail about the Playbook or Playbook App’s behavior.|
Log levels cascade; in other words, any log level will capture details at its own level and at all less granular log levels. For instance, INFO will capture WARN and ERROR messages, but exclude DEBUG and TRACE messages. Apps written in Python do not distinguish between DEBUG and TRACE log levels. Either can be used during Playbook design with the same effect.
Setting the log level for a Playbook App to DEBUG or TRACE activates input- and output-parameter value capture in the Input and Output tabs, respectively, for that App’s step in the Details section of the Execution Mode screen for the Playbook (Figure 53 and Figure 54).
See the “Playbook Execution and Logging” section for more information on the Execution Mode screen.
It is recommended during Playbook development that the log levels of individual Apps be set to DEBUG or TRACE in order to maximize the amount of detail available in the logs on the Execution Mode screen. Once a Playbook is ready for production, it is recommended to drop the Apps’ log levels to INFO, WARN, or ERROR. Leaving the log level for an App at DEBUG or TRACE will generate excessive amounts of information in a high-volume environment and may affect system performance. Similarly, it is recommended to set the log level for the Playbook itself to INFO or WARN.
Use the dropdown menu to select the server or group of servers on which the Playbook should execute. If a private server is available to the user’s Organization, a lock icon will be displayed next to the server’s name. 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.
Use the dropdown menu to select the priority level for the Playbook. 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.
Enter the number of minutes of analyst time that will be saved with each execution of the Playbook in the Minutes box, or use the up and down arrows to add or subtract increments of 1, respectively. Enter the hourly rate of the analyst in the Rate/Hour box, or use the up and down arrows to add or subtract increments of 1. Every time the Playbook executes, these values will be used to calculate how much time and money were saved by executing the Playbook rather than having the analyst do the work manually. See Playbooks: Return on Investment for more information.
Playbook Designer Administrative Options
Click the vertical ellipsis icon in the upper right-hand corner of the Playbook Designer (Figure 55) to view administrative options for the Playbook.
Click the Clone option in Figure 55 to make a clone (copy) of the Playbook. The Clone Playbook window will be displayed (Figure 56).
Click the YES button to clone the Playbook. The cloned Playbook will open in the Playbook Designer with the name “Copy of <original Playbook name>.” If a Playbook with that name already exists (i.e., the Playbook has been cloned previously), then a number will be added to the end of the name (e.g., if “Copy of My Playbook” already exists, then the new Playbook will be named “Copy of My Playbook 1”; if “Copy of My Playbook 1” already exists, then the new Playbook will be named “Copy of My Playbook 2,” etc.).
Clone as Component
Click the Clone as Component option in Figure 55 to clone the Playbook as a Component. See the “Cloning a Playbook as a Component” section in Playbook Components for more information.
Create New Version
Click the Create New Version option in Figure 55 to create a new major version of the Playbook. The Create New Version Playbook window will be displayed (Figure 57).
Enter information about the new version in the Comment section. See Playbook Versions for more information.
Click the Delete option in Figure 55 to delete the Playbook. The Delete Playbook window will be displayed (Figure 58).
Click the YES button to delete the Playbook, including all of its associated versions and ROI metrics.
Click the Export option in Figure 55 to export the Playbook as a .pbx file. See the “Export” section for more information.
Import New Version
Click the Import New Version option in Figure 55 to import a new major version of the Playbook. Choose a .pbx file from the browser window that appears. The file will be imported as a new major version. See Playbook Versions for more information.
Click the Version History option in Figure 55 to view the version history for the Playbook. See Playbook Versions for more information.
Reset Apps Logging Level
Click the Reset Apps Logging Level option in Figure 55 to reset the log levels for all apps in the Playbook to the default log level specified under Log Level in the Settings menu.
Click the screen-mode icon to toggle to full-screen mode (Figure 59) 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.
Activating a Playbook
Toggle the Active slider in the top right-hand corner of the Playbook Designer to orange (on). The Playbook Designer will switch from Design Mode to Execution Mode, as indicated by the Design Mode slider at the top right of the Playbook design pane, which will toggle to gray (off) (Figure 60). Active Playbooks may not be edited. To edit a Playbook, toggle the Active slider back to gray (indicating that the Playbook is now inactive), which will automatically toggle the Design Mode slider back to orange (on). The Design Mode slider may not be toggled to the on position while a Playbook is active.
NOTE: Every time a Playbook is activated, a new minor version of the Playbook is created. See Playbook Versions for more information.
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 61).
Click the red exclamation point icon at the top right of the screen to view a message listing the error(s) that prevented the Playbook from being activated (Figure 62).
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 63).
- 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 right-hand side of the screen displays 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 64).
- Click on an item in the Steps list on the left or a Trigger, App, or Operator element on the right. Details on the execution for that Trigger, App, or Operator will be displayed at the bottom of the screen (Figure 65). 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 depends on the log 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). The logs must be downloaded together as a single .zip file. They cannot be downloaded individually. For Apps that do not support OS logs, no OS Log tab will be available.
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.