Kaspersky Anti Targeted Attack Platform
5.0
English

Contents

API for sending alert information to external systems

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

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

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

Special considerations for operation in the distributed solution

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

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

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>:<default port 443>/kata/scanner/v1/sensors/<sensorId>/detects?detect_type=<one or more technologies that were used to generate the alert>&limit=<number of alerts in the response to the request>&token=<request ID>"

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

Settings

Parameter

Type

Description

sensorId

String

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

detect_type

Array

Technology that was used to generate 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.

Returned value

Return code

Description

200

Operation completed successfully.

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 alert is listed in the following table.

Scope of transmitted alert data

Parameter

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
  • taa – Targeted Attack Analyzer

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

 

Parameter

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 TAA technology, only one domain is listed.
  • 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

Parameter

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 program 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)

Targeted Attack Analyzer

detect

Name of the TAA module alert.

The only possible value is Suspicious remote host activity

Suspicious remote host activity

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

Source of the object

Parameter

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 alerts do not have this parameter.

For URL technology alerts, 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 alert was generated.

String

computername.example.com

IP

IP address of the computer on which the alert 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]