Kaspersky Next XDR Expert

Playbook algorithm

Expand all | Collapse all

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. 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

  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

  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

  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 the JSON format and consists of two main parts:

• General information on the playbook:
  • Name (name)
  • Description (description)
  • Scope (inputType)
  • Transformation of the input data of the playbook (input)
  • Transformation of the output data of the playbook (output)
  • Playbook execution timeout (playbookRunTimeout)
  • Timeout policies that can be applied at specific steps (timeouts)
  • Playbook version (version)
  • DSL schema version (dslSpecVersion)
  • Response action schema version (actionsSpecVersion)
• Playbook execution steps (executionFlow).

The following parameters are required when writing the algorithm:

• dslSpecVersion. The required value: 1.1.0.
• actionsSpecVersion
• version
• executionFlow (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 the alert data model or incident data model in expressions written in the jq language. To do that, write expressions 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 using 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,

in the jq expression, write alert or incident and include 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.

How to call suggestions

You can call suggestions when writing the playbook algorithm. The suggestions contain a search string and help you specify the field value quickly. To view the suggestions, use quotation marks (""). A list of suggestions appears.

The suggestions also allow you to search by name. However, when you select the required value, the name will be automatically changed to an ID in the algorithm. For details, refer to Editing incidents by using playbooks and Editing alerts by using playbooks.

If you select and then delete the parameter name specified between the quotation marks, suggestions for the parameter will not appear, even if you have specified a new parameter between the quotation marks.

To return to the suggestion mode for the parameter, do one of the following:

• Delete the quotation marks, and then add an opening double quotation mark. A closing double quotation mark will be added automatically, and a suggestion will appear.
• Type any character between the quotation marks, and then press Backspace. This will return you to the suggestion mode.

If you delete the parameter name character by character, you will not exit the suggestion mode, even if you delete the parameter name completely.

Example of the playbook algorithm