Debug your playbook - Administrator Guide - Cortex XSIAM - Cortex

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

Cortex XSIAM Documentation

Product

Cortex XSIAM

Creation date

2024-03-06

Last date published

2024-12-12

Choose test data

The debugger uses test data to execute the playbook, so you can see what your expected results would be. The following are options for test data.

New Mock Alert: By default, the debugger runs using an empty mock alert. An empty mock alert is useful to test simple functionality, such as a playbook that does simple tasks such as parsing inputs.
Playground: You can load the contents of the Playground as test data, enabling you to use uploaded files and custom context data for testing purposes.
Existing Alert: You can select an existing alert. For example, when debugging a phishing playbook, you might want to use an existing phishing alert that came from the mail listener integration. Using an existing alert in the debugger does not change the original 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.
Existing Incident: You can select an existing incident. For example, when debugging a phishing playbook, you might want to use an existing phishing incident that came from the mail listener integration. Using an existing incident in the debugger does not change the original incident.
If you need to use event data from third-party software that is not yet set up as an integration, you can import a JSON file into Cortex XSIAM through the mapping feature and create an incident that can then be used as test data.
You can use a file attachment for your test data by adding the file to an incident and selecting the incident or by uploading the file to the playground and using the playground as test data.

Set a breakpoint

At the breakpoint, you can override inputs and outputs to see how changes affect playbook execution. In addition, conditional breakpoints set conditions for the playbook to proceed. The playbook only pauses if your condition is met, letting you manipulate data to see how different scenarios impact how the playbook runs. For example, you can set a conditional breakpoint to pause the playbook when a phishing incident targets a member of a VIP asset list. If there are no VIPs in this incident, the execution does not pause. If there is a VIP in the incident, you can check that the member was properly identified by the playbook task.

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.

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.
After a breakpoint is reached, click the task to override inputs and outputs if needed.
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.
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.

Start and stop the debugger

The debugger runs the playbook 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. When the user sets breakpoints, skips tasks, or overrides inputs or outputs, those changes only apply to the individual user’s session and do not permanently change the playbook. Using an existing alert as test data does not affect the original alert or change the original context data. When tasks run, however, they execute the same as they would without the debugger. For example, if you run the debugger and a task adds an item to a list, that item will be in the real list, accessible across for all users with permission to view that list.

Breakpoints pause playbook execution before a specific task. When the playbook is paused, the Debugger Panel displays the current state of context data, indicators, and task information.

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.

Override inputs and outputs

The debugger enables you to temporarily override inputs and outputs for a playbook run and to view the results in real time. When you override an input or output in the debugger, the change is saved only in the debugger view and only for the user who made the change. If after testing you decide to keep the temporary changes you made and apply them permanently to the playbook for all users, you need to cancel the override and edit the task. Tasks can be edited directly in the debugger or outside of the debugger using the standard playbook editing options.

You can override task inputs or outputs before or during a playbook run to troubleshoot tasks that fail or to try different input and outputs as part of 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 cannot use filters or transformers for overrides.

To override an input or output, open the task and hover over any existing input or output. Click Override Input.
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.
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

For testing purposes, you may want to skip a task that for example closes a port in a firewall, deletes an email, or sends a notification to a manager. Or you might skip a task where the integration has not yet been configured. By skipping a task and overriding the output, you can provide the data necessary to complete the playbook run. When you skip a conditional task, you can choose which branch runs after the skipped task, enabling you to test different outcomes for multiple branches.

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.

How to skip a task

Click the ‘skip’ button for the task.
When a task is set to skip, the ‘skip’ button will be orange.
If the output is required for the playbook to proceed, click 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 by clicking any completed task in the playbook while the debugger is running.