POST lookup

Выполнение поиска индикатора.

Путь

/api/%API_VERSION%/lookup

Метод

POST

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

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

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

Имя

Значение

Описание

Authorization

string (base 64)

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

Accept

application/json

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

Content-Type

application/json

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

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

Content-Length

integer

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

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

Тело запроса

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

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

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

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

Свойство

Значение

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

Описание

object

string

Да

Объект для поиска.

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

Ниже приведен пример запроса POST lookup.

POST https://192.0.2.57/api/1.1/lookup

Accept: application/json

Content-Type: application/json

Authorization: Basic dXNlcjpwYXNzd29yZA==

Content-Length: 81

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

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

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

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

Имя

Значение

Описание

Content-Type

application/json

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

Content-Length

integer

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

Тело ответа

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

[

{

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

...

}

},

...

]

}

]

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

Свойства объекта результатов поиска

Свойство

Значение

Описание

object

string

Объект, поиск которого выполнялся.

result

string

Результат поиска.

Возможны следующие значения:

  • detected

    Обнаружено совпадение с индикаторами.

  • not detected

    Совпадений с индикаторами не обнаружено.

  • error

    Произошла ошибка во время поиска.

categories

array

Массив объектов категорий, см. описание ниже.

Это свойство включается, если result имеет значение "detected".

reason

string

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

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

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

Свойство

Значение

Описание

category

string

Категория обнаружения киберугрозы.

detected_indicator

string

Сопоставленный индикатор.

context

array

Массив объектов контекста.

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

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

Свойство

Значение

Описание

%field_name%

string

Имя свойства соответствует имени одного из полей сопоставленного индикатора.

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

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

Ниже приведен пример ответа на запрос POST lookup.

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

]

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

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

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

[

{

"status": "%ERROR%"

}

]

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

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

Свойство

Значение

Описание

status

string

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

reason

string

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

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

Ниже приведен пример ответа с ошибкой на запрос POST lookup.

НТТР/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 creating supplier", "reason": "Supplier already exists"}]

В начало