Executing a Playbook

Minimum Role: 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

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, 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.

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 Email  at the upper-right corner of the design pane on the Playbook Designer (Figure 1).

Your computer’s default mail client will open a new message with the mailbox’s address listed in the To: field. Alternatively, click Copy  to 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).

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, Groups, Tracks, or Victims. For instructions on accessing an object’s Details screen, see the “Viewing the Details Screen” section of The Details Screen.

If a UserAction Trigger is configured for the selected ThreatConnect object type (an Address Indicator in this example), a Playbook Actions card will be displayed at the top right of the object’s Details screen (Figure 3).

• Run: Click Run  to execute the Playbook. After a few seconds, the Playbook’s status will change (e.g., from Ready to Completed).
• Name: The name of the UserAction Trigger that will trigger the Playbook’s execution.
• Status: The status of the Trigger. The default status is Ready, which will change automatically to Completed after the Playbook execution is complete. You can also configure the Response Body section of the UserAction Trigger to display a custom message or the Playbook’s output in the Status column (Figure 4).

  

   

If the Render as Tip checkbox was selected when configuring the Response Body section of the UserAction Trigger, hovering over the Completed text in the Status column will display the contents of the Trigger’s Response Body as a tooltip (Figure 5).

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 Endpoint at the upper-right corner of the design pane on the Playbook Designer screen (Figure 6).

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

You can also access the Execute Endpoint and Copy Endpoint URL  icons 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 7).

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

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

The Owners parameter determines the Organizations, Communities, or 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 ThreatConnect, the Trigger will initiate the Playbook. For Group, Indicator, and Victim Triggers, available actions include Create, Delete, Tag Applied, Tag Removed, Security Label Applied, and Security Label Removed. For Case Triggers, available actions include Create, Delete, Tag Applied, Tag Removed, Specific Status Set, Set Resolution, and Set Severity. For Track Triggers, the only action available is New Results.

For example, if an Email Subject Indicator Trigger is configured with Create as its Action Type and Demo Organization as its Owner, the Playbook will initiate when you create an Email Subject Indicator in the owner named Demo Organization.

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.01.E