Debug a Playbook

Set breakpoints, conditional breakpoints, skip tasks, and input and output overrides in the Cortex XSOAR playbook debugger
The Cortex XSOAR playbook debugger enables you to build, test, and troubleshoot playbooks. To use the debugger, select a detached system playbook, a copy of a system playbook, or a custom playbook, and click edit to access the debugger features.
You can use the debugger with an attached playbook. However, the debugger must first be opened with a detached playbook. For example, if playbook
Phishing Investigation - Generic v2
is attached and playbook
Abuse Inbox Management Protection
is detached, and you want to open playbook
Phishing Investigation - Generic v2
in the debugger, you need to open playbook
Abuse Inbox Management Protection
first. Then click the + tab icon at the top of the screen to open your attached playbook as well. Sub-playbooks that are attached can also be used with the debugger when the parent playbook is open in the debugger. Open the sub-playbook task within the parent playbook and click
Open sub-playbook
in the task pane.
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.
(
Multi-tenant
) - The debugger cannot be run from the main account in a multi-tenant deployment.

Choose test data

By default, the debugger runs the playbook using an empty mock incident. Other options are to load the contents of the playground or choose an existing incident. Click on
Debugger Panel
and for
Test data
, select the playground or an existing incident from the drop-down. The last fifty incidents appear in the drop-down, as well as any incidents you own or are a member of, or that you have starred. You can enter a search term to find a specific incident from this list to use for test data.
Using an existing incident in the debugger does not affect the original incident or change the original context data.
You can create a new incident from a JSON file using a Cortex XSOAR mapper. This can be useful in cases where you might not yet have an integration set up but you need to test a playbook with third party event data. Once the new incident is created in Cortex XSOAR, you can select it from the list of incidents when choosing test 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 incident 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, click on the breakpoint button for a task. When a breakpoint is set, the breakpoint button changes to orange.
  2. Once a breakpoint is reached, click on the task to overrides inputs and outputs if needed.
  3. When you are finished with 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.
    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.

Set a conditional breakpoint

Conditional breakpoints enable you to debug loops and tasks with multiple values. The playbook only pauses if your condition is met, letting you manipulate data to see how different scenarios impact the playbook run.
  1. Click on the breakpoint button for a task.
    Once a breakpoint is set and the breakpoint icon is orange, a tooltip appears enabling you to add a condition to the breakpoint.
  2. On both sides of the condition statement, you can choose available playbook data
    From previous tasks
    or use
    As value
    to set any other value.
    Clicking on the curly brackets enables you to use data from the current playbook and from sub-playbooks.
  3. Click on the
    Equals (String)
    to select from a set of conditions (contains, ends with, greater than, etc.)
    Note - If the breakpoint condition as defined does not exist when the debugger runs, the condition will default to false. For example, if you choose IP address and there is no IP address available, the playbook will not pause.

Override inputs and outputs

You can override task inputs or outputs before or during a playbook run, to troubleshoot tasks that fail and to 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 on the
    Override
    button.
  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.

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.
  2. If output is required for the playbook to proceed, click on the task and override the output.

Skip conditional tasks

When you skip a conditional task, you can set which branch runs after the skipped task, enabling you to test different outcomes for multiple branches.
  1. Choose
    skip
    for a conditional task. The
    skip
    button will turn orange.
  2. Click on the task. Select which branch runs after the skipped task. If you do not choose, the else branch runs by default.

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.
  1. Click on any completed task in the playbook, while the debugger is running.
    View the results of that task in the debugger panel.

Recommended For You