Overview

Примечание: Эта документация в настоящее время все еще находится в стадии разработки. Ожидайте улучшений в ближайшем будущем.

Google Safe Browsing v5 — это эволюция Google Safe Browsing v4. Два ключевых изменения, внесенных в v5, — это актуальность данных и конфиденциальность IP. Кроме того, поверхность API была улучшена для повышения гибкости, эффективности и уменьшения раздувания. Кроме того, Google Safe Browsing v5 разработан для упрощения миграции с v4 .

В настоящее время Google предлагает как v4, так и v5, и обе считаются готовыми к производству. Вы можете использовать либо v4, либо v5. Мы не объявили дату прекращения поддержки v4; если мы это сделаем, мы дадим уведомление минимум за один год. На этой странице будет описана v5, а также руководство по миграции с v4 на v5; полная документация по v4 остается доступной .

Свежесть данных

В v5 мы вводим режим работы, известный как защита в реальном времени. Это обходит проблему устаревания данных, описанную выше. В v4 клиенты должны загружать и поддерживать локальную базу данных, выполнять проверки по локально загруженным спискам угроз, а затем, когда есть частичное совпадение префикса, выполнять запрос на загрузку полного хеша. В v5, хотя клиенты должны продолжать загружать и поддерживать локальную базу данных списков угроз, клиенты теперь также должны загружать список вероятно безопасных сайтов (называемый глобальным кэшем), выполнять как локальную проверку для этого глобального кэша, так и проверку локального списка угроз, и, наконец, когда есть либо частичное совпадение префикса для списков угроз, либо несовпадение в глобальном кэше, выполнять запрос на загрузку полных хешей. (Подробности о локальной обработке, требуемой клиентом, см. в предоставленной процедуре ниже.) Это представляет собой переход от разрешения по умолчанию к проверке по умолчанию, что может улучшить защиту в свете более быстрого распространения угроз в Интернете. Другими словами, это протокол, предназначенный для обеспечения защиты в режиме, близком к реальному времени: мы стремимся предоставить клиентам возможность использовать более свежие данные Google Safe Browsing.

Конфиденциальность ИС

Google Safe Browsing (v4 или v5) не обрабатывает ничего, связанного с личностью пользователя, в ходе обслуживания запросов. Файлы cookie, если они отправлены, игнорируются. Исходные IP-адреса запросов известны Google, но Google использует IP-адреса только для основных сетевых нужд (т. е. для отправки ответов) и в целях анти-DoS.

Одновременно с v5 мы представляем сопутствующий API, известный как Safe Browsing Oblivious HTTP Gateway API. Он использует Oblivious HTTP для сокрытия IP-адресов конечных пользователей от Google. Он работает, имея не вступающую в сговор третью сторону для обработки зашифрованной версии запроса пользователя, а затем пересылая ее в Google. Таким образом, третья сторона имеет доступ только к IP-адресам, а Google имеет доступ только к содержимому запроса. Третья сторона управляет Oblivious HTTP Relay (например, эта служба Fastly ), а Google управляет Oblivious HTTP Gateway. Это необязательный сопутствующий API. При использовании его вместе с Google Safe Browsing IP-адреса конечных пользователей больше не отправляются в Google.

Режимы работы

Google Safe Browsing v5 позволяет клиентам выбирать из трех режимов работы.

Режим реального времени

Когда клиенты выбирают использование Google Safe Browsing v5 в режиме реального времени, они будут хранить в своей локальной базе данных: (i) глобальный кэш вероятно безопасных сайтов, отформатированный как хэши SHA256 выражений URL-суффикса/префикса пути, (ii) набор списков угроз, отформатированный как хэши префиксов SHA256 выражений URL-суффикса/префикса пути. Идея высокого уровня заключается в том, что всякий раз, когда клиент хочет проверить определенный URL-адрес, выполняется локальная проверка с использованием глобального кэша. Если эта проверка проходит, выполняется проверка локальных списков угроз. В противном случае клиент продолжает проверку хэша в реальном времени, как подробно описано ниже.

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

Подробная спецификация процедуры доступна ниже.

Режим локального списка

Когда клиенты выбирают использовать Google Safe Browsing v5 в этом режиме, поведение клиента аналогично API обновления v4, за исключением использования улучшенной поверхности API v5. Клиенты будут поддерживать в своей локальной базе данных набор списков угроз, отформатированных как префиксы хэша SHA256 выражений URL-адресов суффикс-хост/префикс-путь. Всякий раз, когда клиент хочет проверить определенный URL-адрес, проверка выполняется с использованием локального списка угроз. Если и только если есть совпадение, клиент подключается к серверу для продолжения проверки.

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

