The Playbooks Screen
  • 05 Dec 2022
  • 8 Minutes to read
  • Dark
    Light

The Playbooks Screen

  • Dark
    Light

Minimum Role: Organization role of Read Only User (for viewing); Organization role of User (for creating, modifying, activating, and deleting)

Prerequisites: Playbooks enabled by a System Administrator

Overview

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.

The Playbooks screen lists all Playbooks, including Playbook Components, available in your Organization. From this screen, you can perform a variety of actions, including creating new Playbooks, searching for and opening Playbooks, importing and exporting Playbooks, cloning Playbooks, and deleting Playbooks.

The Playbooks Screen

On the top navigation bar, click Playbooks to display the Playbooks screen, which shows all available Playbooks and Components in your Organization (Figure 1).

Graphical user interface, text, application, email  Description automatically generated

 

Note
If no Playbooks have been created in your Organization, or if there are pre-existing filter settings that do not match any Playbooks in your Organization, the Playbooks screen will display a message stating that no Playbooks were found.

This screen contains up to six tabs at the top left: Activity, App Builder, Environments, Playbooks, Services, and Templates. This article covers the Playbooks tab.

Note
The Activity and Environments tabs will be visible only to users with an Organization role of Organization Administrator. The Apps tab will be visible only to users with an Organization role of Organization Administrator or App Builder. The Services tab will be visible only to users with an Organization role of Organization Administrator and whose Organization has System-level permissions enabled for the app build functionality.

The Playbooks Table

The Playbooks screen is organized into a table with nine columns:

  • Type: This column displays icons that illustrate the type of item in each row.
  • A green checkmark above the Playbook or Component icon (as demonstrated by the Acme and Basic Email Ingest Playbooks and the Block IP Address Component in Figure 1) indicates that the Playbook or Component is active and available for execution.
  • Name: This column displays the name of the Playbook or Component. Click on the name to open the Playbook or Component. If there is a WebHook or Mailbox Trigger in the Playbook, the Trigger URL (WebHook) or Target Mailbox (Mailbox) of the Trigger will be displayed under the Playbook name. Components do not have Trigger URLs or Target Mailboxes 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
    If you hover over any part of a row containing an active Playbook with a URL endpoint, two icons will be displayed to the right of the endpoint. Click the Copy Endpoint icon to copy the URL endpoint to the clipboard. Click the Execute Endpoint icon to execute the Playbook’s endpoint. These icons are not displayed for Components.
  • Version: This column displays the version number of the Playbook or Component.
  • Trigger: This column displays the type of Trigger that initiates execution of the Playbook. 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 the 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 do not have log levels.
  • Updated: This column displays the date and time at which the Playbook or Component was last updated.
  • ROI: Click the graph icon in the ROI column to display a window containing return on investment (ROI) metrics for the Playbook. Components do not have ROI metrics.
  • Administrative Options Menu: Click the vertical ellipsis icon for an item to display a menu with the following administrative options: Clone, Delete, Export, and Import New Version.

Searching and Filtering Playbooks

Playbooks and Components can be searched and filtered by using the menus above the table:

  • Name: Enter the name of a Playbook or Component in the search box.
  • Status: Use this dropdown to filter Playbooks and Components by status (Active or Inactive).
  • Type: Use this dropdown to display a scrollable multi-select list of Trigger types. Select one or more Trigger types to display only Playbooks with those types of Triggers. Select the Component option to display only Playbook Components. Use the All / None links above the dropdown to select or deselect all Trigger types, respectively.
  • Label: Use this dropdown to display a scrollable multi-select list of available labels. Select one or more labels to display only Playbooks and Components with those labels. Use the All / None links above the dropdown to select or deselect all labels, respectively.
Note
The searches and filters you apply to the table on the Playbooks screen will persist, even if you navigate to another screen in ThreatConnect or log out of ThreatConnect.

Creating a New Playbook

  1. Hover over the NEW button at the upper-left corner of the Playbooks screen and select Create Playbook. The Create Playbook window will be displayed (Figure 2). Graphical user interface, text, application, email  Description automatically generated

     

    • Name: Enter a name for the Playbook.
    • Description: Enter a description for the Playbook.
    • Leave the Playbook option selected.
    • Click the SAVE button.
  2. The new Playbook will open in the Playbook Designer.

For more information about creating Playbook Components and Workflow Playbooks, see Creating a Component and Creating a Workflow Playbook, respectively.

Importing a Playbook

