PUT suppliers/{supplier}/indicators

Adds new indicators to a supplier, including InternalTI and FalsePositive suppliers, and updates existing indicators.

Only indicators from suppliers created with the REST API, as well as from InternalTI and FalsePositive suppliers, can be updated with this request.

Path

/api/%API_VERSION%/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%"

},

"tags":

[

"%TAG_NAME_1%",

...

"%TAG_NAME_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.

tags

Indicator tags object

No

Available starting with REST API 1.1.

List of tags assigned to the indicator.

The list must contain only the tags that already exist in the Kaspersky CyberTrace database. To add a new tag to the database, use the POST tags request.

If the indicator tags object is missing, Kaspersky CyberTrace does not change information about indicator tags in the database.

If the indicator tags object is empty, Kaspersky CyberTrace removes all tags from the indicator in the database. Kaspersky CyberTrace does not delete the tags themselves.

When adding or changing tag names, Kaspersky CyberTrace converts letters to uppercase.

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.1/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},"tags":["OSINT", "EXAMPLE"]},

{"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

An error response contains information about the response status.

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