SafetyNet Safe Browsing API

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

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

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

این سند نحوه استفاده از SafetyNet Safe Browsing Lookup API را برای بررسی نشانی وب ازنظر تهدیدهای شناخته‌شده توضیح می‌دهد.

شروط خدمات

بااستفاده از Safe Browsing API، موافقت می‌کنید که به شرایط خدمات پایبند باشید. پیش‌از دسترسی به Safe Browsing API، همه شرایط و خط‌مشی‌های ذی‌ربط را بخوانید و درک کنید.

درخواست و ثبت کلید میانای برنامه‌سازی کاربردی Android

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

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

افزودن وابستگی SafetyNet API

قبل‌از استفاده از Safe Browsing API،‏ SafetyNet API را به پروژه‌تان اضافه کنید. اگر از Android Studio استفاده می‌کنید، این وابستگی را به فایل Gradle سطح برنامه‌تان اضافه کنید. برای اطلاعات بیشتر، محافظت دربرابر تهدیدهای امنیتی با SafetyNet را ببینید.

مقداردهی اولیه میانای برنامه‌سازی کاربردی

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

کاتلین

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

جاوا

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

در نسخه ۵، GmsCore کارخواه «مرور ایمن» را ارائه می‌دهد. باید یک نمونه SafeBrowsingClient دریافت کنید. ما سطح میانای برنامه‌سازی کاربردی را ساده کردیم تا کارایی را افزایش دهیم و حجم را کاهش دهیم.

// 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();
}

درخواست بررسی نشانی وب

از روش lookupUri برای بررسی اینکه آیا شناسه منبع یکنواخت تهدیدی ایجاد می‌کند یا نه استفاده کنید. باید پروتکل موردنظر را مشخص کنید که می‌تواند فهرست غیرمجازهای محلی (v4) یا محافظت هم‌زمان (v5) باشد.

ارسال درخواست بررسی نشانی وب

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

کاتلین

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

جاوا

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

و

کاتلین

var url = "www.google.com"

جاوا

String url = "www.google.com";

معتبر باشد.

کد زیر نحوه ارسال درخواست بررسی نشانی وب را نشان می‌دهد:

کاتلین

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!
        }
    }

خواندن پاسخ بررسی نشانی وب

بااستفاده از شیء SafetyNetApi.SafeBrowsingResponse برگردانده‌شده، روش getDetectedThreats آن را فراخوانی کنید که فهرستی از اشیاء SafeBrowsingThreat را برمی‌گرداند. اگر فهرست برگردانده‌شده خالی باشد، API هیچ تهدید شناخته‌شده‌ای را شناسایی نکرده است. اگر فهرست خالی نیست، getThreatType را در هر عنصر فهرست فراخوانی کنید تا مشخص شود میانای برنامه‌سازی کاربردی کدام تهدیدهای شناخته‌شده را شناسایی کرده است.

برای دیدن زبان هشدار پیشنهادی، راهنمای توسعه‌دهنده Safe Browsing API را ببینید.

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

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

نوع تهدید تعریف
TYPE_POTENTIALLY_HARMFUL_APPLICATION این نوع تهدید نشانی‌های وب صفحه‌هایی را شناسایی می‌کند که به‌عنوان حاوی برنامه‌های بالقوه مضر پرچم‌گذاری شده‌اند.
TYPE_SOCIAL_ENGINEERING این نوع تهدید نشانی‌های وب صفحه‌هایی را شناسایی می‌کند که به‌عنوان حاوی تهدیدهای مهندسی اجتماعی پرچم‌گذاری شده‌اند.

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

بستن جلسه «مرور ایمن»

اگر برنامه‌تان برای مدت طولانی به استفاده از Safe Browsing API نیاز ندارد، همه نشانی‌های وب لازم را در برنامه‌تان بررسی کنید و سپس جلسه «مرور ایمن» را بااستفاده از روش shutdownSafeBrowsing ببندید:

کاتلین

SafetyNet.getClient(this).shutdownSafeBrowsing()

جاوا

SafetyNet.getClient(this).shutdownSafeBrowsing();

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

جزئیات محافظت هم‌زمان

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

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

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

ثابت نوع تهدید شرح
NO_THREAT تهدیدی وجود ندارد.
TYPE_MALWARE تهدیدهای بدافزار عمومی.
TYPE_UNWANTED_SOFTWARE نرم‌افزار یا برنامه‌های ناخواسته.
TYPE_POTENTIALLY_HARMFUL_APPLICATION برنامه‌هایی که ممکن است به دستگاه یا کاربر آسیب برسانند.
TYPE_SOCIAL_ENGINEERING سایت‌های طعمه‌گذاری و دیگر سایت‌های فریبکارانه.
TYPE_TRICK_TO_BILL صفحه‌هایی که کاربران را فریب می‌دهند تا کنش‌های صورت‌حساب انجام دهند.
TYPE_BETTER_ADS_VIOLATION سایت‌هایی که استانداردهای Better Ads را نقض می‌کنند.
TYPE_MALWARE_OFFLINE بدافزار آفلاین.
TYPE_ABUSIVE_EXPERIENCE_VIOLATION نقض‌هایی که منجر به تجربه بدی برای کاربر می‌شود.
TYPE_HIGH_CONFIDENCE_ALLOW_LIST فهرست مجاز با اطمینان بالا

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

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

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

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

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