SafetyNet Safe Browsing API

API مرور ایمن SafetyNet، کتابخانه‌ای که توسط سرویس‌های Google Play پشتیبانی می‌شود، خدماتی را برای تعیین اینکه آیا یک URL توسط Google به عنوان یک تهدید شناخته شده علامت‌گذاری شده است یا خیر، ارائه می‌دهد.

برنامه شما می‌تواند از این API برای تعیین اینکه آیا یک URL خاص توسط گوگل به عنوان یک تهدید شناخته شده طبقه‌بندی شده است یا خیر، استفاده کند. SafetyNet در داخل خود، یک کلاینت برای پروتکل شبکه مرور ایمن نسخه ۴ که توسط گوگل توسعه داده شده است، پیاده‌سازی می‌کند. هم کد کلاینت و هم پروتکل شبکه نسخه ۴ برای حفظ حریم خصوصی کاربران و به حداقل رساندن مصرف باتری و پهنای باند طراحی شده‌اند. از این API برای بهره‌برداری کامل از سرویس مرور ایمن گوگل در اندروید با بهینه‌ترین روش از نظر منابع و بدون پیاده‌سازی پروتکل شبکه آن استفاده کنید.

به‌روزرسانی جدید نسخه ۵ (v5) با استفاده از Oblivious HTTP ، پیشرفت‌های قابل توجهی در تازگی داده‌ها و حفظ حریم خصوصی ارائه می‌دهد.

این سند نحوه استفاده از API جستجوی مرور ایمن SafetyNet را برای بررسی یک URL برای تهدیدهای شناخته شده توضیح می‌دهد.

شرایط خدمات

با استفاده از رابط برنامه‌نویسی کاربردی مرور ایمن، شما موافقت می‌کنید که تابع شرایط خدمات باشید. قبل از دسترسی به رابط برنامه‌نویسی کاربردی مرور ایمن، تمام شرایط و سیاست‌های مربوطه را مطالعه و درک کنید.

درخواست و ثبت کلید API اندروید

قبل از استفاده از API مرور ایمن، یک کلید API اندروید ایجاد و ثبت کنید. برای مراحل خاص، به صفحه مربوط به شروع به کار با مرور ایمن مراجعه کنید.

در نسخه ۵، شما این کلید API را هنگام ایجاد نمونه SafeBrowsingClient ارائه می‌دهید.

وابستگی API مربوط به SafetyNet را اضافه کنید

قبل از استفاده از API مرور ایمن، API SafetyNet را به پروژه خود اضافه کنید. اگر از اندروید استودیو استفاده می‌کنید، این وابستگی را به فایل Gradle سطح برنامه خود اضافه کنید. برای اطلاعات بیشتر، به بخش «محافظت در برابر تهدیدات امنیتی با SafetyNet» مراجعه کنید.

مقداردهی اولیه API

برای استفاده از API مرور ایمن، باید API را با فراخوانی initSafeBrowsing مقداردهی اولیه کنید و منتظر بمانید تا تکمیل شود. قطعه کد زیر مثالی از این مورد را ارائه می‌دهد:

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

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

در نسخه ۵، 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 تهدیدی ایجاد می‌کند یا خیر، استفاده کنید. شما باید پروتکل مورد نظر را مشخص کنید که می‌تواند لیست سیاه محلی (نسخه ۴) یا محافظت در زمان واقعی (نسخه ۵) باشد.

درخواست بررسی 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 کدام تهدیدهای شناخته شده را شناسایی کرده است.

برای مشاهده زبان هشدار پیشنهادی، به راهنمای توسعه‌دهندگان API مرور ایمن مراجعه کنید.

انواع تهدید مورد نظر را مشخص کنید

ثابت‌های موجود در کلاس SafeBrowsingThreat شامل انواع تهدیدهای پشتیبانی‌شده‌ی فعلی هستند:

هنگام استفاده از API، ثابت‌های نوع تهدید را به عنوان آرگومان اضافه می‌کنید. می‌توانید به تعداد مورد نیاز برنامه خود، ثابت‌های نوع تهدید اضافه کنید، اما فقط می‌توانید از ثابت‌هایی استفاده کنید که به عنوان منسوخ شده علامت‌گذاری نشده باشند.

جلسه مرور ایمن خود را خاموش کنید

اگر برنامه شما برای مدت طولانی نیازی به استفاده از API مرور ایمن ندارد، تمام URL های لازم را در برنامه خود بررسی کنید و سپس با استفاده از متد shutdownSafeBrowsing جلسه مرور ایمن خود را خاموش کنید:

SafetyNet.getClient(this).shutdownSafeBrowsing()

SafetyNet.getClient(this).shutdownSafeBrowsing();

توصیه می‌کنیم shutdownSafeBrowsing در متد onPause اکتیویتی خود و initSafeBrowsing را در متد onResume اکتیویتی خود فراخوانی کنید. با این حال، قبل از فراخوانی lookupUri ، مطمئن شوید که اجرای initSafeBrowsing به پایان رسیده است. با اطمینان از اینکه session شما همیشه تازه است، احتمال خطاهای داخلی در برنامه خود را کاهش می‌دهید.

جزئیات حفاظت در لحظه

به‌روزرسانی نسخه ۵، یک حالت محافظت بلادرنگ (Real-Time) را معرفی می‌کند که مشکلات مربوط به قدیمی بودن داده‌ها (که در نسخه ۴ می‌توانست به ۲۰ تا ۵۰ دقیقه برسد) را دور می‌زند. این حالت از پروتکل « اجازه دادن به صورت پیش‌فرض» به «بررسی به صورت پیش‌فرض» تغییر می‌کند و محافظت در برابر تهدیدهای با انتشار سریع را افزایش می‌دهد. در حالت بلادرنگ، کلاینت‌ها یک پایگاه داده محلی و یک حافظه پنهان (Cache) جهانی از سایت‌های احتمالاً بی‌خطر را نگهداری می‌کنند تا محافظت تقریباً بلادرنگ را با جدیدترین داده‌های تهدید ارائه دهند.

انواع تهدیدهای پشتیبانی‌شده

این API به شما امکان می‌دهد انواع تهدیدهای مهم برای نیازهای خود را انتخاب کنید. API نسخه ۵ از طیف وسیع‌تری از انواع تهدیدها پشتیبانی می‌کند:

داده‌های جمع‌آوری‌شده توسط API مرور ایمن SafetyNet

API مرور ایمن SafetyNet هنگام برقراری ارتباط با سرویس مرور ایمن در اندروید، داده‌های زیر را به‌طور خودکار جمع‌آوری می‌کند:

API مرور ایمن SafetyNet پیشوند هش URLها را برای شناسایی URLهای مخرب جمع‌آوری می‌کند. نسخه ۵، Oblivious HTTP را برای محافظت بیشتر از داده‌های کاربر در طول این جستجوها پیاده‌سازی می‌کند.

اگرچه هدف ما شفافیت هرچه بیشتر است، اما شما به تنهایی مسئول تصمیم‌گیری در مورد نحوه پاسخگویی به فرم بخش ایمنی داده‌های گوگل پلی در مورد جمع‌آوری، اشتراک‌گذاری و شیوه‌های امنیتی داده‌های کاربر توسط برنامه خود هستید.