Package google.security.safebrowsing.v4

Индекс

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

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

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

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

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

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

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

{-- TRUSTED_THREAT_REPORTER: доверенные клиенты угроз могут отправлять отчеты в Google для анализа с помощью метода SubmitThreatReport. --}

Обновления FetchThreatListUpdates

rpc FetchThreatListUpdates( FetchThreatListUpdatesRequest ) returns ( FetchThreatListUpdatesResponse )

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

НайтиFullHashes

rpc FindFullHashes( FindFullHashesRequest ) returns ( FindFullHashesResponse )

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

Найти ThreatMatches

rpc FindThreatMatches( FindThreatMatchesRequest ) returns ( FindThreatMatchesResponse )

Находит записи об угрозах, соответствующие спискам безопасного просмотра.

СписокУгрозыСписки

rpc ListThreatLists( Empty ) returns ( ListThreatListsResponse )

Содержит списки угроз безопасного просмотра, доступные для загрузки.

Контрольная сумма

Ожидаемое состояние локальной базы данных клиента.

Поля
sha256

bytes

Хэш SHA256 состояния клиента; то есть отсортированный список всех хешей, присутствующих в базе данных.

Информация о клиенте

Метаданные клиента, связанные с запросами API безопасного просмотра.

Поля
client_id

string

Идентификатор клиента, который (надеюсь) однозначно идентифицирует клиентскую реализацию API безопасного просмотра.

client_version

string

Версия реализации клиента.

Тип сжатия

Способы сжатия наборов записей об угрозах.

Перечисления
COMPRESSION_TYPE_UNSPECIFIED Неизвестный.
RAW Необработанные несжатые данные.
RICE Данные в кодировке Райса-Голомба.

Запрос FetchThreatListUpdatesRequest

Описывает запрос на обновление API безопасного просмотра. Клиенты могут запрашивать обновления для нескольких списков в одном запросе. Сервер может не отвечать на все запросы, если на сервере нет обновлений для этого списка. ПРИМЕЧАНИЕ. Индекс поля 2 не используется. СЛЕДУЮЩИЙ: 5

Поля
client

ClientInfo

Метаданные клиента.

list_update_requests[]

ListUpdateRequest

Запрошенные обновления списка угроз.

ListUpdateRequest

Единый запрос на обновление списка.

Поля
threat_type

ThreatType

Тип угрозы, которую представляют записи, присутствующие в списке.

platform_type

PlatformType

Тип платформы, подверженной риску, по записям, присутствующим в списке.

threat_entry_type

ThreatEntryType

Типы записей, представленных в списке.

state

bytes

Текущее состояние клиента запрошенного списка (зашифрованное состояние клиента, полученное в результате последнего успешного обновления списка).

constraints

Constraints

Ограничения, связанные с этим запросом.

Ограничения

Ограничения для этого обновления.

Поля
max_update_entries

int32

Максимальный размер по количеству записей. Обновление не будет содержать больше записей, чем это значение. Это должна быть степень 2 между 2**10 и 2**20. Если ноль, ограничение размера обновления не установлено.

max_database_entries

int32

Устанавливает максимальное количество записей, которые клиент желает иметь в локальной базе данных для указанного списка. Это должна быть степень 2 между 2**10 и 2**20. Если ноль, ограничение размера базы данных не установлено.

region

string

Запрашивает список для определенного географического местоположения. Если этот параметр не установлен, сервер может выбрать это значение на основе IP-адреса пользователя. Ожидается формат ISO 3166-1 альфа-2.

supported_compressions[]

CompressionType

Типы сжатия, поддерживаемые клиентом.

language

string

Запрашивает списки для определенного языка. Ожидается формат ISO 639 альфа-2.

device_location

string

Физическое местоположение клиента, выраженное в виде кода региона ISO 31166-1 альфа-2.

FetchThreatListUpdatesResponse

Поля
list_update_responses[]

ListUpdateResponse

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

minimum_wait_duration

Duration

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

Листупдатеответ

Обновление индивидуального списка.

Поля
threat_type

ThreatType

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

threat_entry_type

ThreatEntryType

Формат угроз.

platform_type

PlatformType

Тип платформы, для которой возвращаются данные.

response_type

ResponseType

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

additions[]

ThreatEntrySet

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

removals[]

ThreatEntrySet

Набор записей, которые необходимо удалить из списка типов локальных угроз. На практике это поле пусто или содержит ровно один ThreatEntrySet.

new_client_state

bytes

Новое состояние клиента в зашифрованном формате. Непрозрачен для клиентов.

checksum

Checksum

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

Тип ответа

Тип ответа, отправляемого клиенту.

Перечисления
RESPONSE_TYPE_UNSPECIFIED Неизвестный.
PARTIAL_UPDATE Частичные обновления применяются к существующей локальной базе данных клиента.
FULL_UPDATE Полные обновления заменяют всю локальную базу данных клиента. Это означает, что либо клиент серьезно устарел, либо клиент считается поврежденным.

FindFullHashesRequest

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

Поля
client

ClientInfo

Метаданные клиента.

client_states[]

bytes

Текущие состояния клиента для каждого из локальных списков угроз клиента.

threat_info

ThreatInfo

Списки и хэши, которые необходимо проверить.

api_client

ClientInfo

Метаданные клиента, связанные с вызывающими объектами API более высокого уровня, созданными на основе реализации клиента.

Найтифуллхэшесответ

Поля
matches[]

ThreatMatch

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

minimum_wait_duration

Duration

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

negative_cache_duration

Duration

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

Запрос FindThreatMatches

Запрос на проверку записей по спискам.

Поля
client

ClientInfo

Метаданные клиента.

threat_info

ThreatInfo

