Skip to main content
Skip table of contents

Triggers

LAST UPDATED: JAN 7, 2024

Overview

Next-generation playbooks introduce the ability to add and remove triggers as needed, replacing the previous default inclusion of all triggers on the initial playbook node. Additionally, new trigger options have been added to support more varied workflows.

Adding a Trigger

Triggers can now be added individually based on user requirements and preferences.

Adding a Trigger to an Investigation Playbook

READER NOTE

The On Playbook Start trigger is included by default.

add_triggers.gif
  1. Click on the + Add Trigger button.

  2. Select a trigger.

  3. Click on the Add Trigger button.

Adding a Trigger to a Preprocessing Playbook

READER NOTE

The On Event Ingestion trigger is included by default.

preprocess_add_trigger.gif
  1. Click on the Add Trigger button.

  2. Select a trigger.

  3. Click on the Add Trigger button.

Deleting a Trigger

For both preprocessing and investigation playbooks, triggers can be deleted using the Delete Trigger button that pops up upon clicking on a trigger.

delete_triggers.gif
  1. Click on the trigger to delete.

  2. Click on the Delete Trigger button.

  3. Click on the Yes button to confirm deletion.

READER NOTE

Triggers can be deleted unless they are depended by other nodes. In such cases, deletion can be handled in one of two ways:

  • Delete the dependent node(s) first.

  • Remove the linking arrow, leaving orphan nodes.

New Triggers

New trigger options have been added to both preprocessing and investigation playbooks, allowing support for more varied workflows.

Investigation Playbooks

On Playbook Start

All existing playbook nodes previously connected to the header of the root node have been updated to flow from the On Playbook Start trigger node. This is the main workflow of an investigation playbook.

Group 16.png

On Investigation Change

Group 17.png

This trigger activates linked tasks when data in the Investigation tab of the Incident Workspace changes.

Data in the Investigation tab of the incident workspace can be updated manually or through a utility command.

Where is the Investigation tab?
  1. Navigate to Investigation Dashboard, then click into an incident.

    Frame 35 (6)-20241223-224442.png
  2. Click on the Investigation tab.

    Frame 36 (11)-20241223-224556.png

Manual Updates

Updates are made using the

buttons.

Group 21.png

Edits to the investigation summary can be made by clicking on the button or by hovering over the summary and clicking on the image 4 (3)-20241223-223130.png icon.

edit_sum_investigation.gif

Edits to the Summary section can also be done within the Overview tab.

Click on the image 5 (2)-20241223-223702.png icon that appears on hover, or the icon (AI summary re-generation).

edit_sum_overview.gif

Updates via a Utility Command

Changes to the data within the Investigation tab can be done using certain utility commands, such as Add Investigation Details and Add Investigation Table Content.

See the demonstration for details.

Group 22.png
Demonstration

Observe how the On Investigation Change trigger automates responses when a playbook is assigned to an incident:

Demo - Notifying a manager when an analyst adds a remediation strategy to an incident.

WARNING

Task 4 in this demonstration requires using the Test Playbook button, which will impact actual incidents in the system. To avoid unintended effects, perform testing in on a demo site.

Task 1: Adding a Playbook

  1. Add an Investigation Playbook.

    Group 3 (1).png
    1. Navigate to Configuration.

    2. Click on the Investigation Playbooks tab.

    3. Click on the + Playbook button.

  2. Enter a name for the playbook, then click on the OK button.

    Group 4.png

Task 2: Updating Investigation Details

Use the Add Investigation Details utility command task to update the information in the Remediations and Mitigations section of the Investigation tab within the Incident Workspace.

  1. Add the Add Investigation Details utility command task to the On Playbook Start trigger.

    add_invest_details.gif
  2. Configure the command to add Remediations and Mitigations content.

    Group 9 (1).png
    1. Turn on the Dynamic toggle.

    2. Copy and paste the provided code to dynamically retrieve the incident number.

      CODE
      {{ $.PlaybookData.DataSource.incident.IncidentNo }}
    3. Select the Remediations and Mitigations option from the dropdown.

    4. Add the remediation strategy, such as "Recommend to disable infected devices."

    5. Choose the Add option for the Editing Type dropdown.

  3. Enable Auto Run, then click on the image 6 (4)-20241223-231527.png button.

    Group 10.png

