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 the Endpoint Agent component.

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

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

All of the above operations are available on hosts that use Kaspersky Endpoint Agent for Windows or Kaspersky Endpoint Security for Windows in the role of the Endpoint Agent component.

If Kaspersky Endpoint Security for Linux is used in the role of the Endpoint Agent component, you can manage network isolation and run applications.

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

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

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 hosts with the Endpoint Agent component 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

Response

HTTP code: 200

Format: JSON

Returned value

Page top

Host network isolation management

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

1. Creating a request for getting the list of hosts with the Endpoint Agent component
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 hosts with the Endpoint Agent component:
   • 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 application.

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 --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": {

"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

Response

HTTP code: 200

Format: JSON

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 --cert <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 the DELETE parameter

To verify that network isolation is disabled, make a request for information about a task using the HTTP GET method.

Example of entering a command with the GET parameter

If network isolation is disabled, Kaspersky Anti Targeted Attack Platform returns a response to the external system in the following format:

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

Response

HTTP code: 200

Format: JSON

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 hosts with the Endpoint Agent component. For example, you can block certain applications that you consider insecure. The application 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 application'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 application 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. Creating a request for getting the list of hosts with the Endpoint Agent component
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 application 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 --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 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

Response

HTTP code: 200

Format: JSON

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

To verify that the prevention rule is deleted, make a request for information about the prevention rule using the HTTP GET method.

Example of entering a command with the GET parameter

If the prevention rule was deleted, Kaspersky Anti Targeted Attack Platform returns a response to the external system in the following format:

Returned value

Page top

Managing the application run task

To manage the application 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 application in the Tasks section.

Request to obtain 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

Response

HTTP code: 200

Format: JSON

Returned value

Page top

Request to create a task

The HTTP POST method is used for requests to run the Kaspersky Anti Targeted Attack Platform application. 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": {

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

"execCommand": "<name of the application 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 application task is created.

Settings

Example of entering a command with switches

Response

HTTP code: 200

Format: JSON

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 application run task is deleted.

Settings

Example of entering a command with the DELETE parameter

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

To verify that the task is deleted, make a request for information about the task using the HTTP GET method.

Example of entering a command with the GET parameter

If the task was deleted, Kaspersky Anti Targeted Attack Platform returns a response to the external system in the following format:

Returned value

Page top