Kaspersky Threat Intelligence Portal

Working with the API

This section explains how to use Kaspersky Threat Intelligence Portal. You can lookup objects and submit files to the Sandbox analysis by using the Kaspersky Threat Intelligence Portal API.

To work with Kaspersky Threat Intelligence Portal API, you must request an API token.

You can access Kaspersky Threat Intelligence Portal API at the following location:

https://opentip.kaspersky.com/api/v1/<endpoint>

In this section

Managing an API token

Looking up a hash

Looking up an IP address

Looking up a domain

Looking up a web address

Getting basic file analysis report

Getting full file analysis report

Page top
[Topic WorkingWithAPI]

Managing an API token

To be able to use the Kaspersky Threat Intelligence Portal API, you must sign in by using the Kaspersky Account, and then request an API token (hereinafter also referred to as "token").

You can request, view, copy, and revoke your token. The generated token is used as the header parameter X-API-KEY when you run requests by using the Kaspersky Threat Intelligence Portal API.

You can view your token at any time on the Request Token page.

If you revoke the token, it becomes invalid, and cannot be used for working with the Kaspersky Threat Intelligence Portal API.

The maximum token validity period is one year.

To use Kaspersky Feeds for OpenCTI Connector to obtain Demo Threat Data Feeds, you need to request a Demo TAXII Server Token.

To request a token:

  1. Open Kaspersky Threat Intelligence Portal at: https://opentip.kaspersky.com.
  2. Make sure you are signed in with your Kaspersky Account.
  3. In the <your email address> (User icon.) drop-down menu, click Request token.

    The Request Token page opens.

  4. In the API Token section, do the following:
    1. If necessary, specify a validity period or expiration date for the token by using the calendar.

      By default, one year is specified.

      The validity period for the token cannot be changed after it is generated. You can only request another token, and then specify a new required date.

    2. Click the Request token button.

      The generated token appears in the API token field — use the eye icon to view or hide the token.

      Information about the token's validity period and number of days before expiration is displayed.

  5. If necessary, you can copy the token by clicking the Copy to clipboard. button.

To revoke a token:

  1. Open Kaspersky Threat Intelligence Portal at: https://opentip.kaspersky.com.
  2. Make sure you are signed in with your Kaspersky Account.
  3. In the <your email address> (User icon.) drop-down menu, click Request token.

    The Request Token page opens.

  4. In the API Token section, click the Revoke token button.

    The API token becomes invalid.

To be able to work with the Kaspersky Threat Intelligence Portal API again, you must generate a new API token.

See also

Requesting Demo TAXII Server Token

Page top
[Topic ManagingToken]

Looking up a hash

Expand all | Collapse all

Kaspersky Threat Intelligence Portal provides an API for looking up a hash.

Request

Request method: GET

Endpoint: https://opentip.kaspersky.com/api/v1/search/hash

Query parameter: request—Hash that you want to investigate.

cURL command sample:

curl --request GET 'https://opentip.kaspersky.com/api/v1/search/hash?request=<hash>' --header 'x-api-key: <API token>'

Here:

Responses

200 OK

Request processed successfully.

Endpoint returns a JSON object that contains lookup results for the specified hash.

200 OK response parameters

Parameter

Type

Description

Zone

string

Color of the zone that a hash belongs to. Available values:

Red—The file can be classified as Malware.

Yellow—The file is classified as Adware and other (Adware, Pornware, and other programs).

Grey—No data or not enough information is available for the hash.

Green—The file has the Clean or No threats detected status. The No threats detected status is applied if the file was not classified by Kaspersky, but it was previously scanned and/or analyzed, and no threats were detected at the time of the analysis.

FileGeneralInfo

object

General information about the requested hash.

FileStatus

string

Status of the file requested by the hash (Malware, Adware and other, Clean, No threats detected, or Not categorized).

Sha1

string

SHA1 hash of the file requested by the hash.

Md5

string

MD5 hash of the file requested the hash.

Sha256

string

SHA256 hash of the file requested by the hash.

FirstSeen

string <date-time>

Date and time when the requested hash was detected by Kaspersky expert systems for the first time.

