Executing a Playbook
  • 29 Jan 2024
  • 5 Minutes to read
  • Dark
    Light

Executing a Playbook

  • Dark
    Light

Article Summary

Overview

A Trigger is an event that initiates the actions defined within a Playbook, which can vary depending on the type of Trigger used in the Playbook. This article covers how to execute Playbooks that use Mailbox, Timer, UserAction, WebHook, Group, Indicator, Intel Requirement, Case, Track, and Victim Triggers.

In addition to the methods described in the “Executing Playbooks” section of this article, you can create and use a Run Profile to perform a sample execution of a Playbook.

Before You Start

Minimum Role(s)
  • Organization role of Read Only User (for viewing Playbooks)
  • Organization role of Standard User (for creating, modifying, deleting, activating, de-activating, and executing Playbooks)
Prerequisites
  • Playbooks enabled by a System Administrator
  • A configured, active Playbook

Executing Playbooks

Playbooks with a Mailbox Trigger

Playbooks using a Mailbox Trigger execute when an email is received in the Target Mailbox. Information contained in the email will then be passed along to any downstream Apps or Operators in the Playbook.

To test the functionality of an active Playbook that uses a Mailbox Trigger, click Send EmailSend Email iconat the upper-right corner of the design pane on the Playbook Designer (Figure 1).

Figure 1_Executing a Playbook_7.1.0

 

Your computer’s default mail client will open a new message with the mailbox’s address listed in the To: field. Alternatively, click CopyCopy iconto copy the mailbox address to your computer’s clipboard so that you can paste it into an email message.

After an email is sent to and received by the Trigger’s mailbox address, the Playbook will execute.

Playbooks with a Timer Trigger

Playbooks using a Timer Trigger execute based on a set schedule (e.g., once a day, on the fifteenth of the month, etc.) defined in the Trigger’s Schedule and Daily Time parameters (Figure 2).

A picture containing graphical user interface  Description automatically generated

 

For example, if you set the Schedule parameter to Daily and the Daily Time parameter to 09:30, the Playbook will execute every day at 9:30 a.m. UTC. Note that the Coordinated Universal Time (UTC) time standard is used when configuring the Daily Time parameter.

Playbooks with a UserAction Trigger

A UserAction Trigger lets you run Playbooks on demand from the Details screen of Indicators, Intelligence Requirements, Groups, Tracks, and Victims. You can also execute Playbooks with a UserAction configured for Indicators when using Threat Graph.

New Details Screen

When viewing an object’s Details screen , a Playbooks card will be displayed on the Overview tab if there is at least one active Playbook with a UserAction Trigger configured for the object’s type (Figure 3).

Figure 3_Executing a Playbook_7.1.0

 

  • Name: This column displays the name of the UserAction Trigger that will start the Playbook’s execution. It also displays the Playbook’s description, if available.
  • Status: This column displays the Playbook’s status. The default status is Ready, which will change to Complete after the Playbook execution finishes.
  • Run playbookRun playbook icon: Click this button to execute the Playbook. A message stating “Starting playbook…” will be displayed at the lower-left corner of the screen.

If you configured the UserAction Trigger’s response body and selected the Render as Tip checkbox, a tooltip containing the response body will be displayed temporarily on the Playbooks card after the Playbook execution finishes (Figure 4). You can also hover over thePage%20iconicon on the Playbooks card to view this tooltip.

Figure%204_Executing%20a%20Playbook_7.4.0

 

Legacy Details Screen

When viewing an object’s legacy Details screen, a Playbook Actions card will be displayed on the Overview tab if there is at least one active Playbook with a UserAction Trigger configured for the object’s type (Figure 5).

Graphical user interface, application, Teams  Description automatically generated

 

  • Run: Click RunRun iconto execute the Playbook. After a few seconds, the Playbook’s status will change (e.g., from Ready to Completed).
  • Name: This column displays name of the UserAction Trigger that will start the Playbook’s execution.
  • Status: This column displays the Playbook’s status. The default status is Ready, which will change to Completed after the Playbook execution finishes.

