Migration From V4

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

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

Обновление списка конвертации

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

В версии 4 для загрузки списков использовался метод threatListUpdates.fetch . В версии 5 — метод hashLists.batchGet .

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

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

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

  1. Перечисление v4 ResponseType просто заменяется логическим полем с именем partial_update .
  2. Поле minimum_wait_duration теперь может быть равно нулю или опущено. Если это так, клиенту предлагается немедленно выполнить другой запрос. Это происходит только в том случае, если клиент указывает в SizeConstraints ограничение на максимальный размер обновления меньше максимального размера базы данных.
  3. Логика декодирования хэшей, закодированных по алгоритму Райса-Голомба, требует двух основных корректировок:
    • Порядок байтов и сортировка: В версии 4 возвращаемые хеши сортировались как значения с прямым порядком байтов (little endian). В версии 5 они обрабатываются как значения с обратным порядком байтов (big endian). Поскольку лексикографическая сортировка байтовых строк эквивалентна числовой сортировке значений с обратным порядком байтов (big endian), клиентам больше не нужно выполнять специальный этап сортировки. Пользовательскую сортировку с прямым порядком байтов (little endian), подобную той, что реализована в Chromium v4 , можно удалить, если она ранее была реализована.
    • Переменные длины хешей: Алгоритм декодирования должен быть обновлён для поддержки различных длин хешей, которые могут быть возвращены в поле HashList.compressed_additions , а не только четырёхбайтовой длины, используемой в версии 4. Длину хешей, возвращаемых в ответе, можно определить на основе значения HashList.metadata.hash_length возвращаемого из hashLists.list . Кроме того, название запрашиваемого списка хешей также указывает на ожидаемые размеры хешей, возвращаемых из списка. Подробнее о списках хешей см. на странице «Локальная база данных» .

Конвертация хэш-поиска

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

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

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

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

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