LastSeen

string <date-time>

Date and time when the requested hash was detected by Kaspersky expert systems for the last time.

Signer

string

Organization that signed the requested hash.

Packer

string

Packer name (if available).

Size

integer

Size of the object being investigated by the hash (in bytes).

Type

string

Type of the object being investigated the by hash.

HitsCount

integer

Number of hits (popularity) of the requested hash detected by Kaspersky expert systems. Number of hits is rounded to the nearest power of 10.

DetectionsInfo

Array of objects

Information about detected objects.

LastDetectDate

string <date-time>

Date and time when the object was last detected by Kaspersky expert systems.

DescriptionUrl

string

Link to the detected object's description in the Kaspersky threats website (if available).

Zone

string

Color of the zone that the detected object belongs to.

DetectionName

string

Name of the detected object.

DetectionMethod

string

Method used to detect the object.

DynamicAnalisysResults

object

Information about dynamic analysis results.

Detections

Array of objects

The number of detected objects with Malware (red) or Adware and other (yellow) statuses.

Zone—Color of the zone of the detected object (Red or Yellow).

Count—Number of objects that belong to the zone.

SuspiciousActivities

Array of objects

The number of suspicious activities with High (red), Medium (yellow), or Low (grey) levels.

Zone—Color of the zone of the activity (Red, Yellow, or Grey).

Count—Number of activities that belong to the zone.

ExtractedFiles

Array of objects

The number of files that were downloaded or dropped by the file during the execution process, and the proportion of files with the status of Malicious (extracted files that can be classified as malicious, in red), Adware and other (extracted files that can be classified as Not-a-virus, in yellow), Clean (extracted files that can be classified as not malicious, in green), or Not categorized (no information about the extracted files is available, in grey).

Zone—Color of the zone of the file (Red, Yellow, Green, or Grey).

Count—Number of files that belong to the zone.

NetworkActivities

Array of objects

The number of registered network interactions that the file performed during the execution process and the proportion of network interactions with the status of Dangerous (requests to resources with the Dangerous status, in red), Adware and other (requests to resources with the Adware and other status, in yellow), Good (requests to resources with the Good status, in green), or Not categorized (requests to resources with the Not categorized status, in grey).

Zone—Color of the zone of the network activity (Red, Yellow, Green, or Grey).

Count—Number of network activities that belong to the zone.

DynamicDetections

Array of objects

Detects related to the analyzed file.

Zone—Color of the zone of the detected object (Red or Yellow).

Threat—Number of detected objects that belong to the zone.

TriggeredNetworkRules

Array of objects

SNORT and Suricata rules triggered during analysis of traffic from the file.

Zone—Color of the zone of the triggered rule (Red or Yellow).

RuleName—Name of the triggered rule.

400 Bad Request

Request not processed: incorrect query.

Make sure you enter the correct parameter, and then try to run the query again.

401 Unauthorized

Request not processed: user authentication failed.

Make sure you enter the correct credentials, and then try to run the query again.

403 Forbidden

Request not processed: quota or request limit exceeded.

Check your quota and limitations, and try to run the query again later.

404 Not Found

Request not processed: requested object lookup results not found.

Make sure the specified object is correct, and then run the query again.

Page top
[Topic HashLookupAPI]

Looking up an IP address

Expand all | Collapse all

Kaspersky Threat Intelligence Portal provides an API for looking up an IP address.

Request

Request method: GET

Endpoint: https://opentip.kaspersky.com/api/v1/search/ip

Query parameter: request—IP address that you want to investigate.

cURL command sample:

curl --request GET 'https://opentip.kaspersky.com/api/v1/search/ip?request=<IP address>' --header 'x-api-key: <API token>'

Here:

Responses

200 OK

Request processed successfully.

Endpoint returns a JSON object that contains lookup results for the specified IP address.

200 OK response parameters

Parameter

Type

Description

Zone

string

Color of the zone that an IP address belongs to. Available values:

Red—The IP address can be classified as Dangerous.

Orange—The IP address can be classified as Not trusted and may host malicious objects.

Yellow—The IP address is classified as Adware and other (Adware, Pornware, and other programs).