Списки и записи, которые необходимо проверить на совпадения.

FindThreatMatchesResponse

Поля
matches[]

ThreatMatch

Список угроз совпадает.

ListThreatListsResponse

Поля
threat_lists[]

ThreatListDescriptor

Списки доступны для скачивания клиентом.

Тип платформы

Виды платформ.

Перечисления
PLATFORM_TYPE_UNSPECIFIED Неизвестная платформа.
WINDOWS Угроза исходила для Windows.
LINUX Угроза исходит от Linux.
ANDROID Угроза исходила для Android.
OSX Угроза, исходящая для OS X.
IOS Угроза исходила для iOS.
ANY_PLATFORM Угроза исходила как минимум для одной из определенных платформ.
ALL_PLATFORMS Угроза исходила для всех определенных платформ.
CHROME Угроза исходит от Chrome.

RawHashes

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

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

Поля
prefix_size

int32

Количество байтов для каждого префикса, закодированного ниже. Это поле может иметь любое значение от 4 (самый короткий префикс) до 32 (полный хэш SHA256).

raw_hashes

bytes

Хэши в двоичном формате объединены в одну длинную строку. Хэши сортируются в лексикографическом порядке. Для пользователей JSON API хеши имеют кодировку Base64.

Необработанные индексы

Набор необработанных индексов, которые нужно удалить из локального списка.

Поля
indices[]

int32

Индексы, которые необходимо удалить из локального списка, отсортированного по лексикографическому принципу.

РайсДельтаКодирование

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

Поля
first_value

int64

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

rice_parameter

int32

Параметр Голомба-Райса, представляющий собой число от 2 до 28. Это поле отсутствует (то есть равно нулю), если num_entries равно нулю.

num_entries

int32

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

encoded_data

bytes

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

УгрозаВход

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

Поля
hash

bytes

Хэш-префикс, состоящий из старших 4–32 байтов хеша SHA256. Это поле имеет двоичный формат. Для запросов JSON хеши кодируются в формате Base64.

url

string

URL-адрес.

digest

bytes

Дайджест исполняемого файла в формате SHA256. API поддерживает как двоичные, так и шестнадцатеричные дайджесты. Для запросов JSON дайджесты кодируются в формате Base64.

ThreatEntryМетаданные

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

Поля
entries[]

MetadataEntry

Записи метаданных.

МетаданныеВвод

Одна запись метаданных.

Поля
key

bytes

Ключ ввода метаданных. Для запросов JSON ключ имеет кодировку Base64.

value

bytes

Значение записи метаданных. Для запросов JSON значение закодировано в формате Base64.

ThreatEntrySet

Набор угроз, которые необходимо добавить или удалить из локальной базы данных клиента.

Поля
compression_type

CompressionType

Тип сжатия для записей в этом наборе.

raw_hashes

RawHashes

Необработанные записи в формате SHA256.

raw_indices

RawIndices

Необработанные индексы удаления для локального списка.

rice_hashes

RiceDeltaEncoding

Закодированные 4-байтовые префиксы записей в формате SHA256 с использованием кодировки Голомба-Райса. Хэши преобразуются в uint32, сортируются в порядке возрастания, затем дельта-кодируются и сохраняются как encoded_data.

rice_indices

RiceDeltaEncoding

Закодированные локальные индексы списков с лексикографической сортировкой с использованием кодировки Голомба-Райса. Используется для отправки сжатых индексов удаления. Индексы удаления (uint32) сортируются в порядке возрастания, затем дельта-кодируются и сохраняются как encoded_data.

ThreatEntryType

Типы записей, представляющих угрозу. Списки угроз представляют собой наборы записей одного типа.

Перечисления
THREAT_ENTRY_TYPE_UNSPECIFIED Неопределенные.
URL URL-адрес.
EXECUTABLE Исполняемая программа.

Информация об угрозе

Информация об одной или нескольких угрозах, которую клиент отправляет при проверке совпадений в списках угроз.

Поля
threat_types[]

ThreatType

Типы угроз, которые необходимо проверить.

platform_types[]

PlatformType

Типы платформ, которые необходимо проверить.

threat_entry_types[]

ThreatEntryType

Типы записей, которые необходимо проверить.

threat_entries[]

ThreatEntry

Записи об угрозах, подлежащие проверке.

Дескриптор списка угроз

Описывает индивидуальный список угроз. Список определяется тремя параметрами: типом угрозы, типом платформы, на которую направлена ​​угроза, и типом записей в списке.

Поля
threat_type

ThreatType

Тип угрозы, которую представляют записи списка.

platform_type

PlatformType

Тип платформы, на который нацелены записи списка.

threat_entry_type

ThreatEntryType

Типы записей, содержащиеся в списке.

ThreatMatch

Совпадение при проверке записи об угрозе в списках угроз безопасного просмотра.

Поля
threat_type

ThreatType

Тип угрозы, соответствующий этой угрозе.

platform_type

PlatformType

Тип платформы, соответствующий этой угрозе.

threat_entry_type

ThreatEntryType

Тип записи об угрозе, соответствующий этой угрозе.

threat

ThreatEntry

Угроза, соответствующая этой угрозе.

threat_entry_metadata

ThreatEntryMetadata

Необязательные метаданные, связанные с этой угрозой.

cache_duration

Duration

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

Тип угрозы

Виды угроз.

Перечисления
THREAT_TYPE_UNSPECIFIED Неизвестный.
MALWARE Тип угрозы вредоносного ПО.
SOCIAL_ENGINEERING Тип угрозы социальной инженерии.
UNWANTED_SOFTWARE Тип нежелательной программной угрозы.
POTENTIALLY_HARMFUL_APPLICATION Тип потенциально опасного приложения.