Kaspersky Next XDR Expert allows you to respond to alerts and incidents manually or automatically by using playbooks. Responding to alerts or incidents may consist not of a single action, but of a whole set of steps and parameters. These steps depend on the specified conditions, the alert or incident data, and the results of previous response actions.
The playbook algorithm allows you to specify the sequence of response actions, the necessary conditions and the required impact on the target objects in the JSON format. The playbook algorithm steps are performed sequentially, one step after another. You can specify the playbook algorithm when creating or editing a playbook.
After launch, the playbook obtains all the alert or incident data and places them in global data. The playbook uses the following data:
Global data is readable at any step of the playbook. Global data contains information about the alert or incident for which the playbook was launched.
You cannot edit global data by using a playbook, or by changing alert or incident data. Global data remains unchanged for the entire lifetime of the playbook instance.
Operational data is transferred between the steps of the playbook. You can manage operational data by using jq expressions, which are specified in the input and output parameters.
Local data is limited to a specific step. You can manage local data by using the input (local data generation) and output (generation of operational data from local data) parameters.
How to write an algorithm
The playbook algorithm is written in JSON format and consists of two main parts:
name)description)inputType)input)output)playbookRunTimeout)timeouts)version)dslSpecVersion)responseActionsSpecVersion)executionFlow).The following parameters are required when writing the algorithm:
nameinputTypedslSpecVersion. The required value: 1.0.0.responseActionsSpecVersionversionexecutionFlow (at least one execution step)Each execution step has its own required fields.
If you try to save a playbook without filling in the required fields, an error will appear.
The playbook algorithm is case sensitive. To use the asset data of the alert, you need to capitalize the Assets parameter. For example: alert.Assets[]. However, to use asset data in the input data when manually launching the playbook for target objects, do not capitalize the assets parameter. For example: .input.assets[].
Depending on the scope you selected when creating or editing a playbook, you can use alert data model or incident data model in the algorithm. To do that, write expressions in the jq language with an alert or incident value (do not use dot "." at the beginning of the value). For example:
"${[ alert.Assets[] | select(.Type == \"user\" and .IsAttacker) | .ID]}"
You can use alert or incident data in a jq expression at any execution step. The alert or incident data is only available in read mode. This data does not change during the operation of the playbook. If alert or incident data has changed after launching the playbook, it will not affect the playbook execution.
You also can use the jq expressions when use the playbook data in the algorithm. For more information about jq expressions, refer to jq Manual.
If you use quotation marks in the jq expression, you need to escape these marks with backslashes. For example: "${[ alert.Assets[] | select(.Type == \"user\" and .IsAttacker) | .ID]}".
Backslashes that are not used to escape quotation marks must also be escaped by other backslashes. For example: ${\"add_firewall_rule --ip_address=\" + ([.input.observables[] | select(.type == \"ip\") | select(.value | test(\"^(10\\\\.|172\\\\.(1[6-9]|2[0-9]|3[01])\\\\.|192\\\\.168\\\\.|127\\\\.).*\") | not) | .value] | join(\",\"))}.
If you want to launch the playbook for the specific object (observables or assets), use the .input parameter in the algorithm. These objects will be the input to the playbook when it is launched. For example:
"assets": "${ [.input.assets[] | select(.Type == \"host\") | .ID] }"
For details, refer to Launching playbooks for objects specified by users.
How to call hints
If you need a hint on the available fields when writing the algorithm, use quotation marks (""). A list of available fields appears.
To display hints on the alert or incident data, write alert or incident in the jq expression with a dot "." at the end.
The correct hint appears if there are no errors in the above expressions. Otherwise, the list of available fields may be incorrect.
Example of the playbook algorithm