Grey—No data or not enough information is available for the IP address.

Green—The IP address has the Good or No threats detected status. The No threats detected status is applied if the IP address was not classified by Kaspersky, but it was previously scanned and/or analyzed, and no threats were detected at the time of the analysis.

IpGeneralInfo

object

General information about the requested IP address.

Status

string

Status of the IP address (known if the country is detected, reserved for reserved special-purpose IP addresses (see RFC 6890), and NoInfo for IP addresses that do not belong to any country and are not reserved).

CountryCode

string

Two-letter country code (ISO 3166-1 alpha-2 standard) of the country to which the IP address belongs.

HitsCount

integer

Hits number (popularity) of the requested IP address.

FirstSeen

string <date-time>

Date and time when the requested IP address appeared in Kaspersky expert systems statistics for the first time.

Ip

string

Requested IP address.

Categories

Array of strings

Category of the requested IP address.

CategoriesWithZone

Array of objects

Categories of the requested IP address and zones that the category belongs to:

Name—Category name.

Zone—Color of the category's zone (Red or Yellow).

IpWhoIs

object

WHOIS information about the requested IP address.

Asn

Array of objects

Autonomous system number:

Number—Number of the autonomous system, according to RFC 1771 and RFC 4893.

Description—Autonomous system description.

Net

object

Information about the network that the requested IP address belongs to:

RangeStart—Start IP address in the network that the IP address belongs to.

RangeEnd—End IP address in the network that the IP address belongs to.

Created—Date when the IP address was registered.

Changed—Date when information about the IP address was last updated.

Name—Name of the network that the IP address belongs to.

Description—Description of the network that the IP address belongs to.

400 Bad Request

Request not processed: incorrect query.

Make sure you enter the correct parameter, and then try to run the query again.

401 Unauthorized

Request not processed: user authentication failed.

Make sure you enter the correct credentials, and then try to run the query again.

403 Forbidden

Request not processed: quota or request limit exceeded.

Check your quota and limitations, and try to run the query again later.

Page top
[Topic IPLookupAPI]

Looking up a domain

Expand all | Collapse all

Kaspersky Threat Intelligence Portal provides an API for looking up a domain.

Request

Request method: GET

Endpoint: https://opentip.kaspersky.com/api/v1/search/domain

Query parameter: request—Domain that you want to investigate.

cURL command sample:

curl --request GET 'https://opentip.kaspersky.com/api/v1/search/domain?request=<domain>' --header 'x-api-key: <API token>'

Here:

Responses

200 OK

Request processed successfully.

Endpoint returns a JSON object that contains lookup results for the specified domain.

200 OK response parameters

Parameter

Type

Description

Zone

string

Color of the zone that a domain belongs to. Available values:

Red—The domain can be classified as Dangerous.

Orange—The domain can be classified as Not trusted and may host malicious objects.

Yellow—The domain is classified as Adware and other (Adware, Pornware, and other programs).

Grey—No data or not enough information is available for the domain.

Green—The domain has the Good or No threats detected status. The No threats detected status is applied if the domain was not classified by Kaspersky, but it was previously scanned and/or analyzed, and no threats were detected at the time of the analysis.

DomainGeneralInfo

object

General information about the requested domain.

FilesCount

integer

Number of known malicious files.

UrlsCount

integer

Number of known malicious web addresses.

HitsCount

integer

Number of IP addresses related to the domain.

Domain

string

Name of the requested domain.

Ipv4Count

integer

Number of IP addresses (IPv4) for the requested domain.

Categories

Array of strings

Categories of the requested domain.

CategoriesWithZone

Array of objects

Categories of the requested domain and zones that the category belongs to:

Name—Category name.

Zone—Color of the category's zone (Red or Yellow).

DomainWhoIsInfo

object

WHOIS information about the requested domain.

DomainName

string

Name of the requested domain.

Created

string <date-time>

Date when the requested domain was registered.

Updated

string <date-time>

Date when registration information about the requested domain was last updated.

Expires

string <date-time>

Expiration date of the requested domain.

NameServers

Array of strings