Режим реального времени без сохранения данных

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

Всякий раз, когда клиент хочет проверить определенный URL, клиент всегда подключается к серверу для выполнения проверки. Этот режим похож на то, что могут реализовать клиенты v4 Lookup API.

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

Процедура проверки URL в реальном времени

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

Эта процедура принимает один URL u и возвращает SAFE , UNSAFE или UNSURE . Если возвращается SAFE то URL считается безопасным Google Safe Browsing. Если возвращается UNSAFE то URL считается потенциально небезопасным Google Safe Browsing, и следует предпринять соответствующие действия: например, показать предупреждение конечному пользователю, переместить полученное сообщение в папку со спамом или потребовать от пользователя дополнительного подтверждения перед продолжением. Если возвращается UNSURE , то следует использовать следующую процедуру локальной проверки.

  1. Пусть expressions будут списком выражений суффиксов/префиксов, сгенерированных URL-адресом u .
  2. Пусть expressionHashes будет списком, элементами которого являются хеши SHA256 каждого выражения в expressions .
  3. Для каждого hash expressionHashes :
    1. Если hash найден в глобальном кэше, вернуть UNSURE .
  4. Пусть expressionHashPrefixes будет списком, элементами которого являются первые 4 байта каждого хеша в expressionHashes .
  5. Для каждого expressionHashPrefix из expressionHashPrefixes :
    1. Найдите expressionHashPrefix в локальном кэше.
    2. Если кэшированная запись найдена:
      1. Определите, превышает ли текущее время время истечения срока действия.
      2. Если больше:
        1. Удалить найденную кэшированную запись из локального кэша.
        2. Продолжайте петлю.
      3. Если не больше:
        1. Удалить этот конкретный expressionHashPrefix из expressionHashPrefixes .
        2. Проверьте, найден ли в кэшированной записи соответствующий полный хэш в expressionHashes .
        3. Если обнаружено, вернуть UNSAFE .
        4. Если ничего не найдено, продолжайте цикл.
    3. Если кэшированная запись не найдена, продолжайте цикл.
  6. Отправьте expressionHashPrefixes на сервер Google Safe Browsing v5 с помощью RPC SearchHashes или метода REST hashes.search . Если произошла ошибка (включая сетевые ошибки, ошибки HTTP и т. д.), верните UNSURE . В противном случае пусть response будет response , полученным от сервера SB, который представляет собой список полных хэшей вместе с некоторой вспомогательной информацией, идентифицирующей характер угрозы (социальная инженерия, вредоносное ПО и т. д.), а также временем истечения срока действия кэша expiration .
  7. Для каждого fullHash response :
    1. Вставьте fullHash в локальный кэш вместе с expiration .
  8. Для каждого fullHash response :
    1. Пусть isFound будет результатом поиска fullHash в expressionHashes .
    2. Если isFound равен False, продолжайте цикл.
    3. Если isFound имеет значение True, вернуть UNSAFE .
  9. Возврат SAFE .

Хотя этот протокол определяет , когда клиент отправляет expressionHashPrefixes на сервер, этот протокол намеренно не определяет, как именно их отправлять. Например, для клиента приемлемо отправлять все expressionHashPrefixes в одном запросе, а также для клиента приемлемо отправлять каждый отдельный префикс в expressionHashPrefixes на сервер в отдельных запросах (возможно, параллельно). Также приемлемо для клиента отправлять несвязанные или случайно сгенерированные хэш-префиксы вместе с хэш-префиксами в expressionHashPrefixes , пока количество хэш-префиксов, отправленных в одном запросе, не превышает 30.

Процедура проверки URL-адреса LocalThreat List

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

