Interaction with external systems via API

You can set up the integration of Kaspersky Anti Targeted Attack Platform with external systems to manage Threat Response actions, to scan files that are stored in those systems, and to provide access to information about all alerts to the external systems.

External systems interact with Kaspersky Anti Targeted Attack Platform via an API. API method calls are available only to authorized external systems. For authorization, the program administrator must create a request to integrate the external system with the program. Then the administrator must process the request in the web interface of Kaspersky Anti Targeted Attack Platform.

If you have deployed the Central Node and Sensor components as a cluster, you can configure fault-tolerant integration with an external system using one of the following options:

• Using the Round Robin function.
• Configure the external system settings so that if a timeout occurs, the external system switches between the IP addresses of the cluster servers.

To configure the fault-tolerant integration with the external system:

1. Configure Round Robin on the DNS server for the domain name corresponding to the Central Node cluster.
2. Specify this domain name in the mail server settings.

Integration with the mail server will be configured based on the domain name. The mail server will communicate with a random server in the cluster. If this server fails, the mail server will communicate with another healthy server in the cluster.

Integrating an external system with Kaspersky Anti Targeted Attack Platform

To start working with the API, you need to integrate an external system with Kaspersky Anti Targeted Attack Platform. The external system must complete authorization on the Kaspersky Anti Targeted Attack Platform server.

To integrate an external system with Kaspersky Anti Targeted Attack Platform:

1. Generate a unique identifier of the external system for authorization in Kaspersky Anti Targeted Attack Platform – sensorId.
2. Generate a certificate for the external system server.
3. Create any request containing a sensorId from the external system in Kaspersky Anti Targeted Attack Platform. For example, you can create a request to scan an object from an external system in Kaspersky Anti Targeted Attack Platform.

The web interface of Kaspersky Anti Targeted Attack Platform will display the request for authorization from the external system. Contact the program administrator to process the request.

If you need to change the external system server certificate, repeat the steps for integrating the external system with Kaspersky Anti Targeted Attack Platform.

API for scanning objects of external systems

Kaspersky Anti Targeted Attack Platform provides the HTTPS REST interface for scanning objects saved in external systems.

For scanning objects stored in external systems, the following Kaspersky Anti Targeted Attack Platform interaction scenario is recommended:

1. Creating a request for scanning objects using the HTTP POST method
2. Creating a request for scan results using the HTTP GET method

   The API interface is asynchronous, which means that Kaspersky Anti Targeted Attack Platform scans objects in the background instead of immediately upon request of the external system. For this reason, you must periodically send a request from the external system using the HTTP GET method to receive the scan results. The recommended frequency for sending a request is once per minute.

   You can also configure forwarding of notifications about detected objects in the web interface of Kaspersky Anti Targeted Attack Platform.

3. Creating a request to delete scan results using the HTTP method DELETE

   You can delete the results of scanning a specified object or all objects.

Working with a cluster

If the external system consists of several servers that are combined into a cluster, it is recommended to use one ID (sensorId) for all servers. If this is the case, a single integration request will be displayed for the entire system in the web interface of Kaspersky Anti Targeted Attack Platform. If it is necessary to differentiate the receipt of scan results over individual servers, you can assign a unique instance ID (sensorInstanceId) to each server.

Restrictions

The maximum allowed number of object scan requests from external systems and the maximum allowed size of a scanned object are set in the Kaspersky Anti Targeted Attack Platform configuration file.

If the maximum allowed number of simultaneous object scan requests is exceeded, Kaspersky Anti Targeted Attack Platform does not process further requests until the number of object scan requests is less than the maximum allowed number. Until this condition is met, the return code 429 is issued. You must try the scan request again later.

If the maximum allowed object size is exceeded, Kaspersky Anti Targeted Attack Platform does not scan the object. Return code 413 is generated when the HTTP POST method is created. You can find out the maximum allowed size of an object by using the GET method to view the list of object scan restrictions.

Request to scan objects

To create a request for scanning objects, the HTTP POST method is used. You can create a request by using the cURL command-line utility, for example.

You can set the parameters for executing a cURL command by using additional switches (see the table below).

Please refer to the cURL documentation for more information about cURL command switches.

Command syntax

