PUT suppliers/{supplier}/indicators

Добавляет новые индикаторы в источники данных об угрозах, включая источники InternalTI и FalsePositive, и обновляет существующие индикаторы.

С помощью этого запроса можно обновить индикаторы только в источниках данных, созданных с помощью REST API, а также в источниках InternalTI и FalsePositive.

Путь

/api/%API_VERSION%/suppliers/{supplier}/indicators

Метод

PUT

Заголовки запроса

Этот запрос имеет следующие заголовки.

Заголовки запроса

Имя

Значение

Описание

Authorization

string (base 64)

Строка аутентификации.

Accept

application/json

Тип содержимого ответа.

Content-Type

application/json

Тип содержимого запроса.

Также можно указать кодировку utf-8. Например: Content-Type: application/json; charset=utf-8

Content-Length

integer

Размер тела запроса в байтах.

Максимальный размер тела этого запроса составляет 128 МБ (134217728).

Параметры запроса

Этот запрос имеет следующие параметры:

Параметры запроса

Имя

Тип параметра

Описание

supplier

Путь

Имя источника данных об угрозах.

Тело запроса

Тело этого запроса содержит массив объектов индикаторов в формате JSON.

[

{

"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

string

Да

Значение индикатора.

Можно указать следующие типы индикаторов:

  • MD5 Hash
  • SHA1 Hash
  • SHA256 Hash
  • IP Address
  • URL

context

Объект контекста индикатора

Нет (см. описание)

Контекст индикатора.

Это свойство должно содержать объект контекста индикатора.

Если индикаторы добавляются к источнику данных об угрозах FalsePositive, свойство context не указывается.

tags

Объект тегов индикатора

Нет

Доступно, начиная с REST API 1.1.

Список тегов, назначенных индикатору.

Список должен содержать только те теги, которые уже есть в базе данных Kaspersky CyberTrace. Для добавления нового тега в базу данных следует использовать запрос POST tags.

Если объект тегов индикаторов отсутствует, Kaspersky CyberTrace не изменяет информацию о тегах индикаторов в базе данных.

Если передан пустой объект тегов индикаторов, Kaspersky CyberTrace снимает все теги с индикатора в базе данных. Сами теги при этом не удаляются.

При добавлении или изменении имен тегов Kaspersky CyberTrace преобразует буквы в верхний регистр.

mark_detections

boolean

Нет

Доступно, начиная с REST API 1.2.

Флажок, указывающий на то, что связанные с индикатором обнаруженные киберугрозы являются ложными срабатываниями.

Этот параметр используется только в том случае, если в пути запроса для источника данных об угрозах было указано значение FalsePositive.

При использовании REST API 1.2 включите свойство mark_detections в тело запроса. Пример запроса с параметром mark_detections приведен ниже.

Свойства объекта контекста индикатора описаны в следующей таблице.

Свойства объекта контекста индикатора

Свойство

Значение

Обязательный

Описание

%FIELD_NAME%

%FIELD_VALUE%

Да

Одно или несколько полей контекста для индикатора.

Название свойства должно соответствовать названию поля контекста индикатора.

Значение свойства должно соответствовать значению поля контекста индикатора.

Пример запроса

Ниже приведен пример запроса PUT suppliers/{supplier}/indicators.

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

]

Ниже приведен пример запроса PUT suppliers/{supplier}/indicators в случае, когда параметр mark_detections был применен к источнику данных об угрозах FalsePositive.

PUT https://192.0.2.57/api/1.2/suppliers/FalsePositive/indicators

Accept: application/json

Content-Type: application/json

Authorization: Basic dXNlcjpwYXNzd29yZA==

Content-Length: 150

[

{

"indicator":"DC212B238A5A7C0A9DF7BF298546A154",

"tags":

[

"FP"

],

"mark_detections": false

},

...

]

 

Заголовки ответа

Ответ имеет следующие заголовки.

Заголовки ответа

Имя

Значение

Описание

Content-Type

application/json

Тип содержимого ответа.

Content-Length

integer

Размер тела ответа в байтах.

Тело ответа

Тело ответа содержит объект JSON со статусом операции.

[

{

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

}

]

Свойства объекта статуса описаны в следующей таблице.

Свойства объекта статуса

Свойство

Значение

Описание

status

string

Статус операции.

Пример ответа

Ниже приведен пример ответа на запрос PUT suppliers/{supplier}/indicators.

НТТР/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"}]

Ответ о частичном успехе

Этот ответ генерируется, если успешно обработаны были не все индикаторы.

Тело ответа содержит объект частичного успеха со статусом операции и массив объектов ошибок индикатора:

[

{

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

}

]

}

]

Свойства объекта частичного успеха описаны в следующей таблице.

Свойства объекта частичного успеха

Свойство

Значение

Описание

status

string

Статус операции.

error_indicators

Объекты ошибок индикатора

Массив информации об индикаторах, которые не были обработаны.

Свойства объекта ошибки индикатора описаны в следующей таблице.

Свойства объекта ошибки индикатора

Свойство

Значение

Описание

indicator

string

Индикатор, который не был обработан.

reason

string

Причина ошибки.

Это свойство может отсутствовать в ответе.

Пример ответа о частичном успехе

Ниже приведен пример ответа о частичном успехе на запрос PUT suppliers/{supplier}/indicators.

НТТР/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"}]}]

Ответы с ошибкой

Ответы с ошибкой содержат информацию о статусе ответа.

Ответ с ошибкой содержит объект JSON с описанием ошибки.

[

{

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

}

]

Описание свойств объекта ошибки приведено в следующей таблице.

Свойства объекта ошибки

Свойство

Значение

Описание

status

string

Описание ошибки.

Пример ошибочного ответа

Ниже приведен пример ответа с ошибкой на запрос PUT suppliers/{supplier}.

HTTP/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"}]

В начало