Kaspersky Anti Targeted Attack Platform Help

Kaspersky Anti Targeted Attack Platform

Print Support Send link

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

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

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:

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

Parameter	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

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

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 — 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

Contents

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

Request for querying event information

Query language for filtering events

Fields for filtering events