REST API reference

This chapter provides information about using the REST API of Kaspersky CyberTrace.

In this section

About the REST API

Accessing the REST API

Response statuses

Requests

Page top

About the REST API

This section describes the features of the Kaspersky CyberTrace REST API.

About the REST API

Kaspersky CyberTrace provides a REST API interface that you can use to perform the following actions:

Perform an indicator search.
Add new suppliers, and configure and remove suppliers that were added with the REST API.
Add, remove, and update supplier indicators for suppliers that were added with the REST API; and for InternalTI and FalsePositive suppliers.

Supported protocols

The REST API supports HTTPS protocol with basic authentication. All requests are synchronous. Kaspersky CyberTrace processes a request and returns the result in the response.

To communicate by using HTTPS, Kaspersky CyberTrace uses the certificate specified in the GUISettings > HTTPServer >SSLCertificatePath and GUISettings > HTTPServer >SSLPrivateKeyPath elements of the kl_feed_service.conf configuration file.

For more information about authentication, see Accessing the REST API.

The maximum number of processed requests is specified in the ServiceSettings > ScannersCount element of the kl_feed_service.conf configuration file.

REST API suppliers

Suppliers that were added with the REST API are different from regular suppliers. Only the suppliers that you add with the REST API can be accessed through the REST API. You cannot access all other suppliers through the REST API. In addition, the REST API provides a way to manage indicators from FalsePositive and InternalTI suppliers.

Suppliers that were added with the REST API are displayed on the Custom feeds tab. If a vendor is specified for a supplier, the supplier is displayed on the vendor tab instead. Each REST API supplier has a short description that marks it as a REST API supplier.

For suppliers that were added with the REST API, you cannot perform the following actions in Kaspersky CyberTrace Web:

Editing supplier properties.
Enabling or disabling supplier fields.
Specifying filtering rules for a supplier.
Specifying the maximum number of records in a supplier.

You can perform the following actions for suppliers that were added with the REST API in Kaspersky CyberTrace Web:

Specify actionable fields for a supplier.
Enable or disable a supplier.
Delete a supplier.

User roles and REST API

Methods that are available to a user depend on the user's role:

Users with the Administrator role can make all requests.
Users with the Analyst role can perform the indicator search.

REST API and logging

Kaspersky CyberTrace logs the following information about the REST API:

If the logging level is err and above, Kaspersky CyberTrace logs information about REST API errors.
If the logging level is info and above, Kaspersky CyberTrace logs information about all REST API requests and responses.

Page top

Accessing the REST API

This section explains how to access the Kaspersky CyberTrace REST API.

REST API endpoint

Kaspersky CyberTrace accepts requests on the endpoint which consists of the IP address of the computer with Kaspersky CyberTrace and the port specified in the GUISettings > HTTPServer > ConnectionString element of the kl_feed_service.conf configuration file.

The format of the address is:

https://%ENDPOINT%/api/%API_VERSION%/%REQUEST%

For example, if ConnectionString is 0.0.0.0:104, and the IP address of the computer with Kaspersky CyberTrace is 192.168.0.2, the lookup request must be made to the following address:

https://192.168.0.2:104/api/1.0/lookup

Request headers

Each request must have the following headers:

Accept
Response content type. This header must have the application/json value.
Authorization
This header must hold the Basic authorization string.

Basic authorization

The credentials for the Basic authorization scheme are constructed as follows:

The username and the password are combined with a colon.
For example, if a username is user, and a password is password, the string must be user:password.
The resulting string is then base64 encoded.
For the example above, the resulting string is dXNlcjpwYXNzd29yZA==.
The final authorization string is constructed by prepending the "Basic" string to the credentials string.
For the example above, the final authorization string is Basic dXNlcjpwYXNzd29yZA==.

Page top

Response statuses

This section describes Kaspersky CyberTrace REST API response statuses.

For more information about responses, see the individual request descriptions.

200 OK

This status is returned for requests that were successfully processed. The response body holds the result.

201 Created

This status is returned when an entity (a supplier or an indicator) was successfully created. The response body holds the status of the operation.

202 Partial success

This status is returned when only a subset of entities (indicators) were successfully created. The response body holds the status of the operation and information about entities that were not processed.

401 Unauthorized user

The user is not authorized, the specified user does not exist, or the password specified in the authorization header is not valid.

Examples:

A request without the Authorization header returns this status.
A request with an authorization attempt for a non-existent user account returns this status.

