Using Kaspersky Anti Targeted Attack Platform API NDR

The REST API server, which provides access to the NDR functionality to external systems, runs on the Central Node server and processes requests using the REST (Representational State Transfer) architectural style. Requests to the REST API server are made using HTTPS. You can configure the REST API server under Settings → Connection Servers (including replacing the default self-signed certificate with a trusted certificate).

The JSON format is used to represent data in requests and responses.

The documentation containing descriptions of requests based on the REST architectural style is published as an Online Help Guide on the Kaspersky Online Help page. This documentation is a developer guide in English. The developer guide also provides sample code and detailed descriptions of callable elements that are available in requests sent to the REST API server.

Open the documentation describing requests to the REST API server, version 3

Open the documentation describing requests to the REST API server, version 4

External systems can use Kaspersky Anti Targeted Attack Platform API to:

• Receive information about devices known to the application.
• Add, modify, and delete devices.
• Receive information about registered network traffic events (NDR events).
• Send NDR events to Kaspersky Anti Targeted Attack Platform (the system event type with code 4000005400 is used for registering the events).
• Receive information about detected vulnerabilities.
• Receive application messages and audit records.
• Receive information about allow rules.
• Enable, disable, and delete allow rules.
• Receive information about risks associated with devices.
• Receive information about address spaces.
• Send the network topology map report to Kaspersky Anti Targeted Attack Platform.
• Send, receive, and delete information about users on devices.
• Send and receive information about applications and patches on devices.
• Send and delete information about executable files on devices.
• Send the contents of the device logs.
• Receive the following application data:
  • List of servers with application components
  • List of monitoring points and their parameters
  • List of supported protocol stacks and their parameters
  • List of NDR event types and their parameters
  • Current state and operating mode of technologies
  • Application version and release dates of the installed updates
  • Information about the added license key
  • Application localization language

All of the listed actions are available when making requests to the REST API server version 4. Some of these actions are not supported when making requests to the REST API server version 3.

External systems using the Kaspersky Anti Targeted Attack Platform API connect to the Central Node component via connectors. Connectors use certificates for a secure connection. For each external system that you want to send requests to the REST API server, you need to create a separate connector in Kaspersky Anti Targeted Attack Platform.

The external system must use an authentication token to connect to Kaspersky Anti Targeted Attack Platform. Kaspersky Anti Targeted Attack Platform issues an authentication token at the request of an external system and token uses the certificates of the connector that was created for this system. The authentication token remains valid for 10 hours. The external system can renew the authentication token by special request.

Documentation containing a description of queries for authentication token operations is published as an Online Help Guide on the Kaspersky Online Help page. This documentation is a developer guide in English.

Open the documentation describing queries for authentication token operations, version 3.0

Open the documentation describing queries for authentication token operations, version 4

Kaspersky Anti Targeted Attack Platform API allows interacting with external systems in the following ways:

• Interaction based on the REST architectural style
• Interaction over the WebSocket protocol

External systems can use the WebSocket protocol for interaction in the Kaspersky Anti Targeted Attack Platform API to create subscriptions to modified values received by the application.

Ensuring security when using Kaspersky Anti Targeted Attack Platform API

External systems access the functionality of the application using the Kaspersky Anti Targeted Attack Platform API by establishing encrypted HTTPS connections. Certificates issued by the Central Node component of Kaspersky Anti Targeted Attack Platform are used to secure the connections. This component issues certificates for the connectors that external systems use to connect to the Server.

A separate connector must be created in Kaspersky Anti Targeted Attack Platform for each external system. A connection can be established through a connector only by using the specific certificate that was issued by the Central Node component and saved in the communication data package for that connector. A connection cannot be established if the external system presents a certificate from a different connector, a different Central Node component of Kaspersky Anti Targeted Attack Platform, or a certificate used for other connections (for example, a certificate of the Sensor component).

After establishing an encrypted connection, the external system must request an authentication token for the connector that the external system will use in requests sent to the Central Node REST API server.

An authentication token is valid for 10 hours after it was issued. If a token needs to be used for a longer period, the external system must request a time extension before the token expires.

For information about requests and methods supported by Kaspersky Anti Targeted Attack Platform API, see the documentation for the Kaspersky Anti Targeted Attack Platform API.

When processing requests from external systems, Kaspersky Anti Targeted Attack Platform uses the audit log to record information about attempts to perform the following operations:

• Receive an authentication token.
• Extend the validity period for an authentication token.
• Add a device to the devices table.
• Edit device information.
• Delete a device.
• Query the audit log (when first reading audit entries through the connector after loading the web server).

Creating and using connectors for Kaspersky Anti Targeted Attack Platform API

To enable interaction between an external system and Kaspersky Anti Targeted Attack Platform API, you need to add a connector for that system. When creating a connector, you must indicate the Generic system type for the connector.

When adding a connector and when creating a new communication data package for this connector, the Central Node generates a communication data package that you need to use for the connector to work.

A communication data package is an archive containing the following files:

• The certificates.pfx file contains the encrypted public key of the Central Node certificate and the certificate issued by the Central Node for the connector (with the private key). The contents of the file are encrypted with the password that was set when the connector was added or when a new communication data package was created for this connector.
• The metadata.json file contains the configuration data for the connector. Data is represented in JSON format.

The listed files must be used to connect the external system through the connector. To decrypt the certificates.pfx file and apply the certificate and keys that it contains, you can use the standard methods for handling files of this format (for example, openssl commands). The addresses specified in the metadata.json file are required for the connector to work and for sending requests to the REST API server.

The certificate and configuration data in the communication data package are valid until a new communication data package is created or until the connector is removed from the application.