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

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

Фильтр задается с использованием языка выражений Google Common Expression Language, который можно найти по адресу 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 .

Текст запроса

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

Ответный текст

Ответ был получен после поиска по хэшам угроз.

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

Что нового в версии 5 : Разделение между FullHash и FullHashDetail . В случае, когда хеш представляет сайт, содержащий несколько угроз (например, как вредоносное ПО, так и социальная инженерия), полный хеш не нужно отправлять дважды, как в версии 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 следует использовать только для принудительного применения к кадрам.