Kaspersky Anti Targeted Attack Platform

Using Kaspersky Anti Targeted Attack Platform API KATA and KEDR

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 alerts and events to the external systems.

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 external system is configured based on the domain name. The external system will communicate with a random server in the cluster. If this server fails, the external system will communicate with another healthy server in the cluster.

In this Help section

Integrating an external system with Kaspersky Anti Targeted Attack Platform

API for scanning objects of external systems

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

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

API for managing Threat Response actions

Page top
[Topic 247805]

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.

Page top
[Topic 247806]

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.

Limitations

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.

Page top
[Topic 247807]

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

Parameter

Type

Description

sensorId

UUID

Unique ID of the external system used for authorization in Kaspersky Anti Targeted Attack Platform.

content

file

Contents of the scanned object.

scanId

string

Unique ID of the scan request. It must be generated in the external system. It cannot contain spaces or special characters. Do not use file names as a scan request ID.

If this parameter is not defined, viewing scan results is not available.

objectType

string

Type of scanned object.

Possible value of the parameter: file.

sensorInstanceId

string

Unique ID of the external system instance. Servers combined into a cluster are also considered to be instances of an external system. This parameter is optional.

Returned value

Return code

Description

200

Scan completed successfully.

401

Authorization required.

429

Number of requests exceeded. Repeat the request later.

500

Internal server error. Repeat the request later.

Example of entering a command with switches

curl --cert /root/cert.pem --key /root/server.key -X POST "https://10.10.10.1:443/kata/scanner/v1/sensors/dd11a1ee-a00b-111c-b11a-11001b1f1111/scans?sensorInstanceId=instance1" -F "content=@/tmp/test" -F scanId=1 -F "objectType=file"

Page top

[Topic 176838]

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

Setting

Type

Description

sensorId

string

Unique ID of the external system used for authorization in Kaspersky Anti Targeted Attack Platform.

state

array (string element type)

Object scan status. When this parameter is defined, the scan results will be filtered by status.

Indicate one or more statuses separated by commas.

The following parameter values are available:

  • detect
  • not detected
  • processing
  • timeout
  • error

sensorInstanceId

string

Unique ID of the external system instance. Servers combined into a cluster are also considered to be instances of an external system. This parameter is optional.

Response

HTTP code: 200

Format: JSON

type Response []Scans

 

type Scans struct {

ScanID integer `json:"scanId"`

State array `json:"state"`

}

Returned value

Return code

Description

204

No contents.

404

No scan results found for the specified ID.

500

Internal server error. Repeat the request later.

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

curl --cert /root/cert.pem --key /root/server.key -X GET "https://10.10.10.1:443/kata/scanner/v1/sensors/dd11a1ee-a00b-111c-b11a-11001b1f1111/scans/state?sensorInstanceId=instance1&state=detect,not%20detected,processing,error,timeout"

Page top

[Topic 176830]

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

Setting

Type

Description

sensorId

string

Unique ID of the external system used for authorization in Kaspersky Anti Targeted Attack Platform.

scanId

string

Unique ID of the object scan request. If this parameter is not defined, the scan results for all objects will be deleted.

Returned value

Return code

Description

200

Scan completed successfully.

401

Authorization required.

404

No scan results found for the specified ID.

500

Internal server error. Repeat the request later.

Command input example

curl --cert /root/cert.pem --key /root/server.key -X DELETE "https://10.10.10.1:443/kata/scanner/v1/sensors/dd11a1ee-a00b-111c-b11a-11001b1f1111/scans/1"

Page top

[Topic 176836]

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

Setting

Type

Description

sensorId

string

Unique ID of the external system used for authorization in Kaspersky Anti Targeted Attack Platform.

Response

HTTP code: 200

Format: JSON

type Response struct {

MaxObjectSize integer `json:"maxObjectSize"`

Version string `json:"version"`

}

Returned value

Return code

Description

401

Authorization required.

500

Internal server error. Repeat the request later.

Command input example

curl --cert /root/cert.pem --key /root/server.key -X GET "https://10.10.10.1:443/kata/scanner/v1/sensors/dd11a1ee-a00b-111c-b11a-11001b1f1111/scans/filters"

Page top

[Topic 176834]

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.

In this section:

Request to display alert information

Scope of transmitted data

Page top
[Topic 181465]

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

Setting

Type

Description

sensorId

String

Unique ID of the external system used for authorization in Kaspersky Anti Targeted Attack Platform.

detect_type

Array

The technology that created the alert. You can specify a comma-separated list of technologies.

Possible values:

  • am – Anti-Malware Engine
  • sb – Sandbox
  • yara – YARA
  • url_reputation – URL Reputation
  • ids – Intrusion Detection System

If the parameter is not specified, information about all alerts is provided.

limit

Integer

Number of objects for which information is provided in response to the request. Allowed values: integers from 1 to 10,000.

The default value is 1000.

token

String

Request ID. If this parameter is specified, a repeated request does not show alert information that was obtained by prior requests. This helps avoid the duplication of information about the same alerts in case of repeated requests.

If this parameter is not specified, information about all alerts is provided.

Response

HTTP code: 200

Format: JSON

type Response struct {

Detects array `json:"detects"`

Token string `json:"token"`

}

Returned value

