Kaspersky Next XDR Expert Help

Playbook algorithm

Playbook algorithm

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

General information on 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 (responseActionsSpecVersion)
Playbook execution steps (executionFlow).

The following parameters are required when writing the algorithm:

name
inputType
dslSpecVersion. The required value: 1.0.0.
responseActionsSpecVersion
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 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

{
    "responseActionsSpecVersion": "1",
    "dslSpecVersion": "1.0.0",
    "version": "1",
    "playbookRunTimeout": "24h",
    "executionFlow": [
      {
        "responseAction": {
          "function": {
            "type": "blockLDAPAccount",
            "assets": "${[ alert.Assets[] | select(.Type == \"user\" and .IsAttacker) | .ID]}"
          },
          "onError": "stop"
        }
      },
      {
        "split": {
          "batchSize": 1,
          "input": "${ [alert.OriginalEvents[] | [select(.DestinationProcessName != null and .DestinationProcessName != \"\")][] | .DestinationProcessName] }",
          "mode": "parallel",
          "onError": "stop",
          "steps": [
            {
              "responseAction": {
                "function": {
                  "type": "killProcess",
                  "assets": "${[ alert.Assets[] | select(.Type == \"host\") | .ID]}",
                  "params": {
                    "path": "${ .[0] }"
                  }
                }
              }
            }
          ]
        }
      },
      {
        "responseAction": {
          "function": {
            "type": "avScan",
            "assets": "${[ alert.Assets[] | select(.Type == \"host\") | .ID]}",
            "params": {
              "scope": {
                "allowScanNetworkDrives": false,
                "area": "full"
              },
              "wait": false
            }
          },
          "onError": "stop"
        }
      }
    ]
  }

In this section

Playbook parameters

Execution step parameters

ResponseFunction parameters

Page top

Playbook parameters

Parameter ID	Description
`name`	Playbook name. Specified by the system when creating or updating a playbook. If the value is set in the algorithm, it will be replaced by the system.
`description`	Playbook description. Specified by the system when creating or updating a playbook. If the value is set in the algorithm, it will be replaced by the system.
`version`	Playbook version. The minimum length is 1. This parameter is required.
`dslSpecVersion`	DSL schema version. The minimum length is 1. This parameter is required.
`responseActionsSpecVersion`	Response actions schema version. The minimum length is 1. This parameter is required.
`playbookRunTimeout`	The maximum execution time of the playbook, including waiting in the queue. The maximum value is 48 hours (`48h`). You can configure the maximum execution time in hours (h) and/or minutes (m). By default, the value is `24h`.
`inputType`	Inbound object type. The possible values: `alert` or `incident`. The inbound object type is specified by the system when creating or updating a playbook. If the value is set in the algorithm, it will be replaced by the system.
`input`	A jq expression that could be used to transform or filter incoming data before executing a playbook.
`output`	A jq expression that could be used to modify the output of the playbook before execution.
`timeouts`	Timeout definitions.
`executionFlow`	Steps of the playbook execution. This parameter is required.

Page top

Execution step parameters

The array of execution step elements describes a playbook's logic. The execution steps are performed in the order described in the playbook. There are several types of execution steps:

ResponseAction
Split
Scatter-gather
Switch
UpdateData

ResponseAction parameters

The Response action parameters call the response function.

Parameter ID	Description
`function`	An object that defines a response action. For more information, refer to ResponseFunction parameters.
`filterProduct`	This parameter allows you to filter components to perform a response action. When requested, the component plug-ins are filtered by allowed and restricted components. For example, the parameter can be specified as follows: "filterProduct": { "allowed": ["PRODUCT_NAME"] }
`output`	This parameter allows you to edit the value returned by the response action, by using a jq expression and placing it in the playbook data (local or operational).
`timeout`	This parameter allows you to set timeouts for calling the response function. You can specify the name of the timeout policy set in the playbook or set timeout values manually. If the value is not specified, the default timeout is applied.
`manualApprove`	This parameter allows you to configure a manual approval of a response action. Possible values: Boolean value: `true`—Manual approval is enabled with default parameters. `false`—Manual approval is disabled. Object `ManualApprove`.
`onError`	This parameter defines the behavior when an error occurs during the execution of a response action. Possible values: `stop`—Defines the termination of the playbook in case of an error during the execution of the response action. `continue`—Defines that the playbook execution will continue, even if one of the response actions completes with an error. In this case, the playbook launches the next response action specified in the algorithm. By default, the value is `stop`. Note that, if a system error occurs, the playbook execution completes with an error regardless of the specified value of the `onError` parameter.

Timeout policy

The timeout policy of execution steps. The system automatically determines the default timeout policy.

The default timeout policy can be reconfigured by using the default policy name. In this case, the new policy will be automatically applied to all execution steps.

Parameter ID

Description

name

Timeout policy name.

scheduleToCloseTimeout

The maximum execution time, including waiting in the queue and retries. The parameter is specified in the Go string format.

If the value is not specified or 0, the value from the playbookRunTimeout field is used.