403 User does not have rights to this operation

A user does not have rights to perform the operation. This may happen, for example, when the license key does not include the indicator search functionality, or when a user with the Analyst role attempts to add indicators or a new supplier.

The response body may contain the error description.

404 Request not supported

The specified request or API version is not supported.

Examples:

The login request is not supported. A POST /api/1.0/login request returns this status.
The API version 8.0 is not supported. A POST /api/8.0/lookup returns this status.

405 Method Not Allowed

The specified method is not supported.

For example, the lookup request supports only the POST method. A GET /api/1.0/lookup request returns this status.

425 Kaspersky CyberTrace initializing

A request was made while Kaspersky CyberTrace is still initializing.

406 Not Acceptable

The specified data format is not supported.

For example, if the Accept header contains the application/pdf value, the response returns this status.

429 Too Many Requests

Kaspersky CyberTrace cannot process the request.

The request is rejected and is not processed. You must make another request later.

400 Bad Request

The request has an incorrect format:

Mandatory headers are not present in the request.
Request body is required, but not present.
Request body has an incorrect format.
Request body parameters have invalid values.
Request body size does not conform to the size requirements.

500 Internal Server Error

An error occurred while processing the request

The response body may contain the error description.

Page top

Requests

This section describes requests that you can make using the Kaspersky CyberTrace API, responses to these requests, and provides examples.

The requests available in the REST API are described below.

Indicator search

You can perform an indicator search with the following request:

POST /api/1.0/lookup
Performs an indicator search in the General tenant.

Managing suppliers

You can manage REST API suppliers by using the following requests:

GET /api/1.0/suppliers
Gets a list of suppliers and their statuses.
POST /api/1.0/suppliers
Adds a new supplier.
GET /api/1.0/suppliers/{supplier}
Gets information about a specified supplier.
PUT /api/1.0/suppliers/{supplier}
Updates the specified supplier information.
DELETE /api/1.0/suppliers/{supplier}
Deletes the specified supplier.

Managing indicators

You can manage indicators in REST API suppliers by using the following requests:

PUT /api/1.0/suppliers/{supplier}/indicators
Adds new indicators to a supplier and updates existing indicators.
/api/1.0/suppliers/{supplier}/indicators
Deletes the specified indicators from a supplier.

In this section

POST lookup

GET suppliers

POST suppliers

GET suppliers/{supplier}

PUT suppliers/{supplier}

DELETE suppliers/{supplier}

PUT suppliers/{supplier}/indicators

DELETE suppliers/{supplier}/indicators

Page top

POST lookup

Performs an indicator search.

Path

/api/1.0/lookup

Method

POST

Request headers

This request has the following headers.

Request headers

Name	Value	Description
`Authorization`	`string (base 64)`	Authentication string.
`Accept`	`application/json`	Response content type.
`Content-Type`	`application/json`	Request content type. You can also specify the `utf-8` charset type. For example: `Content-Type: application/json; charset=utf-8`
`Content-Length`	`integer`	Request body size, in bytes. The maximum body size for this request is 64 MB (`67108864`).

Request body

This request body contains a JSON array of objects for search. At least one object must be specified.

[{"object":"%OBJECT_VALUE%"},...{"object":"%OBJECT_VALUE%"}]

Object properties are described in the following table.

Object properties

Property	Value	Mandatory	Description
`object`	`string`	Yes	Object for search.

Request example

The following is an example of a POST lookup request.

POST https://192.0.2.57/api/1.0/lookup

Accept: application/json

Content-Type: application/json

Authorization: Basic dXNlcjpwYXNzd29yZA==

Content-Length: 81

[{"object":"http:\/\/example.com"},{"object":"C1153422C5F68E731347F6A33F791598"}]

Response headers

The response has the following headers.

Response headers

Name	Value	Description
Content-Type	`application/json`	Response content type.
Content-Length	`integer`	Response body size, in bytes.

Response body

The response body contains a JSON array of search result objects.