You can import a Playbook by uploading a Playbook file (.pbxz or .pbx) that has been saved on your local drive.

  1. Hover over the NEW button at the upper-left corner of the Playbooks screen and select Import Playbook.
  2. Use the file browser to select a .pbxz or .pbx file to upload. If importing a .pbxz file, the Import Playbook drawer will be displayed (Figure 3). If importing a .pbx file, the Playbook will open in the Playbook DesignerGraphical user interface, application  Description automatically generated

     

    Note
    When importing a Playbook with Service Triggers, you will be prompted to install any Apps that do not exist in your Organization and to associate Triggers being imported with available Trigger Services.
    • A preview image of the Playbook will be displayed in the Playbook Preview section. Click the image to expand it, if desired.
    • To select a different file to upload, click the NEW FILE button.
    • Click the IMPORT button to import the file as a new Playbook in the Playbook Designer.
Important
If a Playbook you are importing contains Components, all Components that do not already exist in your instance will also be imported. 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.
Important
Imported Playbooks and Components will never override existing Playbooks or Components of the same name. If a Playbook you are importing has the same name as a Playbook that already exists on your instance, a “1” will be added to the end of the imported Playbook’s name. The same principle applies to Components that are imported on their own (i.e., not as part of a Playbook).

Importing a Shared Playbook

You can import a shared Playbook via its Share Token.

  1. Hover over the NEW button at the upper-left corner of the Playbooks screen and select Import Shared Playbook. The Import Playbook drawer will be displayed (Figure 4). Graphical user interface, application  Description automatically generated

     

  2. Enter the shared Playbook’s Share Token in the Share Token box, and then click VERIFY. If the Share Token is valid, the Playbook Preview will be displayed (Figure 5). If the Share Token is not valid, a message will be displayed stating that ThreatConnect is unable to import the Playbook and asking you to confirm whether the token is valid. Graphical user interface, application  Description automatically generated

     

  3. Click the IMPORT button to import the file as a new Playbook in the Playbook Designer.

Playbook Administrative Options

On the Playbooks screen (Figure 1), click the vertical ellipsis  icon to the right of each row of the table to display a menu with administrative options for the corresponding Playbook (Figure 6).

Graphical user interface, application, PowerPoint  Description automatically generated

 

Clone

  1. Select the Clone option in Figure 6 to clone a Playbook or Component. The Clone Playbook window will be displayed (Figure 7). Graphical user interface, application  Description automatically generated

     

  2. By default, the name of the new Playbook will be Copy of <original Playbook name>. To edit the name of the Playbook, click in the Name box.
    Important
    When a Playbook is cloned, it is always named Copy of <original Playbook name> by default. If a Playbook has previously been cloned and its name was not edited (i.e., its name was saved as Copy of <original Playbook name>), the name for any subsequent copies of the Playbook will need to be manually edited.
  3. Select the type of object that the Playbook should be cloned as (Playbook, Component, or Workflow Playbook), and then click the CLONE button. The cloned object will open in the Playbook Designer.

Delete

Select the Delete option in Figure 6 to delete a Playbook or Component. The Delete Playbook? window will be displayed. Click the DELETE button to delete the Playbook.

Important
Deleting a Playbook will delete all ROI metrics related to that Playbook.

Export

  1. Select the Export option in Figure 6 to export a Playbook or Component. If there are no encrypted parameters in the Playbook, it will automatically download to your local drive. If there are encrypted variables, the Export Playbook drawer will be displayed (Figure 8). Text  Description automatically generated

     

  2. Review the displayed encrypted parameters, and then click the EXPORT button to download the Playbook to your local drive.
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 .pbxz file.

Import New Version

  1. Select the Import New Version option in Figure 6 to import a Playbook or Component from your local drive as a new version of an existing Playbook or Component, respectively.
  2. Use the file browser to select a .pbxz or .pbx file. If importing a .pbxz file, the Import Playbook Version drawer will be displayed (Figure 9). If importing a .pbx file, the new version of the Playbook will open in the Playbook DesignerGraphical user interface, application  Description automatically generated

     

    • A preview image of the Playbook will be displayed in the Playbook Preview section. Click the image to expand it, if desired.
    • To select a different file to upload, click the NEW FILE button.
    • Click the IMPORT button to import the file as a new version of the Playbook in the Playbook Designer.

ThreatConnect® is a registered trademark of ThreatConnect, Inc.

20112-01 v.02.B


Was this article helpful?