API обновления безопасного просмотра (v4)

Обзор

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

Прежде чем использовать API обновления, вам необходимо настроить локальную базу данных. Безопасный просмотр предоставляет пакет Go, который вы можете использовать для начала работы. Более подробную информацию см. в разделе «Настройка базы данных» в разделе «Локальные базы данных» .

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

Чтобы оставаться в курсе событий, клиентам необходимо периодически обновлять списки безопасного просмотра в своей локальной базе данных. Чтобы сэкономить пропускную способность, клиенты загружают хеш-префиксы URL-адресов, а не необработанные URL-адреса. Например, если www.badurl.com/ находится в списке безопасного просмотра, клиенты загружают префикс хэша SHA256 этого URL-адреса, а не сам URL-адрес. В большинстве случаев хеш-префиксы имеют длину 4 байта, что означает, что средняя стоимость полосы пропускания для загрузки одной записи списка составляет 4 байта до сжатия.

Чтобы обновить списки безопасного просмотра в локальной базе данных, отправьте HTTP-запрос POST методу ThreatListUpdates.fetch :

  • Запрос HTTP POST включает имена списков, которые необходимо обновить, а также различные ограничения клиента для учета ограничений памяти и пропускной способности.
  • Ответ HTTP POST возвращает либо полное, либо частичное обновление. Ответ также может возвращать минимальную продолжительность ожидания.

Пример: ThreatListUpdates.fetch

HTTP POST-запрос

В следующем примере запрашиваются обновления для одного списка безопасного просмотра.

Заголовок запроса

Заголовок запроса включает URL-адрес запроса и тип контента. Не забудьте заменить API_KEY в URL-адресе на свой ключ API.

POST https://safebrowsing.googleapis.com/v4/threatListUpdates:fetch?key=API_KEY HTTP/1.1
Content-Type: application/json

Тело запроса

Тело запроса включает информацию о клиенте (идентификатор и версию) и информацию об обновлении (имя списка, состояние списка и ограничения клиента). Дополнительные сведения см. в тексте запроса ThreatListUpdates.fetch и пояснениях, следующих за примером кода.

{
  "client": {
    "clientId":       "yourcompanyname",
    "clientVersion":  "1.5.2"
  },
  "listUpdateRequests": [{
    "threatType":      "MALWARE",
    "platformType":    "WINDOWS",
    "threatEntryType": "URL",
    "state":           "Gg4IBBADIgYQgBAiAQEoAQ==",
    "constraints": {
      "maxUpdateEntries":      2048,
      "maxDatabaseEntries":    4096,
      "region":                "US",
      "supportedCompressions": ["RAW"]
    }
  }]
}
Информация о клиенте

Поля clientID и clientVersion должны однозначно идентифицировать реализацию клиента, а не отдельного пользователя. (Информация о клиенте используется при регистрации на стороне сервера. Вы можете выбрать любое имя для идентификатора клиента, но мы предлагаем вам выбрать имя, которое отражает истинную личность клиента, например, название вашей компании, представленное одним словом, во всех -строчные буквы.)

Списки безопасного просмотра

Поля threatType , platformType и threatEntryType объединяются для идентификации (именования) списков безопасного просмотра. В примере указан один список: MALWARE/WINDOWS/URL. Прежде чем отправлять запрос, убедитесь, что указанные вами комбинации типов действительны (см. Списки безопасного просмотра ).

Состояние клиента

Поле state содержит текущее состояние клиента в списке безопасного просмотра. (Состояния клиента возвращаются в поле newClientState ответа ThreatListUpdates.fetch .) Для первоначальных обновлений оставьте поле state пустым.

Ограничения по размеру

Поле maxUpdateEntries указывает общее количество обновлений, которыми может управлять клиент (в примере — 2048). Поле maxDatabaseEntries указывает общее количество записей, которыми может управлять локальная база данных (в примере — 4096). Клиенты должны устанавливать ограничения на размер, чтобы защитить ограничения памяти и пропускной способности, а также предотвратить рост списка. Дополнительные сведения см. в разделе «Ограничения обновления ».

Поддерживаемые сжатия

В поле supportedCompressions перечислены типы сжатия, поддерживаемые клиентом. В этом примере клиент поддерживает только необработанные несжатые данные. Однако безопасный просмотр поддерживает дополнительные типы сжатия (см. Сжатие ).

HTTP POST-ответ

В этом примере ответ возвращает частичное обновление списка безопасного просмотра с использованием запрошенного типа сжатия.

Заголовок ответа

Заголовок ответа включает код состояния HTTP и тип контента. Клиенты, получившие код состояния, отличный от HTTP/200, должны войти в режим отсрочки (см. Частота запросов ).

HTTP/1.1 200 OK
Content-Type: application/json

Тело ответа

