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

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

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

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

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

Тело запроса

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

clientId*	Имя пользователя.
clientVersion*	Версия реализации.

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

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). Значение используется в параметрах запросов: Update. Обновление локальной базы списков SB: параметр state. Update. Проверка по хэшу: параметр clientStates.

checksum

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

sha256

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

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

Пример

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

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