API for managing Threat Response actions

Kaspersky Anti Targeted Attack Platform provides an API for performing Threat Response actions. Commands to carry out operations are received at the Central Node server and then relayed to Kaspersky Endpoint Agent.

You can use external systems to perform the following operations on Kaspersky Endpoint Agent hosts:

• Manage network isolation of hosts
• Manage prevention rules
• Run programs

All of the above operations are available on Kaspersky Endpoint Agent for Windows hosts. On Kaspersky Endpoint Agent for Linux hosts, you can only run a program.

Request for getting the list of Kaspersky Endpoint Agent hosts

To create a request for information about Kaspersky Endpoint Agent hosts, the GET HTTP method is used.

Command syntax

GET "<URL of the Central Node server>:<port, 443 by default>/kata/response_api/v1/<external_system_id>/sensors"

If the request is processed successfully, a list of Kaspersky Endpoint Agent hosts is displayed.

You can create a request for information about hosts with specified parameters: IP address, name, or ID of the host. You can specify one, multiple, or all parameters.

When specifying a host name, you need to keep in mind that the filter is case-sensitive.

GET "<URL of the Central Node server>:<port, 443 by default>/kata/response_api/v1/<external_system_id>/sensors?ip=<IP address of the host>&host=<host name>&sensor_id=<sensor_id>"

If the request is processed successfully, information about the selected Kaspersky Endpoint Agent host is displayed.

Settings

Example of entering commands with parameters

Returned value

Page top

Request for information about network isolation and the existence of prevention rules for Kaspersky Endpoint Agent hosts

HTTP method GET is used to create a request to display information about network isolation and the existence of prevention rules for Kaspersky Endpoint Agent hosts.

Command syntax

GET "<URL of the Central Node server>:<port, 443 by default>/kata/response_api/v1/<external_system_id>/settings?sensor_id=<sensor_id>&settings_type=<network_isolation or prevention>"

If the request is processed successfully, the list of Kaspersky Endpoint Agent hosts is displayed, listing hosts that had prevention rules or network isolation rules applied at the moment when the request was processed.

Settings

Example of entering a command with switches

Returned value

Page top

Host network isolation management

To isolate a Kaspersky Endpoint Agent host using the API, the following procedure is recommended for interacting with Kaspersky Anti Targeted Attack Platform:

1. Create a request for getting the list of Kaspersky Endpoint Agent hosts
2. Creating a request for getting information about hosts that already have network isolation enabled
3. Creating a request for one of the following operations with Kaspersky Endpoint Agent hosts:
   • Enable network isolation
   • Disable network isolation
   • Add an exclusion to an existing network isolation rule

You can manage the created network isolation rules in the web interface of the program.

Request to enable network isolation

To enable network isolation for a selected host, you must add a network isolation rule. To create the request, the HTTP POST method is used.

Command settings are passed in the body of the request in JSON format.

Command syntax

curl -k --<path to TLS certificate file> --key <path to private key file> -X POST "<URL of Central Node server>:<port, 443 by default>/kata/response_api/v1/<external_system_id>/settings?sensor_id=<sensor_id>&settings_type=network_isolation" -H 'Content-Type: application/json' -d '

{

"settings": {

"autoTurnoffTimeoutInSec": <network isolation time period>}

}

'

If the request is processed successfully, the network isolation rule is added. Network isolation for the selected host becomes active at the moment when the rule is added.

After a period of time specified when the request is created, network isolation becomes inactive. The network isolation rule itself is not deleted. If necessary, you can delete the selected rule.

To disable network isolation, you must create a request to disable the selected rule.

Settings

Example of entering a command with switches

Returned value

If you want to edit the settings of the created network isolation rule, you must create a new request to add the rule with the new settings.

Request to disable network isolation

To disable network isolation for a selected host, you must create a request to disable the network isolation rule. HTTP method DELETE is used to create the request.

Command syntax

curl -k --<path to TLS certificate file> --key <path to private key file> -X DELETE "<URL of Central Node server>:<port, 443 by default>/kata/response_api/v1/<external_system_id>/settings?sensor_id=<sensor_id>&settings_type=network_isolation"

