The UserAction Trigger

Overview

A Trigger is an event that initiates the actions defined within a Playbook. The UserAction Trigger in ThreatConnect^® lets you run Playbooks on demand while viewing the Details screen or drawer for threat intelligence data objects (Groups, Indicators, Intelligence Requirements, Tracks, and Victims). You can also run UserAction Trigger–based Playbooks for Indicators while using Threat Graph. This Trigger is contextually aware and user driven, and it allows a customized response.

Before You Start

User Roles

• To view Playbooks with a UserAction Trigger, your user account can have any Organization role.
• To add the UserAction Trigger to Playbooks, your user account must have an Organization role of Standard User, Sharing User, Organization Administrator, or App Developer.
• To execute UserAction Trigger–based Playbooks for threat intelligence data objects, your user account must have an Organization role of Standard User, Sharing User, Organization Administrator, or App Developer.

Prerequisites

• To have access to Playbooks, turn on the Playbooks system setting for your ThreatConnect instance on the System Settings screen (must be a System Administrator to perform this action).

Adding a UserAction Trigger to a Playbook

1. Click Playbooks on the top navigation bar in ThreatConnect to open the Playbooks screen.
2. Create a new Playbook or open an existing one.
3. ClickTriggers on the side navigation bar of the Playbook Designer to view all available Triggers. Then select UserAction in the External menu to add a UserAction Trigger to the design pane (Figure 1). 

    

4. Double-click the UserAction Trigger in the design pane to open the Edit Trigger pane.
5. Fill out the fields on the Configure step (Figure 2) as follows:
   Hint

   Click Display Documentationat the upper-right corner of the Edit Trigger pane to view information about the Trigger, including a description of the Trigger, its input parameters, and its output variables.
   

    

   • User Action Name: Enter a name for the Trigger. This name will be displayed on the Playbooks card (if viewing the Details screen or drawer) or Playbook Actions card (if viewing the legacy Details screen) for the object type(s) selected in the Type dropdown.
   • Type: Select the type(s) of objects that can use the Trigger. Available object types include all Group types, all Indicator types, Intelligence Requirements, Tracks, and Victims.
     
     Note

     Although the Type dropdown includes a Case option, the UserAction Trigger is not supported for Workflow Cases.
   • Timeout: Set the Trigger’s timeout length (that is, the amount of time the Trigger can run before timing out). The default timeout length is 5 minutes.
   • Run as current user: (Optional) Select this checkbox to execute the Playbook under the name of the user that initiated the execution from the object’s Details screen or drawer rather than the user selected in the Run As dropdown list of the Settingsmenu at the upper-right corner of the Playbook Designer.
     Note

     If you select the Run as current user checkbox, the Run As dropdown on the Settingsmenu at the upper-right corner of the Playbook Designer will be grayed out and display the text “Overridden by UserAction.”
6. Click NEXT on the Edit Trigger pane to proceed to the Response Body step. Then fill out the fields on the Response Body step (Figure 3) as follows: 

    

   • Render as Tip: (Optional) Select this checkbox to display Trigger’s response body (that is, the text entered in the Body parameter) on the Playbooks card (if viewing the Details screen or drawer) or as a pop-up tooltip on the Playbook Actions card (if viewing the legacy Details screen) after the Playbook execution is complete.
     Important

     Selecting the Render as Tip checkbox is highly recommended. The Trigger’s response body will not be displayed when the Playbook is executed from the Playbooks card on the Details screen or drawer if this checkbox is not selected. When the Playbook is executed from the Playbook Actions card on the legacy Details screen, the Trigger’s response body will be displayed in the card’s Status column if the checkbox is not selected.
   • Body: (Optional) Enter the text that will be the Trigger’s response after it runs (that is, the message you will see after the Playbook execution is complete).
     Hint

     You can use variables in the Body parameter.
7. Click SAVE on the Edit Trigger pane to save the Trigger’s configuration.

Now you can continue to build out and then execute the Playbook. 

When building the Playbook, you can interact with the following elements along the top of the UserAction Trigger in the design pane to view more information about and manage the Trigger:

• Hover over the Hashtagicon at the upper-left corner of the Trigger to view a scrollable list of output variables, which are values that the Trigger can send to other Apps and Operators in the Playbook.
• Hover over the Informationicon at the upper-left corner of the Trigger to view the object type(s) configured to run the Trigger, the Trigger’s timeout length, and whether the Trigger’s Run as current user checkbox is selected.
• Click the Menuicon at the upper-right corner of the Trigger to open a menu with options to edit, disable, clone, and delete the Trigger.

Example Playbook

Figure 4 shows the Get VirusTotal Results Playbook, which includes a UserAction Trigger configured for File Indicators. After activating the Playbook, you can execute it from a File Indicator’s Details screen or Details drawer and view the VirusTotal™ results. In this example, the Trigger’s name is “Get VirusTotal Results.”

Executing the Playbook

Details Screen and Drawer

If viewing the Details screen or Details drawer for a File Indicator, click Run playbookon the Playbooks card (Figure 5) to execute the Playbook.

Depending on how the UserAction Trigger’s response body was configured, the Playbooks card will display the results of the Playbook’s execution in one of the following ways:

• If the Trigger contains a response body and its Render as Tip checkbox was selected, the Playbooks card will display the response body as a tooltip, along with a status of Complete in the Status column for the Playbook.
• If the Trigger contains a response body, but its Render as Tip checkbox was not selected, the Playbooks card will display only a status of Complete in the Status column for the Playbook; it will not display the Trigger’s response body.
• If the Trigger does not contain a response body, the Playbooks card will display a status of Complete in the Status column for the Playbook.

If viewing the legacy Details screen for a File Indicator, click Runon the Playbooks Actions card (Figure 6) to execute the Playbook.

Depending on how the UserAction Trigger’s response body was configured, the Playbook Actions card will display the results of the Playbook’s execution in one of the following ways:

• If the Trigger contains a response body and its Render as Tip checkbox was selected, the Playbook Actions card will display the response body as a tooltip, along with a status of Completed in the Status column for the Playbook. If the tooltip closes, hover over Completed in the Status column to display the tooltip again.
• If the Trigger contains a response body, but its Render as Tip checkbox was not selected, the Playbook Actions card will display the Trigger’s response body in the Status column for the Playbook.
• If the Trigger does not contain a response body, the Playbook Actions card will display a status of Completed in the Status column for the Playbook.

For more information about how statuses are displayed on the Playbooks and Playbook Actions cards, see the “Playbooks with a UserAction Trigger” section of Executing a Playbook.

Threat Graph

If viewing the File Indicator in Threat Graph, you can execute the Playbook from the File Indicator node’s menu or the Graph Objects drawer. For further instruction on executing Playbooks in Threat Graph, see Running Playbooks in Threat Graph.

ThreatConnect^® is a registered trademark of ThreatConnect, Inc.
VirusTotal™ is a trademark of Google, Inc.

20055-01 v.09.A