Return code

Description

400

Incorrect parameters.

429

Number of requests exceeded.

401

Authorization required.

500

Internal server error. Repeat the request later.

Example of entering a command with switches

curl --cert /root/cert.pem --key /root/server.key -X GET "https://10.10.10.1:443/kata/scanner/v1/sensors/dd11a1ee-a00b-111c-b11a-11001b1f1111/detects?detect_type=am,sb&limit=100&token=7b226f6666736574223a20307d"

Page top

[Topic 181506]

Scope of transmitted data

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

Scope of information transmitted for an alert

Setting

Value

Description

alertID

Integer value.

Alert ID.

eventTimeStamp

Date and time.

Event time.

detectTimestamp

Date and time.

Time when alert information was recorded in the Kaspersky Anti Targeted Attack Platform database.

importance

One of the following values:

  • high
  • medium
  • low

Alert importance.

objectSource

One of the following values:

  • web
  • mail
  • endpoint
  • external
  • dns

Source of the detected object.

technology

One of the following values:

  • am – Anti-Malware Engine
  • sb – Sandbox
  • yara – YARA
  • url_reputation – URL Reputation
  • ids – Intrusion Detection System

Technology that was used to detect the object.

objectType

One of the following values:

  • file.
  • URL.
  • host (for remote domains or hosts).

Type of detected object.

object

Depends on the type of detected object.

Data on the detected object.

detection

Depends on the technology that was used to detect the object.

Data on detected threats.

details

Depends on the source of detected object.

Data on the environment of detected objects.

In this section:

Data on detected objects

Data on detected threats

Data on the environment of detected objects

Page top
[Topic 181468]

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

 

Setting

Data type

Description

Example

file

processedObject.MD5

MD5

MD5 hash of the file or composite object that was sent for scanning.

1839a1e9621c58dadf782e131df3821f

processedObject.SHA256

SHA256

SHA256 hash of the file or composite object that was sent for scanning.

7bbfc1d690079b0c591e146c4294305da1cee857e12db40f4318598fdb503a47

processedObject.fileName

String

Name of the file or composite object that was sent for scanning.

EICAR-CURE.com

processedObject.fileType

String

Type of the file or composite object that was sent for scanning.

GeneralTxt

processedObject.fileSize

Integer

Size of the file or composite object that was sent for scanning, in bytes.

184

detectedObject.MD5

MD5

MD5 hash of the file (simple object or file within a composite object) in which the threat was detected.

1839a1e9621c58dadf782e131df3821f

detectedObject.fileName

String

Name of the file (simple object or file within a composite object) in which the threat was detected.

EICAR-CURE.com

detectedObject.fileSize

Integer

Size of the file (simple object or file within a composite object) in which the threat was detected, in bytes.

184

URL

detectedObject

String

URL of the detected object.

http://example.com/link

host

detectedObject

Array

List of domains to which detected objects belong.

For the URL technology, as well as for objects with the objectSource=dns parameter, the list can contain several domains.

example.org, example.net

See also

Data on detected threats

Data on the environment of detected objects

Page top
[Topic 181469]

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

Technology

Setting

Description

Data type

Example

One of the following technologies:

  • Anti-Malware Engine.
  • YARA.
  • Intrusion Detection System.

detect

List of detected threats.

Array

HEUR:Trojan.Win32.Generic, Trojan-DDoS.Win32.Macri.avy, UDS:DangerousObject.Multi.Generic

dataBaseVersion

Version of databases used to scan the file.

Integer

201811190706

Sandbox

detect

List of detected threats.

Array

HEUR:Trojan.Win32.Generic, Trojan-DDoS.Win32.Macri.avy, UDS:DangerousObject.Multi.Generic

image

Name of the virtual machine image where the file was scanned.

String

Win7

dataBaseVersion

Database version in the following format: <version of the application databases which were used to scan the file> / <version of the IDS module databases>.

Integer

201902031107/ 201811190706

URL Reputation

detect

List of URL Reputation categories for the detected object (for objects of type URL or host).

Array

Phishing host, Malicious host, Botnet C&C(Backdoor.Win32.Mokes)

See also

Data on detected objects

Data on the environment of detected objects

Page top
[Topic 181470]

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

Object source

Setting

Description

Data type

Example

web

sourceIp

IP address of the computer that established the connection.

IP address

192.0.2.0

sourceHostname

Name of the computer that established the connection.

String

example.com

destinationIp

IP address of the computer with which the connection was established.

IP address

198.51.100.0

destinationPort

Port of the computer with which the connection was established.

Integer

3128

URL

URL of the web resource that was accessed.

IDS technology detections do not have this parameter.

For URL technology detections, this parameter has the same value as the detectedObject parameter.

String

https://example.com:443/

method.

HTTP request method.

String

Connect

referrer

URL from which the redirect was made.

String

https://example.com:443/

agentString

User agent header of the HTTP request that contains the name and version of the client application.

String

Mozilla/4.0

mail

mailFrom

Sender's email address.

String

sender@example.com

mailTo

Comma-separated list of recipient email addresses.

Array

recipient1@example.com, recipient2@example.com

subject

Subject of the message.

String

'You are the winner'

messageId

Email message ID.

String

