Lookup. Проверка по URL

Запрос позволяет узнать, содержатся ли проверяемые URL в списках Safe Browsing, размещенных на сервере Яндекса. Если URL ресурса найден хотя бы в одном из списков, возвращается информация об угрозе, которую ресурс представляет для пользователя.

Вы можете отправить на проверку несколько URL в одном запросе.

Формат запроса

POST https://sba.yandex.net/v4/threatMatches:find
 ? key=<API-ключ>

key *

Значение API-ключа.

^* Обязательный параметр

Тело запроса

{
  "client": {
    "clientId": "{string}",
    "clientVersion": "{string}"
  },
  "threatInfo": {
    "threatTypes": ["{enum}"],
    "platformTypes": ["{enum}"],
    "threatEntryTypes": ["{enum}"],
    "threatEntries": [
      {"url": "{string}"}
    ]
  }
}

client

Данные пользователя API Safe Browsing. Используются для идентификации запросов, сделанных от его имени.

clientId

Имя пользователя.

clientVersion

Версия реализации.

threatInfo

Параметры списков Safe Browsing и проверяемые ресурсы.

threatTypes

Вид угрозы. Массив объектов.

Возможные значения:

THREAT_TYPE_UNSPECIFIED — неизвестная угроза.
MALWARE — вредоносное программное обеспечение.
SOCIAL_ENGINEERING — угрозы социальной инженерии.
UNWANTED_SOFTWARE — нежелательное программное обеспечение.
POTENTIALLY_HARMFUL_APPLICATION — потенциально опасное приложение.

platformTypes

Платформа. Массив объектов.

Возможные значения:

PLATFORM_TYPE_UNSPECIFIED — платформа неизвестна.
WINDOWS — Windows.
LINUX — Linux.
ANDROID — Android.
OSX — OS X.
IOS — iOS.
ANY_PLATFORM — минимум одна платформа из списка.
ALL_PLATFORMS — все платформы.
CHROME — Chrome.

threatEntryTypes

Тип объекта, который представляет угрозу. Массив объектов.

Возможные значения:

THREAT_ENTRY_TYPE_UNSPECIFIED — тип неизвестен.
URL — URL.
EXECUTABLE — исполняемая программа.

threatEntries

Проверяемые ресурсы. Массив объектов. Максимальное количество — 500.

url

URL в формате: http:// или https://.

^*Обязательный параметр

Формат ответа приведен ниже. Порядок следования и наличие элементов не гарантируется. В ответе могут присутствовать служебные параметры, которые не описаны в документе.

Формат ответа

Если ни один из проверяемых URL не обнаружен в списках Safe Browsing, тело ответа возвращается пустым. Если совпадения есть, ответ содержит подробную информацию об опасности, представляемой каждым из найденных ресурсов.

{
  "matches": [
    {
      "threatType": "{еnum}",
      "platformType": "{еnum}",
      "threatEntryType": "{еnum}",
      "threat": {
        "url": "{string}"
      },
      "cacheDuration": "{string}"
    }
  ]
}

matches

Информация о ресурсах, найденных в списках Safe Browsing. Массив объектов.

threatType

Вид угрозы.

Возможные значения:

THREAT_TYPE_UNSPECIFIED — неизвестная угроза.
MALWARE — вредоносное программное обеспечение.
SOCIAL_ENGINEERING — угрозы социальной инженерии.
UNWANTED_SOFTWARE — нежелательное программное обеспечение.
POTENTIALLY_HARMFUL_APPLICATION — потенциально опасное приложение.

platformType

Платформа, которая подвергается угрозе.

Возможные значения:

PLATFORM_TYPE_UNSPECIFIED — платформа неизвестна.
WINDOWS — Windows.
LINUX — Linux.
ANDROID — Android.
OSX — OS X.
IOS — iOS.
ANY_PLATFORM — минимум одна платформа из списка.
ALL_PLATFORMS — все платформы.
CHROME — Chrome.

threatEntryType

Тип объекта, который представляет угрозу.

Возможные значения:

THREAT_ENTRY_TYPE_UNSPECIFIED — тип неизвестен.
URL — URL.
EXECUTABLE — исполняемая программа.

threat

Ресурс, представляющий угрозу.

url

URL в формате: http:// или https://.

cacheDuration

Время хранения в кэше информации об угрозе, которую ресурс представляет для пользователя. Задается в секундах в формате "<время>s".

^*Обязательный параметр

Пример

Адрес запроса:

https://sba.yandex.net/v4/threatMatches:find?key=2f8...8ea

Тело запроса:

{
  "client": {
    "clientId": "{client_name}",
    "clientVersion": "{1.1.1}"
  },
  "threatInfo": {
    "threatTypes": ["MALWARE", "SOCIAL_ENGINEERING"],
    "platformTypes": ["WINDOWS"],
    "threatEntryTypes": ["URL"],
    "threatEntries": [
      {"url": "http://malware-driveby.test.safebrowsing.yandex"}
    ]
  }
}

Ответ:

{
  "matches": [
    {
      "threatType": "MALWARE",
      "threatEntryType": "URL",
      "platformType": "WINDOWS",
      "threat": {
        "url": "http://malware-driveby.test.safebrowsing.yandex"
      },
      "cacheDuration": "1200.00s"
    }
  ]
}