SafetyNet Safe Browsing API

SafetyNet Safe Browsing API – это библиотека, которая работает на основе сервисов Google Play и позволяет определить, помечен ли URL как известная угроза.

С помощью этого API ваше приложение может определить, классифицирован ли определенный URL как известная угроза. В SafetyNet встроен клиент для сетевого протокола Безопасного просмотра версии 4, разработанного Google. Клиентский код и сетевой протокол версии 4 разработаны таким образом, чтобы обеспечивать конфиденциальность пользователей и минимально расходовать заряд батареи и трафик. Используйте этот API, чтобы в полной мере воспользоваться преимуществами сервиса "Безопасный просмотр" на устройствах Android, не реализуя его сетевой протокол и оптимизируя использование ресурсов.

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

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

Условия использования

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

Как запросить и зарегистрировать ключ API Android

Прежде чем использовать Safe Browsing API, создайте и зарегистрируйте ключ Android API. Подробнее о том, как начать работу с Безопасным просмотром…

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

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

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

Инициализация API

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

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

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

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

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

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

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

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

и

var url = "www.google.com"

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}")
           }
       }

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.

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

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

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

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

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

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

SafetyNet.getClient(this).shutdownSafeBrowsing()

SafetyNet.getClient(this).shutdownSafeBrowsing();

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

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

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

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

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

Данные, собираемые SafetyNet Safe Browsing API

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

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

Мы постарались максимально полно описать работу SDK, однако вы несете единоличную ответственность за то, какую информацию о сборе, передаче и защите пользовательских данных вы добавляете в раздел безопасности данных Google Play.