Name servers of the requested domain.

Contacts

Array of strings

Contact information for the owner of the requested domain.

Registrar

object

Information about the requested domain's registrar:

Info—Name of the requested domain's registrar.

IanaId—IANA ID of the requested domain's registrar.

DomainStatus

Array of strings

Statuses of the requested domain.

RegistrationOrganization

string

Name of the registration organization.

400 Bad Request

Request not processed: incorrect query.

Make sure you enter the correct parameter, and then try to run the query again.

401 Unauthorized

Request not processed: user authentication failed.

Make sure you enter the correct credentials, and then try to run the query again.

403 Forbidden

Request not processed: quota or request limit exceeded.

Check your quota and limitations, and try to run the query again later.

404 Not Found

Request not processed: requested object lookup results not found.

Make sure the specified object is correct, and then run the query again.

Page top
[Topic DomainLookupAPI]

Looking up a web address

Expand all | Collapse all

Kaspersky Threat Intelligence Portal provides an API for looking up a web address.

Request

Request method: GET

Endpoint: https://opentip.kaspersky.com/api/v1/search/url

Query parameter: request—Web address that you want to investigate.

cURL command sample:

curl --request GET 'https://opentip.kaspersky.com/api/v1/search/url?request=<web address>' --header 'x-api-key: <API token>'

Here:

Responses

200 OK

Request processed successfully.

Endpoint returns a JSON object that contains lookup results for the specified domain.

200 OK response parameters

Parameter

Type

Description

Zone

string

Color of the zone that a web address belongs to. Available values:

Red—The web address can be classified as Dangerous.

Orange—The web address can be classified as Not trusted and may host malicious objects.

Yellow—The web address is classified as Adware and other (Adware, Pornware, and other programs).

Grey—No data or not enough information is available for the web address.

Green—The web address has the Good or No threats detected status. The No threats detected status is applied if the web address was not classified by Kaspersky, but it was previously scanned and/or analyzed, and no threats were detected at the time of the analysis.

UrlGeneralInfo

object

General information about the requested web address.

Url

string

Requested web address.

Host

string

Name of the upper-level domain of the requested web address.

Ipv4Count

integer

Number of IP addresses (IPv4) for the requested web address.

FilesCount

integer

Number of known malicious files.

Categories

Array of strings

Categories of the requested web address. If the web address does not belong to any defined categories, the General category is displayed.

CategoriesWithZone

Array of objects

Categories of the requested web address and zones that the category belongs to:

Name—Category name.

Zone—Color of the category's zone (Red or Yellow). If the web address does not belong to any defined categories, the General category is displayed.

UrlDomainWhoIs

object

WHOIS information about the requested web address.

DomainName

string

Name of the domain of the requested web address.

Created

string <date-time>

Date when the requested web address was registered.

Updated

string <date-time>

Date when registration information about the domain for the requested web address was last updated.

Expires

string <date-time>

Expiration date of the prepaid domain registration term.

NameServers

Array of strings

List of name servers of the domain for the requested web address.

Contacts

Array of strings

Contact information for the owner of the requested web address.

Registrar

object

Information about the domain's registrar:

Info—Name of the domain's registrar.

IanaId—IANA ID of the domain's registrar.

DomainStatus

Array of strings

Statuses of the domain for the requested web address.

RegistrationOrganization

string

Name of the registration organization.

400 Bad Request

Request not processed: incorrect query.

Make sure you enter the correct parameter, and then try to run the query again.

401 Unauthorized

Request not processed: user authentication failed.

Make sure you enter the correct credentials, and then try to run the query again.

403 Forbidden

Request not processed: quota or request limit exceeded.

Check your quota and limitations, and try to run the query again later.

404 Not Found

Request not processed: requested object lookup results not found.

Make sure the specified object is correct, and then run the query again.

414 URI Too Long

Request not processed: Web address length exceeds 2000 characters.

For a web address, its length is limited to a maximum of 2000 characters. Web addresses with a length exceeding 2000 characters cannot be requested by using the RESTful API.

Specify another web address, and then run the query.

Page top
[Topic URLLookupAPI]

Getting basic file analysis report

