Overview

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

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

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

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

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

IP-конфиденциальность

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

Одновременно с версией 5 мы представляем сопутствующий API, известный как API безопасного просмотра Oblivious HTTP Gateway. При этом используется 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 обновления версии 4, за исключением использования улучшенной поверхности API версии 5. Клиенты будут хранить в своей локальной базе данных набор списков угроз, отформатированных как хэш-префиксы SHA256 выражений URL-адресов суффикса хоста/префикса пути. Всякий раз, когда клиент желает проверить определенный URL-адрес, проверка выполняется с использованием локального списка угроз. Если и только если есть совпадение, клиент подключается к серверу, чтобы продолжить проверку.

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

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

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

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

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

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

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

Эта процедура принимает один URL-адрес u и возвращает SAFE , UNSAFE или UNSURE . Если он возвращает SAFE URL-адрес считается безопасным с точки зрения безопасного просмотра Google. Если он возвращает UNSAFE URL-адрес считается потенциально небезопасным безопасным просмотром Google, и необходимо предпринять соответствующие действия: например, показать предупреждение конечному пользователю, переместить полученное сообщение в папку со спамом или потребовать от пользователя дополнительного подтверждения перед продолжением. Если он возвращает 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 , полученный от сервера 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

Эта процедура используется, когда клиент выбирает режим работы локального списка. Он также используется, когда клиент описанная выше процедура 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 , полученный от сервера 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 , полученный от сервера 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. Обычно рекомендуется использовать сгенерированную языковую привязку, поскольку она автоматически обрабатывает кодирование и декодирование удобным способом. Пожалуйста, обратитесь к документации по этой привязке.

Вот пример 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/v5alpha1/hashLists:batchGet?key=INSERT_YOUR_API_KEY_HERE&names=se&names=mw-4b

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