The UserAction Trigger
  • 11 Jan 2024
  • 4 Minutes to read
  • Dark
    Light

The UserAction Trigger

  • Dark
    Light

Article Summary

Overview

A Trigger is an event that initiates the actions defined within a Playbook. The UserAction Trigger in ThreatConnect® allows you to run Playbooks on demand from the Details screen of Groups, Indicators, Intelligence Requirements (IRs), 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.

Note
If a Playbook's design includes a UserAction Trigger with a connection from an App or Operator back to the Trigger, the Playbook's priority level will automatically be set to High, regardless of the priority level manually set for the Playbook.

Before You Start

Minimum Role(s)
  • Organization role of Read Only User to view Playbooks with a UserAction Trigger
  • Organization role of Standard User to use the UserAction Trigger in a Playbook and to execute a Playbook from the Playbooks or Playbook Actions card of an object’s Details screen
PrerequisitesPlaybooks enabled by a System Administrator

Creating a New UserAction Trigger

  1. On the top navigation bar, click Playbooks to display the Playbooks screen.
  2. Create a new Playbook or open an existing one.
  3. ClickPlaybook Designer Triggers iconTriggers on the side navigation bar of the Playbook Designer to view all available Triggers (Figure 1). Figure 1_The UserAction Trigger_7.0.2

     

  4. Select UserAction from the External menu to add a UserAction Trigger to the design pane (Figure 2). A picture containing diagram  Description automatically generated

     

    • HashtagPlaybook Trigger Hashtag iconicon: Hover the cursor over this icon at the upper-left corner of the Trigger in the design pane to display a scrollable list of output variables, which are values that the Trigger can send to other Apps and Operators.
    • InformationPlaybook Trigger Information iconicon: Hover the cursor over this icon at the upper-left corner of the Trigger in the design pane to display the object type(s) configured to run the Trigger, the Trigger’s timeout length, and whether the Run as current user checkbox is selected.
    • MenuPlaybook Trigger Menu iconicon: Click this icon at the upper-right corner of the Trigger box to display a menu with options to edit, disable, clone, or delete the Trigger.
  5. Double-click the Trigger. The Configure section of the Edit Trigger pane will be displayed on the left side of the screen (Figure 3).
    Note
    Click the Display DocumentationPlaybooks_Display Documentation iconicon at 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.
    Graphical user interface, text, application, Teams  Description automatically generated

     

    • User Action Name: Enter a name for the Trigger. This name will be displayed on the Playbook Actions card of the Details screen for the object type(s) selected from the Type dropdown menu.
    • Type: Select the type(s) of objects that can use the Trigger. Available object types include all Group types, all Indicator types, IRs, Tracks, and Victims.
    • Timeout: By default, the Trigger’s timeout length (that is, the amount of time the Trigger can run before timing out) is set to 5 minutes. Click in the box to edit this value, if desired.
    • Run as current user: Select this checkbox to execute the Playbook under the name of the user that initiated the execution from the Playbook Actions card on the Details screen of an object rather than the user selected in the Run As dropdown list of the SettingsPlaybook Settings menumenu at the upper-right corner of the Playbook Designer.
      Note
      If you select the Run as current user checkbox, the Run As dropdown list will be disabled under the SettingsPlaybook Settings menumenu at the upper-right corner of the Playbook Designer and replaced with the text “Overridden by UserAction.”
    • Click the NEXT button.
  6. The Response Body section of the Edit Trigger pane will be displayed (Figure 4). The Response Body is the message you will see after the Playbook execution is complete. Graphical user interface, text, application, Teams  Description automatically generated

     

    • Render as Tip: Select this checkbox to display the text entered in the Body section as a pop-up tooltip in the Playbook Actions card on the Details screen after the Playbook execution is complete. If this checkbox is not selected, the text will be displayed in the Status column of the Playbook Actions card.
    • Body: Enter the text that will be the Trigger’s response when it is run.
      Note
      You can use variables in the Response Body parameter.
    • Click the SAVE button.

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

Example Playbook

The Get VirusTotal Results Playbook (Figure 5) includes a UserAction Trigger configured for File Indicators. After setting the Playbook’s status to Active, you can execute the Playbook from a File Indicator’s Details screen and view VirusTotal™ results on this screen. In this example, the Trigger is named “Get VirusTotal Results.”

Figure 5_The UserAction Trigger_7.0.2

 

Executing the Playbook

Details Screen

If viewing the new Details screen for a File Indicator, click Run playbookRun playbook icon_Details screenin the Playbooks card (Figure 6) on the right side of the Overview tab to execute the Playbook. A message stating “Starting playbook...” will be displayed at the lower-left corner of the screen.

Figure 6_The UserAction Trigger_7.0.2

 

If viewing the legacy Details screen for a File Indicator, click RunRun icon_Legacy Details screenin the Playbooks Actions card (Figure 7) at the top right of the Overview tab to execute the Playbook.

Graphical user interface, application, Teams  Description automatically generated

 

If the Trigger's Render as Tip checkbox was selected, the results of the Playbook’s execution will be displayed as a tooltip in the card. Otherwise, only a status of Completed will be displayed in the Status column for the Playbook. For more information about how statuses are displayed on each card, see the “Playbooks with a UserAction Trigger” section of Executing a Playbook.

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

Threat Graph

If viewing the File Indicator in Threat Graph, you can execute the Playbook from the File Indicator node’s contextual menu or the Details table. 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.08.A


Was this article helpful?