API for scanning objects of external systems

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

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

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

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

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

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

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

Working with a cluster

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

Restrictions

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

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

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

Request to scan objects

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

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

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

Command syntax

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

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

Settings

Returned value

Example of entering a command with switches

Page top

Request for scan results

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

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

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

Command syntax

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

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

Settings

Returned value

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

Page top

Request to delete scan results

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

Command syntax

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

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

Settings

Returned value

Command input example

Page top

Request to display object scan restrictions

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

Command syntax

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

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

Settings

Returned value

Command input example

Page top