If the request is processed successfully, the network isolation rule is disabled.

Settings

Example of entering a command with switches

Returned value

Page top

Request to add an exclusion to a network isolation rule

To add an exclusion to a previously created network isolation rule, you must create a request to add an exclusion. To create the request, the HTTP POST method is used.

Command settings are passed in the body of the request in JSON format.

Command syntax

curl -k --cert <path to TLS certificate file> --key <path to private key file> -X POST "<URL of Central Node server>:<port, 443 by default>/kata/response_api/v1/<external_system_id>/settings?sensor_id=<sensor_id>&settings_type=network_isolation" -H 'Content-Type: application/json' -d '

{
"settings":
{"excludedRules": [
{
"direction": "<outbound, inbound, or both>",
"protocol": <number of the IP protocol>,
"remoteIpv4Address": "<IP address of the host with the Endpoint Agent component whose traffic must not be blocked>",
"localPortRange":
{
"fromPort": <port number>,
"toPort": <port number>
}
}
,
{
"direction": "<outbound, inbound, or both>",
"protocol": <number of the IP protocol>,
"remoteIpv4Address": "<IP address of the host with the Endpoint Agent component whose traffic must not be blocked>",
"remotePortRange":
{
"fromPort": <port number>,
"toPort": <port number>
}
}
,
{
"direction": "<outbound, inbound, or both>",
"protocol": <number of the IP protocol>,
"remoteIpv4Address": "<IP address of the host with the Endpoint Agent component whose traffic must not be blocked>"
}
]
,
"autoTurnoffTimeoutInSec": <network isolation duration>
}
}
'

If the request is processed successfully, the exclusion from the network isolation rule is added.

Settings

Example of entering a command with switches

Returned value

If you want to edit the settings of the created exclusion, you must create a new request to add the exclusion with the new settings.

Managing prevention rules

You can use prevention rules to prevent files or processes from running on a selected hosts or all Kaspersky Endpoint Agent hosts. For example, you can block certain programs, which you consider insecure. The program identifies files based on their hash by using the MD5 and SHA256 hashing algorithms. A prevention rule created through external systems can contain multiple file hashes.

You can use external systems to manage all prevention rules created for a single host or all hosts at the same time. When you create a prevention rule for a selected host through external systems, Kaspersky Anti Targeted Attack Platform replaces all prevention rules applied to this host with a prevention rules with new parameters. For example, if you had added multiple prevention rules for a selected hosts through the program's web interface, and subsequently added a prevention rule through external systems, all prevention rules added in the web interface are replaced with the rule added through external systems.

When the parameters of a prevention rule created through external systems are modified, the program saves only the new parameters. For example, if you have added a prevention rule that contains hashes for multiple files, and want to add another hash to that rule, you must create a request to add a prevention rule and specify all hashes for which you had a prevention previously, plus the new hash.

The described scenario is also relevant for prevention rules applied to all hosts.

To create a prevention rule using the API, the following procedure is recommended for interacting with Kaspersky Anti Targeted Attack Platform:

1. Create a request for getting the list of Kaspersky Endpoint Agent hosts
2. Create a request for getting information about hosts that already have prevention rules.
3. Create a request for one of the following operations with prevention rules:
   • Create rule
   • Delete rule

Added prevention rules are displayed in the web interface of the program in the Prevention section, Prevention rules subsection.

If you are creating a prevention rule for all hosts through an external system, you must first make sure that no prevention rule for the same file exists on the server or is applied to one or multiple hosts. This prerequisite is also relevant if you want to create a prevention rule through an external system for a selected host: you must make sure that a prevention rule for the same file does not exist on the server and is not applied to all hosts. Otherwise, the server returns an error to the external system with a list of hosts that already have a prevention rule applied.

If the prevention rule created through an external system contains multiple file hashes, the error information mentions only the first file that caused the error. Information about other duplicated prevention rules is not displayed.

To modify a prevention rule previously created through the web interface or external systems, you must create a request to add a prevention rules with updated parameters.

Request to create a prevention rule