Task 3: Notifying the Manager of Data Changes

Add a Send Email utility command task to the On Investigation Change node to notify the manager about investigation changes.

  1. Add the On Investigation Change trigger.

    add_invest_change_trig.gif
  2. Connect a Send Email utility command task to the On Investigation Change trigger.

    add_send_email.gif
  3. Follow these steps:

    Group 95.png
    1. Enter the manager’s email address.

    2. Copy and paste the provided code to generate the email subject "Changes to <Incident number>."

      CODE
      {{ 'Changes to ' ~ PlaybookData | jsonpath('$.DataSource.incident.IncidentNo') }}
    3. Copy and paste the provided code to generate the email body "There is a change to the <Investigation Type> section of incident <Incident ID>. The following message has been added: <HTML data>."

      CODE
      {{ 'There is a change to the ' ~ (PlaybookData | jsonpath('$.Trigger.change.InvestigationType')) ~ ' section of incident ' ~ (PlaybookData | jsonpath('$.DataSource.incident.ID')) ~ '. The following message has been added: ' ~ (PlaybookData | jsonpath('$.Trigger.change.Data[*].NewValue.HtmlData')) }}
  4. Enable Auto Run, then click on the image 6 (4)-20241223-231527.png button.

    Group 13.png

Task 4: Testing the Playbook and Confirming Email Delivery

  1. Test the playbook on an incident.

    Group 11.png
    1. Click on the Test Playbook button.

    2. Ensure that the trigger is set to On Playbook Start.

    3. Select a site.

    4. Choose an incident.

    5. Click on the Run Test button.

  2. Verify that the manager has received the email.

    Group 15.png

On Playbook Task Error

The On Playbook Task Error trigger initiates tasks linked to it when a playbook task has the Error Trigger checkbox selected (selected by default). Tasks on this path will not trigger additional error paths, ensuring simple error handling and avoiding loops.

This trigger node can be added to both Investigation Playbooks and Preprocessing Playbooks.

Group 18.png
Demonstration

Observe how the On Playbook Task Error trigger supports troubleshooting below:

Demo - Notifying the manager when a playbook task fails.

WARNING

Task 4 in the demonstration below requires using the Test Playbook button, which will impact actual incidents in the system. To avoid unintended effects, perform testing in a demo environment.

Task 1: Adding a Playbook

  1. Add an Investigation Playbook.

    Group 3 (1).png
    1. Navigate to Configuration.

    2. Click on the Investigation Playbooks module.

    3. Click on the + Playbook button.

  2. Enter a name for the playbook, then click on the OK button.

    Group 4 (1).png

Task 2: Adding a Command Task Designed to Fail

  1. Add a Check IP Reputation task from VirusTotal. Any other integration command task can be used.

    add_check_ip.gif
  2. Set the task to Auto Run, then ensure that the Error Trigger error handling option is ticked.

    Group 1 (1).png
  3. Leave the connection dropdown empty to intentionally trigger task failure during playbook execution, then click on the image 6 (4)-20241223-231527.png button.

    Group 2 (1).png
Task 3: Adding a Task to Troubleshoot the Error
  1. Add the On Playbook Task Error trigger.

    add_error_trig.gif
  2. Connect a Send Email utility command task to the On Playbook Task Error trigger. This will be used to send an email notification to the manager, informing them of the failure to execute the Check IP Reputation task.

    add_send_email_error.gif
  3. Enter the manager’s email address, email subject, and email body.

    Group 5 (3).png
  4. Set this task to Auto Run, then click on the image 6 (4)-20241223-231527.png button.

    Group 6 (2).png
Task 4: Testing the Playbook
  1. Test the playbook on an incident.

    Group 7.png
    1. Click on the Test Playbook button.

    2. Ensure that the trigger is set to On Playbook Start.

    3. Select a site.

    4. Choose an incident.

    5. Click on the Run Test button.

  2. Verify that the manager has received the email regarding the task failure.

    Group 8.png

Preprocessing Playbooks

On Playbook Task Error

See On Playbook Task Error.

JavaScript errors detected

Please note, these errors can depend on your browser setup.

If this problem persists, please contact our support.