1745028736.156014.1542897410859.JavaMail.svc_jira_pool@hqconflapp2

  • endpoint
  • external

hostName

Name of the computer on which the detection was generated.

String

computername.example.com

IP

IP address of the computer on which the detection was generated.

IP address

198.51.100.0

dns

sourceIp

IP address of the computer which initiated the DNS connection.

IP address

192.0.2.0

destinationIp

IP address of the computer with which the DNS connection was established (typically, a DNS server).

IP address

198.51.100.0

destinationPort

Port of the computer with which the DNS connection was established (typically, a DNS server).

Integer

3128

dnsMessageType

Type of the DNS message:

  • Request
  • Response

String

Request

dnsRequestType

One of the following DNS request types:

  • A.
  • AAA.
  • CNAME.
  • MX.

String

MX

domainToBeResolved

Domain name from the DNS request.

String

example.com

See also

Data on detected objects

Data on detected threats

Page top
[Topic 181471]

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.

Page top
[Topic 248949]

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

Setting

Type

Description

external_system_id

UUID

Unique ID of the external system used for authorization in Kaspersky Anti Targeted Attack Platform.

filter

string

Event filtering settings. These are set using the event query language.

max_timeout

int

Maximum event collection time. Specified in the following format: PT<integer value>S. For example, PT300S. The server sends information about events collected during the specified time.

The default value is 5 minutes. This value is used unless otherwise specified in the request.

The maximum event collection time may not exceed 5 minutes. If you specify a value greater than 5 minutes, the Central Node server returns an error.

The actual total time to wait for events may be increased.

max_events

int

Maximum number of events

If no value is specified in the request, Kaspersky Anti Targeted Attack Platform calculates it based on the number of hosts on which the Endpoint Agent component is installed.

Examples of values for typical configurations:

  • For 1000 hosts: 64,000.
  • For 5000 hosts: 128,000.
  • For 10,000 hosts: 208,000.
  • For 15,000 hosts: 288,000.
  • For 30,000 hosts: 528,000.

The value specified in the request must not exceed these limits.

continuation_token

string

Value of the token.

Example of entering commands with parameters

curl --cert <path to the TLS certificate file> --key <path to the private key file> -X GET "https://10.10.0.22:443/kata/events_api/v1/c440a37b-5c01-4505-a30e-3d23b20dd609/events"

curl --cert <path to the TLS certificate file> --key <path to the private key file> -X GET "https://10.10.0.22:443/kata/events_api/v1/c440a37b-5c01-4505-a30e-3d23b20dd609/events?
filter=EventType=='threatdetect' OR EventType=='threatprocessingresult'&max_timeout=PT300S&max_events=64000&continuation_token=
CiQyZDcyNjNiOS0zZmNlLTQxNzktYTdhOC03N2E0ZmUwNjNjMTkSBAgAEAoSBAgBEAMSBAgCEAsSBAgDEAcSBAgEEAgSBAgFEAkSBAgGEAQSBAg
HEAUSBAgIEAcSBAgJEAMYiYyCmvIw"

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

curl --cert <path to the TLS certificate file> --key <path to the private key file> -X GET "https://10.10.0.22:443/kata/events_api/v1/c440a37b-5c01-4505-a30e-3d23b20dd609/events?
filter=EventType=='threatdetect' OR EventType=='threatprocessingresult'&max_timeout=PT300S&max_events=64000&continuation_token=
CiQ%3Dcy%7ENiOS0zZmNlLTQxNzktYTdhOC03N2E0Z40%wNjNjMTkSBAgAEAoSBAgB%5EMSB%3CEAsSBAgDEAcSBAgEEAgSBAgFEAkSBAgGEAQSBAg
HEAUSBAgIEAcSBAgJEAMYiYyCmvIw"

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

curl --cert <path to the TLS certificate> --key <path to the private key file> --GET -d "max_events=64000" -d "max_timeout=PT300S" -d "filter=EventType=='threatdetect'" --data-urlencode "continuation_token=
CiQ?Dcy~NiOS0zZmNlLTQxNzktYTdhOC03N2E0Z@wNjNjMTkSBAgAEAoSBAgB^MSB?CEAsSBAgDEAcSBAgEEAgSBAgFEAkSBAgGEAQSBAg
HEAUSBAgIEAcSBAgJEAMYiYyCmvIw" https://10.10.0.22:443/kata/events_api/v1/c440a37b-5c01-4505-a30e-3d23b20dd609/events

Response

HTTP code: 200

Format: JSON

type Response struct {

Events array `json:"events"`

ContinuationToken string `json:"continuationToken"`

}

Returned value

Return code

Description

400

Incorrect parameters.

401

Authorization required.

500, 502, 503, 504

Internal server error. Repeat the request later.

Page top

[Topic 248951]

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.

EventType=='threatdetect' OR EventType=='threatprocessingresult'

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.

Page top
[Topic 249006]

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

Field name

Type

Description

hostName

string

Host name.

HostIp

string

IP address of the host.

EventType

string

