Method: hashes.search

Найдите полные хеши, соответствующие указанным префиксам.

Это настраиваемый метод, как определено https://google.aip.dev/136 (настраиваемый метод относится к этому методу, имеющему настраиваемое имя в общей номенклатуре разработки API Google; он не относится к использованию настраиваемого метода HTTP).

HTTP-запрос

GET https://safebrowsing.googleapis.com/v5alpha1/hashes:search

URL-адрес использует синтаксис транскодирования gRPC .

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

Параметры
hashPrefixes[]

string ( bytes format)

Необходимый. Хэш-префиксы, которые необходимо найти. Клиенты НЕ ДОЛЖНЫ отправлять более 1000 хэш-префиксов. Однако после процедуры обработки URL-адреса клиентам НЕ ДОЛЖНО отправляться более 30 хэш-префиксов.

В настоящее время длина каждого хеш-префикса должна составлять ровно 4 байта. В будущем это МОЖЕТ быть смягчено.

Строка в кодировке Base64.

filter

string

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

Фильтр задается с использованием языка общих выражений Google, который можно найти по адресу https://github.com/google/cel-spec вместе с общими примерами. Вот несколько конкретных примеров, которые можно здесь использовать:

Фильтр "threatType == ThreatType.SOCIAL_ENGINEERING" требует, чтобы в FullHashDetail тип угрозы был SOCIAL_ENGINEERING . Идентификатор "threatType" относится к текущему типу угрозы. Идентификатор "ThreatType" относится к коллекции всех возможных типов угроз.

Фильтр "threatType in [ ThreatType.UNWANTED_SOFTWARE, ThreatType.MALWARE ]" требует, чтобы тип угрозы был UNWANTED_SOFTWARE или MALWARE .

Тело запроса

Тело запроса должно быть пустым.

Тело ответа

Ответ вернулся после поиска хэшей угроз.

Если ничего не найдено, сервер вернет статус ОК (код состояния HTTP 200) с пустым полем fullHashes , а не возвратит статус NOT_FOUND (код состояния HTTP 404).

Что нового в V5 : существует разделение между FullHash и FullHashDetail . В случае, когда хэш представляет сайт, имеющий несколько угроз (например, MALWARE и SOCIAL_ENGINEERING), полный хэш не нужно отправлять дважды, как в версии 4. Кроме того, продолжительность кэша была упрощена до одного поля cacheDuration .

В случае успеха тело ответа содержит данные следующей структуры:

JSON-представление 
{
  "fullHashes": [
    {
      object (FullHash)
    }
  ],
  "cacheDuration": string
}
Поля
fullHashes[]

object ( FullHash )

Неупорядоченный список. Неупорядоченный список найденных полных хешей.

cacheDuration

string ( Duration format)

Продолжительность кэша на стороне клиента. Клиент ДОЛЖЕН добавить эту продолжительность к текущему времени, чтобы определить срок действия. Затем срок действия применяется к каждому префиксу хеша, запрошенному клиентом в запросе, независимо от того, сколько полных хешей возвращается в ответе. Даже если сервер не возвращает полных хешей для определенного префикса хэша, этот факт ДОЛЖЕН также кэшироваться клиентом.

Если и только если поле fullHashes пусто, клиент МОЖЕТ увеличить cacheDuration , чтобы определить новый срок действия, который позже, чем указанный сервером. В любом случае увеличенная длительность кэша не должна превышать 24 часов.

Важно: клиент НЕ ДОЛЖЕН предполагать, что сервер вернет одинаковую продолжительность кэша для всех ответов. Сервер МОЖЕТ выбирать разную продолжительность кэширования для разных ответов в зависимости от ситуации.

Длительность в секундах, содержащая до девяти дробных цифр и оканчивающаяся на « s ». Пример: "3.5s" .

FullHash

Полный хеш, идентифицированный с одним или несколькими совпадениями.

JSON-представление 
{
  "fullHash": string,
  "fullHashDetails": [
    {
      object (FullHashDetail)
    }
  ]
}
Поля
fullHash

string ( bytes format)

Соответствующий полный хеш. Это хеш SHA256. Длина будет ровно 32 байта.

Строка в кодировке Base64.

fullHashDetails[]

object ( FullHashDetail )

Неупорядоченный список. Повторяющееся поле, определяющее детали, относящиеся к этому полному хешу.

FullHashDetail

Подробности о соответствующем полном хеше.

Важное примечание о прямой совместимости: новые типы угроз и атрибуты угроз могут быть добавлены сервером в любое время; эти дополнения считаются незначительными изменениями версии. Политика Google не раскрывает второстепенные номера версий в API (политику управления версиями см. на странице https://cloud.google.com/apis/design/versioning ), поэтому клиенты ДОЛЖНЫ быть готовы получать сообщения FullHashDetail , содержащие значения перечисления ThreatType или ThreatAttribute . значения перечисления, которые клиент считает недействительными. Таким образом, ответственность за проверку правильности всех значений перечислений ThreatType и ThreatAttribute лежит на клиенте; если какое-либо значение считается недействительным, клиент ДОЛЖЕН игнорировать все сообщение FullHashDetail .

JSON-представление 
{
  "threatType": enum (ThreatType),
  "attributes": [
    enum (ThreatAttribute)
  ]
}
Поля
threatType

enum ( ThreatType )

Тип угрозы. Это поле никогда не будет пустым.

attributes[]

enum ( ThreatAttribute )

Неупорядоченный список. Дополнительные атрибуты этих полных хешей. Это может быть пусто.

Атрибут угрозы

Атрибуты угроз. Эти атрибуты могут придавать дополнительное значение конкретной угрозе, но не влияют на тип угрозы. Например, атрибут может указывать более низкую достоверность, тогда как другой атрибут может указывать более высокую достоверность. В будущем могут быть добавлены дополнительные атрибуты.

Перечисления
THREAT_ATTRIBUTE_UNSPECIFIED Неизвестный атрибут. Если это возвращается сервером, клиент должен вообще игнорировать включающий FullHashDetail .
CANARY Указывает, что ThreatType не следует использовать для принудительного применения.
FRAME_ONLY Указывает, что ThreatType следует использовать только для принудительного применения к кадрам.