API безопасного просмотра SafetyNet

Библиотека SafetyNet Safe Browsing API, работающая на базе сервисов Google Play , предоставляет инструменты для определения того, помечен ли URL-адрес компанией Google как известная угроза.

Ваше приложение может использовать этот API для определения того, классифицирован ли Google конкретный URL-адрес как известную угрозу. Внутри SafetyNet реализован клиент для протокола Safe Browsing Network Protocol v4, разработанного Google. И клиентский код, и сетевой протокол v4 были разработаны для сохранения конфиденциальности пользователей и минимизации потребления заряда батареи и трафика. Используйте этот API, чтобы в полной мере воспользоваться преимуществами сервиса Safe Browsing от Google на Android с оптимальным использованием ресурсов и без необходимости реализации его сетевого протокола.

В новой версии 5 (v5) внесены значительные улучшения в актуальность данных и конфиденциальность благодаря использованию протокола Oblivious HTTP .

В этом документе объясняется, как использовать API SafetyNet Safe Browsing Lookup для проверки URL-адреса на наличие известных угроз.

Условия предоставления услуг

Используя API безопасного просмотра, вы соглашаетесь соблюдать Условия предоставления услуг . Перед использованием API безопасного просмотра ознакомьтесь со всеми применимыми условиями и политиками.

Запросите и зарегистрируйте ключ API для Android.

Перед использованием API безопасного просмотра создайте и зарегистрируйте ключ API для Android. Подробные инструкции см. на странице, посвященной началу работы с безопасным просмотром .

В версии 5 этот ключ API указывается при создании экземпляра SafeBrowsingClient .

Добавьте зависимость от SafetyNet API.

Перед использованием API безопасного просмотра добавьте API SafetyNet в свой проект. Если вы используете Android Studio, добавьте эту зависимость в файл Gradle на уровне приложения. Для получения дополнительной информации см. раздел «Защита от угроз безопасности с помощью SafetyNet» .

Инициализируйте API.

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

Котлин 

Tasks.await(SafetyNet.getClient(this).initSafeBrowsing)

Java 

Tasks.await(SafetyNet.getClient(this).initSafeBrowsing);

В версии 5 GmsCore предлагает клиент безопасного просмотра. Вам необходимо получить экземпляр SafeBrowsingClient . Мы оптимизировали интерфейс API для повышения эффективности и уменьшения избыточности.

// Draft interface for the new client
public interface SafeBrowsingClient extends HasApiKey<SafeBrowsingApiOptions> {
  Task<SafeBrowsingResponse> lookupUri(String uri, @ThreatType List<Integer> threatTypes, @Protocol int protocol);
  Task<SupportedThreatTypesResponse> getSupportedThreatTypes();
}

Запросить проверку URL-адреса

Используйте метод lookupUri , чтобы проверить, представляет ли URI угрозу. Необходимо указать предполагаемый протокол, который может быть либо локальным списком блокировки (v4), либо протоколом защиты в реальном времени (v5).

Отправьте запрос на проверку URL-адреса.

API не зависит от используемой схемы, поэтому вы можете передавать URL-адрес как со схемой, так и без нее. Например, оба варианта.

Котлин 

var url = "https://www.google.com"

Java 

String url = "https://www.google.com";

и

Котлин 

var url = "www.google.com"

Java 

String url = "www.google.com";

являются действительными.

Следующий код демонстрирует, как отправить запрос на проверку URL-адреса:

Котлин 

SafetyNet.getClient(this).lookupUri(
       url,
       SAFE_BROWSING_API_KEY,
       SafeBrowsingThreat.TYPE_POTENTIALLY_HARMFUL_APPLICATION,
       SafeBrowsingThreat.TYPE_SOCIAL_ENGINEERING
)
       .addOnSuccessListener(this) { sbResponse ->
           // Indicates communication with the service was successful.
           // Identify any detected threats.
           if (sbResponse.detectedThreats.isEmpty()) {
               // No threats found.
           } else {
               // Threats found!
           }
       }
       .addOnFailureListener(this) { e: Exception ->
           if (e is ApiException) {
               // An error with the Google Play services API contains some
               // additional details.
               Log.d(TAG, "Error: ${CommonStatusCodes.getStatusCodeString(e.statusCode)}")

               // Note: If the status code, s.statusCode,
               // is SafetyNetStatusCode.SAFE_BROWSING_API_NOT_INITIALIZED,
               // you need to call initSafeBrowsing(). It means either you
               // haven't called initSafeBrowsing() before or that it needs
               // to be called again due to an internal error.
           } else {
               // A different, unknown type of error occurred.
               Log.d(TAG, "Error: ${e.message}")
           }
       }

Java 