Event type. Possible values:

  • process — process started.
  • process_terminate — process terminated.
  • module — module loaded.
  • connection — remote connection.
  • applock — prevention rule.
  • blockdocument — document blocked.
  • filechange – file modified.
  • windowsevent — system event log.
  • registry — registry modified.
  • portlisten — port listened.
  • driver — driver loaded.
  • threatdetect — the alert.
  • threatprocessingresult — alert processing result.
  • amsiscan — AMSI scan.
  • process_interpretated_file_run — interpreted run of a file.
  • process_console_interactive_input — interactive input of commands on the console.

UserName

string

User name.

OsFamily

string

Family of the operating system.

OsVersion

string

Version of the operating system being used on the host.

Ioa.Rules.Id

string

TAA (IOA) rule ID.

Ioa.Rules.Name

string

Information about the results of file analysis using the Targeted Attack Analyzer technology: name of the TAA (IOA) rule that was used to create the alert.

Ioa.Rules.Techniques

string

MITRE technique

Ioa.Rules.Tactics

string

MITRE tactic

Ioa.Severity

string

Importance level that is assigned to an event generated using this TAA (IOA) rule.

Possible values:

  • Low
  • Medium
  • High

Ioa.Confidence

string

Level of confidence depending on the likelihood of false alarms caused by the rule.

Possible values:

  • Low
  • Medium
  • High

FileCreationTime

integer

File creation time.

DllCreationTime

integer

DLL creation time.

DroppedCreationTime

integer

Creation time of the modified file.

InterpretedFileCreationTime

integer

Creation time of the interpreted file.

FileName

string

File name.

DllName

string

DLL name.

DroppedName

string

Name of the modified file.

BlockedName

string

Name of the blocked file.

InterpretedFileName

string

Name of the interpreted file.

FilePath

string

Path to the directory where the file is located.

DllPath

string

Path to the directory where the DLL is located.

DroppedPath

string

Path to the directory where the modified file is located.

BlockedPath

string

Path to the directory where the blocked file is located.

InterpretedFilePath

string

Path to the directory where the interpreted file is located.

FileFullName

string

Full path to the file. Includes the path to the directory and the file name.

DllFullName

string

Full path to the DLL. Includes the path to the directory and the file name.

DroppedFullName

string

Full path to the modified file. Includes the path to the directory and the file name.

BlockedFullName

string

Full path to the blocked file. Includes the path to the directory and the file name.

DetectedName

string

Full path to the detected file. Includes the path to the directory and the file name.

OriginalFileName

string

Full path to the original file. Includes the path to the directory and the file name.

InterpretedFileFullName

string

Full path to the interpreted file. Includes the path to the directory and the file name.

FileModificationTime

integer

File modification time.

DllModificationTime

integer

DLL modification time.

DroppedModificationTime

integer

Modification time of the modified time.

InterpretedFileModificationTime

integer

Modification time of the interpreted time.

FileSize

integer

File size.

DllSize

integer

DLL size.

DroppedSize

integer

Size of the modified file.

InterpretedFileSize

integer

Size of the interpreted file.

Md5

string

MD5 hash of the file.

DllMd5

string

MD5 hash of the DLL

DroppedMd5

string

MD5 hash of the modified file.

InterpretedMd5

string

MD5 hash of the interpreted file.

DetectedMd5

string

MD5 hash of the detected file.

Sha256

string

SHA256 hash of the file.

DllSha256

string

SHA256 hash of the DLL.

DroppedSha256

string

SHA256 hash of the modified file.

BlockedSha256

string

SHA256 hash of the blocked file.

InterpretedSha256

string

SHA256 hash of the interpreted file.

DetectedSha256

string

SHA256 hash of the detected file.

HijackingPath

string

A malicious DLL placed in a directory on the standard search path to make the operating system load it before the original DLL.

LogonRemoteHost

string

IP address of the host that initiated remote access.

RealUserName

string

Name of the user assigned when the user was registered in the system.

EffectiveUserName

string

User name that was used to log in to the system.

Environment

string

Environment variables.

ProcessType

integer

Process type. Possible values:

  • 1 – exec
  • 2 – fork
  • 3 – vfork
  • 4 – clone

LinuxOperationResult

string

Result of the operation. Possible values:

  • success.
  • failed.

SystemPid.

integer

Process ID.

ParentFileFullName.

string

Path to the parent process file.

ParentMd5

string

MD5 hash of the parent process file.

ParentSha256

string

SHA256 hash of the parent process file.

StartupParameters

string

Process start options.

ParentSystemPid

integer

Parent process ID.

ParentStartupParameters

string

Parent process startup settings.

Method.

string

HTTP request method.

Direction.

string

Connection direction. Possible values:

  • inbound
  • outbound

LocalIp

string

IP address of the local computer from which the remote connection attempt was made.

LocalPort

integer

Port of the local computer from which the remote connection attempt was made.

RemoteHostName

string

Name of the computer that was the target of the remote connection attempt.

RemoteIp

string

IP address of the computer that was the target of the remote connection attempt.

RemotePort

integer

Port of the computer that was the target of the remote connection attempt.

URI

string

Address of the resource to which the HTTP request was made.

KeyName

string

Path to the registry key.

ValueName

string

Registry value name.

ValueData

string

Registry value data.

RegistryOperationType

integer

Type of the operation with the registry. Possible values:

  • 0 – Registry key created.
  • 1 – Registry key deleted.
  • 2 – Registry modified.
  • 3 – Registry key renamed.

PreviousKeyName

string

