Update. Обновление локальной базы списков Safe Browsing

Запрос возвращает частичное или полное обновление для локальной базы списков Safe Browsing. Вы можете получить обновления для одного или нескольких списков в зависимости от заданных вами параметров.

  1. Формат запроса
  2. Формат ответа
  3. Пример

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

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

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

key *

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

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

Тело запроса

{ 
  "client": {
  "clientId": "{string}",
  "clientVersion": "{string}"
  },
  "listUpdateRequests": [
    {
      "threatType": "{еnum}",
      "platformType": "{еnum}",
      "threatEntryType": "{еnum}",
      "state": "{string}",
      "constraints": {
        "supportedCompressions": ["{enum}"]
      }
    }
  ]
}
client *

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

clientId *

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

clientVersion *

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

listUpdateRequests *

Параметры, идентифицирующие локальный список Safe Browsing, который необходимо обновить. Массив объектов.

Совет. Отправьте запрос Получение списков 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 —  исполняемая программа.

state *

Текущий статус списка Safe Browsing. Соответствует значению параметра newClientState, полученному при последнем успешном обновлении списка.

Если параметр не задан, в результате запроса будет выполнена полная замена текущего списка на новый.

constraints

Дополнительные ограничения.

supportedCompressions *

Тип сжатия данных, поддерживаемый клиентом. Массив объектов.

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

  • COMPRESSION_TYPE_UNSPECIFIED— тип сжатия неизвестен.

  • RAW — строка без сжатия.

  • RICE — сжатие в кодировке Rice-Golomb.

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

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

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

{
  "listUpdateResponses": [
    {
      "threatType": "{еnum}",
      "threatEntryType": "{еnum}",
      "platformType": "{еnum}",
      "responseType" : "{еnum}",
      "additions": [
        {
          "compressionType": "{еnum}",
          "rawHashes": {
            "prefixSize": "{number}",
            "rawHashes": "{string}"
          },
          "riceHashes": {
            "firstValue": "{string}",
            "riceParameter": "{number}",
            "numEntries": "{number}",
            "encodedData": "{string}"
          } 
        }
      ],
      "removals": [
        { 
          "compressionType": "{еnum}",
          "rawIndices": {
            "indices": [
              "{number}"
            ] 
          },
          "riceIndices": {
            "firstValue": "{string}",
            "riceParameter": "{number}",
            "numEntries": "{number}",
            "encodedData": "{string}"
          }
        }
      ],
      "newClientState": "{string}",
      "checksum": {
        "sha256": "{string}"
      }     
    }
  ],
  "minimumWaitDuration": "{string}"
}
listUpdateResponses

Параметры обновленного списка Safe Browsing. Массив объектов.

threatType *

Вид угрозы.

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

  • THREAT_TYPE_UNSPECIFIED —  неизвестная угроза.

  • MALWARE —  вредоносное программное обеспечение.

  • SOCIAL_ENGINEERING —  угрозы социальной инженерии.

  • UNWANTED_SOFTWARE —  нежелательное программное обеспечение.

  • POTENTIALLY_HARMFUL_APPLICATION —  потенциально опасное приложение.

threatEntryType *

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

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

  • THREAT_ENTRY_TYPE_UNSPECIFIED —  тип неизвестен.

  • URL —  URL.

  • EXECUTABLE —  исполняемая программа.

platformType *

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

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

  • PLATFORM_TYPE_UNSPECIFIED —  платформа неизвестна.

  • WINDOWS —  Windows.

  • LINUX —  Linux.

  • ANDROID —  Android.

  • OSX —  OS X.

  • IOS —  iOS.

  • ANY_PLATFORM —  минимум одна платформа из списка.

  • ALL_PLATFORMS —  все платформы.

  • CHROME —  Chrome.

responseType

Тип обновления. Возможные значения:

  • RESPONSE_TYPE_UNSPECIFIED — тип обновления неизвестен.

  • FULL_UPDATE — полная замена текущего списка на новый. Выполняется, если в запросе не был задан параметр state , а также если список в локальной базе сильно устарел или поврежден.

  • PARTIAL_UPDATE — частичное обновление локального списка.

additions

Записи, которые следует добавить в локальный список. Параметр возвращается при полном или частичном обновлении списка. Массив объектов.

compressionType

Тип сжатия данных.

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

  • COMPRESSION_TYPE_UNSPECIFIED— тип сжатия неизвестен.

  • RAW — строка без сжатия.

  • RICE — сжатие в кодировке Rice-Golomb.

rawHashes

Хэши SHA-256 произвольной длины.

Параметр возвращается, если сжатие не применялось ("compressionType": "RAW").