SafetyNet.getClient(this).lookupUri(url,
         SAFE_BROWSING_API_KEY,
         SafeBrowsingThreat.TYPE_POTENTIALLY_HARMFUL_APPLICATION,
         SafeBrowsingThreat.TYPE_SOCIAL_ENGINEERING)
   .addOnSuccessListener(this,
       new OnSuccessListener<SafetyNetApi.SafeBrowsingResponse>() {
           @Override
           public void onSuccess(SafetyNetApi.SafeBrowsingResponse sbResponse) {
               // Indicates communication with the service was successful.
               // Identify any detected threats.
               if (sbResponse.getDetectedThreats().isEmpty()) {
                   // No threats found.
               } else {
                   // Threats found!
               }
        }
   })
   .addOnFailureListener(this, new OnFailureListener() {
           @Override
           public void onFailure(@NonNull Exception e) {
               // An error occurred while communicating with the service.
               if (e instanceof ApiException) {
                   // An error with the Google Play services API contains some
                   // additional details.
                   ApiException apiException = (ApiException) e;
                   Log.d(TAG, "Error: " + CommonStatusCodes
                       .getStatusCodeString(apiException.getStatusCode()));

                   // Note: If the status code, apiException.getStatusCode(),
                   // is SafetyNetStatusCode.SAFE_BROWSING_API_NOT_INITIALIZED,
                   // you need to call initSafeBrowsing(). It means either you
                   // haven't called initSafeBrowsing() before or that it needs
                   // to be called again due to an internal error.
               } else {
                   // A different, unknown type of error occurred.
                   Log.d(TAG, "Error: " + e.getMessage());
               }
           }
   });

Обновленная сигнатура lookupUri принимает URI, список типов угроз и протокол. 

val threatTypes = listOf(ThreatType.TYPE_SOCIAL_ENGINEERING, ThreatType.TYPE_MALWARE)
val protocol = Protocol.REAL_TIME // or Protocol.LOCAL_BLOCK_LIST

safeBrowsingClient.lookupUri(url, threatTypes, protocol)
    .addOnSuccessListener { response ->
        if (response.detectedThreats.isEmpty()) {
            // No threats found
        } else {
            // Threats detected!
        }
    }

Прочитайте ответ проверки URL-адреса.

Используя возвращенный объект SafetyNetApi.SafeBrowsingResponse , вызовите его метод getDetectedThreats , который возвращает список объектов SafeBrowsingThreat . Если возвращенный список пуст, API не обнаружил ни одной известной угрозы. Если список не пуст, вызовите getThreatType для каждого элемента списка, чтобы определить, какие известные угрозы были обнаружены API.

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

Укажите интересующие вас типы угроз.

Константы класса SafeBrowsingThreat содержат список поддерживаемых в настоящее время типов угроз:

тип угрозы Определение
TYPE_POTENTIALLY_HARMFUL_APPLICATION Этот тип угроз идентифицирует URL-адреса страниц, помеченных как содержащие потенциально вредоносные приложения.
TYPE_SOCIAL_ENGINEERING Этот тип угроз идентифицирует URL-адреса страниц, помеченных как содержащие угрозы социальной инженерии.

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

Завершите сеанс безопасного просмотра.

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

Котлин 

SafetyNet.getClient(this).shutdownSafeBrowsing()

Java 

SafetyNet.getClient(this).shutdownSafeBrowsing();

Мы рекомендуем вызывать shutdownSafeBrowsing в методе onPause вашей активности и initSafeBrowsing в методе onResume . Однако убедитесь, что initSafeBrowsing завершил выполнение перед вызовом lookupUri Гарантируя, что ваша сессия всегда актуальна, вы снижаете вероятность внутренних ошибок в вашем приложении.

Подробная информация о защите в режиме реального времени

В обновлении v5 представлен режим защиты в реальном времени , который обходит проблемы устаревания данных (которые в версии v4 могли достигать 20-50 минут). Он переходит от протокола «разрешение по умолчанию» к протоколу «проверка по умолчанию» , повышая защиту от быстро распространяющихся угроз. В режиме реального времени клиенты поддерживают локальную базу данных и глобальный кэш потенциально безопасных сайтов , обеспечивая защиту практически в реальном времени с использованием самых свежих данных об угрозах.

Поддерживаемые типы угроз

API позволяет выбрать, какие типы угроз важны для ваших нужд. API версии 5 поддерживает более широкий спектр типов угроз:

Тип угрозы Постоянный Описание
НЕТ УГРОЗЫ Угрозы нет.
TYPE_MALWARE Общие угрозы вредоносного ПО.
TYPE_UNWANTED_SOFTWARE Нежелательное программное обеспечение или приложения.
TYPE_POTENTIALLY_HARMFUL_APPLICATION Приложения, которые могут нанести вред устройству или пользователю.
TYPE_SOCIAL_ENGINEERING Фишинговые и другие мошеннические сайты.
TYPE_TRICK_TO_BILL Страницы, которые обманом заставляют пользователей совершать платежи.
TYPE_BETTER_ADS_VIOLATION Сайты, нарушающие стандарты качества рекламы.
TYPE_MALWARE_OFFLINE Вредоносное ПО, работающее в автономном режиме.
TYPE_ABUSIVE_EXPERIENCE_VIOLATION Нарушения, приводящие к негативному опыту для пользователя.
TYPE_HIGH_CONFIDENCE_ALLOW_LIST Список разрешенных объектов с высокой степенью достоверности

Данные, собранные с помощью API SafetyNet Safe Browsing.

API SafetyNet Safe Browsing автоматически собирает следующие данные при взаимодействии со службой Safe Browsing на Android:

Данные Описание
Активность приложения Собирает префиксы хеша URL-адресов после совпадения с локальным префиксом хеша с целью обнаружения вредоносных URL-адресов.

API SafetyNet Safe Browsing собирает хеш-префикс URL-адресов для обнаружения вредоносных URL-адресов. В версии 5 реализован протокол Oblivious HTTP для дополнительной защиты пользовательских данных во время таких запросов.

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