Previous path to the registry key.

PreviousValueData

string

Previous name of the registry value.

System.EventID.value

string

Type ID of the security event in the Windows log.

LinuxEventType
(this field is used to obtain the type of event recorded in the event log of Linux and macOS operating systems)

string

Event type. Possible values:

  • MemberAddedToGroup — User account created.
  • UserAccountDeleted – User account deleted.
  • GroupCreated – Group created.
  • GroupDeleted – Group modified.
  • MemberAddedToGroup — User account added to a group.
  • UserPasswordChanged – User account password changed.
  • LinuxAuth – Authentication in Linux or macOS performed.
  • LinuxSessionStart – Linux or macOS session started.
  • LinuxSessionEnd – Linux or macOS session ended.
  • ServiceStart – Service started.
  • ChangeAccountExpirationDate – Account expiration date changed.
  • OperatingSystemShuttingDown — Operating system shut down.
  • OperatingSystemStarted – Operating system started.
  • ModifyPromiscuousMode – Promiscuous mode modified.
  • AuditdConfigurationChanged – Audit settings modified.

System.Channel.value

string

Log name.

System.EventRecordID.value

string

Entry ID in the log.

System.Provider.Name.value

string

ID of the system that logged the event.

EventData.Data.TargetDomainName.value

string

Domain name of the remote computer.

EventData.Data.ObjectName.value

string

Name of the object that initiated the event.

EventData.Data.PackageName.value

string

Name of the package that initiated the event.

EventData.Data.ProcessName.value

string

Name of the process that initiated the event.

VerdictName

string

Name of the detected object.

RecordId

integer

ID of the triggered rule.

ProcessingMode

string

Scanning mode. Possible values:

  • Default – default.
  • OnDemand – on demand.
  • OnAccess – on access.
  • OnExecute – on execution.
  • OnDownload – on download.
  • OnStartup – on startup of applications.
  • OnMail – on sending a message.
  • OnPostpone – postponed scanning.
  • OnDisinfect – on disinfection.
  • OnVulnerability – when scanning for vulnerabilities.
  • OnFirstLaunch – on first launch.
  • OnEngineLoad – on system startup.
  • OnQuarantineRescan – on rescanning objects in the Storage.
  • OnWebRequest – on web request.
  • OnAmsiScan – on AMSI scanning.
  • OnSystemWatcherScan – on analyzing application behavior.

DetectedName

string

Name of the object.

DetectedObjectType

string

Type of the object. Possible values:

  • Unknown.
  • File.
  • LogicalDrive – logical drive.
  • PhysicalDisk – physical disk.
  • SystemMemory – system memory.
  • MemoryProcess – process memory.
  • MemoryModule – memory module.
  • MailMsgRef – References header of the email message.
  • MailMsgMime – MIME attachments.
  • MailMsgBody – body of the email message.
  • MailMsgAttach – attachment of the email message.
  • StartUp – startup objects.
  • Folder – directory.
  • Script – script.
  • Url – URL address.
  • AmsiStream – AMSI scan stream.

ThreatStatus

string

Discovery mode. Possible values:

  • Untreated – object not processed.
  • Untreatable – object cannot be processed.
  • NotFound – object not found.
  • Disinfected – object disinfected.
  • Deleted – object deleted.
  • Quarantined – object moved to quarantine.
  • AddedByUser – object added by the user.
  • Unknown.
  • AddedToExclude – object added to exclusions.
  • Terminated – processing terminated.
  • Clear – object is not infected.
  • FalseAlarm – false alarm.
  • RolledBack – Rolled back to a previous state.
  • IpNotBlocked – IP address not blocked.
  • IpBlocked – IP address blocked.
  • IpCannotBeBlocked — IP address could not be blocked.
  • IpBlockIsNotRequired — IP address blocking not required.

UntreatedReason

string

Object processing status. Possible values:

  • None – no data.
  • NonCurable – object cannot be disinfected.
  • Locked – object locked.
  • ReportOnly – application in Report only mode.
  • NoRights – no rights to perform the action.
  • Canceled – processing canceled.
  • WriteProtect – object is write-protected.
  • TaskStopped – processing task interrupted.
  • Postponed – action postponed.
  • NonOverwritable – object cannot be overwritten.
  • CopyFailed – failed to create a copy of the object.
  • WriteError – data write error.
  • OutOfSpace – Out of disk space.
  • ReadError - data read error.
  • DeviceNotReady – device not ready.
  • ObjectNotFound – object not found.
  • WriteNotSupported – data writing not supported.
  • CannotBackup – failed to create a backup of the object.
  • SystemCriticalObject – object is critical for the system.
  • AlreadyProcessed – object already processed.

InteractiveInputText

string

Interpreter command.

ObjectContent

string

Contents of the script sent to be scanned.

ObjectContentType

integer

Content type of the script. Possible values:

  • 1 – text
  • 2 – binary code

FileOperationType

integer

Type of the file operation. Possible values:

  • 1 – file created
  • 2 – file modified
  • 3 – file renamed
  • 4 – file attributes modified
  • 5 – file deleted
  • 6 – file read

PreviousFileName

string

Path to the directory where the file was previously located.

PreviousFileFullName

string

Full name of the file including the path to the directory where the file was previously located and/or the previous file name.