Тело ответа включает информацию об обновлении (имя списка, тип ответа, добавления и удаления, которые будут применены к локальной базе данных, новое состояние клиента и контрольную сумму). В этом примере ответ также включает минимальную продолжительность ожидания. Дополнительные сведения см. в тексте ответа ThreatListUpdates.fetch и пояснениях, следующих за примером кода.

{
  "listUpdateResponses": [{
    "threatType":      "MALWARE",
    "threatEntryType": "URL",
    "platformType":    "WINDOWS",
    "responseType" :   "PARTIAL_UPDATE",
    "additions": [{
      "compressionType": "RAW",
      "rawHashes": {
        "prefixSize": 4,
        "rawHashes":  "rnGLoQ=="
      }
    }],
    "removals": [{
      "compressionType": "RAW",
      "rawIndices": {
        "indices": [0, 2, 4]
      }
    }],
    "newClientState": "ChAIBRADGAEiAzAwMSiAEDABEAFGpqhd",
    "checksum": {
      "sha256": "YSgoRtsRlgHDqDA3LAhM1gegEpEzs1TjzU33vqsR8iM="
    }
  }],
  "minimumWaitDuration": "593.440s"
}
Обновления базы данных

Поле responseType будет указывать частичное или полное обновление. В этом примере возвращается частичное обновление, поэтому ответ включает как добавления, так и удаления. Может быть несколько наборов дополнений, но только один набор удалений (см. Обновления базы данных ).

Новое состояние клиента

Поле newClientState содержит новое состояние клиента для недавно обновленного списка безопасного просмотра. Клиенты должны сохранять новое состояние клиента для последующих запросов на обновление (поле state в запросе ThreatListUpdates.fetch или поле clientStates в запросе fullHashes.find ).

Контрольные суммы

Контрольная сумма позволяет клиентам убедиться, что локальная база данных не повреждена. Если контрольная сумма не совпадает, клиент должен очистить базу данных и повторно выпустить обновление с пустым полем state . Однако клиенты в этой ситуации все равно должны соблюдать временные интервалы обновлений (см. Частота запросов ).

Минимальная продолжительность ожидания

Поле minimumWaitDuration указывает, что клиент должен подождать 593,44 секунды (9,89 минуты) перед отправкой следующего запроса на обновление. Обратите внимание, что период ожидания может быть включен или не включен в ответ (см. Частота запросов ).

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

Чтобы проверить, находится ли URL-адрес в списке безопасного просмотра, клиент должен сначала вычислить хэш и префикс хеш-адреса URL-адреса (см. URL-адреса и хеширование ). Затем клиент запрашивает локальную базу данных, чтобы определить, есть ли совпадение. Если префикс хеша отсутствует в локальной базе данных, URL-адрес считается безопасным (не в списках безопасного просмотра).

Если префикс хэша присутствует в локальной базе данных (конфликт префикса хэша), клиент должен отправить префикс хэша на серверы безопасного просмотра для проверки. Серверы вернут все полноразмерные хеши SHA 256, содержащие заданный префикс хэша. Если один из этих полноразмерных хешей совпадает с полноразмерным хешем рассматриваемого URL-адреса, то URL-адрес считается небезопасным. Если ни один из полноразмерных хешей не соответствует полноразмерному хешу рассматриваемого URL-адреса, то этот URL-адрес считается безопасным.

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

Чтобы проверить, находится ли URL-адрес в списке безопасного просмотра, отправьте HTTP-запрос POST методу fullHashes.find :

  • Запрос HTTP POST может включать до 500 записей об угрозах.
  • Запрос HTTP POST включает хеш-префиксы проверяемых URL-адресов. Клиентам рекомендуется объединять несколько записей об угрозах в один запрос, чтобы снизить использование полосы пропускания.
  • Ответ HTTP POST возвращает соответствующие полноразмерные хеши, а также положительную и отрицательную длительность кэша. Ответ также может возвращать минимальную продолжительность ожидания.

Пример: fullHashes.find

HTTP POST-запрос

В следующем примере имена двух списков безопасного просмотра и трех хэш-префиксов отправляются для сравнения и проверки.

Заголовок запроса

Заголовок запроса включает URL-адрес запроса и тип контента. Не забудьте заменить API_KEY в URL-адресе на свой ключ API.

POST https://safebrowsing.googleapis.com/v4/fullHashes:find?key=API_KEY HTTP/1.1
Content-Type: application/json

Тело запроса

Тело запроса включает информацию о клиенте (идентификатор и версию), состояния клиента и информацию об угрозах (имена списков и хэш-префиксы). Для запросов JSON префиксы хэша должны отправляться в форме, закодированной в формате Base64. Дополнительные сведения см. в теле запроса fullHashes.find и пояснениях, следующих за примером кода.