If you configured the UserAction Trigger’s response body and did not select the Render as Tip checkbox, the response body will be displayed in the Status column (Figure 6).

A picture containing graphical user interface  Description automatically generated

 

If you configured the Trigger’s response body and selected the Render as Tip checkbox, you can view a tooltip containing the Trigger’s response body by hovering over the Completed text in the Status column (Figure 7).

A picture containing graphical user interface  Description automatically generated

 

Note
If the Playbook does not fully complete its workflow after the amount of time specified for the UserAction Trigger’s Timeout parameter, the Trigger will time out and display a status of “Error 500”, but the Playbook will continue to run. If the Render as Tip checkbox was selected when configuring the Trigger, the tooltip will return a response after the entire Playbook workflow is complete. Associating a midstream App to the Trigger to generate an earlier response (i.e., before the Playbook workflow is complete) is not a supported workaround.

Playbooks with a WebHook Trigger

A WebHook Trigger creates an HTTPS endpoint that can process nearly any piece of information that can be sent via HTTP.

To execute an active Playbook that uses a WebHook Trigger, click Execute EndpointExecute Endpoint iconat the upper-right corner of the design pane on the Playbook Designer screen (Figure 8).

A picture containing diagram  Description automatically generated

 

A new tab will open in your browser. Alternatively, click Copy Endpoint URLCopy iconto copy the endpoint URL and paste it into your browser’s search bar.

You can also access the Execute Endpointand Copy Endpoint URLicons from the Playbooks screen by hovering over a Playbook that uses a WebHook Trigger. Doing so will display both icons in the Name column following the endpoint URL (Figure 9).

Graphical user interface, application  Description automatically generated

 

Playbooks with a Group, Indicator, Case, Intel Requirement, Track, or Victim Trigger

Group, Indicator, Case, Intel Requirement, Track, and Victim Triggers represent the Group, Indicator, Case, Intelligence Requirement, Track, and Victim objects in ThreatConnect, respectively. Playbooks that use any of these Triggers will execute based on how you configured the Trigger’s Owners and Action Type parameters (Figure 10).

A picture containing graphical user interface  Description automatically generated

 

The Owners parameter determines the ThreatConnect owner(s) (i.e., Organization, Communities, and Sources) in which the Playbook can be executed. You must select at least one owner when configuring the Trigger.

The Action Type parameter determines the action for which the Trigger will listen. When the selected action takes place in one of the specified ThreatConnect owners, the Trigger will start the Playbook. For example, if an Email Subject Indicator Trigger is configured with Create as its Action Type and Demo Organization as its Owner, the Trigger will start the Playbook whenever an Email Subject Indicator is created in the owner named Demo Organization.

See Table 1 for a list of accepted values for the Action Type parameter and the supported Trigger types for each value.

 

Accepted ValueSupported Trigger Type(s)
CreateCase; Group; Indicator; Intel Requirement; Victim
DeleteCase; Group; Indicator; Intel Requirement; Victim
New ResultsIntel Requirement; Track
Security Label AppliedGroup; Indicator; Victim
Security Label RemovedGroup; Indicator; Victim
Set ResolutionCase
Set SeverityCase
Specific Status SetCase
Tag AppliedCase; Group; Indicator; Intel Requirement; Victim
Tag RemovedCase; Group; Indicator; Intel Requirement; Victim

Playbooks with a Service Trigger

Service Apps are microservices that constantly run in the background. Executing a Playbook that uses a Trigger Service will vary based on how you configure the Trigger Service and its corresponding Playbook Trigger. See Playbook Services for more information on creating Trigger Services.

Stopping a Playbook Execution

You can stop Playbook executions from the Executions pane of the Playbook Designer. See the “Stopping a Playbook Execution” section of Playbook Executions for more information.


ThreatConnect® is a registered trademark of ThreatConnect, Inc.

20115-01 v.03.A


Was this article helpful?