Package google.security.safebrowsing.v5alpha1

Индекс

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

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

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

rpc BatchGetHashLists( BatchGetHashListsRequest ) returns ( BatchGetHashListsResponse )

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

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

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

Получить хешлист

rpc GetHashList( GetHashListRequest ) returns ( HashList )

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

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

ListHashСписки

rpc ListHashLists( ListHashListsRequest ) returns ( ListHashListsResponse )

Получение списков хэшей.

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

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

Поисковые хэши

rpc SearchHashes( SearchHashesRequest ) returns ( SearchHashesResponse )

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

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

Пакетный запрос GetHashLists

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

Поля
names[]

string

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

version[]

bytes

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

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

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

desired_hash_length

HashLength

Желаемая длина префикса хеша возвращаемых хешей в байтах. Затем сервер вернет все хеш-префиксы указанной длины.

Различные хэш-списки предъявляют разные требования к допустимым значениям поля desired_hash_length . Это можно найти в поле supported_hash_lengths в HashListMetadata . Если desired_hash_length не указывает значение в supported_hash_lengths , клиентам будет возвращена ошибка.

В частности, для BatchGetHashListsRequest клиенты не могут указать другую desired_hash_length для разных списков. Если есть необходимость сделать это, клиент должен разделить на несколько BatchGetHashListsRequest .

size_constraints

SizeConstraints

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

Пакетный метод GetHashListsResponse

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

Поля
hash_lists[]

HashList

Хэш-списки располагаются в том же порядке, что указан в запросе.

FullHash

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

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

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

Получить запрос HashList

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

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

Поля
name

string

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

version

bytes

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

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

desired_hash_length

HashLength

Желаемая длина префикса хеша возвращаемых хешей в байтах. Затем сервер вернет все хеш-префиксы указанной длины.

Различные хэш-списки предъявляют разные требования к допустимым значениям поля desired_hash_length . Это можно найти в поле supported_hash_lengths в HashListMetadata . Если desired_hash_length не указывает значение в supported_hash_lengths , будет возвращена ошибка.

size_constraints

SizeConstraints

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

Хэшлист

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

Поля
name

string

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

version

bytes

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

partial_update

bool

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

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

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

compressed_removals

RiceDeltaEncoded32Bit

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

minimum_wait_duration

Duration

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

metadata

HashListMetadata

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

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

RiceDeltaEncoded32Bit

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

additions_eight_bytes

RiceDeltaEncoded64Bit

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

additions_sixteen_bytes

RiceDeltaEncoded128Bit

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

additions_thirty_two_bytes

RiceDeltaEncoded256Bit

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

checksum сумма поля объединения. Это контрольная сумма отсортированного списка всех хешей, присутствующих в базе данных после применения предоставленного обновления. Это поле «oneof», позволяющее использовать несколько алгоритмов хеширования. Сервер также может пропустить это поле (в случае, если обновления не были предоставлены), чтобы указать, что клиент должен использовать существующую контрольную сумму. checksum может быть только одной из следующих:
sha256_checksum

bytes

Отсортированный список всех хэшей, снова хешированный с помощью SHA256.

HashListМетаданные

Метаданные об определенном хеш-списке.

Поля
threat_types[]

ThreatType

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

likely_safe_types[]

LikelySafeType

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

mobile_optimized

bool

Оптимизирован ли этот список для мобильных устройств (Android и iOS).

description

string

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

supported_hash_lengths[]

HashLength

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

длина хеша

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

Перечисления
HASH_LENGTH_UNSPECIFIED Неопределенная длина. Сервер не будет возвращать это значение в ответах клиенту (в поле supported_hash_lengths ), но клиенту разрешено отправлять это значение на сервер (в поле desired_hash_length ), и в этом случае сервер выберет значение автоматически. Клиенты ДОЛЖНЫ позволить серверу выбрать значение.
FOUR_BYTES Каждый хэш представляет собой четырехбайтовый префикс.
EIGHT_BYTES Каждый хэш представляет собой восьмибайтовый префикс.
SIXTEEN_BYTES Каждый хэш представляет собой шестнадцатибайтовый префикс.
THIRTY_TWO_BYTES Каждый хэш представляет собой полный хеш длиной тридцать два байта.

ВероятноСафеТип

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

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

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

ListHashListsЗапрос

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

Поля
page_size

int32

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

page_token

string

Токен страницы, полученный в результате предыдущего вызова ListHashLists . Предоставьте это, чтобы получить следующую страницу.

ListHashListsResponse

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

Поля
hash_lists[]

HashList

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

next_page_token

string

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

РайсDeltaEncoded128Bit

То же, что и 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

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

РайсDeltaEncoded256Bit

То же, что и 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

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

РайсDeltaEncoded32Bit

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

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

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

Поля
first_value

uint32

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

rice_parameter

int32

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

entries_count

int32

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

encoded_data

bytes

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

РайсDeltaEncoded64Bit

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

Поля
first_value

uint64

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

rice_parameter

int32

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

entries_count

int32

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

encoded_data

bytes

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

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

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

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

Что нового в версии 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 .

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

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

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

Что нового в V5 : существует разделение между FullHash и FullHashDetail . В случае, когда хэш представляет сайт, имеющий несколько угроз (например, MALWARE и SOCIAL_ENGINEERING), полный хеш не нужно отправлять дважды, как в версии 4. Кроме того, продолжительность кэша была упрощена до одного поля 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 Указывает, что тип_угрозы не следует использовать для принудительного применения.
FRAME_ONLY Указывает, что тип_угрозы следует использовать только для принудительного применения к кадрам.

Тип угрозы

Виды угроз.

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

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

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

SOCIAL_ENGINEERING

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

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

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