Package google.security.safebrowsing.v5

Индекс

Безопасный просмотр

API безопасного просмотра позволяют клиентам проверять веб-ресурсы (чаще всего URL-адреса) по постоянно обновляемым спискам небезопасных веб-ресурсов Google.

Пакетное получение хэш-списков

rpc BatchGetHashLists( BatchGetHashListsRequest ) returns ( BatchGetHashListsResponse )

Получите несколько списков хешей одновременно.

Клиенту очень часто требуется получить несколько списков хешей. Использование этого метода предпочтительнее, чем многократное использование обычного метода Get.

Это стандартный пакетный метод Get, определенный в https://google.aip.dev/231 , а HTTP-метод также называется GET.

ПолучитьHashList

rpc GetHashList( GetHashListRequest ) returns ( HashList )

Получить последнее содержимое списка хэшей. Список хэшей может быть либо списком угроз, либо списком не угроз, таким как глобальный кэш.

Это стандартный метод Get, определенный в https://google.aip.dev/131 , а метод HTTP также называется GET.

СписокХэшСписки

rpc ListHashLists( ListHashListsRequest ) returns ( ListHashListsResponse )

Список хэш-списков.

В API V5 Google никогда не удалит список хэшей, который когда-либо был возвращен этим методом. Это позволяет клиентам пропустить использование этого метода и просто жестко закодировать все необходимые им списки хэшей.

Это стандартный метод List, определенный в https://google.aip.dev/132 , а метод HTTP — GET.

ПоискХэшей

rpc SearchHashes( SearchHashesRequest ) returns ( SearchHashesResponse )

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

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

Пакетный запрос на получение хэш-списков

Запрос на получение нескольких списков хешей одновременно.

Поля
names[]

string

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

version[]

bytes

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

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

Историческая справка: в API V4 это называлось states ; теперь для ясности оно переименовано в version .

size_constraints

SizeConstraints

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

BatchGetHashListsОтвет

Ответ, содержащий несколько хэш-списков.

Поля
hash_lists[]

HashList

Списки хешей в том же порядке, что и в запросе.

ПолныйХэш

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

Поля
full_hash

bytes

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

full_hash_details[]

FullHashDetail

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

FullHashDetail

Подробная информация о совпадающем полном хэше.

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

Поля
threat_type

ThreatType

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

attributes[]

ThreatAttribute

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

GetHashListRequest

Запрос на получение списка хэшей, который может быть списком угроз или списком отсутствия угроз, например, глобальным кэшем.

Что нового в V5 : То, что раньше называлось states в V4, переименовано в version для ясности. Списки теперь именованы, типы платформ и типы записей угроз удалены. Теперь несколько списков могут иметь один и тот же тип угрозы или один список, связанный с несколькими типами угроз. В отличие от префиксов хеша переменной длины V4, которые вызывали проблемы во многих клиентских реализациях: все хеши в списке теперь имеют одну длину, что позволяет реализовать гораздо более эффективные клиентские реализации. Ограничения были упрощены, а тип сжатия удален (сжатие всегда применяется).

Поля
name

string

Обязательно. Имя этого конкретного списка хэшей. Это может быть список угроз или это может быть глобальный кэш.

version

bytes

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

Что нового в V5 : в API V4 это называлось states ; теперь для ясности это переименовано в version .

size_constraints

SizeConstraints

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

HashList

Список хэшей, идентифицированных по имени.

Поля
name

string

Имя списка хэшей. Обратите внимание, что глобальный кэш также является просто списком хэшей и на него можно ссылаться здесь.

version

bytes

Версия списка хэшей. Клиент НЕ ДОЛЖЕН манипулировать этими байтами.

partial_update

bool

Если true, это частичный diff, содержащий добавления и удаления на основе того, что уже есть у клиента. Если false, это полный список хешей.

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

Если задано значение true, клиент ДОЛЖЕН применить инкрементное обновление, применив удаления, а затем добавления.

compressed_removals

RiceDeltaEncoded32Bit

Версия индексов удаления, закодированная с помощью Rice-delta. Поскольку каждый хэш-список определенно содержит менее 2^32 записей, индексы рассматриваются как 32-битные целые числа и кодируются.

minimum_wait_duration

Duration

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

sha256_checksum

bytes

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

metadata

HashListMetadata

Метаданные о списке хешей. Это не заполняется методом GetHashList , но заполняется методом ListHashLists .

Поле объединения compressed_additions . Версия дополнений, закодированная с помощью дельта-кода Райса. Длины префиксов хеша дополнений одинаковы для всех дополнений в списке. compressed_additions может быть только одним из следующих:
additions_four_bytes

RiceDeltaEncoded32Bit

4-байтовые дополнения.