Эта процедура принимает один URL-адрес u и возвращает SAFE или UNSAFE .

  1. Пусть expressions будут списком выражений суффиксов/префиксов, сгенерированных URL-адресом u .
  2. Пусть expressionHashes будет списком, элементами которого являются хеши SHA256 каждого выражения в expressions .
  3. Пусть expressionHashPrefixes будет списком, элементами которого являются первые 4 байта каждого хеша в expressionHashes .
  4. Для каждого expressionHashPrefix из expressionHashPrefixes :
    1. Найдите expressionHashPrefix в локальном кэше.
    2. Если кэшированная запись найдена:
      1. Определите, превышает ли текущее время время истечения срока действия.
      2. Если больше:
        1. Удалить найденную кэшированную запись из локального кэша.
        2. Продолжайте петлю.
      3. Если не больше:
        1. Удалить этот конкретный expressionHashPrefix из expressionHashPrefixes .
        2. Проверьте, найден ли в кэшированной записи соответствующий полный хэш в expressionHashes .
        3. Если обнаружено, вернуть UNSAFE .
        4. Если ничего не найдено, продолжайте цикл.
    3. Если кэшированная запись не найдена, продолжайте цикл.
  5. Для каждого expressionHashPrefix из expressionHashPrefixes :
    1. Найдите expressionHashPrefix в локальной базе данных списков угроз.
    2. Если expressionHashPrefix не найден в локальной базе данных списков угроз, удалите его из expressionHashPrefixes .
  6. Отправьте expressionHashPrefixes на сервер Google Safe Browsing v5 с помощью RPC SearchHashes или метода REST hashes.search . Если произошла ошибка (включая сетевые ошибки, ошибки HTTP и т. д.), верните SAFE . В противном случае пусть response будет response , полученным от сервера SB, который представляет собой список полных хэшей вместе с некоторой вспомогательной информацией, идентифицирующей характер угрозы (социальная инженерия, вредоносное ПО и т. д.), а также временем истечения срока действия кэша expiration .
  7. Для каждого fullHash response :
    1. Вставьте fullHash в локальный кэш вместе с expiration .
  8. Для каждого fullHash response :
    1. Пусть isFound будет результатом поиска fullHash в expressionHashes .
    2. Если isFound равен False, продолжайте цикл.
    3. Если isFound имеет значение True, вернуть UNSAFE .
  9. Возврат SAFE .

Процедура проверки URL в реальном времени без локальной базы данных

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

Эта процедура принимает один URL-адрес u и возвращает SAFE или UNSAFE .

  1. Пусть expressions будут списком выражений суффиксов/префиксов, сгенерированных URL-адресом u .
  2. Пусть expressionHashes будет списком, элементами которого являются хеши SHA256 каждого выражения в expressions .
  3. Пусть expressionHashPrefixes будет списком, элементами которого являются первые 4 байта каждого хеша в expressionHashes .
  4. Для каждого expressionHashPrefix из expressionHashPrefixes :
    1. Найдите expressionHashPrefix в локальном кэше.
    2. Если кэшированная запись найдена:
      1. Определите, превышает ли текущее время время истечения срока действия.
      2. Если больше:
        1. Удалить найденную кэшированную запись из локального кэша.
        2. Продолжайте петлю.
      3. Если не больше:
        1. Удалить этот конкретный expressionHashPrefix из expressionHashPrefixes .
        2. Проверьте, найден ли в кэшированной записи соответствующий полный хэш в expressionHashes .
        3. Если обнаружено, вернуть UNSAFE .
        4. Если ничего не найдено, продолжайте цикл.
    3. Если кэшированная запись не найдена, продолжайте цикл.
  5. Отправьте expressionHashPrefixes на сервер Google Safe Browsing v5 с помощью RPC SearchHashes или метода REST hashes.search . Если произошла ошибка (включая сетевые ошибки, ошибки HTTP и т. д.), верните SAFE . В противном случае пусть response будет response , полученным от сервера SB, который представляет собой список полных хэшей вместе с некоторой вспомогательной информацией, идентифицирующей характер угрозы (социальная инженерия, вредоносное ПО и т. д.), а также временем истечения срока действия кэша expiration .
  6. Для каждого fullHash response :
    1. Вставьте fullHash в локальный кэш вместе с expiration .
  7. Для каждого fullHash response :
    1. Пусть isFound будет результатом поиска fullHash в expressionHashes .
    2. Если isFound равен False, продолжайте цикл.
    3. Если isFound имеет значение True, вернуть UNSAFE .
  8. Возврат SAFE .

Как и процедура проверки URL в реальном времени, эта процедура не определяет, как именно отправлять префиксы хеша на сервер. Например, клиент может отправить все expressionHashPrefixes в одном запросе, а также клиент может отправить каждый отдельный префикс в expressionHashPrefixes на сервер в отдельных запросах (возможно, параллельно). Клиент также может отправлять несвязанные или случайно сгенерированные префиксы хеша вместе с префиксами хеша в expressionHashPrefixes , при условии, что количество префиксов хеша, отправленных в одном запросе, не превышает 30.

Примеры запросов

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

Вот пример HTTP-запроса с использованием метода hashes.search :

GET https://safebrowsing.googleapis.com/v5/hashes:search?key=INSERT_YOUR_API_KEY_HERE&hashPrefixes=WwuJdQ

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

Вот пример HTTP-запроса с использованием метода hashLists.batchGet :

GET https://safebrowsing.googleapis.com/v5/hashLists:batchGet?key=INSERT_YOUR_API_KEY_HERE&names=se&names=mw-4b

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