{
  "client": {
    "clientId":      "yourcompanyname",
    "clientVersion": "1.5.2"
  },
  "clientStates": [
    "ChAIARABGAEiAzAwMSiAEDABEAE=",
    "ChAIAhABGAEiAzAwMSiAEDABEOgH"
  ],
  "threatInfo": {
    "threatTypes":      ["MALWARE", "SOCIAL_ENGINEERING"],
    "platformTypes":    ["WINDOWS"],
    "threatEntryTypes": ["URL"],
    "threatEntries": [
      {"hash": "WwuJdQ=="},
      {"hash": "771MOg=="},
      {"hash": "5eOrwQ=="}
    ]
  }
}
Информация о клиенте

Поля clientID и clientVersion должны однозначно идентифицировать реализацию клиента, а не отдельного пользователя. (Информация о клиенте используется при регистрации на стороне сервера. Вы можете выбрать любое имя для идентификатора клиента, но мы предлагаем вам выбрать имя, которое отражает истинную личность клиента, например название вашей компании, представленное одним словом, в только строчные буквы.)

Все состояния клиента

Поле clientStates содержит состояния клиента для всех списков безопасного просмотра в локальной базе данных клиента. (Состояния клиента возвращаются в поле newClientState ответа ThreatListUpdates.fetch .)

Списки безопасного просмотра

Поля threatTypes , platformTypes и threatEntryTypes объединяются для идентификации (именования) списков безопасного просмотра. В примере идентифицируются два списка: MALWARE/WINDOWS/URL и SOCIAL_ENGINEERING/WINDOWS/URL. Прежде чем отправлять запрос, убедитесь, что указанные вами комбинации типов действительны (см. Списки безопасного просмотра ).

Префиксы хэшей угроз

Массив ThreatEntries содержит хеш-префиксы URL-адресов, которые вы хотите проверить. Поле hash должно содержать точный префикс хэша, который присутствует в локальной базе данных. Например, если длина локального хеш-префикса составляет 4 байта, то длина записи об угрозе должна составлять 4 байта. Если локальный хеш-префикс был увеличен до 7 байт, то длина записи об угрозе должна составлять 7 байт.

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

Примечание. API обновления и метод fullHashes.find всегда должны использовать поле hash , а не поле URL адреса (см. ThreatEntry ).

HTTP POST-ответ

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

Заголовок ответа

Заголовок ответа включает код состояния HTTP и тип контента. Клиенты, получившие код состояния, отличный от HTTP/200, должны отключиться (см. Частота запросов ).

HTTP/1.1 200 OK
Content-Type: application/json

Тело ответа

Тело ответа включает информацию о совпадении (имена списков и полные хэши, метаданные, если они доступны, и длительность кэша). В этом примере тело ответа также включает минимальную продолжительность ожидания. Дополнительные сведения см. в теле ответа fullHashes.find и пояснениях, следующих за примером кода.

{
  "matches": [{
    "threatType":      "MALWARE",
    "platformType":    "WINDOWS",
    "threatEntryType": "URL",
    "threat": {
      "hash": "WwuJdQx48jP-4lxr4y2Sj82AWoxUVcIRDSk1PC9Rf-4="
    },
    "threatEntryMetadata": {
      "entries": [{
        "key": "bWFsd2FyZV90aHJlYXRfdHlwZQ==",  // base64-encoded "malware_threat_type"
        "value": "TEFORElORw=="  // base64-encoded "LANDING"
       }]
    },
    "cacheDuration": "300.000s"
  }, {
    "threatType":      "SOCIAL_ENGINEERING",
    "platformType":    "WINDOWS",
    "threatEntryType": "URL",
    "threat": {
      "hash": "771MOrRPMn6xPKlCrXx_CrR-wmCk0LgFFoSgGy7zUiA="
    },
    "threatEntryMetadata": {
      "entries": []
    },
    "cacheDuration": "300.000s"
  }],
  "minimumWaitDuration": "300.000s",
  "negativeCacheDuration": "300.000s"
}
Матчи

Объект Matches возвращает соответствующий полный хэш для двух префиксов хеша. URL-адреса, соответствующие этим хешам, считаются небезопасными. Для третьего префикса хэша не найдено совпадений, поэтому ничего не возвращается; URL-адрес, соответствующий этому хэш-префиксу, считается безопасным.

Обратите внимание, что в этом примере один полный хеш соответствует одному хэш-префиксу; однако может быть несколько полных хешей, которые соответствуют одному и тому же префиксу хеша.

Метаданные

Поле threatEntryMetadata является необязательным и предоставляет дополнительную информацию о совпадении угрозы. В настоящее время метаданные доступны для списка безопасного просмотра MALWARE/WINDOWS/URL (см. Метаданные ).

Длительность кэша

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

Минимальная продолжительность ожидания

Поле minimumWaitDuration указывает, что клиент должен подождать 300 секунд (5 минут) перед отправкой еще одного запроса FullHashes. Обратите внимание, что период ожидания может быть включен или не включен в ответ (см. Частота запросов ).