prefixSize

Длина хэш-префикса в байтах. Диапазон значений — от 4 (минимальное значение префикса) до 32 (полный хэш) байт.

rawHashes

Хэши в формате Base64. Записаны в одной строке в лексикографическом порядке.

riceHashes

Минимальные (4 байта) префиксы хэшей SHA-256, сжатые с использованием кодировки Rice-Golomb.

Параметр возвращается, если "compressionType": "RICE".

firstValue

Смещение первой записи. Если при обновлении списка добавляется только одна запись, возвращается значение этой записи.

riceParameter

Параметр Golomb-Rice. Возможные значения — число в промежутке от 2 до 28.

Не возвращается, если "numEntries": 0.

numEntries

Количество добавляемых записей. Если при обновлении списка добавлена только одна запись, значение параметра равно 0.

encodedData

Дельты, полученные в результате сжатия Golomb-Rice. Строка в кодировке base64.

removals

Записи, которые следует удалить из локального списка. Параметр возвращается только при частичном обновлении списка. Массив объектов.

compressionType

Тип сжатия данных.

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

  • COMPRESSION_TYPE_UNSPECIFIED— тип сжатия неизвестен.

  • RAW — строка без сжатия.

  • RICE — сжатие в кодировке Rice-Golomb.

rawIndices

Параметр возвращается, если сжатие не применялось ("compressionType": "RAW").

indices

Позиции подлежащих удалению хэшей в сортированном списке всех хэшей. Массив объектов.

riceIndices

Параметр возвращается, если "compressionType": "RICE".

firstValue

Смещение первой записи. Если для обновления следует удалить только одну запись, возвращается значение этой записи.

riceParameter

Параметр Golomb-Rice. Возможные значения — число в промежутке от 2 до 28.

Не возвращается, если "numEntries": 0.

numEntries

Количество удаляемых записей. Если для обновления следует удалить только одну запись, значение параметра равно 0.

encodedData

Дельты, полученные в результате сжатия Golomb-Rice. Строка в кодировке base64.

newClientState
Статус локального списка Safe Browsing после обновления (в кодировке base64). Значение используется в параметрах запросов:
checksum

Ожидаемая контрольная сумма локального списка после обновления. Если значение ожидаемой контрольной суммы не соответствует реальной, отмените обновление и повторно выполните запрос Update. Обновление локальной базы списков Safe Browsing.

Примечание. При повторной отправке запроса учитывайте значение параметра minimumWaitDuration.
sha256

Значение контрольной суммы — перечень всех хэшей SHA-256 в обновленном списке Safe Browsing. Строка в кодировке base64.

minimumWaitDuration

Минимальное время в секундах до отправки следующего запроса на обновление списков Safe Browsing. Задается в формате "minimumWaitDuration": "<время>s". Допускается до девяти знаков после запятой.

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

Пример

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

https://sba.yandex.net/v4/threatListUpdates:fetch?key=2f8...8ea

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

{
  "client": {
    "clientId": "client_name",
    "clientVersion": "1.1.1"
  },
  "listUpdateRequests": [
    {
      "threatType": "MALWARE",
      "platformType": "ANY_PLATFORM",
      "threatEntryType": "URL",
      "state": "",
      "constraints": {
        "supportedCompressions": ["RAW"]
      }
    }
  ]
}

Ответ:

{
  "listUpdateResponses": [
    {
      "responseType": "FULL_UPDATE",
      "threatType": "MALWARE",
      "newClientState": "NjU3OTRhNzM2MTU4NGU...NTk2ZTZiN=",
      "checksum": {
        "sha256": "cJtIDwizkuJigkPe+uax+1ZYAXI6zP/2NH60/bjp6oY="
      },
      "threatEntryType": "URL",
      "additions": [
        {
          "compressionType": "RAW",
          "rawHashes": {
            "prefixSize": 8,
            "rawHashes": "BpxeY80IjdgMk9zDOTrDdA8tAP...uDTeqvchw=="
          }
        },
        {
          "compressionType": "RAW",
          "rawHashes": {
            "prefixSize": 4,
            "rawHashes": "AAAbtwAAKNYAAD1lAAD7RgABjYMAA...F4ledReTNRUXliXg=="
          }
        },
        {
          "compressionType": "RAW",
          "rawHashes": {
            "prefixSize": 7,
            "rawHashes": "BUI8ZWf1VQWf2ulg27kKW7JaaHHsD7UhE5sBzBit7mQ977U1wQBFu00wTXuBOf1OHQ=="
          }
        }
      ],
      "platformType": "ANY_PLATFORM"
    }
  ],
  "minimumWaitDuration": "300.00s"
}