DroppedFileType

integer

Type of the modified file. Possible values:

  • 0 – unknown
  • 1 – other files
  • 2 – PE image
  • 3 – PE DLL
  • 4 – PE resources
  • 5 – .NET resource file
  • 6 – ELF file

Page top

[Topic 249086]

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:

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.

In this Help section

Request for getting the list of hosts with the Endpoint Agent component

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

Host network isolation management

Managing prevention rules

Managing the application run task

Page top
[Topic 227245]

Request for getting the list of hosts with the Endpoint Agent component

To create a request for information about hosts with the Endpoint Agent component, 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 hosts with the Endpoint Agent component is displayed.

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

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 host with the Endpoint Agent component is displayed.

Settings

Parameter

Type

Description

external_system_id

UUID

Unique ID of the external system used for authorization in Kaspersky Anti Targeted Attack Platform.

sensor_id

UUID

Unique ID of the host with the Endpoint Agent component

ip

string

IP address of the host with the Endpoint Agent component.

host

string

Name of the host with the Endpoint Agent component.

Example of entering commands with parameters

GET "https://10.10.0.22:443/kata/response_api/v1/15301050-0490-4A41-81EA-B0391CF21EF3/sensors"

GET "https://10.10.0.22:443/kata/response_api/v1/15301050-0490-4A41-81EA-B0391CF21EF3/sensors?ip=10.16.40.243&host=host4&sensor_id=DF64838B-B518-414B-B769-2B8BE341A2F0"

Response

HTTP code: 200

Format: JSON

type Response Sensors

 

type Server struct {

Version string `json:"version"`

},

 

type Sensors struct {

SensorID UUID `json:"sensorId"`

HostIP string `json:"hostIp"`

LastAccessTimestamp `json:"lastAccessTimestamp"`

Version string `json:"version"`

SelfDefenseState boolean `json:"selfDefenseState"`

LicenseStatus string `json:"licenseStatus"`

OSFamily string `json:"osFamily"`

OSName string `json:"osName"`

Capabilities array `json:"capabilities"`

   

}

Returned value

Return code

Description

400

Authorization required.

401

Incorrect parameters.

500, 502, 503, 504

Internal server error. Repeat the request later.

Page top

[Topic 227251]

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

Parameter

Type

Description

external_system_id

UUID

Unique ID of the external system used for authorization in Kaspersky Anti Targeted Attack Platform.

sensor_id

UUID

Unique ID of the host with the Endpoint Agent component

settings_type

enum

Rule type: network_isolation or prevention.

Example of entering a command with switches

GET "https://10.10.0.22:443/kata/response_api/v1/15301050-0490-4A41-81EA-B0391CF21EF3/settings?sensor_id=DF64838B-B518-414B-B769-2B8BE341A2F0&settings_type=network_isolation"

Response

HTTP code: 200

Format: JSON

type Response []Settings

 

type Settings struct {

ExcludedRules array `json:"excludedRules"`

AutoTurnoffTimeoutInSec int `json:"autoTurnoffTimeoutInSec"`

}

 

Returned value

Return code

Description

400

Authorization required.

401

Incorrect parameters.

404

Specified hosts with the Endpoint Agent component not found.

500, 502, 503, 504

Internal error. Repeat the request later.

Page top

[Topic 227597]

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:

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

Page top
[Topic 227293]

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

Parameter

Type

Description

external_system_id

UUID

Unique ID of the external system used for authorization in Kaspersky Anti Targeted Attack Platform.

sensor_id

UUID

Unique ID of the host with the Endpoint Agent component

autoTurnoffTimeoutInSec

integer

Period of time during which the network isolation will be active.

Allowed range - 1 to 9999 hours. Network isolation time period is specified in seconds. For example, if you want to enable network isolation of a host for two hours, you must specify 7200 seconds.

Example of entering a command with switches

curl -k --cert <path to TLS certificate file> --key <path to private key file> -X POST "https://10.10.0.22:443/kata/response_api/v1/15301050-0490-4A41-81EA-B0391CF21EF3/settings?sensor_id=DF64838B-B518-414B-B769-2B8BE341A2F0&settings_type=network_isolation" -H 'Content-Type: application/json' -d '

{

"settings": {

"autoTurnoffTimeoutInSec": 7200}

}

'

 

Response

HTTP code: 200

Format: JSON

type Response []Settings

 

type Settings struct {

ExcludedRules array `json:"excludedRules"`

AutoTurnoffTimeoutInSec integer `json:"autoTurnoffTimeoutInSec"`

}

 

Returned value

Return code

Description

400

Incorrect parameters.

401

Authorization required.

404

Specified hosts with the Endpoint Agent component not found.

500, 502, 503, 504

Internal server error. Repeat the request later.

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.

Page top
[Topic 227448]

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

Setting

Type

Description

external_system_id

UUID

Unique ID of the external system used for authorization in Kaspersky Anti Targeted Attack Platform.

sensor_id

UUID

Unique ID of the host with the Endpoint Agent component

Example of entering a command with the DELETE parameter

curl -k --cert <path to TLS certificate file> --key <path to private key file> -X DELETE "https://10.10.0.22:443/kata/response_api/v1/15301050-0490-4A41-81EA-B0391CF21EF3/settings?sensor_id=DF64838B-B518-414B-B769-2B8BE341A2F0&settings_type=network_isolation"

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

