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-адрес в представление ASCII Punycode. 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 концептуально содержат набор хэшей или хэш-префиксов, которые статистически неотличимы от случайных целых чисел. Если бы нам пришлось отсортировать эти целые числа и взять соседнюю разность, то ожидается, что такая смежная разница будет в некотором смысле «маленькой». Кодирование Голомба-Райса затем использует эту малость.

Предположим, что три выражения префикса пути суффикса хоста, а именно a.example.com/ , b.example.com/ и y.example.com/ , должны передаваться с использованием 4-байтовых хэш-префиксов. Далее предположим, что параметр Райса, обозначаемый k, выбран равным 30. Сервер начнет с вычисления полного хеша для этих строк, которые соответственно:

291bc5421f1cd54d99afcc55d166e2b9fe42447025895bf09dd41b2110a687dc  a.example.com/
1d32c5084a360e58f1b87109637a6810acad97a861a7769e8f1841410d2a960c  b.example.com/
f7a502e56e8b01c6dc242b35122683c9d25d07fb1f532d9853eb0ef3ff334f03  y.example.com/

Затем сервер формирует 4-байтовые префиксы хеша для каждого из вышеперечисленных, которые представляют собой первые 4 байта 32-байтового полного хэша, интерпретируемые как 32-битные целые числа с прямым порядком байтов. Большой порядок байтов относится к тому факту, что первый байт полного хеша становится самым значимым байтом 32-битного целого числа. Результатом этого шага являются целые числа 0x291bc542, 0x1d32c508 и 0xf7a502e5.

Серверу необходимо лексикографически отсортировать эти три хэш-префикса (эквивалентно числовой сортировке с прямым порядком байтов), и результатом сортировки будет 0x1d32c508, 0x291bc542, 0xf7a502e5. Первый префикс хеша сохраняется без изменений в поле first_value .

Затем сервер вычисляет две соседние разницы: 0xbe9003a и 0xce893da3 соответственно. Учитывая, что k выбрано равным 30, сервер разбивает эти два числа на частную и остаточную части длиной 2 и 30 бит соответственно. Для первого числа частная часть равна нулю, а остаток равен 0xbe9003a; для второго числа частная часть равна 3, поскольку два старших бита равны 11 в двоичном формате, а остаток равен 0xe893da3. Для данного частного q оно кодируется в (1 << q) - 1 используя ровно 1 + q бит; остаток кодируется напрямую с использованием k бит. Частная часть первого числа кодируется как 0, а оставшаяся часть имеет двоичный код 001011111010010000000000111010; Частная часть второго числа кодируется как 0111, а оставшаяся часть — 001110100010010011110110100011.

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

001110100010010011110110100011 # Second number, remainder part
0111 # Second number, quotient part
001011111010010000000000111010 # First number, remainder part
0 # First number, quotient part

Написанное в одну строку, это будет

00111010001001001111011010001101110010111110100100000000001110100

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

0 01110100 01001001 11101101 00011011 10010111 11010010 00000000 01110100

Кодировка с прямым порядком байтов затем берет каждый байт справа и помещает его в строку байтов:

01110100
00000000
11010010
10010111
00011011
11101101
01001001
01110100
00000000

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

В конечном итоге это приводит к

additions_four_bytes {
  first_value: 489866504
  rice_parameter: 30
  entries_count: 2
  encoded_data: "t\000\322\227\033\355It\000"
}

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

Декодирование индексов удаления

Индексы удаления кодируются с использованием той же методики, что и выше, с использованием 32-битных целых чисел. Кодировка и декодирование индексов удаления не изменились между v4 и v5.

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

Следующие списки рекомендуются для использования в 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 обновления v4 , существует простой путь перехода с v4 на v5 без необходимости сброса или удаления локальной базы данных. В этом разделе описано, как это сделать.

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

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

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

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

Следующие изменения должны быть внесены в ответ:

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

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

В V4 можно было бы использовать метод Fullhashes.find , чтобы получить полный хэши. Эквивалентный метод в V5 - это метод HASE.Search .

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

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

Следующие изменения должны быть внесены в ответ:

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