Package google.security.safebrowsing.v5alpha1

Индекс

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

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

BatchGetHashLists

rpc BatchGetHashLists( BatchGetHashListsRequest ) returns ( BatchGetHashListsResponse )

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

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

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

GetHashList

rpc GetHashList( GetHashListRequest ) returns ( HashList )

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

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

ListHashLists

rpc ListHashLists( ListHashListsRequest ) returns ( ListHashListsResponse )

Списки хэшей.

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

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

SearchHashes

rpc SearchHashes( SearchHashesRequest ) returns ( SearchHashesResponse )

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

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

SearchUrls

rpc SearchUrls( SearchUrlsRequest ) returns ( SearchUrlsResponse )

Поиск URL-адресов, соответствующих известным угрозам. Проверяется каждый URL-адрес, а также его суффикс хоста и префикс пути (до ограниченной глубины). Это означает, что ответ может содержать URL-адреса, которые не были включены в запрос, но являются выражениями запрошенных URL-адресов.

BatchGetHashListsRequest

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

Поля
names[]

string

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

version[]

bytes

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

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

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

size_constraints

SizeConstraints

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

BatchGetHashListsResponse

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

Поля
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

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

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

Поля
name

string

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

version

bytes

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

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

size_constraints

SizeConstraints

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

HashList

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

Поля
name

string

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

version

bytes

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

partial_update

bool

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

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

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

compressed_removals

RiceDeltaEncoded32Bit

Версия индексов удаления, закодированная с помощью дельта-кода Райса. Поскольку каждый хеш-список определённо содержит менее 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 . Укажите его для получения следующей страницы.

ListHashListsResponse

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

Поля
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 .

Историческая справка: кодирование Райса-дельта впервые было использовано в версии 4 этого API. В версии 5 были внесены два существенных улучшения: во-первых, кодирование Райса-дельта теперь доступно для хеш-префиксов длиной более 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

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

SearchHashesRequest

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

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

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

Поля
hash_prefixes[]

bytes

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

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

filter

string

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

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

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

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

SearchHashesResponse

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

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

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

Поля
full_hashes[]

FullHash

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

cache_duration

Duration

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

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

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

SearchUrlsRequest

Запрос, который отправляет клиент для поиска угроз, соответствующих указанным URL-адресам.

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

Поля
urls[]

string

Обязательно. URL-адреса для поиска. Клиенты НЕ ДОЛЖНЫ отправлять более 50 URL-адресов.

SearchUrlsResponse

Ответ возвращен после поиска угроз, соответствующих указанным URL-адресам.

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

Поля
threats[]

ThreatUrl

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

cache_duration

Duration

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

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

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

Ограничения по размеру

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

Поля
max_update_entries

int32

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

max_database_entries

int32

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

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

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

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

ThreatType

Виды угроз.

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

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

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

SOCIAL_ENGINEERING

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

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

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

ThreatUrl

URL-адрес, соответствующий одной или нескольким угрозам.

Поля
url

string

Запрошенный URL-адрес, соответствующий одной или нескольким угрозам.

threat_types[]

ThreatType

Неупорядоченный список. Неупорядоченный список угроз, к которым относится URL.