curl -k --cert <path to TLS certificate file> --key <path to private key file> -X GET "https://10.10.0.22:443/kata/response_api/v1/15301050-0490-4A41-81EA-B0391CF21EF3/settings?sensor_id=DF64838B-B518-414B-B769-2B8BE341A2F0&settings_type=network_isolation"| python -m json.tool

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

{

"error": "Not Found"

}

Returned value

Return code

Description

400

Incorrect parameters.

401

Authorization required.

404

Specified hosts with the Endpoint Agent component not found.

500, 502, 503, 504

Internal server error. Repeat the request later.

Page top

[Topic 227577]

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

Parameter

Type

Description

external_system_id

UUID

Unique ID of the external system used for authorization in Kaspersky Anti Targeted Attack Platform.

sensor_id

UUID

Unique ID of the host with the Endpoint Agent component

direction.

array

Direction of network traffic that must not be blocked. Possible values:

  • inbound
  • outbound
  • both

If you do not specify a value for this parameter, the default value is 'both', which means the application transmits traffic in both directions.

protocol

integer

IP protocol number assigned by the Internet Assigned Numbers Authority (IANA).

If you do not specify a value for this parameter, by default, network isolation is applied to all protocols.

remoteIpv4Address

string

IP address of the host with the Endpoint Agent component whose traffic must not be blocked

remotePortRange

string

Destination port.

You can specify a destination port only if you have selected an outbound direction of network traffic. Port ranges cannot be specified for bidirectional traffic.

localPortRange

string

Port from which the connection is initiated.

You can specify a destination port only if you have selected an inbound direction of network traffic. Port ranges cannot be specified for bidirectional traffic.

autoTurnoffTimeoutInSec

integer

Period of time during which the network isolation will be active.

Allowed range - 1 to 9999 hours. Network isolation time period is specified in seconds. For example, if you want to enable network isolation of a host for two hours, you must specify 7200 seconds.

Example of entering a command with switches

curl -k --cert <path to TLS certificate file> --key <path to private key file> -X POST "https://10.10.0.22:443/kata/response_api/v1/15301050-0490-4A41-81EA-B0391CF21EF3/settings?sensor_id=DF64838B-B518-414B-B769-2B8BE341A2F0&settings_type=network_isolation" -H 'Content-Type: application/json' -d '

{
"settings":
{"excludedRules": [
{
"direction": "inbound",
"protocol": 6,
"remoteIpv4Address": "10.16.41.0",
"localPortRange":
{
"fromPort": 3389,
"toPort": 3389
}
}
,
{
"direction": "outbound",
"remoteIpv4Address": "10.16.41.1",
"remotePortRange":
{
"fromPort": 13957,
"toPort": 55409
}
}
,
{
"direction": "both",
"protocol": 6,
"remoteIpv4Address": "10.16.41.2"
}
]
,
"autoTurnoffTimeoutInSec": 7200
}
}
'

Response

HTTP code: 200

Format: JSON

type Response []Settings
type Settings struct {
ExcludedRules array `json:"excludedRules"`
AutoTurnoffTimeoutInSec integer `json:"autoTurnoffTimeoutInSec"`
}
type ExcludedRules struct {
Direction array `json:"direction"`
Protocol integer `json:"autoTurnoffTimeoutInSec"`
RemotePortRange string `json:"remotePortRange"`
LocalPortRange string `json:"localPortRange"`
}

Returned value

Return code

Description

400

Incorrect parameters.

401

Authorization required.

404

Specified hosts with the Endpoint Agent component not found.

500, 502, 503, 504

Internal server error. Repeat the request later.

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.

Page top
[Topic 227499]

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:

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.

Page top
[Topic 227294]

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

Parameter

Type

Description

external_system_id

UUID

Unique ID of the external system used for authorization in Kaspersky Anti Targeted Attack Platform.

sensor_id

UUID

Unique ID of the host with the Endpoint Agent component

objects

string

Type of the object that you want to prevent from running.

Possible value of the parameter: file.

sha256 or md5

string

SHA256 or MD5 has of the object that you want to prevent from running.

Example of entering a command with switches

curl -k --cert <path to TLS certificate file> --key <path to private key file> -X POST "https://10.10.0.22:443/kata/response_api/v1/15301050-0490-4A41-81EA-B0391CF21EF3/settings?sensor_id=all&settings_type=prevention" -H 'Content-Type: application/json' -d '

{

"settings": {

"objects": [

{

"file": {

"sha256": "830195824b742ee59390bc5b9302688c778fc95a64e7d597e28a74c03a04dd63"

}

},

{

"file": {

"md5": "d8e577bf078c45954f4531885478d5a9"

}

}

]

}

}

'

Response

HTTP code: 200

Format: JSON

type Response []Objects

 

type Objects struct {

type file struct {

SHA256 string `json:"sha256"`

},

type file struct {

MD5 string `json:"md5"`

}

}

Returned value

Return code

Description

400

Incorrect parameters.

401

Authorization required.

404

Specified hosts with the Endpoint Agent component not found.

500, 502, 503, 504

Internal server error. Repeat the request later.

