Индекс
-
SafeBrowsing(интерфейс) -
BatchGetHashListsRequest(message) -
BatchGetHashListsResponse(message) -
FullHash(message) -
FullHash.FullHashDetail(message) -
GetHashListRequest(message) -
HashList(сообщение) -
HashListMetadata(message) -
HashListMetadata.HashLength(перечисление) -
LikelySafeType(enum) -
ListHashListsRequest(message) -
ListHashListsResponse(сообщение) -
RiceDeltaEncoded128Bit(message) -
RiceDeltaEncoded256Bit(message) -
RiceDeltaEncoded32Bit(message) -
RiceDeltaEncoded64Bit(message) -
SearchHashesRequest(message) -
SearchHashesResponse(message) -
SearchUrlsRequest(message) -
SearchUrlsResponse(message) -
SizeConstraints(message) -
ThreatAttribute(enum) -
ThreatType(enum) -
ThreatUrl(message)
Безопасный просмотр
API-интерфейсы Safe Browsing позволяют клиентам проверять веб-ресурсы (чаще всего URL-адреса) по постоянно обновляемым спискам небезопасных веб-ресурсов Google.
| BatchGetHashLists |
|---|
Получает несколько хэш-списков одновременно. Клиентам очень часто требуется получить несколько списков хешей. Использование этого метода предпочтительнее, чем многократное использование обычного метода Get. Это стандартный пакетный метод GET, как определено в https://google.aip.dev/231 , и метод HTTP также является GET. |
| GetHashList |
|---|
Получает актуальное содержимое хэш-списка. Хэш-список может представлять собой либо список угроз, либо список не представляющих угрозы угроз, например, глобальный кэш. Это стандартный метод GET, как определено в https://google.aip.dev/131 , и метод HTTP также является GET. |
| ListHashLists |
|---|
Списки, хэш-списки. В API версии V5 Google никогда не удалит список хешей, который когда-либо возвращался этим методом. Это позволяет клиентам обходиться без использования этого метода и просто жестко задавать все необходимые списки хешей. Это стандартный метод List, определенный в https://google.aip.dev/132 , и HTTP-метод — GET. |
| SearchHashes |
|---|
Выполняет поиск полных хешей, соответствующих указанным префиксам. Это пользовательский метод, как определено в https://google.aip.dev/136 (пользовательский метод означает, что этот метод имеет собственное имя в рамках общей номенклатуры разработки API Google; он не относится к использованию пользовательского HTTP-метода). |
| SearchUrls |
|---|
Выполняется поиск URL-адресов, соответствующих известным угрозам. Проверяется каждый URL-адрес, а также его суффикс хоста и префикс пути (до ограниченной глубины). Это означает, что ответ может содержать URL-адреса, которые не были включены в запрос, но являются выражениями запрошенных URL-адресов. |
BatchGetHashListsRequest
Запрос на получение нескольких хеш-списков одновременно.
| Поля | |
|---|---|
names[] | Обязательно. Названия конкретных хэш-списков. Список МОЖЕТ быть списком угроз или глобальным кэшем. Названия НЕ ДОЛЖНЫ содержать дубликаты; в противном случае клиент получит ошибку. |
version[] | Версии списка хешей, которые уже есть у клиента. Если клиент впервые получает списки хешей, это поле следует оставить пустым. В противном случае клиент должен предоставить версии, ранее полученные от сервера. Клиент НЕ ДОЛЖЕН манипулировать этими байтами. Клиенту не обязательно отправлять версии в том же порядке, что и соответствующие имена в списках. Клиент может отправить в запросе меньше или больше версий, чем имен. Однако клиент НЕ ДОЛЖЕН отправлять несколько версий, соответствующих одному и тому же имени; в противном случае клиент получит ошибку. Историческая справка: в версии 4 API это называлось |
size_constraints | Ограничения по размеру для каждого списка. Если не указано, ограничений нет. Обратите внимание, что размеры здесь указаны для каждого списка отдельно, а не суммированы по всем спискам. |
BatchGetHashListsResponse
Ответ, содержащий несколько списков хешей.
| Поля | |
|---|---|
hash_lists[] | Хэш-списки расположены в том же порядке, что и в запросе. |
FullHash
Полный хеш, соответствующий одному или нескольким совпадениям.
| Поля | |
|---|---|
full_hash | Соответствующий полный хеш. Это хеш SHA256. Длина составит ровно 32 байта. |
full_hash_details[] | Неупорядоченный список. Повторяющееся поле, определяющее детали, относящиеся к этому полному хешу. |
FullHashDetail
Подробности о совпадающем полном хеше.
Важное замечание относительно обратной совместимости: сервер может в любое время добавлять новые типы угроз и атрибуты угроз; эти дополнения считаются изменениями минорных версий. Политика Google не предусматривает раскрытие номеров минорных версий в API (см. https://cloud.google.com/apis/design/versioning для ознакомления с политикой версионирования), поэтому клиенты ДОЛЖНЫ быть готовы получать сообщения FullHashDetail содержащие значения перечисления ThreatType или ThreatAttribute , которые клиент считает недействительными. Следовательно, клиент несет ответственность за проверку действительности всех значений перечисления ThreatType и ThreatAttribute ; если какое-либо значение считается недействительным, клиент ДОЛЖЕН игнорировать все сообщение FullHashDetail .
| Поля | |
|---|---|
threat_type | Тип угрозы. Это поле никогда не будет пустым. |
attributes[] | Неупорядоченный список. Дополнительные атрибуты, относящиеся к этим полным хешам. Может быть пустым. |
GetHashListRequest
Запрос на получение списка хешей, который может представлять собой список угроз или список не представляющих угрозы объектов, например, Global Cache.
Что нового в версии 5 : То, что в версии 4 называлось states для большей ясности переименовано в version . Списки теперь имеют имена, типы платформ и типы записей угроз удалены. Теперь несколько списков могут содержать один и тот же тип угрозы, или один список может содержать несколько типов угроз. В отличие от префиксов хешей переменной длины в версии 4, которые вызывали проблемы во многих клиентских реализациях: теперь все хеши в списке имеют одинаковую длину, что позволяет создавать гораздо более эффективные клиентские реализации. Ограничения упрощены, а тип сжатия удален (сжатие применяется всегда).
| Поля | |
|---|---|
name | Обязательно. Название данного списка хешей. Это может быть список угроз или глобальный кэш. |
version | Версия списка хешей, которая уже имеется у клиента. Если клиент впервые получает список хешей, это поле ДОЛЖНО оставаться пустым. В противном случае клиент ДОЛЖЕН предоставить версию, ранее полученную от сервера. Клиент НЕ ДОЛЖЕН манипулировать этими байтами. Что нового в версии 5 : в версии 4 API это называлось |
size_constraints | Ограничения по размеру указаны в списке. Если они опущены, ограничений нет. Ограничения рекомендуются для всех устройств с ограниченной вычислительной мощностью, пропускной способностью или объемом памяти. |
Хэш-лист
Список хешей, идентифицированных по их имени.
| Поля | |
|---|---|
name | Название списка хешей. Обратите внимание, что глобальный кэш также представляет собой просто список хешей, и на него можно ссылаться здесь. |
version | Версия хеш-списка. Клиенту ЗАПРЕЩЕНО манипулировать этими байтами. |
partial_update | Если значение равно true, это частичное сравнение, содержащее добавления и удаления на основе уже имеющихся у клиента данных. Если значение равно false, это полный список хешей. Если значение равно false, клиент ОБЯЗАН удалить все локально сохраненные версии для этого списка хешей. Это означает, что либо версия, имеющаяся у клиента, серьезно устарела, либо данные клиента считаются поврежденными. Поле Если это так, клиент ОБЯЗАН выполнить инкрементальное обновление, сначала удалив, а затем добавив данные. |
compressed_removals | Версия индексов удаления, закодированная с помощью алгоритма Райса-дельта. Поскольку каждый хеш-список определенно содержит менее 2^32 элементов, индексы рассматриваются как 32-битные целые числа и кодируются. |
minimum_wait_duration | Клиентам следует подождать как минимум это время, чтобы снова получить список хешей. Если значение отсутствует или равно нулю, клиенты ДОЛЖНЫ получить список немедленно, поскольку это указывает на то, что сервер должен отправить клиенту дополнительное обновление, но не смог этого сделать из-за ограничений, указанных клиентом. |
sha256_checksum | Отсортированный список всех хешей, повторно хешированных с помощью SHA256. Это контрольная сумма для отсортированного списка всех хешей, присутствующих в базе данных после применения предоставленного обновления. В случае, если обновления не были предоставлены, сервер опустит это поле, чтобы указать клиенту, что следует использовать существующую контрольную сумму. |
metadata | Метаданные о списке хешей. Этот параметр не заполняется методом |
Поле объединения compressed_additions . Версия adds, закодированная по алгоритму Райса-дельта. Длина префикса хеша adds одинакова для всех adds в списке. compressed_additions может принимать только одно из следующих значений: | |
additions_four_bytes | Сложение 4 байтов. |
additions_eight_bytes | 8-байтовые сложения. |
additions_sixteen_bytes | Добавление 16 байт. |
additions_thirty_two_bytes | Добавление 32 байт. |
Хэш-списМетаданные
Метаданные, относящиеся к конкретному хеш-списку.
| Поля | |
|---|---|
threat_types[] | Неупорядоченный список. Если не пуст, это указывает на то, что список хешей является своего рода списком угроз, и в нем перечислены типы угроз, связанных с хешами или префиксами хешей в этом списке. Может быть пустым, если запись не представляет угрозу, то есть если она представляет собой вероятный безопасный тип. |
likely_safe_types[] | Неупорядоченный список. Если он не пуст, это означает, что список хешей представляет собой перечень вероятно безопасных хешей и перечисляет способы, которыми они считаются вероятно безопасными. Это поле взаимоисключающее с полем threat_types. |
description | Удобочитаемое описание этого списка. Написано на английском языке. |
hash_length | Поддерживаемая длина хеша для этого списка хешей. Каждый список хешей поддерживает ровно одну длину. Если для одного и того же набора типов угроз или типов безопасности задана другая длина хеша, она будет задана как отдельный список с уникальным именем и соответствующим набором длин хешей. |
HashLength
Длина хешей в хеш-списке.
| Перечисления | |
|---|---|
HASH_LENGTH_UNSPECIFIED | Длина не указана. |
FOUR_BYTES | Каждый хеш представляет собой четырехбайтовый префикс. |
EIGHT_BYTES | Каждый хеш представляет собой восьмибайтовый префикс. |
SIXTEEN_BYTES | Каждый хеш представляет собой шестнадцатибайтовый префикс. |
THIRTY_TWO_BYTES | Каждый хеш представляет собой полный хеш размером тридцать два байта. |
LikelySafeType
Типы потенциально безопасных мест.
Обратите внимание, что объект SearchHashesResponse намеренно не содержит LikelySafeType .
| Перечисления | |
|---|---|
LIKELY_SAFE_TYPE_UNSPECIFIED | Неизвестный. |
GENERAL_BROWSING | Этот сайт, вероятно, достаточно безопасен для обычного просмотра. Это также известно как глобальный кэш. |
CSD | Вероятно, этот сайт достаточно безопасен, поэтому нет необходимости запускать модели обнаружения угроз на стороне клиента или проверять защиту паролем. |
DOWNLOAD | Вероятно, этот сайт достаточно безопасен, поэтому проверять файлы, скачиваемые с него, не нужно. |
ListHashListsRequest
Запрос на вывод списка доступных хэш-таблиц.
| Поля | |
|---|---|
page_size | Максимальное количество хэш-списков для возврата. Сервис может вернуть меньшее количество. Если значение не указано, сервер выберет размер страницы, который может быть больше количества хэш-списков, поэтому пагинация не потребуется. |
page_token | Токен страницы, полученный из предыдущего вызова |
ListHashListsResponse
Ответ, содержащий метаданные о списках хешей.
| Поля | |
|---|---|
hash_lists[] | Хэш-списки располагаются в произвольном порядке. Будут включены только метаданные о хэш-списках, а не их содержимое. |
next_page_token | Токен, который можно отправить в качестве |
RiceDeltaEncoded128Bit
Аналогично RiceDeltaEncoded32Bit , за исключением того, что здесь кодируются 128-битные числа.
| Поля | |
|---|---|
first_value_hi | Старшие 64 бита первой записи в закодированных данных (хешах). Если поле пустое, все старшие 64 бита равны нулю. |
first_value_lo | Младшие 64 бита первой записи в закодированных данных (хешах). Если поле пустое, все младшие 64 бита равны нулю. |
rice_parameter | Параметр Голомба-Райса. Гарантируется, что значение этого параметра находится в диапазоне от 99 до 126 включительно. |
entries_count | Количество записей, закодированных с помощью дельта-кодирования в закодированных данных. Если закодировано только одно целое число, это значение будет равно нулю, и единственное значение будет сохранено в |
encoded_data | Закодированные дельты, закодированные с использованием кодера Голомба-Райса. |
RiceDeltaEncoded256Bit
Аналогично RiceDeltaEncoded32Bit , за исключением того, что здесь кодируются 256-битные числа.
| Поля | |
|---|---|
first_value_first_part | Первые 64 бита первой записи в закодированных данных (хешах). Если поле пустое, первые 64 бита равны нулю. |
first_value_second_part | Биты с 65-го по 128-й первой записи в закодированных данных (хешах). Если поле пустое, все биты с 65-го по 128-й равны нулю. |
first_value_third_part | Биты с 129-го по 192-й первой записи в закодированных данных (хешах). Если поле пустое, то все биты с 129-го по 192-й равны нулю. |
first_value_fourth_part | Последние 64 бита первой записи в закодированных данных (хешах). Если поле пустое, последние 64 бита равны нулю. |
rice_parameter | Параметр Голомба-Райса. Гарантируется, что значение этого параметра находится в диапазоне от 227 до 254 включительно. |
entries_count | Количество записей, закодированных с помощью дельта-кодирования в закодированных данных. Если закодировано только одно целое число, это значение будет равно нулю, и единственное значение будет сохранено в |
encoded_data | Закодированные дельты, закодированные с использованием кодера Голомба-Райса. |
RiceDeltaEncoded32Bit
Данные, закодированные по алгоритму Райса-Голомба. Используются либо для хешей, либо для индексов удаления. Гарантируется, что каждый хеш или индекс имеет одинаковую длину, которая составляет ровно 32 бита.
В общем случае, если мы отсортируем все записи лексикографически, мы обнаружим, что старшие биты, как правило, изменяются не так часто, как младшие. Это означает, что если мы также возьмем соседнюю разность между записями, старшие биты с высокой вероятностью будут равны нулю. Эта высокая вероятность нуля используется для выбора определенного количества битов; все биты старше этого количества, скорее всего, будут равны нулю, поэтому мы используем унарное кодирование. См. поле rice_parameter .
Историческая справка: кодировка Райса-дельта впервые была использована в версии 4 этого API. В версии 5 были внесены два существенных улучшения: во-первых, кодировка Райса-дельта теперь доступна для хеш-префиксов длиннее 4 байт; во-вторых, закодированные данные теперь обрабатываются в порядке байтов big-endian, чтобы избежать дорогостоящего этапа сортировки.
| Поля | |
|---|---|
first_value | Первая запись в закодированных данных (хешах или индексах) или, если был закодирован только один префикс хеша или индекс, значение этой записи. Если поле пустое, значение равно нулю. |
rice_parameter | Параметр Голомба-Райса. Гарантируется, что значение этого параметра находится в диапазоне от 3 до 30 включительно. |
entries_count | Количество записей, закодированных с помощью дельта-кодирования в закодированных данных. Если закодировано только одно целое число, это значение будет равно нулю, и единственное значение будет сохранено в |
encoded_data | Закодированные дельты, закодированные с использованием кодера Голомба-Райса. |
RiceDeltaEncoded64Bit
Аналогично RiceDeltaEncoded32Bit , за исключением того, что здесь кодируются 64-битные числа.
| Поля | |
|---|---|
first_value | Первая запись в закодированных данных (хешах) или, если был закодирован только один префикс хеша, значение этой записи. Если поле пустое, значение равно нулю. |
rice_parameter | Параметр Голомба-Райса. Гарантируется, что значение этого параметра находится в диапазоне от 35 до 62 включительно. |
entries_count | Количество записей, закодированных с помощью дельта-кодирования в закодированных данных. Если закодировано только одно целое число, это значение будет равно нулю, и единственное значение будет сохранено в |
encoded_data | Закодированные дельты, закодированные с использованием кодера Голомба-Райса. |
SearchHashesRequest
Запрос, который клиент отправляет для поиска определенных префиксов хеша.
Эта функция предназначена для поиска только по спискам угроз и не выполняет поиск по спискам, не представляющим угрозы, таким как глобальный кэш.
Что нового в версии 5 : Клиентам больше не нужно указывать ClientInfo или состояния списков хешей в своей локальной базе данных. Это сделано для повышения конфиденциальности. Кроме того, клиентам больше не нужно указывать, какие типы угроз их интересуют.
| Поля | |
|---|---|
hash_prefixes[] | Обязательно. Хэш-префиксы, которые необходимо найти. Клиенты НЕ ДОЛЖНЫ отправлять более 1000 хэш-префиксов. Однако, в соответствии с процедурой обработки URL-адресов, клиентам НЕ ДОЛЖНО потребоваться отправлять более 30 хэш-префиксов. В настоящее время длина каждого префикса хеша должна составлять ровно 4 байта. В будущем это требование МОЖЕТ быть смягчено. |
filter | Необязательно. Если клиент заинтересован в фильтрации, например, в получении только определенных типов угроз, этот параметр можно указать. Если он опущен, будут возвращены все соответствующие угрозы. Настоятельно рекомендуется опустить этот параметр для обеспечения максимально полной защиты, которую может предложить Safe Browsing. Фильтр задается с использованием языка выражений Google Common Expression Language, который можно найти по адресу https://github.com/google/cel-spec вместе с общими примерами. Вот несколько конкретных примеров, которые можно использовать: Фильтр Фильтр |
SearchHashesResponse
Ответ был получен после поиска по хэшам угроз.
Если ничего не найдено, сервер вернет статус OK (код состояния HTTP 200) с пустым полем full_hashes , вместо статуса NOT_FOUND (код состояния HTTP 404).
Что нового в версии 5 : Разделение между FullHash и FullHashDetail . В случае, когда хеш представляет сайт, содержащий несколько угроз (например, как вредоносное ПО, так и социальная инженерия), полный хеш не нужно отправлять дважды, как в версии 4. Кроме того, длительность кэширования упрощена и теперь представляет собой одно поле cache_duration .
| Поля | |
|---|---|
full_hashes[] | Неупорядоченный список. Неупорядоченный список найденных полных хешей. |
cache_duration | Длительность кэширования на стороне клиента. Клиент ОБЯЗАТЕЛЬНО должен добавить эту длительность к текущему времени, чтобы определить время истечения срока действия. Время истечения срока действия затем применяется ко всем префиксам хешей, запрашиваемым клиентом в запросе, независимо от того, сколько полных хешей возвращается в ответе. Даже если сервер не возвращает полных хешей для конкретного префикса хешей, этот факт также ДОЛЖЕН быть кэширован клиентом. Только если поле Важно: клиент НЕ ДОЛЖЕН предполагать, что сервер вернет одинаковую продолжительность кэширования для всех ответов. Сервер МОЖЕТ выбрать разную продолжительность кэширования для разных ответов в зависимости от ситуации. |
SearchUrlsRequest
Запрос, отправляемый клиентом для поиска угроз, соответствующих указанным URL-адресам.
Эта функция предназначена для поиска только по спискам угроз и не выполняет поиск по спискам, не представляющим угрозы, таким как глобальный кэш.
| Поля | |
|---|---|
urls[] | Обязательно. URL-адреса, которые необходимо проверить. Клиенты НЕ ДОЛЖНЫ отправлять более 50 URL-адресов. |
SearchUrlsResponse
Ответ был получен после поиска угроз, соответствующих указанным URL-адресам.
Если ничего не найдено, сервер вернет статус OK (код состояния HTTP 200) с пустым полем threats , вместо статуса NOT_FOUND (код состояния HTTP 404).
| Поля | |
|---|---|
threats[] | Неупорядоченный список. Неупорядоченный список найденных совпадений угроз. Каждая запись содержит URL-адрес и типы угроз, которые были найдены в соответствии с этим URL-адресом. Размер списка может быть больше, чем количество URL-адресов в запросе, поскольку были бы рассмотрены все выражения URL-адреса. |
cache_duration | Длительность кэширования на стороне клиента. Клиент ОБЯЗАТЕЛЬНО должен добавить эту длительность к текущему времени, чтобы определить время истечения срока действия. Время истечения срока действия затем применяется ко всем URL-адресам, запрашиваемым клиентом в запросе, независимо от того, сколько URL-адресов возвращается в ответе. Даже если сервер не возвращает совпадений для конкретного URL-адреса, этот факт также ДОЛЖЕН быть кэширован клиентом. Только если поле Важно: клиент НЕ ДОЛЖЕН предполагать, что сервер вернет одинаковую продолжительность кэширования для всех ответов. Сервер МОЖЕТ выбрать разную продолжительность кэширования для разных ответов в зависимости от ситуации. |
Ограничения размера
Ограничения на размеры хеш-списков.
| Поля | |
|---|---|
max_update_entries | Максимальное количество записей. Обновление не будет содержать больше записей, чем это значение, но возможно, что оно будет содержать меньше записей, чем это значение. Это значение ДОЛЖНО быть не менее 1024. Если оно опущено или равно нулю, ограничение на размер обновления не устанавливается. |
max_database_entries | Устанавливает максимальное количество записей, которое клиент готов хранить в локальной базе данных для списка. (Сервер МОЖЕТ заставить клиента хранить меньшее количество записей.) Если параметр опущен или равен нулю, ограничение размера базы данных не устанавливается. |
Атрибут угрозы
Атрибуты угроз. Эти атрибуты могут придавать конкретному угрозе дополнительное значение, но не влияют на её тип. Например, один атрибут может указывать на более низкую степень уверенности, а другой — на более высокую. В будущем могут быть добавлены и другие атрибуты.
| Перечисления | |
|---|---|
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 . |
ThreatUrl
URL-адрес, соответствующий одной или нескольким угрозам.
| Поля | |
|---|---|
url | Запрошенный URL-адрес, совпавший с одной или несколькими угрозами. |
threat_types[] | Неупорядоченный список. Неупорядоченный список угроз, к которым относится данный URL-адрес. |