Expand all | Collapse all

Kaspersky Threat Intelligence Portal provides an API for sending a file for analysis in the Sandbox and getting a basic report.

Request

Request method: POST

Endpoint: https://opentip.kaspersky.com/api/v1/scan/file

Query parameter: filename—Name of the file you want to analyze.

cURL command sample:

curl --request POST 'https://opentip.kaspersky.com/api/v1/scan/file?filename=<file name>' --header 'x-api-key: <API token>' --header 'Content-Type: application/octet-stream' --data-binary '@<path to file>'

Here:

Responses

200 OK

Request processed successfully.

Endpoint returns a JSON object that contains basic information about the analyzed file.

File analysis may take several minutes, therefore some sections may be not included in the method response. You can obtain the updated results by using the getresult/file method.

200 OK response parameters

Parameter

Type

Description

Zone

string

Color of the zone that a file belongs to. Available values:

Red—The file can be classified as Malware.

Yellow—The file is classified as Adware and other (Adware, Pornware, and other programs).

Green—The file has the Clean or No threats detected status. The No threats detected status is applied if the file was not classified by Kaspersky, but it was previously scanned and/or analyzed, and no threats were detected at the time of the analysis.

Grey—No data or not enough information is available for the file.

FileGeneralInfo

object

General information about the analyzed file.

FileStatus

string

Status of the submitted file (Malware, Adware and other, Clean, No threats detected, or Not categorized).

Sha1

string

SHA1 hash of the analyzed file.

Md5

string

MD5 hash of the analyzed file.

Sha256

string

SHA256 hash of the analyzed file.

FirstSeen

string <date-time>

Date and time when the analyzed file was detected by Kaspersky expert systems for the first time.

LastSeen

string <date-time>

Date and time when the analyzed file was detected by Kaspersky expert systems for the last time.

Signer

string

Organization that signed the analyzed file.

Packer

string

Packer name (if available).

Size

integer

Size of the analyzed file (in bytes).

Type

string

Type of the analyzed file.

HitsCount

integer

Number of hits (popularity) of the analyzed file detected by Kaspersky expert systems. Number of hits is rounded to the nearest power of 10.

DetectionsInfo

Array of objects

Information about detected objects.

LastDetectDate

string <date-time>

Date and time when the object was last detected by Kaspersky expert systems.

DescriptionUrl

string

Link to the detected object's description in the Kaspersky threats website (if available).

Zone

string

Color of the zone that the detected object belongs to.

DetectionName

string

Name of the detected object.

DetectionMethod

string

Method used to detect the object.

DynamicDetections

Array of objects

Detects related to the analyzed file.

Zone—Color of the zone of the detected object (Red or Yellow).

Threat—Number of detected objects that belong to the zone.

400 Bad Request

Request not processed: incorrect query.

Make sure you enter the correct parameter, and then try to run the query again.

401 Unauthorized

Request not processed: user authentication failed.

Make sure you enter the correct credentials, and then try to run the query again.

413 Payload Too Large

Request not processed: file size exceeds a size limit.

To execute the file, make sure its size does not exceed 256 MB.

Page top
[Topic SubmitFileAPI]

Getting full file analysis report

Expand all | Collapse all

Kaspersky Threat Intelligence Portal provides an API for getting the full analysis results of a file previously submitted to the Sandbox in the web interface.

The full report is available only if the Get a full dynamic analysis report check box was selected while submitting the file. The check box is available after signing in with Kaspersky Account.

You can use the scan/file method to obtain the file hash (MD5, SHA1, SHA256).

Request

Request method: POST

Endpoint: https://opentip.kaspersky.com/api/v1/getresult/file

Query parameter: request—Hash for which you want to get the analysis results.

cURL command sample:

curl --request POST 'https://opentip.kaspersky.com/api/v1/getresult/file?request=<file hash> --header 'x-api-key: <API token>'

Here:

Responses

200 OK

Request processed successfully.

Endpoint returns a JSON object that contains basic information about the previously analyzed file.

200 OK response parameters

Parameter

Type

Description

Status

string

File analysis status. Available values:

in progress—The file is still being analyzed.