Output

The output parameter generates operational data at the end of a step, which will then be transferred to the next step. Specify the output parameter if you want to use the results of the current step of the playbook in the next step.

To avoid overloading the system, it is recommended to limit the data placed in the playbook data (local or operational).

Parameter ID

Description

action

This parameter defines whether the playbook data (local or operational) will be overwritten or merged. Possible values:

merge—The new data is merged with the current data.
overwrite—The current data is overwritten with new data.

filter

This parameter defines the jq expression for processing output data.

Manual approve

Parameter ID

Description

timeout

The timeout for manual approval in minutes. The minimum value is 10 minutes (10m), the maximum is 180 minutes (180m).

By default, the value is 60 minutes (60m).

emailNotifications

This parameter allows you to configure the sending of email notifications.

Email notification settings

Parameter ID

Description

enabled

Flag for enabling email notifications.

delay

This parameter defines the delay before sending the email notification. The value is specified in minutes.

The minimum value is 5 minutes (5m), the maximum is 30 minutes (30m).

By default, the value is 10 minutes (10m).

Page top

Split

Before specifying the split parameter, make sure that the aggregate parameter is also specified in the playbook algorithm.

The split parameters are used to split the array of incoming data by elements and to perform various actions on the elements.

Parameter ID	Description
`input`	A jq expression for composing an array or referencing an array.
`aggregate`	This parameter allows you to configure aggregation rules by using a jq expression.
`output`	Configuring how to apply the output data to the current playbook data. Possible values: String constant: `merge` or `overwrite`. Object `Output`.
`mode`	Split operation mode. Possible values: `parallel`—Defines that all elements are processed in parallel. The number of threads is controlled by the interpreter. `sequence`—Defines that all elements are processed sequentially. By default, the value is `parallel`.
`batchSize`	This parameter allows you to specify the number of array elements that will be processed in one loop or one parallel thread. You can use this parameter if the plug-in function limits the number of input elements. For example, if a plug-in function can handle no more than 10 elements in one loop, you can specify the following parameter value: `batchSize=10`. By default, the value is `1`.
`onError`	This parameter defines the behavior when an error occurs in one of the branches. Possible values: `stop`—Defines the termination of all branches if an error has occurred. The other branches will continue to run. If `mode=sequence`, after an error occurs in one branch, all subsequent branches will be stopped. If `mode=parallel`, after an error occurs in one branch, all branches will continue to run independently of each other. `continue`—Defines the stop of one of the branches where the error occurred. The other branches will continue to run. By default, the value is `stop`.
`steps`	Array of execution steps.

Page top

Scatter-gather

Before specifying the scatter-gather parameter, make sure that the aggregate parameter is also specified in the playbook algorithm.

The Scatter-gather parameters are used to perform several actions on the data at the same time. Unlike Split, Scatter-gather transmits the same input data to different execution branches.

Parameter ID	Description
`input`	A jq expression for composing an array.
`aggregate`	This parameter allows you to configure aggregation rules by using a jq expression.
`output`	Configuring how to apply the output data to the current playbook data. Possible values: String constant: `merge` or `overwrite`. Object `Output`.
`onError`	This parameter defines the behavior when an error occurs in one of the branches. Possible values: `stop`—Defines the termination of all branches if an error has occurred. The other branches will continue to run. `continue`—Defines the stop of one of the branches where the error occurred. The other branches will continue to run. By default, the value is `stop`.
`branches`	Execution branches.

Branch

Parameter ID	Description
`name`	The name of the branch that is unique within Scatter-gather.
`steps`	Array of execution steps.

Page top

Switch

An execution step that allows you to perform a step or set of steps according to a condition. Note that only the first verified condition will be executed.

Parameter ID	Description
`conditions`	Array of conditions.

Condition

Parameter ID	Description
`condition`	A jq expression that contains execution conditions.
`steps`	Execution steps for the current branch.

Page top

UpdateData

The UpdateData parameter can be described either as a jq script with state change logic, or as an Output object.

Page top

ResponseFunction parameters

Parameter ID	Description
`responseAction`	Response action name.
`params`	The parameter allows you to describe the parameters of a response action you want to launch. You can specify the parameter as a jq expression or as an object. Parameters of the response actions are described in the table below.
`assets`	The parameter allows you to use a jq expression or string array to specify a list of assets for which you want to launch a response action. The `assets` parameter is required for response actions with assets and is not applicable for response actions without assets.

Response action parameters