additions_eight_bytes

RiceDeltaEncoded64Bit

8-байтовые дополнения.

additions_sixteen_bytes

RiceDeltaEncoded128Bit

16-байтовые дополнения.

additions_thirty_two_bytes

RiceDeltaEncoded256Bit

32-байтовые дополнения.

HashListMetadata

Метаданные о конкретном списке хэшей.

Поля
threat_types[]

ThreatType

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

likely_safe_types[]

LikelySafeType

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

description

string

Человекочитаемое описание этого списка. Написано на английском языке.

hash_length

HashLength

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

HashLength

Длина хешей в списке хешей.

Перечисления
HASH_LENGTH_UNSPECIFIED Длина не указана.
FOUR_BYTES Каждый хеш представляет собой четырехбайтовый префикс.
EIGHT_BYTES Каждый хеш представляет собой восьмибайтовый префикс.
SIXTEEN_BYTES Каждый хеш представляет собой шестнадцатибайтовый префикс.
THIRTY_TWO_BYTES Каждый хеш представляет собой полный хеш размером тридцать два байта.

ВероятноБезопасныйТип

Типы потенциально безопасных сайтов.

Обратите внимание, что SearchHashesResponse намеренно не содержит LikelySafeType .

Перечисления
LIKELY_SAFE_TYPE_UNSPECIFIED Неизвестный.
GENERAL_BROWSING Этот сайт, скорее всего, достаточно безопасен для общего просмотра. Это также известно как глобальный кэш.
CSD Этот сайт, скорее всего, достаточно безопасен, поэтому нет необходимости запускать модели обнаружения на стороне клиента или проверки защиты паролем.
DOWNLOAD Вероятно, этот сайт достаточно безопасен, поэтому нет необходимости проверять загрузки с него.

ListHashListsRequest

Запрос на вывод списка доступных списков хэшей.

Поля
page_size

int32

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

page_token

string

Токен страницы, полученный от предыдущего вызова ListHashLists . Укажите его для получения последующей страницы.

ListHashListsОтвет

Ответ, содержащий метаданные о хэш-списках.

Поля
hash_lists[]

HashList

Списки хешей в произвольном порядке. Будут включены только метаданные о списках хешей, а не содержимое.

next_page_token

string

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

RiceDeltaEncoded128Bit

То же, что и RiceDeltaEncoded32Bit за исключением того, что кодирует 128-битные числа.

Поля
first_value_hi

uint64

Верхние 64 бита первой записи в закодированных данных (хэшах). Если поле пустое, верхние 64 бита все равны нулю.

first_value_lo

fixed64

Нижние 64 бита первой записи в закодированных данных (хэшах). Если поле пустое, нижние 64 бита все равны нулю.

rice_parameter

int32

Параметр Голомба-Райса. Этот параметр гарантированно находится в диапазоне от 99 до 126 включительно.

entries_count

int32

Количество записей, которые дельта-кодированы в закодированных данных. Если было закодировано только одно целое число, это будет ноль, и одно значение будет сохранено в first_value .

encoded_data

bytes

Закодированные дельты, закодированные с помощью кодера Голомба-Райса.

RiceDeltaEncoded256Bit

То же, что и RiceDeltaEncoded32Bit за исключением того, что кодирует 256-битные числа.

Поля
first_value_first_part

uint64

Первые 64 бита первой записи в закодированных данных (хэшах). Если поле пустое, то первые 64 бита равны нулю.

first_value_second_part

fixed64

Биты с 65 по 128 первой записи в закодированных данных (хэши). Если поле пустое, биты с 65 по 128 равны нулю.

first_value_third_part

fixed64

Биты с 129 по 192 первой записи в закодированных данных (хэши). Если поле пустое, биты с 129 по 192 равны нулю.

first_value_fourth_part

fixed64

Последние 64 бита первой записи в закодированных данных (хэшах). Если поле пустое, последние 64 бита равны нулю.

rice_parameter

int32

Параметр Голомба-Райса. Этот параметр гарантированно находится в диапазоне от 227 до 254 включительно.

entries_count

int32

Количество записей, которые дельта-кодированы в закодированных данных. Если было закодировано только одно целое число, это будет ноль, и одно значение будет сохранено в first_value .

encoded_data

bytes

Закодированные дельты, закодированные с помощью кодера Голомба-Райса.

RiceDeltaEncoded32Bit

Данные, закодированные по Райсу-Голомбу. Используется для хэшей или индексов удаления. Гарантируется, что каждый хэш или индекс здесь имеет одинаковую длину, и эта длина составляет ровно 32 бита.