curl --cert <path to the TLS certificate file> --key <path to the private key file> -X POST "<URL of the server with the Central Node component>:<port, 443 by default>/kata/scanner/v1/sensors/<sensorId>/scans?sensorInstanceId=<sensorInstanceId>" -F "content=<path to the file that you want to scan>" -F scanId=<scan request ID> -F "objectType=file"

If the request is processed successfully, the OK status will be displayed.

Settings

Returned value

Example of entering a command with switches

Page top

Request for scan results

To create a request for receiving scan results, the HTTP GET method is used. You can create a request by using the cURL command-line utility, for example.

You can set the parameters for executing a cURL command by using additional switches (see the table below).

Please refer to the cURL documentation for more information about cURL command switches.

Command syntax

curl --cert <path to the TLS certificate file> --key <path to the private key file> -X GET<URL of the server with the Central Node component>:<default port 443>/kata/scanner/v1/sensors/<sensorId>/scans/state?sensorInstanceId=<sensorInstanceId>&state=<one or more scan statuses that you want to display in scan results>"

If the request is sent successfully, a list of requests for scanning objects and the results of scanning these objects will be displayed. The scan results will be filtered by the statuses that you specified in the state parameter. For example, if you specified state = processing, detect in the request for scan results, the program will display only the object scan requests that are being processed or in which the program has detected a threat.

Settings

Returned value

Example of entering a command with switches if you want to display all object scan statuses in the scan results

Page top

Request to delete scan results

To create a request to delete the scan results for one or more objects, use the DELETE method. You can create a request by using the cURL command-line utility, for example.

Command syntax

curl --cert <path to the TLS certificate file> --key <path to the private key file> -X DELETE "<URL of the server with the Central Node component>:<default port 443>/kata/scanner/v1/sensors/<sensorId>/scans/<scanId>"

If the request is processed successfully, the object scan results will be deleted. The OK status is displayed.

Settings

Returned value

Command input example

Page top

Request to display object scan restrictions

To create a request to display the program's restrictions on scanning objects (for example, by size), the HTTP GET method is used. You can create a request by using the cURL command-line utility, for example.

Command syntax

curl --cert <path to the TLS certificate file> --key <path to the private key file> -X GET "<URL of the server with the Central Node component>:<default port 443>/kata/scanner/v1/sensors/<sensorId>/scans/filters"

If the request is processed successfully, the program's object scan restrictions will be displayed. For example, the maxObjectSize restriction is the maximum allowed size of an object that you can submit for scanning.

Settings

Returned value

Command input example

Page top

API for sending alert information to external systems

Kaspersky Anti Targeted Attack Platform provides an API that lets external systems access information about all alerts of the program and not just to scan results for objects stored in these external systems.

In order to receive information only for alerts that satisfy certain conditions, you can specify filters in the request parameters.

The program does not automatically send information about new alerts based on prior requests. A new request must be sent to receive up-to-date information.

Special considerations for operation in the distributed solution

If the program operates in the distributed solution mode, an external system can complete the authorization procedure only on the SCN server. Authorization on the PCN server is not available.

In this case, an external system cannot receive information about all alerts registered in the infrastructure using a single request. This limitation arises because the common database which contains records about all alerts in the infrastructure is stored on the PCN server. To receive information about all alerts, the external system must query each SCN server separately.

Request to display alert information

To create a request to display information about Kaspersky Anti Targeted Attack Platform alerts, the HTTP GET method is used. You can create a request by using the cURL command-line utility, for example.

Command syntax

curl --cert <path to the TLS certificate file> --key <path to the private key file> -X GET "<URL of the server with the Central Node component>:<default port 443>/kata/scanner/v1/sensors/<sensorId>/detects?detect_type=<one or more technologies that were used to generate the alert>&limit=<number of alerts in the response to the request>&token=<request ID>"

If the request is processed successfully, you will see a list of alerts generated by Kaspersky Anti Targeted Attack Platform on the server of the external system.

Settings

Returned value

Example of entering a command with switches

Page top

Scope of transmitted data

Information that is transmitted for each alert is listed in the following table.

Scope of transmitted alert data

Data on detected objects

The scope of transmitted data on detected objects depending on the type of the object is listed in the following table.

Data on detected objects

Data on detected threats

The scope of transmitted data on detected threats depending on the technology that was used to generate the alert is listed in the table below.

Data on detected threats

Data on the environment of detected objects

The scope of transmitted data on the environment of detected objects depending on the source of the object is listed in the following table.

Data on the environment of detected objects

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