Page top

[Topic 227449]

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

Parameter

Type

Description

external_system_id

UUID

Unique ID of the external system used for authorization in Kaspersky Anti Targeted Attack Platform.

sensor_id

UUID

Unique ID of the host with the Endpoint Agent component

Example of command for a new request

curl -k --cert <path to TLS certificate file> --key <path to private key file> -X POST "https://10.10.0.22:443/kata/response_api/v1/15301050-0490-4A41-81EA-B0391CF21EF3/settings?sensor_id=all&settings_type=prevention" -H 'Content-Type: application/json' -d '

{

"settings": {

"objects": []

}

}

'

Example of entering a command with the DELETE parameter

curl -k --cert <path to TLS certificate file> --key <path to private key file> -X DELETE "https://10.10.0.22:443/kata/response_api/v1/15301050-0490-4A41-81EA-B0391CF21EF3/settings?sensor_id=all&settings_type=prevention"

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

curl -k --cert <path to TLS certificate file> --key <path to private key file> -X GET "https://10.10.0.22:443/kata/response_api/v1/15301050-0490-4A41-81EA-B0391CF21EF3/settings?sensor_id=all&settings_type=prevention"| python -m json.tool

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

{

"error": "Not Found"

}

Returned value

Return code

Description

400

Incorrect parameters.

401

Authorization required.

404

Specified hosts with the Endpoint Agent component not found.

500, 502, 503, 504

Internal server error. Repeat the request later.

Page top

[Topic 227588]

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:

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

Page top
[Topic 227589]

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

Settings

Type

Description

external_system_id

UUID

Unique ID of the external system used for authorization in Kaspersky Anti Targeted Attack Platform.

sensor_id

UUID

Unique ID of the host with the Endpoint Agent component

task_id

UUID

Unique ID of the task.

settings

boolean

Possible values:

  • true.

    If you enter this value, information is displayed about settings, creation time, and completion status of the task.

  • false.

    If you enter this value, information about creation time and completion status of the task is displayed.

Example of entering a command with switches

GET https://10.10.0.22:443/kata/response_api/v1/15301050-0490-4A41-81EA-B0391CF21EF3/tasks/2EEB4CBC-10C6-4DC4-BE0A-72A75CDB0BE8?settings=<true or false>

Response

HTTP code: 200

Format: JSON

type Response struct {

State `json:"state"`

LatestStartDateTime `json:"latestStartDateTime"`

type Task struct {

type Schedule struct {

StartNow boolean `json:"startNow"`

ExecCommand string `json:"execCommand"`

}

}

}

 

Returned value

Return code

Description

400

Incorrect parameters.

401

Authorization required.

409

The task with the specified ID was already exists.

500, 502, 503, 504

Internal server error. Repeat the request later.

Page top

[Topic 227590]

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

Setting

Type

Description

external_system_id

UUID

Unique ID of the external system used for authorization in Kaspersky Anti Targeted Attack Platform.

sensor_id

UUID

Unique ID of the host with the Endpoint Agent component

task_id

UUID

Unique ID of the task.

Example of entering a command with switches

curl -k --example.cert --example.key -X POST "https://10.10.0.22:443/kata/response_api/v1/15301050-0490-4A41-81EA-B0391CF21EF3/tasks/2EEB4CBC-10C6-4DC4-BE0A-72A75CDB0BE8?sensor_id=DF64838B-B518-414B-B769-2B8BE341A2F0&task_type=run_process" -H 'Content-Type: application/json' -d '

{

"task": {

"schedule": {"startNow": true},

"execCommand": "Example.exe",

"cmdLineParameters": "C:\Windows\System32\",

"workingDirectory": "/all"

}

}

'

Response

HTTP code: 200

Format: JSON

type Response struct {

State `json:"state"`

LatestStartDateTime `json:"latestStartDateTime"`

type Task struct {

type Schedule struct {

StartNow boolean `json:"startNow"`

ExecCommand string `json:"execCommand"`

}

}

}

 

Returned value

Return code

Description

400

Incorrect parameters.

401

Authorization required.

404

The task with the specified ID was not found.

500, 502, 503, 504

Internal server error. Repeat the request later.

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.

Page top
[Topic 227591]

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

Setting

Type

Description

external_system_id

UUID

Unique ID of the external system used for authorization in Kaspersky Anti Targeted Attack Platform.

task_id

UUID

Unique ID of the task.

Example of entering a command with the DELETE parameter

curl -k --example.cert --example.key -X DELETE "https://10.10.0.22:443/kata/response_api/v1/15301050-0490-4A41-81EA-B0391CF21EF3/tasks/2EEB4CBC-10C6-4DC4-BE0A-72A75CDB0BE8"

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

curl -k --example.cert --example.key -X GET "https://10.10.0.22:443/kata/response_api/v1/15301050-0490-4A41-81EA-B0391CF21EF3/tasks/2EEB4CBC-10C6-4DC4-BE0A-72A75CDB0BE8?settings=false"| python -m json.tool

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

{

"error": "Not Found"

}

Returned value

Return code

Description

400

Incorrect parameters.

401

Authorization required.

404

The task with the specified ID was not found.

500, 502, 503, 504

Internal server error. Repeat the request later.

Page top

[Topic 227592]