Debug a playbook - Administrator Guide - Cortex XSIAM - Cortex - Security Operations

Cortex XSIAM Administrator Guide

Product
Cortex XSIAM
Creation date
2024-02-26
Last date published
2024-04-16
Category
Administrator Guide
Abstract

Set breakpoints, conditional breakpoints, skip tasks, and input and output overrides in the playbook debugger

The playbook debugger enables you to build, test, and troubleshoot playbooks. To open a detached system playbook, a copy of a system playbook, or a custom playbook in the debugger, select the playbook and click Edit. To open an attached playbook in the debugger, select the playbook and click View to access the debugger. While editing a playbook, sub-playbooks can be opened directly in the debugger by choosing Open sub-playbook in the task pane.

Note

The debugger runs with the permissions of the logged in user. If a user runs potentially harmful commands, they are logged to the audit trail with the user’s username.

In some cases, you may have a playbook that includes two or more copies of the same sub-playbook. When you set breakpoints, override inputs or outputs, or skip tasks in sub-playbook A, the same changes apply to the identical sub-playbook B. In addition, if you set a breakpoint, override inputs or outputs, or skip tasks within a loop in a playbook, that setting will be applied every time the loop executes.

Choose test data

By default, the debugger runs the playbook using an empty mock alert, or loads the contents of an existing alert. Click the Debugger Panel and in the Test data field, select an existing alert. The last fifty alerts appear in the drop-down, as well as any alerts you own or are a member of, or that you have participated.

Note

Using an existing alert in the debugger does not affect the original alert or change the original context data.

Start and stop the debugger

To start the debugger, click Run. When you click Stop, the debugger stops, and the context data is reset to the original alert data. In the case of a new mock incident, the context data is cleared and the context is empty. Any breakpoints, skips, or overrides you applied are still available.

Set a breakpoint

Breakpoints help you understand task results. Breakpoints do not apply to manual tasks, as a manual task will always pause the playbook run unless you skip the manual task. When the playbook reaches a breakpoint, no new tasks begin, but parallel tasks that have already begun continue. Breakpoints can be set in both the parent playbook and sub-playbooks.

  1. To set a breakpoint, go to a task and click on the breakpoint button. When a breakpoint is set, the breakpoint button changes to orange.

    debug-break.png
  2. Once a breakpoint is reached, click on the task to Override inputs and outputs if needed.

  3. When you are finished with the task, run the debugger, and in the task, select an option for the playbook to continue.

    For an automated task, you have the options Run automation now or Complete Manually. If you choose Complete Manually, click on Mark Completed for the playbook to continue.

    For a task that is a sub-playbook, click Run playbook now for the playbook to continue.

    For a conditional task, choose which branch the playbook should follow and click Mark Completed for the playbook to continue. The default branch is else.

    When the playbook reaches a breakpoint, the task has an orange line at the top to indicate the breakpoint.

    debug-breakpoint.png

    Breakpoint alerts are also displayed at the top of the playbook, enabling you to navigate between multiple breakpoints that have been reached in the playbook or sub-playbooks.

Override inputs and outputs

You can override task inputs or outputs before or during a playbook run, to troubleshoot tasks that fail, and test different options for playbook development. If you override an input or output during a playbook run, the override is applied to the run if the playbook has not yet reached that task. If you edit (permanently change) inputs during a playbook run, the changes only take effect the next time you run the playbook. You can not use filters or transformers for overrides.

  1. To override an input or output, open the task and hover over any existing input or output. Click Override Input.

    debug-override.png
  2. Enter a new input or output that will be used only in the debugger. For output overrides, you can enter a value, an array of values, or JSON. For input overrides, you can only enter plain text.

  3. Click OK to save your changes.

    The playbook task card displays a label indicating that the task input or output has been overridden.

Skip tasks

You might need to skip tasks within a playbook:

  • To check if a particular task is causing an issue.

  • To avoid performing tasks not relevant for your troubleshooting.

  • To skip tasks with potentially harmful results such as blocking a user or opening a port in a firewall.

  • To skip tasks for integrations that are not yet configured.

  1. To skip a task, click the ‘skip’ button for the task.

    When a task is set to skip, the ‘skip’ button will be orange.

    debug-skip.png
  2. If the output is required for the playbook to proceed, click on the task and Override inputs and outputs.

View context data, indicators, and task information

Within the debugger panel, you can view the context data during the playbook run, as well as the indicators as they are extracted.

  • Click on any completed task in the playbook, while the debugger is running.

    View the results of that task in the debugger panel.

    debug-results.png