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 остается доступной .

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

Одним из существенных улучшений Google Safe Browsing v5 по сравнению с v4 (в частности, API обновления v4 ) является актуальность и охват данных. Поскольку защита сильно зависит от локальной базы данных, обслуживаемой клиентом, задержка и размер обновления локальной базы данных являются основной причиной отсутствия защиты. В версии 4 обычному клиенту требуется от 20 до 50 минут для получения самой последней версии списков угроз. К сожалению, фишинговые атаки распространяются быстро: по состоянию на 2021 год 60% сайтов, подвергающихся атакам, живут менее 10 минут. Наш анализ показывает, что около 25–30% случаев отсутствия защиты от фишинга связано с устаревшими данными. Кроме того, некоторые устройства не оснащены для управления всеми списками угроз Google Safe Browsing, которые со временем продолжают расти.

В версии 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.

Надлежащее использование

Разрешенное использование

API безопасного просмотра предназначен только для некоммерческого использования (что означает «не для продажи или получения дохода»). Если вам нужно решение для коммерческих целей, обратитесь к веб-риску .

Цены

Все API безопасного просмотра Google бесплатны.

Квоты

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

Соответствующие URL-адреса

Google Safe Browsing предназначен для воздействия на URL-адреса, которые будут отображаться в адресной строке браузера. Он не предназначен для проверки подресурсов (таких как JavaScript или изображение, на которое ссылается HTML-файл, или URL-адрес WebSocket, инициированный JavaScript). Такие URL-адреса подресурсов не следует проверять на соответствие Google Safe Browsing.

Если посещение URL-адреса приводит к перенаправлению (например, HTTP 301), целесообразно проверить перенаправленный URL-адрес на соответствие Google Safe Browsing. Манипулирование URL-адресами на стороне клиента, такое как History.pushState , не приводит к проверке новых URL-адресов на соответствие Google Safe Browsing.

Предупреждения пользователя

Если вы используете Google Safe Browsing, чтобы предупреждать пользователей о рисках, связанных с определенными веб-страницами, применяются следующие рекомендации.

Эти рекомендации помогают защитить и вас, и Google от недопонимания, поскольку они ясно дают понять, что страница не является со 100% уверенностью небезопасным веб-ресурсом и что предупреждения просто указывают на возможный риск.

• В своем видимом для пользователя предупреждении вы не должны заставлять пользователей поверить в то, что рассматриваемая страница, без сомнения, является небезопасным веб-ресурсом. Когда вы ссылаетесь на идентифицированную страницу или на потенциальные риски, которые она может представлять для пользователей, вы должны квалифицировать предупреждение, используя такие термины, как: подозрительно, потенциально, возможно, вероятно, может быть.
• Ваше предупреждение должно позволить пользователю узнать больше, ознакомившись с определениями различных угроз Google. Предлагаются следующие ссылки:
  • Социальная инженерия: https://developers.google.com/search/docs/monitor-debug/security/social-engineering .
  • Вредоносное и нежелательное программное обеспечение: https://developers.google.com/search/docs/monitor-debug/security/malware .
  • Потенциально опасные приложения (только для Android): https://developers.google.com/android/play-protect/potentially-harmful-applications.
• Когда вы показываете предупреждения для страниц, определенных Службой безопасного просмотра как опасные, вы должны указать ссылку на Google, включив строку «Рекомендации, предоставленные Google» со ссылкой на рекомендации по безопасному просмотру . Если ваш продукт также отображает предупреждения, основанные на других источниках, вы не должны включать атрибуцию Google в предупреждения, полученные на основе данных, не принадлежащих Google.

• В документации к вашему продукту вы должны предоставить уведомление, информирующее пользователей о том, что защита, обеспечиваемая безопасным просмотром Google, не идеальна. Он должен сообщить им, что существует вероятность как ложноположительных результатов (безопасные сайты помечены как опасные), так и ложноотрицательных (рискованные сайты не помечены). Мы предлагаем использовать следующий язык:

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

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

Проверка URL-адресов

В этом разделе содержатся подробные сведения о том, как клиенты проверяют URL-адреса.

Канонизация URL-адресов

Прежде чем какие-либо URL-адреса будут проверены, ожидается, что клиент выполнит некоторую канонизацию этого URL-адреса.