Вообще говоря, если мы отсортируем все записи лексикографически, то обнаружим, что биты более высокого порядка, как правило, не меняются так часто, как биты более низкого порядка. Это означает, что если мы также возьмем смежную разницу между записями, биты более высокого порядка имеют высокую вероятность быть нулевыми. Это использует эту высокую вероятность нуля, по сути выбирая определенное количество бит; все биты более значимые, чем это, вероятно, будут нулевыми, поэтому мы используем унарное кодирование. Смотрите поле rice_parameter .

Историческая справка: кодировка Rice-delta впервые была использована в версии V4 этого API. В версии V5 были сделаны два существенных улучшения: во-первых, кодировка Rice-delta теперь доступна с префиксами хэша длиннее 4 байтов; во-вторых, закодированные данные теперь обрабатываются как big-endian, чтобы избежать дорогостоящего этапа сортировки.

Поля
first_value

uint32

Первая запись в закодированных данных (хэши или индексы) или, если был закодирован только один префикс хеша или индекс, значение этой записи. Если поле пустое, запись равна нулю.

rice_parameter

int32

Параметр Голомба-Райса. Этот параметр гарантированно находится в диапазоне от 3 до 30 включительно.

entries_count

int32

Количество записей, которые дельта-кодированы в закодированных данных. Если было закодировано только одно целое число, это будет ноль, и одно значение будет сохранено в first_value .

encoded_data

bytes

Закодированные дельты, закодированные с помощью кодера Голомба-Райса.

RiceDeltaEncoded64Bit

То же, что и RiceDeltaEncoded32Bit за исключением того, что кодирует 64-битные числа.

Поля
first_value

uint64

Первая запись в закодированных данных (хэшах) или, если был закодирован только один префикс хеша, значение этой записи. Если поле пустое, запись равна нулю.

rice_parameter

int32

Параметр Голомба-Райса. Этот параметр гарантированно находится в диапазоне от 35 до 62 включительно.

entries_count

int32

Количество записей, которые дельта-кодированы в закодированных данных. Если было закодировано только одно целое число, это будет ноль, и одно значение будет сохранено в first_value .

encoded_data

bytes

Закодированные дельты, закодированные с помощью кодера Голомба-Райса.

ПоискХэшиЗапрос

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

Он предназначен только для поиска в списках угроз и не ищет в списках, не содержащих угроз, таких как глобальный кэш.

Что нового в V5 : Клиентам не нужно указывать ClientInfo или состояния списков хэшей в своей локальной базе данных. Это сделано для улучшения конфиденциальности. Кроме того, клиентам не нужно отправлять, какие типы угроз их интересуют.

Поля
hash_prefixes[]

bytes

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

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

ПоискХэшиОтвет

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

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

Что нового в V5 : Существует разделение между FullHash и FullHashDetail . В случае, когда хэш представляет сайт с несколькими угрозами (например, как ВРЕДОНОСНОЕ ПО, так и СОЦИАЛЬНАЯ_ИНЖЕНЕРИЯ), полный хэш не нужно отправлять дважды, как в V4. Кроме того, длительность кэша была упрощена до одного поля cache_duration .

Поля
full_hashes[]

FullHash

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

cache_duration

Duration

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

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

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

РазмерОграничения

Ограничения на размеры хеш-списков.

Поля
max_update_entries

int32

Максимальный размер в количестве записей. Обновление не будет содержать больше записей, чем это значение, но возможно, что обновление будет содержать меньше записей, чем это значение. Это ДОЛЖНО быть не менее 1024. Если пропущено или равно нулю, ограничение на размер обновления не устанавливается.

max_database_entries

int32

Устанавливает максимальное количество записей, которое клиент готов иметь в локальной базе данных для списка. (Сервер МОЖЕТ заставить клиента хранить меньше этого количества записей.) Если параметр опущен или равен нулю, ограничение на размер базы данных не устанавливается.

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

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

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

Тип угрозы

Виды угроз.

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

Тип угрозы вредоносного ПО. Вредоносное ПО — это любое программное обеспечение или мобильное приложение, специально разработанное для нанесения вреда компьютеру, мобильному устройству, программному обеспечению, которое оно запускает, или его пользователям. Вредоносное ПО демонстрирует вредоносное поведение, которое может включать установку программного обеспечения без согласия пользователя и установку вредоносного программного обеспечения, такого как вирусы.

Более подробную информацию можно найти здесь .

SOCIAL_ENGINEERING

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

Более подробную информацию можно найти здесь .

UNWANTED_SOFTWARE Нежелательное ПО — тип угрозы. Нежелательное ПО — это любое ПО, которое не соответствует принципам Google в отношении ПО, но не является вредоносным ПО.
POTENTIALLY_HARMFUL_APPLICATION Потенциально опасный тип угрозы приложения , используемый Google Play Protect для Play Store .