Response action name	Parameters
`updateBases`	Update databases response action. Possible parameters: `wait`. Possible values: `true` `false` To launch this response action, you need to specify the `asset` parameter of the response function.
`avScan`	Run malware scan response action. Possible parameters: `wait`. Possible values: `true` `false` `scope`. Possible values: `full`—Perform a full scan of the device where the alert is detected. `critical`—Perform a scan of the kernel memory, running processes, and disk boot sectors. `selective`—Perform a scan of the specified files. To specify a path to the files, use the `path` parameter. `allowScanNetworkDrives`. Possible values: `true` `false` By default, the value is `false`. This parameter is available only if you want to perform a full scan. Note that scanning network drives can overload the system. `path`—A jq expression or a string with a path to the files you want to scan. You can also specify multiple file paths. To launch this response action, you need to specify the `asset` parameter of the response function.
`moveHostsToAdministrationGroup`	Move to group response action. Possible parameters: `group`—Open Single Management Platform administration group path. For examples, `HQ/OrgUnit1`. To launch this response action, you need to specify the `asset` parameter of the response function.
`quarantineFile`	Move to quarantine response action. Possible parameters: `path`—Path to the file you want to quarantine. `md5`—MD5 hash of the file. `sha256`—SHA256 hash of the file. You can specify the response action parameters in one of the following ways: Specify the full path to the file you want to quarantine. In this case, you do not need to specify an MD5 hash or a SHA256 hash. Specify the file path and the file hash (MD5 or SHA256). To launch this response action, you need to specify the `asset` parameter of the response function.
`killProcess`	Terminate process response action. Possible parameters: `pid`—Process identifier. `path`—Path to the file you want to quarantine. `md5`—MD5 hash of the file. `sha256`—SHA256 hash of the file. To launch this response action, you need to specify the `asset` parameter of the response function.
`changeAuthorizationStatus`	Change authorization status response action. Possible parameter: `authorized`. Possible values: `true` `false` To launch this response action, you need to specify the `asset` parameter of the response function.
`netIsolateOn`	Enable network isolation response action. Possible parameters: `isolationTimeoutSec`—Network isolation period. You can specify this parameter in hours or days. The minimum value in hours is 1 hour, the maximum is 9999 hours. The minimum value in days is 1 day, the maximum is 416 days. The network isolation period is specified in seconds. `exclusions`—Exclusion rules. You can specify one or more exclusion rules. `remoteIPV4Address`—Network traffic from the specified IPv4 address will be excluded from the block. For example, `192.168.2.15`. `remoteIPV6Address`—Network traffic from the specified IPv6 address will be excluded from the block. For example, `2001:0db8:0000:0000:0000:ff00:0042`. `remotePortRange`—Interval of remote ports. `localPortRange`—Interval of local ports. If the `remotePortRange` and `localPortRange` are not specified, the exclusion rule applies to all ports. `exclusionsConflictBehavior`—Defines the behavior if there is a conflict between different exclusion rules. Possible parameters: `replace` `skip` `fail`
`netIsolateOff`	Disable network isolation response action. To launch this response action, you need to specify the `asset` parameter of the response function.
`executeCommand`	Run executable file response action. Possible parameters: `path`—Path to the custom script or executable file that you want to run. `workingDirectory`—Path to the working directory. `commandLineParameters`—Command-line parameters that you want to apply to the command. To launch this response action, you need to specify the `asset` parameter of the response function.
`addFilePreventionRules`	Add prevention rule response action. Possible parameters: `md5`—MD5 hash array. `sha256`—SHA256 hash array. To launch this response action, you need to specify the `asset` parameter of the response function.
`deleteFilePreventionRules`	Delete prevention rule response action. Possible parameters: `md5`—MD5 hash array. `sha256`—SHA256 hash array. To launch this response action, you need to specify the `asset` parameter of the response function.
`resetFilePreventionRules`	Delete all prevention rules. To launch this response action, you need to specify the `asset` parameter of the response function.
`assignKasapGroup`	Assign KASAP group response action. Possible parameters: `groupId`—KASAP group identifier. To launch this response action, you need to specify the `asset` parameter of the response function.
`addToLDAPGroup`	Add user to security group response action. Possible parameters: `groupDN`—Distinguished name (DN) of the LDAP group. To launch this response action, you need to specify the `asset` parameter of the response function.
`removeFromLDAPGroup`	Delete user from security group response action. Possible parameters: `groupDN`—Distinguished name (DN) of the LDAP group. To launch this response action, you need to specify the `asset` parameter of the response function.
`blockLDAPAccount`	Lock account response action. To launch this response action, you need to specify the `asset` parameter of the response function.
`resetLDAPPassword`	Reset password response action. To launch this response action, you need to specify the `asset` parameter of the response function.
`executeCustomScript`	Execution of custom scripts. Possible parameters: `commandLine`—Command to run. `commandLineParameters`—Command-line parameters that you want to apply to the command. `stdIn`—Standard input stream. Use this parameter if a script requires some additional data from the standard input. `workingDirectory`—Path to the working directory.
`iocsEnrichment`	Data enrichment. Possible parameters: `observables`—A jq expression with an array of observables that you want to enrich. `source`—Source of data. Possible values: `OpenTIP` `TIP` `fullEnrichment`—Defines the number of records to be requested. Possible values: `true`—Request all records from the source. `false`—Request the top 100 records from the source.

Page top

Contents

Playbook algorithm

Playbook parameters

Execution step parameters

Split

Scatter-gather

Switch

UpdateData

ResponseFunction parameters