Для начала мы предполагаем, что клиент проанализировал URL-адрес и сделал его действительным в соответствии с RFC 2396. Если URL-адрес использует интернационализированное доменное имя (IDN), клиент должен преобразовать URL-адрес в представление Punycode ASCII. URL-адрес должен включать компонент пути; то есть после домена должна быть хотя бы одна косая черта ( http://google.com/ вместо http://google.com ).

Сначала удалите из URL-адреса символы табуляции (0x09), CR (0x0d) и LF (0x0a). Не удаляйте escape-последовательности для этих символов (например, %0a ).

Во-вторых, если URL-адрес заканчивается фрагментом, удалите этот фрагмент. Например, сократите http://google.com/#frag до http://google.com/ .

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

Чтобы канонизировать имя хоста:

Извлеките имя хоста из URL-адреса, а затем:

1. Удалите все ведущие и конечные точки.
2. Замените последовательные точки одной точкой.
3. Если имя хоста можно проанализировать как адрес IPv4, нормализуйте его до 4 десятичных значений, разделенных точками. Клиент должен обрабатывать любую допустимую кодировку IP-адреса, включая восьмеричную, шестнадцатеричную и менее четырех компонентов.
4. Если имя хоста можно проанализировать как IPv6-адрес в скобках, нормализуйте его, удалив ненужные начальные нули в компонентах и ​​свернув нулевые компоненты, используя синтаксис двойного двоеточия. Например, [2001:0db8:0000::1] следует преобразовать в [2001:db8::1] . Если имя хоста является одним из двух следующих специальных типов адресов IPv6, преобразуйте их в IPv4:
   • Адрес IPv6, сопоставленный с IPv4, например [::ffff:1.2.3.4] , который должен быть преобразован в 1.2.3.4 ;
   • Адрес NAT64 с известным префиксом 64:ff9b::/96 , например [64:ff9b::1.2.3.4] , который следует преобразовать в 1.2.3.4 .
5. В нижнем регистре всю строку.

Чтобы канонизировать путь:

1. Разрешите последовательности /../ и /./ в пути, заменив /./ на / и удалив /../ вместе с предыдущим компонентом пути.
2. Замените серию последовательных косых черт одним символом косой черты.

Не применяйте канонизацию пути к параметрам запроса.

В URL-адресе экранируйте процентами все символы <= ASCII 32, >= 127, # или % . В escape-последовательности следует использовать шестнадцатеричные символы верхнего регистра.

Выражения префикса пути и суффикса хоста

После канонизации URL-адреса следующим шагом будет создание выражений суффикса/префикса. Каждое выражение суффикса/префикса состоит из суффикса хоста (или полного хоста) и префикса пути (или полного пути).

Клиент сформирует до 30 различных возможных комбинаций суффикса хоста и префикса пути. Эти комбинации используют только компоненты хоста и пути URL-адреса. Схема, имя пользователя, пароль и порт удаляются. Если URL-адрес включает параметры запроса, то хотя бы одна комбинация будет включать полный путь и параметры запроса.

Для хоста клиент будет пробовать не более пяти разных строк. Они есть:

• Если имя хоста не является литералом IPv4 или IPv6, до четырех имен хостов формируются путем начала с домена eTLD+1 и последовательного добавления ведущих компонентов. Определение eTLD+1 должно основываться на списке общедоступных суффиксов . Например, abexample.com приведет к домену eTLD+1 example.com , а также к хосту с одним дополнительным компонентом хоста b.example.com .
• Точное имя хоста в URL. Следуя предыдущему примеру, будет проверен abexample.com .

Для пути клиент попробует не более шести разных строк. Они есть:

• Точный путь URL-адреса, включая параметры запроса.
• Точный путь URL-адреса без параметров запроса.
• Четыре пути формируются путем начала с корня (/) и последовательного добавления компонентов пути, включая косую черту в конце.

Следующие примеры иллюстрируют поведение проверки:

Для URL-адреса http://abcom/1/2.html?param=1 клиент попытается использовать следующие возможные строки:

a.b.com/1/2.html?param=1
a.b.com/1/2.html
a.b.com/
a.b.com/1/
b.com/1/2.html?param=1
b.com/1/2.html
b.com/
b.com/1/

Для URL-адреса http://abcdefcom/1.html клиент будет пробовать следующие возможные строки:

a.b.c.d.e.f.com/1.html
a.b.c.d.e.f.com/
c.d.e.f.com/1.html
c.d.e.f.com/
d.e.f.com/1.html
d.e.f.com/
e.f.com/1.html
e.f.com/
f.com/1.html
f.com/

(Примечание: пропустите bcdefcom , поскольку мы возьмем только пять последних компонентов имени хоста и полное имя хоста.)

Для URL-адреса http://1.2.3.4/1/ клиент попробует следующие возможные строки:

1.2.3.4/1/
1.2.3.4/

Для URL-адреса http://example.co.uk/1 клиент будет пробовать следующие возможные строки:

example.co.uk/1
example.co.uk/

Хеширование

Google Safe Browsing использует исключительно SHA256 в качестве хэш-функции. Эту хэш-функцию следует применить к приведенным выше выражениям.

Полный 32-байтовый хэш будет, в зависимости от обстоятельств, сокращен до 4, 8 или 16 байт:

• При использовании метода hashes.search мы в настоящее время требуем, чтобы хеши в запросе были усечены ровно до 4 байт. Отправка дополнительных байтов в этом запросе поставит под угрозу конфиденциальность пользователя.

• При загрузке списков для локальной базы данных с помощью метода hashList.get или метода hashLists.batchGet на длину хешей, отправляемых сервером, влияет как природа списка, так и предпочтения клиента в отношении длины хеша, передаваемые параметр desired_hash_length .

Процедура проверки 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.

Обслуживание локальной базы данных

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

Обновления базы данных

Клиент будет регулярно вызывать метод hashList.get или метод hashLists.batchGet для обновления базы данных. Поскольку типичный клиент захочет обновить несколько списков одновременно, рекомендуется использовать метод hashLists.batchGet .

Списки идентифицируются по своим отдельным именам. Имена представляют собой короткие строки ASCII длиной в несколько символов.

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

После того, как имя было выбрано для списка, он никогда не будет переименован. Более того, если список появился, он никогда не будет удален (если список перестанет быть полезным, он станет пустым, но продолжит существовать). Поэтому целесообразно жестко запрограммировать эти имена в клиентском коде Google Safe Browsing.

И метод hashList.get , и метод hashLists.batchGet поддерживают инкрементные обновления. Использование дополнительных обновлений экономит полосу пропускания и повышает производительность. Инкрементные обновления работают путем предоставления разницы между версией списка клиента и последней версией списка. (Если клиент развернут недавно и у него нет доступных версий, доступно полное обновление.) Инкрементное обновление содержит индексы удаления и дополнения. Ожидается, что клиент сначала удалит записи по указанным индексам из своей локальной базы данных, а затем применит дополнения.

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

Декодирование содержимого списка

Все списки доставляются с использованием специальной кодировки для уменьшения размера. Эта кодировка работает, признавая, что списки безопасного просмотра Google концептуально содержат набор хэшей или хэш-префиксов, которые статистически неотличимы от случайных целых чисел. Если бы нам пришлось отсортировать эти целые числа и взять соседнюю разность, то ожидается, что такая смежная разница будет в некотором смысле «маленькой». Кодирование Голомба-Райса затем использует эту малость.

Google Safe Browsing v5 имеет четыре различных типа для обработки 4-байтовых данных, 8-байтовых данных, 16-байтовых данных и 32-байтовых данных. Давайте рассмотрим пример, в котором закодированы три последовательных 4-байтовых целых числа. Пусть параметр Райса, обозначаемый k, равен 3. Частная часть кодирования — это просто значение соседней разности, сдвинутое вправо на k бит. Поскольку данные целые числа являются последовательными, их соседняя разность равна 1, а после сдвига на 3 бита частная часть равна нулю. Младшие k битов — это 001. Нулевое частное кодируется как один нулевой бит. Остаток равен 1 и кодируется как 100. Это повторяется еще раз, чтобы сформировать битовый поток 01000100. Результирующий битовый поток кодируется с прямым порядком байтов как 00100010. Следовательно, он соответствует следующим данным:

rice_parameter: 3
entries_count: 2
encoded_data: "\x22"

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

Доступные списки

Следующие списки рекомендуются для использования в v5alpha1:

Имя списка	Соответствующее перечисление ThreatType v4	Описание
gc	Никто	Этот список представляет собой список глобального кэша. Это специальный список, используемый только в режиме реального времени.
se	SOCIAL_ENGINEERING	В этом списке содержатся угрозы типа SOCIAL_ENGINEERING.
mw	MALWARE	В этом списке содержатся угрозы типа ВРЕДОНОСНОЕ ПО для настольных платформ.
uws	UNWANTED_SOFTWARE	В этом списке содержатся угрозы типа UNWANTED_SOFTWARE для настольных платформ.
uwsa	UNWANTED_SOFTWARE	В этом списке содержатся угрозы типа UNWANTED_SOFTWARE для платформ Android.
pha	POTENTIALLY_HARMFUL_APPLICATION	В этом списке содержатся угрозы типа POTENTIALLY_HARMFUL_APPLICATION для платформ Android.

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

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

Частота обновления

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

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

В этом разделе описаны некоторые примеры прямого использования 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

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

Руководство по миграции

Если вы в настоящее время используете API обновления версии 4 , существует простой путь перехода с версии 4 на версию 5 без необходимости сброса или удаления локальной базы данных. В этом разделе описано, как это сделать.

Преобразование обновлений списка

В версии 4 для загрузки списков можно было использовать метод ThreatListUpdates.fetch . В v5 можно было бы переключиться на метод hashLists.batchGet .

В запрос необходимо внести следующие изменения:

1. Полностью удалите объект ClientInfo v4 . Вместо того, чтобы предоставлять идентификацию клиента с помощью специального поля, просто используйте известный заголовок User-Agent . Хотя не существует предписанного формата для предоставления идентификатора клиента в этом заголовке, мы предлагаем просто включать исходный идентификатор клиента и версию клиента, разделенные пробелом или косой чертой.
2. Для каждого объекта ListUpdateRequest версии 4 :
   • Найдите соответствующее имя списка версии 5 в таблице выше и укажите это имя в запросе версии 5.
   • Удалите ненужные поля, такие как threat_entry_type или platform_type .
   • Поле state в версии 4 напрямую совместимо с полем versions 5. Ту же самую строку байтов, которая будет отправлена ​​на сервер с использованием поля state в версии 4, можно просто отправить в версии 5 с использованием поля versions .
   • Для ограничений версии 4 версия 5 использует упрощенную версию под названием SizeConstraints . Дополнительные поля, такие как region следует удалить.

В ответ необходимо внести следующие изменения:

1. Перечисление ResponseType версии 4 просто заменяется логическим полем с именем partial_update .
2. Поле minimum_wait_duration теперь может быть нулевым или опущено. Если это так, клиенту предлагается немедленно сделать еще один запрос. Это происходит только тогда, когда клиент указывает в SizeConstraints меньшее ограничение на максимальный размер обновления, чем максимальный размер базы данных.
3. Алгоритм декодирования Райса для 32-битных целых чисел необходимо будет скорректировать. Разница в том, что закодированные данные кодируются с другим порядком байтов. И в версии 4, и в версии 5 32-битные хеш-префиксы сортируются лексикографически. Но в версии 4 эти префиксы при сортировке обрабатываются как с прямым порядком байтов, тогда как в версии 5 эти префиксы при сортировке обрабатываются как с прямым порядком байтов. Это означает, что клиенту не нужно выполнять какую-либо сортировку, поскольку лексикографическая сортировка идентична числовой сортировке с прямым порядком байтов. Пример такого рода в реализации Chromium v4 можно найти здесь . Такую сортировку можно убрать.
4. Алгоритм декодирования Райса необходимо будет реализовать для других длин хеша.

Преобразование хэш-поиска

В версии 4 для получения полных хешей можно было бы использовать метод fullHashes.find . Эквивалентным методом в v5 является метод hashes.search .

В запрос необходимо внести следующие изменения:

1. Структурируйте код так, чтобы отправлять только хеш-префиксы длиной ровно 4 байта.
2. Полностью удалите объекты ClientInfo v4 . Вместо того, чтобы предоставлять идентификацию клиента с помощью выделенного поля, просто используйте известный заголовок User-Agent . Хотя не существует предписанного формата для предоставления идентификатора клиента в этом заголовке, мы предлагаем просто включать исходный идентификатор клиента и версию клиента, разделенные пробелом или косой чертой.
3. Удалите поле client_states . В этом больше нет необходимости.
4. Больше нет необходимости включать threat_types и подобные поля.

В ответ необходимо внести следующие изменения:

1. Поле minimum_wait_duration было удалено. Клиент всегда может выпустить новый запрос на необходимости.
2. Объект v4 ThreatMatch был упрощен в объект FullHash .
3. Кэширование было упрощено в одну продолжительность кэша. См. Приведенные выше процедуры для взаимодействия с кэшем.