complete—The file analysis successfully completed.

not started—The file has not been previously submitted for analysis.

Zone

string

Color of the zone that a file belongs to. Available values:

Red—The file can be classified as Malware.

Yellow—The file is classified as Adware and other (Adware, Pornware, and other programs).

Green—The file has the Clean or No threats detected status. The No threats detected status is applied if the file was not classified by Kaspersky, but it was previously scanned and/or analyzed, and no threats were detected at the time of the analysis.

Grey—No data or not enough information is available for the file.

FileGeneralInfo

object

General information about the requested hash.

FileStatus

string

Status of the submitted file (Malware, Adware and other, Clean, No threats detected, or Not categorized).

Sha1

string

SHA1 hash of the file requested by the hash.

Md5

string

MD5 hash of the file requested by the hash.

Sha256

string

SHA256 hash of the file requested by the hash.

FirstSeen

string <date-time>

Date and time when the requested hash was detected by Kaspersky expert systems for the first time.

LastSeen

string <date-time>

Date and time when the requested hash was detected by Kaspersky expert systems for the last time.

Signer

string

Organization that signed the requested hash.

Packer

string

Packer name (if available).

Size

integer

Size of the object being investigated by the hash (in bytes).

Type

string

Type of the object being investigated by the hash.

HitsCount

integer

Number of hits (popularity) of the requested hash detected by Kaspersky expert systems. Number of hits is rounded to the nearest power of 10.

DetectionsInfo

Array of objects

Information about detected objects.

LastDetectDate

string <date-time>

Date and time when the object was last detected by Kaspersky expert systems.

DescriptionUrl

string

Link to the detected object's description in the Kaspersky threats website (if available).

Zone

string

Color of the zone that the detected object belongs to.

DetectionName

string

Name of the detected object.

DetectionMethod

string

Method used to detect the object.

DynamicAnalisysResults

object

Information about dynamic analysis results.

Detections

Array of objects

The number of detected objects with Malware (red) or Adware and other (yellow) statuses.

Zone—Color of the zone of the detected object (Red or Yellow).

Count—Number of objects that belong to the zone.

SuspiciousActivities

Array of objects

The number of suspicious activities with High (red), Medium (yellow), or Low (grey) levels.

Zone—Color of the zone of the activity (Red, Yellow, or Grey).

Count—Number of activities that belong to the zone.

ExtractedFiles

Array of objects

The number of files that were downloaded or dropped by the file during the execution process, and the proportion of files with the status of Malicious (extracted files that can be classified as malicious, in red), Adware and other (extracted files that can be classified as Not-a-virus, in yellow), Clean (extracted files that can be classified as not malicious, in green), or Not categorized (no information about the extracted files is available, in grey).

Zone—Color of the zone of the file (Red, Yellow, Green, or Grey).

Count—Number of files that belong to the zone.

NetworkActivities

Array of objects

The number of registered network interactions that the file performed during the execution process and the proportion of network interactions with the status of Dangerous (requests to resources with the Dangerous status, in red), Adware and other (requests to resources with the Adware and other status, in yellow), Good (requests to resources with the Good status, in green), or Not categorized (requests to resources with the Not categorized status, in grey).

Zone—Color of the zone of the network activity (Red, Yellow, Green, or Grey).

Count—Number of network activities that belong to the zone.

DynamicDetections

Array of objects

Detects related to the analyzed file.

Zone—Color of the zone of the detected object (Red or Yellow).

Threat—Number of detected objects that belong to the zone.

TriggeredNetworkRules

Array of objects

SNORT and Suricata rules triggered during analysis of traffic from the file.

Zone—Color of the zone of the triggered rule (Red or Yellow).

RuleName—Name of the triggered rule.

400 Bad Request

Request not processed: incorrect query.

Make sure you enter the correct parameter, and then try to run the query again.

401 Unauthorized

Request not processed: user authentication failed.

Make sure you enter the correct credentials, and then try to run the query again.

403 Forbidden

Request not processed: quota or request limit exceeded.

Check your quota and limitations, and try to run the query again later.

Page top
[Topic GetFileReport]