To create the request, the HTTP POST method is used. Command settings are passed in the body of the request in JSON format.

Command syntax

curl -k --<path to TLS certificate file> --key <path to private key file> -X POST "<URL of Central Node server>:<port, 443 by default>/kata/response_api/v1/<external_system_id>/settings?sensor_id=<sensor_id or all, if you want to create the prevention rule for all hosts>&settings_type=prevention" -H 'Content-Type: application/json' -d '

{

"settings": {

"objects": [

{

"file": {

"<sha256 or md5>": "<SHA256- or MD5-hash of the file that you want to prevent from starting>"

}

},

{

"file": {

"<sha256 or md5>": "<SHA256- or MD5-hash of the file that you want to prevent from starting>"

}

'

If the request is processed successfully, the prevention rule is added. The prevention rule becomes active at the moment when it is added.

If necessary, you can delete the prevention rule.

Settings

Example of entering a command with switches

Returned value

Page top

Request to delete a prevention rule

You can delete a prevention rule using a new request with blank values or a request with the DELETE parameter. POST and DELETE HTTP methods are used to create requests.

Command syntax for a new request

Command settings are passed in the body of the request in JSON format.

curl -k --<path to TLS certificate file> --key <path to private key file> -X POST "<URL of Central Node server>:<port, 443 by default>/kata/response_api/v1/<external_system_id>/settings?sensor_id=<sensor_id or all, if you want to delete the prevention rule for all hosts>&settings_type=prevention" -H 'Content-Type: application/json' -d '

{

"settings": {

"objects": []

}

}

'

Command syntax with the DELETE parameter

curl -k --<path to TLS certificate file> --key <path to private key file> -X DELETE "<URL of Central Node server>:<port, 443 by default>/kata/response_api/v1/<external_system_id>/settings?sensor_id=<sensor_id or all, if you want to delete the prevention rule for all hosts>&settings_type=prevention"

Settings

Example of command for a new request

Example of entering a command with the DELETE parameter

If the request is processed successfully, the prevention rule is deleted.

Returned value

Page top

Managing the program run task

To manage the program run task using the API, the following procedure is recommended for interacting with Kaspersky Anti Targeted Attack Platform:

1. Creating a request for information about settings, creation time, and completion status of the task
2. Creating a request for one of the following operations with the task:
   • Creating the task
   • Deleting the task

Added tasks are displayed in the web interface of the program in the Tasks section.

Getting information about a task

To create a request for getting information about a task, the HTTP GET method is used.

Command syntax

GET "<URL of the Central Node server>:<port, 443 by default>/kata/response_api/v1/<external_system_id>/tasks/<task_id>?settings=<true or false>"

If the request is processed successfully, information is displayed about settings, creation time, and completion status of the task.

Settings

Example of entering a command with switches

Returned value

Page top

Request to create a task

To create a request to run Kaspersky Anti Targeted Attack Platform, the HTTP POST method is used. Command settings are passed in the body of the request in JSON format.

Command syntax

curl -k --<path to the TLS certificate file> --key <path to private key file> -X POST "<URL of Central Node server>:<port, 443 by default>/kata/response_api/v1/<external_system_id>/tasks/<task_id>?sensor_id=<sensor_id>&task_type=run_process" -H 'Content-Type: application/json' -d '

{

"task": {

"schedule": {"startNow": <true or false>},

"execCommand": "<name of the program that you want to run>",

"cmdLineParameters": "<additional options for running the file or command>",

"workingDirectory": "<working directory>"

}

}

'

If the request is processed successfully, the run program task is created.

Settings

Example of entering a command with switches

Returned value

If you want to edit the settings of the created task, you must create a new request to add the task with the new settings.

Request to delete a task

To create a request to delete a Kaspersky Anti Targeted Attack Platform task, the HTTP DELETE method is used.

Command syntax

curl -k --<path to TLS certificate file> --key <path to private key file> -X DELETE "<URL of the Central Node server>:<port, 443 by default>/kata/response_api/v1/<external_system_id>/tasks/<task_id>

If the request is processed successfully, the program run task is deleted.

Settings

Example of entering a command with switches

Returned value

Page top