[

{

"object": "%OBJECT_VALUE%",

"result": "%LOOKUP_RESULT%",

"categories":

[

{

"category": "%CATEGORY_1%",

"detected_indicator": "%DETECTED_INDICATOR%",

"context":

{

"%supplier_field_1%": "%supplier_field_1_value%",

...

"%supplier_field_N%": "%supplier_field_N_value%"

}

},

...

{

"category": "%CATEGORY_N%",

"detected_indicator": "%DETECTED_INDICATOR%",

"context":

{

"%supplier_field_1%": "%supplier_field_1_value%",

...

"%supplier_field_N%": "%supplier_field_N_value%"

}

]

},

...

{

"object": "%OBJECT_VALUE%",

"result": "%LOOKUP_RESULT%",

"categories":

[

{

"category": "%CATEGORY_1%",

"detected_indicator": "%DETECTED_INDICATOR%",

"context":

{

"%supplier_field_1%": "%supplier_field_1_value%",

...

}

},

...

]

}

]

Search result object properties are described in the following table.

Search result object properties

Property	Value	Description
`object`	`string`	Object that was searched.
`result`	`string`	Search result. The following values are possible: detected A match with indicators was detected. not detected No matches with indicators were detected. error An error occurred during the search.
`categories`	`array`	An array of category objects, as described below. This property is included if result is `"detected"`.
`reason`	`string`	Cause of the error.

Properties of category objects are described in the following table.

Category object properties

Property	Value	Description
`category`	`string`	Detection category.
`detected_indicator`	`string`	Matched indicator.
`context`	`array`	Array of context objects.

Properties of context objects are described in the following table.

Context object properties

Property	Value	Description
`%field_name%`	`string`	The name of the property corresponds to the name of a field of a matched indicator. The value of the property contains the value of the field.

Property

Value

Description

%field_name%

string

The name of the property corresponds to the name of a field of a matched indicator.

The value of the property contains the value of the field.

Response example

The following is an example of a POST lookup request response.

НТТР/1.1 200 ОК

Date:Mon, 23 Dec 2019 09:56:10 UTC

Content-Type: application/json

Content-Length: 372

[{"object":"http:\/\/example.com","result":"not detected"},

{"object":"C1153422C5F68E731347F6A33F791598","result":"detected", "detects":

[{"category":"KL_Malicious_Hash","detected_indicator":"C1153422C5F68E731347F6A33F791598","context":{"first_seen":"10.07.2015 23:53","threat":"Trojan.Win32.Generic"}}]},

{"object":"http:\/\/error.example.com","result":"error","reason":"Limit on the lookup operation exceeded"}

]

Error responses

For more information about possible response statuses, see Response statuses.

An error response contains a JSON object with the error description.

[

{

"status": "%ERROR%"

}

]

Error object properties are described in the following table.

Error object properties

Property	Value	Description
`status`	`string`	Error description.
`reason`	`string`	Cause of the error.

Error response example

The following is an example of a POST lookup error response.

НТТР/1.1 500 Internal Server Error

Date:Mon, 23 Dec 2019 09:56:10 UTC

Content-Type: application/json

Content-Length: 75

[{"status": "An error occurred while performing the lookup of indicators", "reason": "The database is not available"}]

Page top

GET suppliers

Gets a list of suppliers and their statuses.

Only suppliers that were created with the REST API, FalsePositive, and InternalTI suppliers are returned.

Path

/api/1.0/suppliers

Method

GET

Request headers

This request has the following headers.

Request headers

Name	Value	Description
`Authorization`	`string (base 64)`	Authentication string.
`Accept`	`application/json`	Response content type.

Request body

This request has an empty body.

Request example

The following is an example of a GET suppliers request.

GET https://192.0.2.57/api/1.0/suppliers

Accept: application/json

Authorization: Basic dXNlcjpwYXNzd29yZA==

Response headers

The response has the following headers.

Response headers

Name	Value	Description
Content-Type	`application/json`	Response content type.
Content-Length	`integer`	Response body size, in bytes.

Response body

The response body contains a JSON array of supplier status objects.

[

{

"name":"%SUPPLIER_NAME_1%",

"status": "%SUPPLIER_STATUS%"

},

...

{

"name":"%SUPPLIER_NAME_N%",

"status": "%SUPPLIER_STATUS%"

}

]

Supplier status object properties are described in the following table.

Supplier status object properties

Property

Value

Description

name

string

Name of the supplier.

status

string

Status of the supplier.

This value is enabled if the supplier is enabled.

This value is disabled if the supplier is disabled.

Response example

The following is an example of a GET suppliers request response.

НТТР/1.1 200 ОК

Date:Mon, 23 Dec 2019 09:56:10 UTC

Content-Type: application/json

Content-Length: 99

[

{"name":"ExampleSupplier", "status":"enabled"}, {"name":"AnotherExampleSupplier", "status":"disabled"}

]

Error responses

For more information about possible response statuses, see Response statuses.

An error response contains a JSON object with the error description.

[

{

"status": "An error occurred while getting a list of suppliers",

}

]

Error object properties are described in the following table.

Error object properties

Property	Value	Description
`status`	`string`	Error description.

Error response example

The following is an example of a GET suppliers error response.

НТТР/1.1 500 Internal Server Error

Date:Mon, 23 Dec 2019 09:56:10 UTC

Content-Type: application/json

Content-Length: 63

[{"status": "An error occurred while getting a list of suppliers"}]

Page top

POST suppliers

Adds a new supplier.

The added supplier is a REST API supplier and can be managed with REST API methods. The new supplier is enabled by default.

Path

/api/1.0/suppliers

Method

POST

Request headers

This request has the following headers.

Request headers

Name	Value	Description
`Authorization`	`string (base 64)`	Authentication string.
`Accept`	`application/json`	Response content type.
`Content-Type`	`application/json`	Request content type. You can also specify the `utf-8` charset type. For example: `Content-Type: application/json; charset=utf-8`
`Content-Length`	`integer`	Request body size, in bytes. The maximum body size for this request is 128 MB (`134217728`).

Request body

This request body contains a JSON array with a supplier object. Only one supplier object must be specified.

[

{

"name":"%SUPPLIER_NAME%",

"confidence": %SUPPLIER_CONFIDENCE%,

"retention": %SUPPLIER_RETENTION%,

"vendor": "%SUPPLIER_VENDOR%"

}

]

Supplier object properties are described in the following table.

Supplier object properties

Property	Value	Mandatory	Description
`name`	`string`	Yes	Name of the supplier. The name of the supplier must contain only Latin letters, digits, hyphens (`"-"`), and underscores (`"_"`). The space symbol (`" "`) cannot be used in the supplier name. Do not use FalsePositive or InternalTI as the supplier name, since they are reserved for the built-in supplier names of Kaspersky CyberTrace.
`confidence`	`integer`	Yes	Confidence level for indicators from this supplier. The range of values for this parameter is from `0` to `100`.
`retention`	`integer`	Yes	Retention period for indicators, in minutes. This parameter determines the timeout after which indicators from this supplier are not used in matching. The timeout is calculated from the last update of the indicator.
`vendor`	`string`	No	Supplier vendor name.

Request example

The following is an example of a POST suppliers request.

POST https://192.0.2.57/api/1.0/suppliers

Accept: application/json

Content-Type: application/json

Authorization: Basic dXNlcjpwYXNzd29yZA==

Content-Length: 91

[

{"name":"ExampleSupplier", "confidence": 90, "retention": 5000, "vendor": "ExampleVendor"}

]

Response headers

The response has the following headers.

Response headers

Name	Value	Description
Content-Type	`application/json`	Response content type.
Content-Length	`integer`	Response body size, in bytes.

Response body

The response body contains a JSON object with a status of the operation.

[

{

"status": "Supplier successfully created"

}

]

Status object properties are described in the following table.

Status object properties

Property	Value	Description
`status`	`string`	Status of the operation.

Response example

The following is an example of a POST suppliers request response.

НТТР/1.1 201 ОК

Date:Mon, 23 Dec 2019 09:56:10 UTC

Content-Type: application/json

Content-Length: 41

[{"status": "Supplier successfully created"}]

Error responses

For more information about possible response statuses, see Response statuses.

An error response contains a JSON object with the error description.

[

{

"status": "An error occurred while creating some suppliers",

"reason": "%REASON%"

}

]

Error object properties are described in the following table.

Error object properties

Property	Value	Description
`status`	`string`	Error description.
`reason`	`string`	Cause of the error.

Error response example

The following is an example of a POST suppliers error response.

ННТТР/1.1 400 Bad Request

Date:Mon, 23 Dec 2019 09:56:10 UTC

Content-Type: application/json

Content-Length: 92

[{"status": "An error occurred while creating some suppliers", "reason": "Incorrect supplier name"}]

Page top

GET suppliers/{supplier}

Gets information about a specified supplier.

Only suppliers that were created with REST API, FalsePositive, and InternalTI suppliers are returned.

Path

/api/1.0/suppliers/{supplier}

Method

GET

Request headers

This request has the following headers.

Request headers

Name	Value	Description
`Authorization`	`string (base 64)`	Authentication string.
`Accept`	`application/json`	Response content type.

Request parameters

This request has the following parameters:

Request parameters

Name	Parameter type	Description
`supplier`	Path	Name of the supplier.

Request body

This request has an empty body.

Request example

The following is an example of a GET suppliers/{supplier} request.

GET https://192.0.2.57/api/1.0/suppliers/ExampleSupplier

Accept: application/json

Authorization: Basic dXNlcjpwYXNzd29yZA==

Response headers

The response has the following headers.

Response headers

Name	Value	Description
Content-Type	`application/json`	Response content type.
Content-Length	`integer`	Response body size, in bytes.

Response body

The response body contains a JSON array with a supplier information object.

[

{

"name": "%SUPPLIER_NAME%",

"status": "%SUPPLIER_STATUS%",

"confidence": %SUPPLIER_CONFIDENCE%,

"retention": %SUPPLIER_RETENTION%,

"vendor": "%SUPPLIER_VENDOR%"

}

]

Supplier information object properties are described in the following table.

Supplier information object properties

Property	Value	Description
`name`	`string`	Name of the supplier.
`status`	`string`	Status of the supplier. This value is `enabled` if the supplier is enabled. This value is `disabled` if the supplier is disabled.
`confidence`	`integer`	Confidence level for indicators from this supplier.
`retention`	`integer`	Retention period for indicators, in minutes.
`vendor`	`string`	Supplier vendor name.

Response example

The following is an example of a GET suppliers/{supplier} request response.

НТТР/1.1 200 ОК

Date:Mon, 23 Dec 2019 09:56:10 UTC

Content-Type: application/json

Content-Length: 108

[

{name:"ExampleSupplier", "status":"enabled", "confidence": 90, "retention": 5000, "vendor": "ExampleVendor"}

]

Error responses

For more information about possible response statuses, see Response statuses.

An error response contains a JSON object with the error description.

[

{

"status": "Supplier doesn't exist",

}

]

Error object properties are described in the following table.

Error object properties

Property	Value	Description
`status`	`string`	Error description.

Error response example

The following is an example of a GET suppliers error response.

НТТР/1.1 404 Supplier doesn't exist

Date:Mon, 23 Dec 2019 09:56:10 UTC

Content-Type: application/json

Content-Length: 34

[{"status": "Supplier doesn't exist"}]

Page top

PUT suppliers/{supplier}

Updates the specified supplier information.

Only suppliers that were created with the REST API can be updated with this request.

Path

/api/1.0/suppliers/{supplier}

Method

PUT

Request headers

This request has the following headers.

Request headers

Name	Value	Description
`Authorization`	`string (base 64)`	Authentication string.
`Accept`	`application/json`	Response content type.
`Content-Type`	`application/json`	Request content type. You can also specify the `utf-8` charset type. Example: `Content-Type: application/json; charset=utf-8`
`Content-Length`	`integer`	Request body size, in bytes. The maximum body size for this request is 128 MB (`134217728`).

Request parameters

This request has the following parameters:

Request parameters

Name	Parameter type	Description
`supplier`	Path	Name of the supplier.

Request body

This request body contains a JSON array with a supplier object. Only one supplier object must be specified.

[

{

"name":"%SUPPLIER_NAME%",

"status":"%SUPPLIER_STATUS%,

"confidence": %SUPPLIER_CONFIDENCE%,

"retention": %SUPPLIER_RETENTION%,

"vendor": "%SUPPLIER_VENDOR%"

}

]

Supplier object properties are described in the following table.

Supplier object properties

Property	Value	Mandatory	Description
`name`	`string`	No	Name of the supplier.
`status`	`string`	No	Status of the supplier. This value must be `enabled` if the supplier is to be enabled. This value must be `disabled` if the supplier is to be disabled.
`confidence`	`integer`	No	Confidence level for indicators from this supplier.
`retention`	`integer`	No	Retention period for indicators, in hours. This parameter determines the period after which indicators from this supplier are not used in matching.
`vendor`	`string`	No	Supplier vendor name.

Request example

The following is an example of a PUT suppliers/{supplier} request.

PUT https://192.0.2.57/api/1.0/suppliers/ExampleSupplier

Accept: application/json

Content-Type: application/json

Authorization: Basic dXNlcjpwYXNzd29yZA==

Content-Length: 41

[

{"name":"NewName", "confidence": 90}

]

Response headers

The response has the following headers.

Response headers

Name	Value	Description
Content-Type	`application/json`	Response content type.
Content-Length	`integer`	Response body size, in bytes.

Response body

The response body contains a JSON object with a status of the operation.

[

{

"status": "Supplier info successfully updated"

}

]

Status object properties are described in the following table.

Status object properties

Property	Value	Description
`status`	`string`	Status of the operation.

Response example

The following is an example of a PUT suppliers/{supplier} request response.

НТТР/1.1 201 ОК

Date:Mon, 23 Dec 2019 09:56:10 UTC

Content-Type: application/json

Content-Length: 46

[{"status": "Supplier info successfully updated"}]

Error responses

For more information about possible response statuses, see Response statuses.

An error response contains a JSON array with the error description.

[

{

"status": "An error occurred while updating Supplier info",

"reason": "%REASON%"

}

]

Error object properties are described in the following table.

Error object properties

Property	Value	Description
`status`	`string`	Error description.
`reason`	`string`	Cause of the error.

Error response example

The following is an example of a PUT suppliers/{supplier} error response.

НТТР/1.1 404 Supplier doesn't exist

Date:Mon, 23 Dec 2019 09:56:10 UTC

Content-Type: application/json

Content-Length: 93

[{"status": "An error occurred while updating supplier info", "reason": "Supplier doesn't exist"}]

Page top

DELETE suppliers/{supplier}

Deletes the specified supplier.

Only suppliers that were created with the REST API can be deleted with this request.

Path

/api/1.0/suppliers/{supplier}

Method

DELETE

Request headers

This request has the following headers.

Request headers

Name	Value	Description
`Authorization`	`string (base 64)`	Authentication string.
`Accept`	`application/json`	Response content type.

Request parameters

This request has the following parameters:

Request parameters

Name	Parameter type	Description
`supplier`	Path	Name of the supplier.

Request body

This request has an empty body.

Request example

The following is an example of a DELETE suppliers/{supplier} request.

DELETE https://192.0.2.57/api/1.0/suppliers/ExampleSupplier

Accept: application/json

Authorization: Basic dXNlcjpwYXNzd29yZA==

Response headers

The response has the following headers.

Response headers

Name	Value	Description
Content-Type	`application/json`	Response content type.
Content-Length	`integer`	Response body size, in bytes.

Response body

The response body contains a JSON object with a status of the operation.

[

{

"status": "Supplier successfully removed"

}

]

Status object properties are described in the following table.

Status object properties

Property	Value	Description
`status`	`string`	Status of the operation.

Response example

The following is an example of a DELETE suppliers/{supplier} request response.

НТТР/1.1 201 ОК

Date:Mon, 23 Dec 2019 09:56:10 UTC

Content-Type: application/json

Content-Length: 46

[{"status": "Supplier successfully removed"}]

Error responses

For more information about possible response statuses, see Response statuses.

An error response contains a JSON object with the error description.

[

{

"status": "An error occurred while removing the supplier",

"reason": "%REASON%"

}

]

Error object properties are described in the following table.

Error object properties

Property

Value

Description

status

string

Error description.

reason

string

Cause of the error.

This property may not be present in the response.

Error response example

The following is an example of a DELETE suppliers/{supplier} error response.

ННТТР/1.1 404 Supplier doesn't exist

Date:Mon, 23 Dec 2019 09:56:10 UTC

Content-Type: application/json

Content-Length: 86

[{"status": "An error occurred while removing the supplier", "reason": "Supplier doesn't exist"}]

Page top

PUT suppliers/{supplier}/indicators

Adds new indicators to a supplier and updates existing indicators.

Only indicators from suppliers created with the REST API can be updated with this request.

Path

/api/1.0/suppliers/{supplier}/indicators

Method

PUT

Request headers

This request has the following headers.

Request headers

Name	Value	Description
`Authorization`	`string (base 64)`	Authentication string.
`Accept`	`application/json`	Response content type.
`Content-Type`	`application/json`	Request content type. You can also specify the `utf-8` charset type. Example: `Content-Type: application/json; charset=utf-8`
`Content-Length`	`integer`	Request body size, in bytes. The maximum body size for this request is 128 MB (`134217728`).

Request parameters

This request has the following parameters:

Request parameters

Name	Parameter type	Description
`supplier`	Path	Name of the supplier.

Request body

This request body contains a JSON array of indicator objects.

[

{

"indicator":"%INDICATOR_VALUE_1%",

"context":

{

"%FIELD_NAME_1%":"%FIELD_VALUE_1%",

...

"%FIELD_NAME_N%":"%FIELD_VALUE_N%"

}

},

...

{

"indicator":"%INDICATOR_VALUE_N%",

"context":

{

"%FIELD_NAME_1%":"%FIELD_VALUE_1%",

...

"%FIELD_NAME_N%":"%FIELD_VALUE_N%"

}

]

Indicator object properties are described in the following table.

Indicator object properties

Property

Value

Mandatory

Description

indicator

string

Yes

Value of the indicator.

You can specify the following indicator types:

MD5 hash
SHA1 hash
SHA256 hash
IP address
URL

context

Indicator context object

No (see description)

Indicator context.

This property must contain an indicator context object.

If you are adding indicators to the FalsePositive supplier, do not specify the context property.

Indicator context object properties are described in the following table.

Indicator context object properties

Property

Value

Mandatory

Description

%FIELD_NAME%

%FIELD_VALUE%

Yes

One or more context fields for the indicator.

The name of the property must correspond to the name of the context field of the indicator.

The value of the property must correspond to the value of the context field of the indicator.

Request example

The following is an example of a PUT suppliers/{supplier}/indicators request.

PUT https://192.0.2.57/api/1.0/suppliers/ExampleSupplier/indicators

Accept: application/json

Content-Type: application/json

Authorization: Basic dXNlcjpwYXNzd29yZA==

Content-Length: 150

[

{"indicator":"tux.example.com","context":{"ip":"192.0.2.42","name":"ExampleIndicator", "threat_level":1}},

{"indicator":"malicious.example.com"}

]

Response headers

The response has the following headers.

Response headers

Name	Value	Description
Content-Type	`application/json`	Response content type.
Content-Length	`integer`	Response body size, in bytes.

Response body

The response body contains a JSON object with a status of the operation.

[

{

"status": "All indicators were successfully added to the database"

}

]

Status object properties are described in the following table.

Status object properties

Property	Value	Description
`status`	`string`	Status of the operation.

Response example

The following is an example of a PUT suppliers/{supplier}/indicators request response.

НТТР/1.1 201 ОК

Date:Mon, 23 Dec 2019 09:56:10 UTC

Content-Type: application/json

Content-Length: 46

[{"status": "All indicators successfully added to the database"}]

Partial success response

This response is generated when not all indicators were successfully processed.

The response body contains the partial success object with the status of the operation and an array of indicator error objects:

[

{

"status": "An error occurred while adding some of the indicators to the database",

"error_indicators":[

{

"indicator": "%INDICATOR_VALUE_1%",

"reason": "%REASON%"

},

...

{

"indicator": "%INDICATOR_VALUE_N%",

"reason": "%REASON%"

}

]

}

]

Partial success object properties are described in the following table.

Partial success object properties

Property	Value	Description
`status`	`string`	Status of the operation.
`error_indicators`	Indicator error objects	Array of information about indicators that were not processed.

Indicator error object properties are described in the following table.

Indicator error object properties

Property

Value

Description

indicator

string

Indicator that was not processed.

reason

string

Cause of the error.

This property may not be present in the response.

Partial success response example

The following is an example of a partial success response for the PUT suppliers/{supplier}/indicators request.

НТТР/1.1 202 Partial success

Date:Mon, 23 Dec 2019 09:56:10 UTC

Content-Type: application/json

Content-Length: 265

[{"status": "An error occurred while adding some of the indicators to the database","error_indicators":[{"indicator":"bad\.example.com", "reason": "Invalid indicator format"},{"indicator":"bad2.example.com bad3.example.com", "reason": "Invalid indicator format"}]}]

Error responses

For more information about possible response statuses, see Response statuses.

An error response contains a JSON object with the error description.

[

{

"status": "An error occurred while adding indicators to the database",

}

]

Error object properties are described in the following table.

Error object properties

Property	Value	Description
`status`	`string`	Error description.

Error response example

The following is an example of a PUT suppliers/{supplier} error response.

ННТТР/1.1 500 Internal Server Error

Date:Mon, 23 Dec 2019 09:56:10 UTC

Content-Type: application/json

Content-Length: 73

[{"status": "An error occurred while adding indicators to the database"}]

Page top

DELETE suppliers/{supplier}/indicators

Deletes the specified indicators from a supplier.

Only indicators from suppliers created with the REST API can be deleted with this request.

Path

/api/1.0/suppliers/{supplier}/indicators

Method

DELETE

Request headers

This request has the following headers.

Request headers

Name	Value	Description
`Authorization`	`string (base 64)`	Authentication string.
`Accept`	`application/json`	Response content type.
`Content-Type`	`application/json`	Request content type. You can also specify the `utf-8` charset type. Example: `Content-Type: application/json; charset=utf-8`
`Content-Length`	`integer`	Request body size, in bytes. The maximum body size for this request is 64 MB (`67108864`).

Request parameters

This request has the following parameters:

Request parameters

Name	Parameter type	Description
`supplier`	Path	Name of the supplier.

Request body

This request body contains a JSON array of indicator objects.

[

{

"indicator":"%INDICATOR_VALUE_1%",

},

...

{

"indicator":"%INDICATOR_VALUE_N%",

}

]

Indicator object properties are described in the following table.

Indicator object properties

Property

Value

Mandatory

Description

indicator

string

Yes

An indicator that must be deleted.

You can specify the following indicator types:

MD5 hash
SHA1 hash
SHA256 hash
IP address
URL

Request example

The following is an example of a DELETE suppliers/{supplier}/indicators request.

DELETE https://192.0.2.57/api/1.0/suppliers/ExampleSupplier/indicators

Accept: application/json

Content-Type: application/json

Authorization: Basic dXNlcjpwYXNzd29yZA==

Content-Length: 77

[

{"indicator":"tux.example.com"},

{"indicator":"malicious.example.com"}

]

Response headers

The response has the following headers.

Response headers

Name	Value	Description
Content-Type	`application/json`	Response content type.
Content-Length	`integer`	Response body size, in bytes.

Response body

The response body contains a JSON object with a status of the operation.

[

{

"status": "All indicators were successfully deleted from the database"

}

]

Status object properties are described in the following table.

Status object properties

Property	Value	Description
`status`	`string`	Status of the operation.

Response example

The following is an example of a DELETE suppliers/{supplier}/indicators request response.

НТТР/1.1 201 ОК

Date:Mon, 23 Dec 2019 09:56:10 UTC

Content-Type: application/json

Content-Length: 74

[{"status": "All indicators were successfully deleted from the database"}]

Partial success response

This response is generated when not all indicators were successfully deleted.

The response body contains the partial success object with the status of the operation and an array of indicator error objects:

[

{

"status": "An error occurred while deleting some of the indicators from the database",

"error_indicators":[

{

"indicator": "%INDICATOR_VALUE_1%",

"reason": "%REASON%"

},

...

{

"indicator": "%INDICATOR_VALUE_N%",

"reason": "%REASON%"

}

]

}

]

Partial success object properties are described in the following table.

Partial success object properties

Property	Value	Description
`status`	`string`	Status of the operation.
`error_indicators`	Indicator error objects	Array of information about indicators that were not deleted.

Indicator error object properties are described in the following table.

Indicator error object properties

Property

Value

Description

indicator

string

Indicator that was not deleted.

reason

string

Cause of the error.

This property may not be present in the response.

Partial success response example

The following is an example of a partial success response for the DELETE suppliers/{supplier}/indicators request.

НТТР/1.1 202 Partial success

Date:Mon, 23 Dec 2019 09:56:10 UTC

Content-Type: application/json

Content-Length: 251

[{"status": "An error occurred while deleting some of the indicators from the database","error_indicators":[{"indicator":"bad.example.com", "reason": "Indicator doesn't exist"},{"indicator":"bad2\.example.com", "reason": "Invalid indicator format"}]}]

Error responses

For more information about possible response statuses, see Response statuses.

An error response contains a JSON object with the error description.

[

{

"status": "An error occurred while deleting indicators from the database",

}

]

Error object properties are described in the following table.

Error object properties

Property	Value	Description
`status`	`string`	Error description.

Error response example

The following is an example of a PUT suppliers/{supplier} error response.

ННТТР/1.1 500 Internal Server Error

Date:Mon, 23 Dec 2019 09:56:10 UTC

Content-Type: application/json

Content-Length: 77

[{"status": "An error occurred while deleting indicators from the database"}]

Page top

Contents

REST API reference

About the REST API

Accessing the REST API

Response statuses

Requests

POST lookup

GET suppliers

POST suppliers

GET suppliers/{supplier}

PUT suppliers/{supplier}

DELETE suppliers/{supplier}

PUT suppliers/{supplier}/indicators

DELETE suppliers/{supplier}/indicators