Interaction with external systems via API

You can configure 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 application alerts and events 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 application administrator must create a request to integrate the external system with the application. 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 high availability integration with an external system using one of the following options:

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

To configure high availability integration with an external system using the Round Robin function:

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 application 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>:<port, 443 by default>/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 application will display only the object scan requests that are being processed or in which the application has detected a threat.

Settings

Response

HTTP code: 200

Format: JSON

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 application'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 application'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

Response

HTTP code: 200

Format: JSON

Returned value

Command input example

Page top

API that external systems can use to receive information about application alerts

Kaspersky Anti Targeted Attack Platform provides an API that lets external systems access information about all alerts of the application 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 application 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 application runs in distributed solution mode, you must separately configure the integration with the external system for each PCN and SCN server from which you want to receive information about alerts. This limitation is due to the fact that the web interface of the PCN server displays information about all alerts, but the alerts database stores only those alerts that have been registered on that specific server.

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>:<port, 443 by default>/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

Response

HTTP code: 200

Format: JSON

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 that external systems can use to receive information about application events

Kaspersky Anti Targeted Attack Platform provides an API for external systems that provides access to information about events registered by the application.

To receive information only for events that satisfy certain conditions, you can specify filters in the request parameters.

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

Information about new events can be retrieved for no more than two hours after these events appear in the Kaspersky Anti Targeted Attack Platform database.

Special considerations for operation in the distributed solution

If the application runs in distributed solution mode, you must separately configure the integration with the external system for each PCN and SCN server from which you want to receive events. This limitation is due to the fact that the web interface of the PCN server displays information about all events, but the events database stores only those events that have been registered on that specific server.

Request for querying event information

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

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.

At the first request, Kaspersky Anti Targeted Attack Platform creates a ContinuationToken (hereinafter also referred to as the "token"). The application sends events available in the system at the time of the token creation. When a new token is created, Kaspersky Anti Targeted Attack Platform sends events available in the system at the time of creation of this token.

The token contains information about which data were transmitted last. If you want to receive events recorded after the last request, you must save the created token and use it in future requests.

Command syntax

For the first request:

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>:<port, 443 by default>/kata/events_api/v1/<external_system_id>/events"

If the request is processed successfully, information about requested events and the token value are displayed.

For subsequent requests:

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>:<port, 443 by default>/kata/events_api/v1/<external_system_id>/events&continuation_token=<token value received by the first request>"

If the request is processed successfully, information about events received since the last request is displayed.

You can create a request to output information about events by specifying the maximum collection time and number of events, as well as event filtering parameters:

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>:<port, 443 by default>/kata/events_api/v1/<external_system_id>/events?filter=<event filter>&max_timeout=<maximum event collection time>&max_events=<maximum number of events>&continuation_token=<token value received by the first request>"

If you specified the value of the filter parameter for the first request, you do not have to specify it during subsequent requests: the filtering parameters are saved from the previous request and are used if no new parameters are passed in subsequent requests. If you do not want to use filtering, do not specify a value for the parameter.

Settings

Example of entering commands with parameters

If parameter values contain special characters, you must use URL encoding or the
--data-urlencode option in requests.

Example of commands with URL-encoded parameters

Example of commands with parameters that use the --data-urlencode option

Response

HTTP code: 200

Format: JSON

Returned value

Page top

Query language for filtering events

The event filtering query language supports the following functions and operators:

• Functions: in.
• Comparison operators for String or Boolean values:
  • ==
  • !=
• Comparison operators for numbers and variables:
  • AND
  • OR
  • NOT
  • ==
  • !=
  • >
  • >=
  • <
  • <=

You can view the list of fields by which you can filter events in the Fields for filtering events section.

If you want to receive information about events of different types, you must create a separate request for each type of event.

Numerical and string constants are supported. String constants must be enclosed in single quotation marks: 'example'. Wildcards * and ? are supported for string constants. If you do not want to use these characters as wildcards, you must escape them: \*, \?. Also, in string constants, you must escape special characters.

Fields for filtering events

The fields for filtering events are listed in the table below.

If field values contain special characters, you must use URL encoding or the
--data-urlencode option in requests.

List of fields for filtering events

Page top

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

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