Executing a 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.

Before You Start

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 Emailat 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 Copyto 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. 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).

• Name: This column displays the name of the UserAction Trigger that will trigger the Playbook’s execution. It also displays the Playbook’s description, if available.
• Run playbook: Click this button to execute the Playbook. A message stating “Starting playbook…” will be displayed at the lower-left corner of the screen.

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 4).

• Run: Click Runto 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 5).

  

   

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 6).

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

A new tab will open in your browser. Alternatively, click Copy Endpoint URLto 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 8).

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 9).

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.02.A