Overview

مقدمه

توجه: این مستندات در حال حاضر در حال توسعه است. انتظار پیشرفت در آینده نزدیک را داشته باشید.

Google Safe Browsing v5 تکامل یافته Google Safe Browsing v4 است. دو تغییر کلیدی ایجاد شده در نسخه 5، تازگی داده ها و حریم خصوصی IP هستند. علاوه بر این، سطح API برای افزایش انعطاف پذیری، کارایی و کاهش نفخ بهبود یافته است. علاوه بر این، Google Safe Browsing v5 برای آسان کردن مهاجرت از نسخه 4 طراحی شده است.

در حال حاضر، گوگل نسخه 4 و 5 را ارائه می دهد و هر دو آماده تولید در نظر گرفته می شوند. می توانید از نسخه 4 یا 5 استفاده کنید. ما تاریخی برای غروب آفتاب v4 اعلام نکرده ایم. اگر چنین کنیم، حداقل یک سال اخطار خواهیم داد. این صفحه نسخه 5 و همچنین راهنمای مهاجرت از نسخه 4 به نسخه 5 را شرح خواهد داد. مستندات کامل v4 در دسترس است.

تازگی داده ها

یکی از پیشرفت‌های قابل توجه Google Safe Browsing نسخه 5 نسبت به نسخه 4 (به طور خاص، API به‌روزرسانی v4 ) تازگی و پوشش داده است. از آنجایی که حفاظت به شدت به پایگاه داده محلی نگهداری شده توسط سرویس گیرنده بستگی دارد، تاخیر و اندازه به روز رسانی پایگاه داده محلی عامل اصلی حفاظت از دست رفته است. در نسخه 4، مشتری معمولی 20 تا 50 دقیقه طول می کشد تا به روزترین نسخه لیست تهدیدات را به دست آورد. متأسفانه، حملات فیشینگ به سرعت گسترش می‌یابد: تا سال 2021، 60 درصد سایت‌هایی که حملات را انجام می‌دهند کمتر از 10 دقیقه عمر می‌کنند. تجزیه و تحلیل ما نشان می دهد که حدود 25 تا 30 درصد از محافظت از دست رفته فیشینگ به دلیل چنین بیاتی داده ها است. علاوه بر این، برخی از دستگاه‌ها برای مدیریت کل لیست‌های تهدید مرور ایمن Google مجهز نیستند، که به مرور زمان بزرگ‌تر می‌شود.

در نسخه 5، ما یک حالت عملیاتی را معرفی می کنیم که به عنوان حفاظت در زمان واقعی شناخته می شود. این مشکل بیات بودن داده در بالا را دور می زند. در نسخه 4، از کلاینت‌ها انتظار می‌رود که یک پایگاه داده محلی را دانلود و نگهداری کنند، لیست‌های تهدید بارگیری شده محلی را بررسی کنند، و سپس هنگامی که یک پیشوند جزئی وجود دارد، درخواستی برای دانلود هش کامل انجام دهند. در نسخه 5، اگرچه کلاینت‌ها باید به دانلود و نگهداری یک پایگاه داده محلی از لیست‌های تهدید ادامه دهند، اکنون از مشتریان انتظار می‌رود که فهرستی از سایت‌های احتمالی خوش‌خیم (به نام کش جهانی) را دانلود کنند، و یک بررسی محلی برای این کش جهانی نیز انجام دهند. به عنوان یک بررسی لیست تهدیدات محلی، و در نهایت هنگامی که یک پیشوند جزئی برای لیست های تهدید یا عدم تطابق در کش جهانی وجود دارد، درخواستی برای دانلود هش کامل انجام دهید. (برای جزئیات در مورد پردازش محلی مورد نیاز مشتری، لطفاً به روش ارائه شده در زیر مراجعه کنید.) این نشان دهنده تغییر از مجوز به پیش فرض به بررسی پیش فرض است، که می تواند حفاظت را در پرتو انتشار سریعتر تهدیدات در سیستم بهبود بخشد. وب به عبارت دیگر، این پروتکلی است که برای ارائه حفاظت در زمان واقعی طراحی شده است: هدف ما این است که مشتریان از داده‌های مرور ایمن Google جدیدتر بهره ببرند.

حریم خصوصی IP

مرور ایمن Google (نسخه 4 یا 5) هیچ چیز مرتبط با هویت کاربر را در طول ارائه درخواست‌ها پردازش نمی‌کند. کوکی ها، در صورت ارسال، نادیده گرفته می شوند. آدرس‌های IP اصلی درخواست‌ها برای Google شناخته شده است، اما Google فقط از آدرس‌های IP برای نیازهای ضروری شبکه (یعنی برای ارسال پاسخ‌ها) و برای اهداف ضد DoS استفاده می‌کند.

همزمان با نسخه 5، یک API همراه به نام Safe Browsing Oblivious HTTP Gateway API معرفی می کنیم. این از HTTP فراموش شده برای پنهان کردن آدرس IP کاربران نهایی از Google استفاده می کند. با داشتن یک شخص ثالث بدون تبانی برای رسیدگی به نسخه رمزگذاری شده درخواست کاربر و سپس ارسال آن به Google کار می کند. بنابراین شخص ثالث فقط به آدرس های IP دسترسی دارد و گوگل فقط به محتوای درخواست دسترسی دارد. شخص ثالث یک رله HTTP فراموش‌شده (مانند این سرویس توسط Fastly ) را راه‌اندازی می‌کند و Google دروازه HTTP فراموش‌شده را اجرا می‌کند. این یک API همراه اختیاری است. هنگام استفاده از آن در ارتباط با مرور ایمن Google، آدرس IP کاربران نهایی دیگر به Google ارسال نمی شود.

استفاده مناسب

استفاده مجاز

Safe Browsing API فقط برای استفاده غیرتجاری است (به معنی "نه برای اهداف فروش یا درآمدزایی"). اگر به راه حلی برای اهداف تجاری نیاز دارید، لطفاً به Web Risk مراجعه کنید.

قیمت گذاری

همه APIهای مرور ایمن Google رایگان هستند.

سهمیه ها

با فعال کردن Safe Browsing API یک سهمیه استفاده پیش‌فرض به توسعه‌دهندگان اختصاص داده می‌شود. تخصیص و استفاده فعلی را می توان در کنسول برنامه نویس Google مشاهده کرد. اگر انتظار دارید بیشتر از سهمیه اختصاص داده شده فعلی خود استفاده کنید، می توانید سهمیه اضافی را از رابط سهمیه کنسول برنامه نویس درخواست کنید. ما این درخواست‌ها را بررسی می‌کنیم و هنگام درخواست برای افزایش سهمیه به یک مخاطب نیاز داریم تا اطمینان حاصل کنیم که در دسترس بودن خدمات ما نیازهای همه کاربران را برآورده می‌کند.

آدرس های اینترنتی مناسب

Google Safe Browsing برای عمل بر روی URL هایی طراحی شده است که در نوار آدرس مرورگر نمایش داده می شوند. برای بررسی منابع فرعی (مانند جاوا اسکریپت یا تصویری که توسط یک فایل HTML ارجاع داده می شود، یا URL WebSocket که توسط جاوا اسکریپت آغاز شده است) استفاده نمی شود. چنین نشانی‌های اینترنتی زیرمنابعی نباید در مقابل مرور ایمن Google بررسی شوند.

اگر بازدید از یک URL منجر به تغییر مسیر (مانند HTTP 301) شود، مناسب است که URL هدایت‌شده در مقابل مرور ایمن Google بررسی شود. دستکاری URL سمت کلاینت مانند History.pushState منجر به بررسی URL های جدید در برابر مرور ایمن Google نمی شود.

هشدارهای کاربر

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

این دستورالعمل‌ها به محافظت از شما و Google در برابر سوء تفاهم‌ها کمک می‌کنند و این را روشن می‌کنند که این صفحه با اطمینان 100% به عنوان یک منبع وب ناامن شناخته نمی‌شود و هشدارها صرفاً خطر احتمالی را شناسایی می‌کنند.

• در اخطار قابل مشاهده کاربر، نباید کاربران را به این باور برسانید که صفحه مورد نظر، بدون شک، یک منبع وب ناامن است. هنگامی که به صفحه در حال شناسایی یا خطرات بالقوه ای که ممکن است برای کاربران ایجاد کند مراجعه می کنید، باید هشدار را با استفاده از عباراتی مانند: مشکوک، بالقوه، ممکن، محتمل، ممکن است واجد شرایط کنید.
• اخطار شما باید به کاربر این امکان را بدهد که با بررسی تعریف Google از تهدیدات مختلف، اطلاعات بیشتری کسب کند. لینک های زیر پیشنهاد می شود:
  • مهندسی اجتماعی: https://developers.google.com/search/docs/monitor-debug/security/social-engineering
  • بدافزار و نرم افزارهای ناخواسته: https://developers.google.com/search/docs/monitor-debug/security/malware
  • برنامه های بالقوه مضر (فقط برای اندروید): https://developers.google.com/android/play-protect/potentially-harmful-applications
• وقتی هشدارهایی را برای صفحاتی که توسط سرویس مرور ایمن به عنوان خطرناک شناسایی شده نشان می‌دهید، باید با قرار دادن خط "مشاوره ارائه شده توسط Google" به همراه پیوندی به مشاوره مرور ایمن به Google نسبت دهید. اگر محصول شما همچنین اخطارهایی را بر اساس منابع دیگر نشان می‌دهد، نباید انتساب Google را در هشدارهای ناشی از داده‌های غیر Google لحاظ کنید.

• در اسناد محصول خود، باید اخطاری ارائه دهید تا به کاربران اطلاع دهید که محافظت ارائه شده توسط مرور ایمن Google کامل نیست. باید به آنها اطلاع دهد که احتمال مثبت کاذب (سایت های ایمن که به عنوان خطرناک پرچم گذاری شده اند) و منفی کاذب (سایت های پرخطر پرچم گذاری نشده اند) وجود دارد. پیشنهاد می کنیم از زبان زیر استفاده کنید:

  Google برای ارائه دقیق ترین و به روزترین اطلاعات در مورد منابع وب ناامن کار می کند. با این حال، Google نمی تواند تضمین کند که اطلاعاتش جامع و بدون خطا است: برخی از سایت های پرخطر ممکن است شناسایی نشوند و برخی از سایت های امن ممکن است به اشتباه شناسایی شوند.

حالت های عملیات

Google Safe Browsing v5 به مشتریان این امکان را می دهد که از بین سه حالت کار انتخاب کنند.

حالت زمان واقعی

وقتی مشتریان استفاده از مرور ایمن Google نسخه 5 را در حالت بلادرنگ انتخاب می‌کنند، مشتریان در پایگاه داده محلی خود این موارد را حفظ می‌کنند: (1) یک حافظه پنهان جهانی از سایت‌های احتمالاً خوش خیم، قالب‌بندی شده به عنوان هش SHA256 از عبارت‌های URL پسوند میزبان/پیشوند مسیر، (ب) مجموعه‌ای از لیست‌های تهدید، که به عنوان پیشوندهای هش SHA256 از عبارت‌های URL پسوند میزبان/پیشوند مسیر، قالب‌بندی شده‌اند. ایده سطح بالا این است که هر زمان که مشتری بخواهد یک URL خاص را بررسی کند، یک بررسی محلی با استفاده از کش جهانی انجام می شود. اگر آن چک بگذرد، بررسی لیست تهدیدات محلی انجام می شود. در غیر این صورت، مشتری به بررسی هش بلادرنگ به شرح زیر ادامه می‌دهد.

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

مشخصات دقیق این روش در زیر موجود است.

حالت فهرست محلی

وقتی کلاینت‌ها استفاده از Google Safe Browsing v5 را در این حالت انتخاب می‌کنند، رفتار سرویس گیرنده شبیه به v4 Update API است به جز استفاده از سطح API بهبود یافته v5. کلاینت‌ها مجموعه‌ای از لیست‌های تهدید را در پایگاه داده محلی خود نگه می‌دارند که به صورت پیشوندهای هش SHA256 از عبارت‌های URL پسوند میزبان/پیشوند راه‌اندازی شده‌اند. هر زمان که مشتری بخواهد یک URL خاص را بررسی کند، با استفاده از لیست تهدید محلی، بررسی انجام می شود. اگر و تنها در صورت وجود تطابق، کلاینت برای ادامه بررسی به سرور متصل می شود.

همانند موارد فوق، کلاینت یک کش محلی را نیز حفظ خواهد کرد که نیازی به ذخیره سازی دائمی ندارد.

حالت بی‌درنگ بدون ذخیره‌سازی

وقتی مشتریان استفاده از مرور ایمن Google نسخه 5 را در حالت بی‌درنگ بدون ذخیره‌سازی انتخاب می‌کنند، مشتری نیازی به نگهداری پایگاه داده محلی دائمی ندارد. با این حال، همچنان انتظار می رود که مشتری یک حافظه پنهان محلی را حفظ کند. چنین حافظه پنهان محلی لازم نیست در ذخیره سازی دائمی باشد و ممکن است در صورت فشار حافظه پاک شود.

هر زمان که مشتری بخواهد یک URL خاص را بررسی کند، مشتری همیشه برای انجام بررسی به سرور متصل می شود. این حالت مشابه چیزی است که مشتریان API جستجوی v4 ممکن است اجرا کنند.

در مقایسه با حالت Real-Time، این حالت ممکن است از پهنای باند شبکه بیشتری استفاده کند، اما اگر برای مشتری برای حفظ وضعیت محلی پایدار ناخوشایند باشد، ممکن است مناسب تر باشد.

بررسی URL ها

این بخش شامل مشخصات دقیقی از نحوه چک کردن URL ها توسط مشتریان است.

متعارف سازی URL ها

قبل از اینکه هر URL بررسی شود، از مشتری انتظار می رود تا مقداری متعارف سازی را در آن URL انجام دهد.

برای شروع، فرض می کنیم که مشتری URL را تجزیه کرده و آن را مطابق RFC 2396 معتبر کرده است. اگر URL از یک نام دامنه بین المللی (IDN) استفاده می کند، مشتری باید URL را به نمایندگی ASCII Punycode تبدیل کند. URL باید شامل یک جزء مسیر باشد. یعنی باید حداقل یک اسلش پس از دامنه ( http://google.com/ به جای http://google.com ) داشته باشد.

ابتدا کاراکترهای تب (0x09)، CR (0x0d) و LF (0x0a) را از URL حذف کنید. دنباله های فرار را برای این کاراکترها حذف نکنید (مثلا %0a ).

دوم، اگر URL به یک قطعه ختم می شود، قطعه را حذف کنید. برای مثال، http://google.com/#frag به http://google.com/ کوتاه کنید.

سوم، به طور مکرر درصد از URL خارج شود تا زمانی که دیگر درصد فرار نداشته باشد. (این ممکن است URL را نامعتبر کند.)

برای متعارف سازی نام میزبان:

نام میزبان را از URL استخراج کنید و سپس:

1. تمام نقاط پیشرو و انتهایی را حذف کنید.
2. نقطه های متوالی را با یک نقطه جایگزین کنید.
3. اگر نام میزبان را می توان به عنوان یک آدرس IPv4 تجزیه کرد، آن را به 4 مقدار اعشاری جدا شده با نقطه نرمال کنید. مشتری باید هر کدگذاری آدرس IP قانونی، از جمله اکتال، هگز و کمتر از چهار مؤلفه را کنترل کند.
4. اگر می‌توان نام میزبان را به‌عنوان یک آدرس IPv6 پرانتزی تجزیه کرد، با حذف صفرهای غیرضروری ابتدایی در مؤلفه‌ها و جمع کردن مؤلفه‌های صفر با استفاده از نحو دو نقطه، آن را عادی کنید. برای مثال [2001:0db8:0000::1] باید به [2001:db8::1] تبدیل شود. اگر نام میزبان یکی از دو نوع آدرس IPv6 ویژه زیر است، آنها را به IPv4 تبدیل کنید:
   • یک آدرس IPv6 با نقشه IPv4، مانند [::ffff:1.2.3.4] ، که باید به 1.2.3.4 تبدیل شود.
   • یک آدرس NAT64 با استفاده از پیشوند معروف 64:ff9b::/96 ، مانند [64:ff9b::1.2.3.4] ، که باید به 1.2.3.4 تبدیل شود.
5. تمام رشته را با حروف کوچک بنویسید.

برای متعارف کردن مسیر:

1. دنباله های /../ و /./ در مسیر را با جایگزین کردن /./ با / و حذف /../ به همراه مولفه مسیر قبلی حل کنید.
2. اجراهای اسلش های متوالی را با یک کاراکتر اسلش جایگزین کنید.

این متعارف سازی مسیرها را برای پارامترهای پرس و جو اعمال نکنید.

در URL، درصد فرار از همه کاراکترهایی که <= ASCII 32، >= 127، # یا % هستند. Escape ها باید از حروف هگز بزرگ استفاده کنند.

میزبان-پسوند مسیر- عبارات پیشوند

هنگامی که URL متعارف شد، گام بعدی ایجاد عبارات پسوند/پیشوند است. هر عبارت پسوند/پیشوند از یک پسوند میزبان (یا میزبان کامل) و یک پیشوند مسیر (یا مسیر کامل) تشکیل شده است.

مشتری حداکثر 30 ترکیب مختلف پسوند میزبان و پیشوند مسیر را تشکیل می دهد. این ترکیب ها فقط از اجزای میزبان و مسیر URL استفاده می کنند. طرح، نام کاربری، رمز عبور و پورت حذف می شوند. اگر URL شامل پارامترهای پرس و جو باشد، حداقل یک ترکیب شامل مسیر کامل و پارامترهای پرس و جو می شود.

برای میزبان ، مشتری حداکثر پنج رشته مختلف را امتحان خواهد کرد. آنها عبارتند از:

• اگر نام میزبان تحت اللفظی IPv4 یا IPv6 نباشد، حداکثر چهار نام میزبان با شروع با دامنه eTLD+1 و افزودن مؤلفه‌های اصلی متوالی تشکیل می‌شود. تعیین eTLD+1 باید بر اساس فهرست پسوند عمومی باشد. به عنوان مثال، abexample.com منجر به ایجاد دامنه eTLD+1 از example.com و همچنین میزبانی با یک جزء میزبان اضافی b.example.com می شود.
• نام دقیق میزبان در URL. به دنبال مثال قبلی، abexample.com بررسی می شود.

برای مسیر ، مشتری حداکثر شش رشته مختلف را امتحان خواهد کرد. آنها عبارتند از:

• مسیر دقیق URL، از جمله پارامترهای پرس و جو.
• مسیر دقیق URL، بدون پارامترهای پرس و جو.
• چهار مسیر با شروع از ریشه (/) و پیوستن متوالی مؤلفه‌های مسیر، از جمله یک اسلش انتهایی، تشکیل می‌شوند.

مثال‌های زیر رفتار چک را نشان می‌دهند:

برای URL http://abcom/1/2.html?param=1 ، مشتری این رشته های ممکن را امتحان می کند:

a.b.com/1/2.html?param=1
a.b.com/1/2.html
a.b.com/
a.b.com/1/
b.com/1/2.html?param=1
b.com/1/2.html
b.com/
b.com/1/

برای URL http://abcdefcom/1.html ، مشتری این رشته های ممکن را امتحان می کند:

a.b.c.d.e.f.com/1.html
a.b.c.d.e.f.com/
c.d.e.f.com/1.html
c.d.e.f.com/
d.e.f.com/1.html
d.e.f.com/
e.f.com/1.html
e.f.com/
f.com/1.html
f.com/

(توجه: از bcdefcom رد شوید، زیرا ما فقط پنج جزء آخر نام میزبان و نام میزبان کامل را می گیریم.)

برای URL http://1.2.3.4/1/ ، مشتری این رشته های ممکن را امتحان می کند:

1.2.3.4/1/
1.2.3.4/

برای URL http://example.co.uk/1 ، مشتری این رشته های ممکن را امتحان می کند:

example.co.uk/1
example.co.uk/

هش کردن

مرور ایمن Google منحصراً از SHA256 به عنوان عملکرد هش استفاده می کند. این تابع هش باید برای عبارات بالا اعمال شود.

هش کامل 32 بایت، بسته به شرایط، به 4 بایت، 8 بایت یا 16 بایت کوتاه می شود:

• هنگام استفاده از روش hashes.search ، در حال حاضر نیاز داریم که هش های موجود در درخواست دقیقاً به 4 بایت کوتاه شوند. ارسال بایت های اضافی در این درخواست حریم خصوصی کاربر را به خطر می اندازد.

• هنگام دانلود لیست‌ها برای پایگاه داده محلی با استفاده از روش hashList.get یا روش hashLists.batchGet ، طول هش‌های ارسال شده توسط سرور هم تحت تأثیر ماهیت فهرست و هم ترجیح مشتری از طول هش قرار می‌گیرد. پارامتر desired_hash_length .

روش بررسی URL بلادرنگ

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

این روش یک URL واحد u را می گیرد و SAFE , UNSAFE یا UNSURE را برمی گرداند . اگر SAFE را برگرداند، URL توسط مرور ایمن Google ایمن تلقی می شود. اگر UNSAFE را برگرداند، URL به‌طور بالقوه توسط «مرور ایمن Google» ناامن تلقی می‌شود و باید اقدامات لازم انجام شود: مانند نشان دادن یک هشدار به کاربر نهایی، انتقال پیام دریافتی به پوشه هرزنامه، یا نیاز به تأیید اضافی توسط کاربر قبل از ادامه. اگر UNSURE برگردد، باید از روش بررسی محلی زیر استفاده شود.

1. اجازه دهید expressions لیستی از عبارات پسوند/پیشوند تولید شده توسط URL u باشند.
2. اجازه دهید expressionHashes یک لیست باشد که در آن عناصر هش SHA256 هر عبارت در expressions هستند.
3. برای هر hash از expressionHashes :
   1. اگر می‌توان hash در کش جهانی پیدا کرد، UNSURE برگردانید.
4. اجازه دهید expressionHashPrefixes یک لیست باشد که در آن عناصر 4 بایت اول هر هش در expressionHashes هستند.
5. برای هر expressionHashPrefix of expressionHashPrefixes :
   1. expressionHashPrefix را در کش محلی جستجو کنید.
   2. اگر ورودی حافظه پنهان پیدا شد:
      1. تعیین کنید که آیا زمان فعلی بیشتر از زمان انقضای آن است یا خیر.
      2. اگر بیشتر باشد:
         1. ورودی کش پیدا شده را از کش محلی حذف کنید.
         2. با حلقه ادامه دهید.
      3. اگر بزرگتر نیست:
         1. این عبارت خاص expressionHashPrefix از expressionHashPrefixes حذف کنید.
         2. بررسی کنید که آیا هش کامل مربوطه در expressionHashes در ورودی ذخیره شده یافت می شود.
         3. اگر پیدا شد، UNSAFE را برگردانید.
         4. اگر پیدا نشد، با حلقه ادامه دهید.
   3. اگر ورودی حافظه پنهان پیدا نشد، با حلقه ادامه دهید.
6. با استفاده از RPC SearchHashes یا روش REST hashes.search ، expressionHashPrefixes به سرور مرور ایمن Google v5 ارسال کنید. اگر خطایی رخ داد (از جمله خطاهای شبکه، خطاهای HTTP و غیره)، UNSURE را برگردانید. در غیر این صورت، اجازه دهید پاسخ، response دریافت شده از سرور SB باشد، که فهرستی از هش‌های کامل همراه با برخی اطلاعات کمکی شناسایی کننده ماهیت تهدید (مهندسی اجتماعی، بدافزار و غیره) و همچنین expiration زمان انقضای حافظه پنهان است.
7. برای هر fullHash response :
   1. fullHash به همراه expiration در حافظه پنهان محلی وارد کنید.
8. برای هر fullHash response :
   1. بگذارید isFound نتیجه یافتن fullHash در expressionHashes باشد.
   2. اگر isFound نادرست است، با حلقه ادامه دهید.
   3. اگر isFound درست است، UNSAFE را برگردانید.
9. SAFE برگردید

در حالی که این پروتکل مشخص می کند که کلاینت چه زمانی expressionHashPrefixes را به سرور ارسال می کند، این پروتکل به طور هدفمند نحوه ارسال آنها را دقیقاً مشخص نمی کند. به عنوان مثال، ارسال تمام پیشوندهای expressionHashPrefixes در یک درخواست برای کلاینت قابل قبول است و همچنین ارسال هر پیشوند منفرد در expressionHashPrefixes به سرور در درخواست‌های جداگانه (شاید به صورت موازی) قابل قبول است. همچنین برای مشتری قابل قبول است که پیشوندهای هش نامرتبط یا به طور تصادفی تولید شده را همراه با پیشوندهای هش در expressionHashPrefixes ارسال کند، تا زمانی که تعداد پیشوندهای هش ارسال شده در یک درخواست از 30 تجاوز نکند.

رویه بررسی URL لیست LocalThreat

این رویه زمانی استفاده می شود که مشتری حالت عملیات لیست محلی را انتخاب کند. همچنین زمانی استفاده می‌شود که رویه RealTimeCheck بالا مقدار UNSURE را برمی‌گرداند.

این روش یک URL واحد u را می گیرد و SAFE یا UNSAFE را برمی گرداند.

1. اجازه دهید expressions لیستی از عبارات پسوند/پیشوند تولید شده توسط URL u باشند.
2. اجازه دهید expressionHashes یک لیست باشد که در آن عناصر هش SHA256 هر عبارت در expressions هستند.
3. اجازه دهید expressionHashPrefixes یک لیست باشد که در آن عناصر 4 بایت اول هر هش در expressionHashes هستند.
4. برای هر expressionHashPrefix of expressionHashPrefixes :
   1. expressionHashPrefix را در کش محلی جستجو کنید.
   2. اگر ورودی حافظه پنهان پیدا شد:
      1. تعیین کنید که آیا زمان فعلی بیشتر از زمان انقضای آن است یا خیر.
      2. اگر بیشتر باشد:
         1. ورودی کش پیدا شده را از کش محلی حذف کنید.
         2. با حلقه ادامه دهید.
      3. اگر بزرگتر نیست:
         1. این عبارت خاص expressionHashPrefix از expressionHashPrefixes حذف کنید.
         2. بررسی کنید که آیا هش کامل مربوطه در expressionHashes در ورودی ذخیره شده یافت می شود.
         3. اگر پیدا شد، UNSAFE را برگردانید.
         4. اگر پیدا نشد، با حلقه ادامه دهید.
   3. اگر ورودی حافظه پنهان پیدا نشد، با حلقه ادامه دهید.
5. برای هر expressionHashPrefix of expressionHashPrefixes :
   1. expressionHashPrefix را در پایگاه داده لیست تهدیدات محلی جستجو کنید.
   2. اگر expressionHashPrefix در پایگاه داده لیست تهدید محلی یافت نشد، آن را از expressionHashPrefixes حذف کنید.
6. با استفاده از RPC SearchHashes یا روش REST hashes.search ، expressionHashPrefixes به سرور مرور ایمن Google v5 ارسال کنید. اگر خطایی رخ داد (از جمله خطاهای شبکه، خطاهای HTTP و غیره)، SAFE را برگردانید. در غیر این صورت، اجازه دهید پاسخ، response دریافت شده از سرور SB باشد، که فهرستی از هش‌های کامل همراه با برخی اطلاعات کمکی شناسایی کننده ماهیت تهدید (مهندسی اجتماعی، بدافزار و غیره) و همچنین expiration زمان انقضای حافظه پنهان است.
7. برای هر fullHash response :
   1. fullHash به همراه expiration در حافظه پنهان محلی وارد کنید.
8. برای هر fullHash response :
   1. بگذارید isFound نتیجه یافتن fullHash در expressionHashes باشد.
   2. اگر isFound نادرست است، با حلقه ادامه دهید.
   3. اگر isFound درست است، UNSAFE را برگردانید.
9. SAFE برگردید

روش بررسی URL بلادرنگ بدون پایگاه داده محلی

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

این روش یک URL واحد u را می گیرد و SAFE یا UNSAFE را برمی گرداند.

1. اجازه دهید expressions لیستی از عبارات پسوند/پیشوند تولید شده توسط URL u باشند.
2. اجازه دهید expressionHashes یک لیست باشد که در آن عناصر هش SHA256 هر عبارت در expressions هستند.
3. اجازه دهید expressionHashPrefixes یک لیست باشد که در آن عناصر 4 بایت اول هر هش در expressionHashes هستند.
4. برای هر expressionHashPrefix of expressionHashPrefixes :
   1. expressionHashPrefix را در کش محلی جستجو کنید.
   2. اگر ورودی حافظه پنهان پیدا شد:
      1. تعیین کنید که آیا زمان فعلی بیشتر از زمان انقضای آن است یا خیر.
      2. اگر بزرگتر است:
         1. ورودی کش پیدا شده را از کش محلی حذف کنید.
         2. با حلقه ادامه دهید.
      3. اگر بزرگتر نیست:
         1. این عبارت خاص expressionHashPrefix از expressionHashPrefixes حذف کنید.
         2. بررسی کنید که آیا هش کامل مربوطه در expressionHashes در ورودی ذخیره شده یافت می شود.
         3. اگر پیدا شد، UNSAFE را برگردانید.
         4. اگر پیدا نشد، با حلقه ادامه دهید.
   3. اگر ورودی حافظه پنهان پیدا نشد، با حلقه ادامه دهید.
5. با استفاده از RPC SearchHashes یا روش REST hasshes.search ، expressionHashPrefixes به سرور مرور ایمن Google v5 ارسال کنید. اگر خطایی رخ داد (از جمله خطاهای شبکه، خطاهای HTTP و غیره)، SAFE را برگردانید. در غیر این صورت، اجازه دهید پاسخ، response دریافت شده از سرور SB باشد، که فهرستی از هش‌های کامل همراه با برخی اطلاعات کمکی شناسایی کننده ماهیت تهدید (مهندسی اجتماعی، بدافزار و غیره) و همچنین expiration زمان انقضای حافظه پنهان است.
6. برای هر fullHash response :
   1. fullHash به همراه expiration در حافظه پنهان محلی وارد کنید.
7. برای هر fullHash response :
   1. بگذارید isFound نتیجه یافتن fullHash در expressionHashes باشد.
   2. اگر isFound نادرست است، با حلقه ادامه دهید.
   3. اگر isFound درست است، UNSAFE را برگردانید.
8. SAFE برگردید

درست مانند رویه بررسی URL در زمان واقعی، این روش دقیقاً نحوه ارسال پیشوندهای هش را به سرور مشخص نمی کند. به عنوان مثال، ارسال تمام پیشوندهای expressionHashPrefixes در یک درخواست برای کلاینت قابل قبول است و همچنین ارسال هر پیشوند منفرد در expressionHashPrefixes به سرور در درخواست‌های جداگانه (شاید به صورت موازی) قابل قبول است. همچنین برای مشتری قابل قبول است که پیشوندهای هش نامرتبط یا به طور تصادفی تولید شده را همراه با پیشوندهای هش در expressionHashPrefixes ارسال کند، تا زمانی که تعداد پیشوندهای هش ارسال شده در یک درخواست از 30 تجاوز نکند.

تعمیر و نگهداری پایگاه داده محلی

Google Safe Browsing v5 از مشتری انتظار دارد که یک پایگاه داده محلی را حفظ کند، به جز زمانی که مشتری حالت بی‌درنگ بدون ذخیره‌سازی را انتخاب کند. فرمت و ذخیره سازی این پایگاه داده محلی به مشتری بستگی دارد. محتویات این پایگاه داده محلی را می توان از نظر مفهومی به عنوان یک پوشه حاوی لیست های مختلف به عنوان فایل در نظر گرفت و محتویات این فایل ها هش یا پیشوند هش SHA256 است.

به روز رسانی پایگاه داده

کلاینت مرتباً متد hashList.get یا متد hashLists.batchGet را برای به روز رسانی پایگاه داده فراخوانی می کند. از آنجایی که مشتری معمولی می خواهد چندین لیست را در یک زمان به روز کند، توصیه می شود از روش hashLists.batchGet استفاده کنید.

فهرست ها با نام های متمایزشان شناسایی می شوند. نام ها رشته های ASCII کوتاه و چند کاراکتر هستند.

بر خلاف V4، که در آن لیست ها با چند نوع تهدید، نوع پلت فرم، نوع ورود تهدید شناسایی می شوند، در V5 لیست ها به سادگی با نام شناسایی می شوند. هنگامی که چندین لیست v5 می توانند یک نوع تهدید را به اشتراک بگذارند، این انعطاف پذیری را فراهم می کند. انواع پلت فرم و انواع ورود تهدید در نسخه 5 حذف شده اند.

هنگامی که یک نام برای یک لیست انتخاب شده است، هرگز تغییر نام نخواهد داد. علاوه بر این، هنگامی که یک لیست ظاهر شد، هرگز حذف نخواهد شد (اگر لیست دیگر مفید نباشد، خالی می شود اما به وجود خود ادامه می دهد). بنابراین، مناسب است که این نام ها را در کد سرویس گیرنده Google Safe Browsing کدگذاری کنید.

هم روش hashList.get و هم روش hashLists.batchGet از به روز رسانی های افزایشی پشتیبانی می کنند. استفاده از به روز رسانی های افزایشی باعث صرفه جویی در پهنای باند و بهبود عملکرد می شود. به روز رسانی های افزایشی با ارائه یک دلتا بین نسخه مشتری از لیست و آخرین نسخه لیست کار می کنند. (اگر یک کلاینت به تازگی مستقر شده باشد و هیچ نسخه ای در دسترس نداشته باشد، یک به روز رسانی کامل در دسترس است.) به روز رسانی افزایشی شامل شاخص های حذف و اضافه شده است. ابتدا از مشتری انتظار می رود که ورودی های شاخص های مشخص شده را از پایگاه داده محلی خود حذف کند و سپس اضافات را اعمال کند.

در نهایت، برای جلوگیری از فساد، کلاینت باید داده های ذخیره شده را در مقابل چک جمع ارائه شده توسط سرور بررسی کند. هر زمان که جمع چک مطابقت نداشته باشد، مشتری باید به روز رسانی کامل را انجام دهد.

رمزگشایی محتوای فهرست

رمزگشایی هش ها و پیشوندهای هش

همه لیست ها با استفاده از یک رمزگذاری ویژه برای کاهش اندازه تحویل داده می شوند. این رمزگذاری با تشخیص اینکه لیست‌های مرور ایمن Google از نظر مفهومی حاوی مجموعه‌ای از پیشوندهای هش یا هش هستند، کار می‌کند که از نظر آماری از اعداد صحیح تصادفی قابل تشخیص نیستند. اگر بخواهیم این اعداد صحیح را مرتب کنیم و تفاوت مجاور آنها را بگیریم، انتظار می رود چنین تفاوت مجاور به یک معنا "کوچک" باشد. رمزگذاری Golomb-Rice سپس از این کوچکی سوء استفاده می کند.

فرض کنید که سه عبارت پسوند مسیر میزبان، یعنی a.example.com/ ، b.example.com/ ، و y.example.com/ ، قرار است با استفاده از پیشوندهای هش 4 بایتی منتقل شوند. بعلاوه فرض کنید که پارامتر Rice که با k نشان داده می شود 30 انتخاب شده است. سرور با محاسبه هش کامل این رشته ها شروع می کند که به ترتیب عبارتند از:

291bc5421f1cd54d99afcc55d166e2b9fe42447025895bf09dd41b2110a687dc  a.example.com/
1d32c5084a360e58f1b87109637a6810acad97a861a7769e8f1841410d2a960c  b.example.com/
f7a502e56e8b01c6dc242b35122683c9d25d07fb1f532d9853eb0ef3ff334f03  y.example.com/

سپس سرور پیشوندهای هش 4 بایتی را برای هر یک از موارد فوق تشکیل می دهد که 4 بایت اول هش کامل 32 بایتی است که به عنوان اعداد صحیح 32 بیتی بزرگ endian تفسیر می شود. endianness بزرگ به این واقعیت اشاره دارد که اولین بایت از هش کامل به مهم ترین بایت عدد صحیح 32 بیتی تبدیل می شود. این مرحله به اعداد صحیح 0x291bc542، 0x1d32c508 و 0xf7a502e5 منجر می شود.

لازم است سرور این سه پیشوند هش را به صورت واژگانی (معادل مرتب سازی عددی در big endian) مرتب کند و نتیجه مرتب سازی 0x1d32c508، 0x291bc542، 0xf7a502e5 است. اولین پیشوند هش بدون تغییر در فیلد first_value ذخیره می شود.

سپس سرور دو تفاوت مجاور را محاسبه می کند که به ترتیب 0xbe9003a و 0xce893da3 هستند. با توجه به اینکه k به عنوان 30 انتخاب شده است، سرور این دو عدد را به قسمت های ضریب و قسمت های باقیمانده که به ترتیب 2 و 30 بیت هستند تقسیم می کند. برای عدد اول، قسمت ضریب صفر و باقیمانده 0xbe9003a است. برای عدد دوم، قسمت ضریب 3 است زیرا مهم ترین دو بیت 11 در باینری و بقیه 0xe893da3 است. برای یک ضریب مشخص q به (1 << q) - 1 دقیقاً با استفاده از بیت های 1 + q کدگذاری می شود. باقیمانده مستقیماً با استفاده از k بیت کدگذاری می شود. قسمت ضریب عدد اول به صورت 0 کدگذاری می شود و قسمت باقیمانده به صورت باینری 001011111010010000000000111010 است. قسمت ضریب عدد دوم به صورت 0111 کدگذاری می شود و قسمت باقیمانده 001110100010010011110110100011 است.

هنگامی که این اعداد به یک رشته بایت تبدیل می شوند، اندیان کمی استفاده می شود. از نظر مفهومی ممکن است تصور اینکه یک رشته بیت طولانی از بیت‌های کم‌اهمیت شروع می‌شود، آسان‌تر باشد: بخش ضریب عدد اول را می‌گیریم و قسمت باقیمانده عدد اول را پیش‌فرض می‌کنیم. سپس قسمت ضریب عدد دوم را پیش‌فرض می‌کنیم و قسمت باقیمانده را پیش‌فرض می‌کنیم. این باید به تعداد زیاد زیر منجر شود (خطوط و نظرات اضافه شده برای وضوح):

001110100010010011110110100011 # Second number, remainder part
0111 # Second number, quotient part
001011111010010000000000111010 # First number, remainder part
0 # First number, quotient part

نوشته شده در یک خط این خواهد بود

00111010001001001111011010001101110010111110100100000000001110100

بدیهی است که این تعداد بسیار بیشتر از 8 بیت موجود در یک بایت است. سپس رمزگذاری اندیان کوچک، 8 بیت کم‌اهمیت را در آن عدد می‌گیرد و آن را به عنوان اولین بایت که 01110100 است، خروجی می‌دهد.

0 01110100 01001001 11101101 00011011 10010111 11010010 00000000 01110100

سپس رمزگذاری اندیان کوچک هر بایت را از سمت راست می گیرد و آن را در یک بایت تست قرار می دهد:

01110100
00000000
11010010
10010111
00011011
11101101
01001001
01110100
00000000

مشاهده می شود که از آنجایی که از نظر مفهومی قطعات جدید را به عدد بزرگ سمت چپ اضافه می کنیم (یعنی اضافه کردن بیت های مهم تر) اما از سمت راست (یعنی کم اهمیت ترین بیت ها) رمزگذاری می کنیم، رمزگذاری و رمزگشایی می تواند به صورت تدریجی انجام شود.

این در نهایت نتیجه می دهد

additions_four_bytes {
  first_value: 489866504
  rice_parameter: 30
  entries_count: 2
  encoded_data: "t\000\322\227\033\355It\000"
}

کلاینت به سادگی مراحل بالا را به صورت معکوس دنبال می کند تا پیشوندهای هش را رمزگشایی کند. برخلاف نسخه 4، به دلیل اینکه اعداد صحیح پیشوند هش به عنوان اندیان بزرگ تفسیر می شوند، نیازی به انجام تعویض بایت در پایان نیست.

رمزگشایی شاخص های حذف

شاخص های حذف دقیقاً با استفاده از روش فوق با استفاده از اعداد صحیح 32 بیتی کدگذاری می شوند. رمزگذاری و رمزگشایی شاخص های حذف بین v4 و v5 تغییر نکرده است.

لیست های موجود

لیست های زیر برای استفاده در v5alpha1 توصیه می شود:

نام لیست	مربوطه v4 ThreatType Enum	توضیحات
gc	هیچ کدام	این لیست یک لیست کش جهانی است. این یک لیست ویژه است که فقط در حالت Real Time استفاده می شود.
se	SOCIAL_ENGINEERING	این لیست حاوی تهدیدهایی از نوع تهدید SOCIAL_ENGINEERING است.
mw	MALWARE	این لیست حاوی تهدیداتی از نوع تهدید بدافزار برای پلتفرم های دسکتاپ است.
uws	UNWANTED_SOFTWARE	این لیست حاوی تهدیداتی از نوع تهدید UNWANTED_SOFTWARE برای پلتفرم های دسکتاپ است.
uwsa	UNWANTED_SOFTWARE	این لیست حاوی تهدیداتی از نوع تهدید UNWANTED_SOFTWARE برای پلتفرم های اندروید است.
pha	POTENTIALLY_HARMFUL_APPLICATION	این لیست حاوی تهدیداتی از نوع تهدید POTENTIALLY_HARMFUL_APPLICATION برای پلتفرم های Android است.

لیست های اضافی در تاریخ بعدی در دسترس قرار خواهند گرفت و در آن زمان جدول فوق گسترش خواهد یافت.

برای کلاینت مجاز است که از یک سرور پروکسی کش برای بازیابی برخی یا همه لیست های بالا استفاده کند و سپس از مشتری بخواهد با سرور پراکسی تماس بگیرد. اگر این مورد اجرا شود، مدت زمان کش کوتاهی مانند پنج دقیقه را توصیه می کنیم. در آینده این مدت زمان حافظه پنهان ممکن است با استفاده از هدر استاندارد Cache-Control HTTP ارتباط برقرار کند.

فرکانس به روز رسانی

کلاینت باید مقدار برگشتی سرور را در فیلد minimum_wait_duration بررسی کند و از آن برای برنامه ریزی به روز رسانی بعدی پایگاه داده استفاده کند. این مقدار احتمالاً صفر است (فیلد minimum_wait_duration به طور کامل وجود ندارد)، در این صورت مشتری باید فوراً به‌روزرسانی دیگری را انجام دهد.

نمونه درخواست ها

این بخش نمونه هایی از استفاده مستقیم از HTTP API برای دسترسی به مرور ایمن Google را مستند می کند. به طور کلی توصیه می شود که از یک اتصال زبان تولید شده استفاده کنید زیرا به طور خودکار رمزگذاری و رمزگشایی را به روشی راحت انجام می دهد. لطفاً برای آن الزام آور به مستندات مراجعه کنید.

در اینجا یک نمونه درخواست HTTP با استفاده از روش hashes.search آورده شده است:

GET https://safebrowsing.googleapis.com/v5/hashes:search?key=INSERT_YOUR_API_KEY_HERE&hashPrefixes=WwuJdQ

بدنه پاسخ یک باری با فرمت پروتکل بافر است که می توانید آن را رمزگشایی کنید.

در اینجا یک نمونه درخواست HTTP با استفاده از روش hashLists.batchGet آورده شده است:

GET https://safebrowsing.googleapis.com/v5alpha1/hashLists:batchGet?key=INSERT_YOUR_API_KEY_HERE&names=se&names=mw

بدنه پاسخ، بار دیگر، یک باری با فرمت پروتکل بافر است که می توانید آن را رمزگشایی کنید.

راهنمای مهاجرت

اگر در حال حاضر از v4 Update API استفاده می‌کنید، یک مسیر یکپارچه از نسخه 4 به نسخه 5 بدون نیاز به تنظیم مجدد یا پاک کردن پایگاه داده محلی وجود دارد. این بخش نحوه انجام آن را مستند می کند.

تبدیل به‌روزرسانی‌های فهرست

در نسخه 4، برای دانلود لیست ها از متد gefListUpdates.fetch استفاده می شود. در نسخه 5، می توان به روش hashLists.batchGet سوئیچ کرد.

تغییرات زیر باید در درخواست ایجاد شود:

1. شی v4 ClientInfo را به طور کامل حذف کنید. به جای ارائه شناسه مشتری با استفاده از یک فیلد اختصاصی، به سادگی از هدر معروف User-Agent استفاده کنید. در حالی که هیچ فرمت مشخصی برای ارائه شناسه مشتری در این هدر وجود ندارد، پیشنهاد می کنیم به سادگی شناسه مشتری اصلی و نسخه مشتری را که با یک نویسه فاصله یا یک کاراکتر اسلش از هم جدا شده اند، اضافه کنید.
2. برای هر شیء v4 ListUpdateRequest :
   • نام فهرست v5 مربوطه را در جدول بالا جستجو کنید و آن نام را در درخواست v5 وارد کنید.
   • فیلدهای غیرضروری مانند threat_entry_type یا platform_type را حذف کنید.
   • فیلد state در v4 مستقیماً با قسمت versions v5 سازگار است. همان رشته بایتی که با استفاده از فیلد state در v4 به سرور ارسال می شود، می تواند به سادگی با استفاده از فیلد versions در v5 ارسال شود.
   • برای محدودیت های v4، v5 از یک نسخه ساده شده به نام SizeConstraints استفاده می کند. فیلدهای اضافی مانند region باید حذف شوند.

تغییرات زیر باید در پاسخ ایجاد شود:

1. v4 enum ResponseType به سادگی با یک فیلد بولی به نام partial_update جایگزین می شود.
2. اکنون می‌توان فیلد minimum_wait_duration را صفر یا حذف کرد. اگر چنین باشد، از مشتری درخواست می شود که فوراً درخواست دیگری ارائه دهد. این تنها زمانی اتفاق می‌افتد که مشتری در SizeConstraints محدودیت کوچک‌تری را برای حداکثر اندازه به‌روزرسانی نسبت به حداکثر اندازه پایگاه داده تعیین کند.
3. الگوریتم رمزگشایی Rice برای اعداد صحیح 32 بیتی باید تنظیم شود. تفاوت در این است که داده های کدگذاری شده با endianness متفاوت کدگذاری می شوند. در هر دو نسخه 4 و 5، پیشوندهای هش 32 بیتی به صورت واژگانی مرتب شده اند. اما در v4، آن پیشوندها هنگام مرتب‌سازی به‌عنوان اندیان کوچک در نظر گرفته می‌شوند، در حالی که در v5 آن پیشوندها هنگام مرتب‌سازی به عنوان اندیان بزرگ در نظر گرفته می‌شوند. این بدان معناست که مشتری نیازی به مرتب سازی ندارد، زیرا مرتب سازی واژگانی با مرتب سازی عددی با اندیان بزرگ یکسان است. نمونه‌ای از این نوع در اجرای Chromium نسخه 4 را می‌توانید در اینجا پیدا کنید. چنین مرتب سازی را می توان حذف کرد.
4. الگوریتم رمزگشایی Rice باید برای سایر طول های هش پیاده سازی شود.

تبدیل جستجوهای هش

در نسخه 4، از روش fullHashes.find برای بدست آوردن هش کامل استفاده می شود. روش معادل در v5 روش hash.search است.

تغییرات زیر باید در درخواست ایجاد شود:

1. ساختار کد را طوری تنظیم کنید که فقط پیشوندهای هش که دقیقاً 4 بایت طول دارند ارسال کند.
2. اشیاء v4 ClientInfo را به طور کامل حذف کنید. به جای ارائه شناسه مشتری با استفاده از یک فیلد اختصاصی، به سادگی از هدر معروف User-Agent استفاده کنید. در حالی که هیچ فرمت مشخصی برای ارائه شناسه مشتری در این هدر وجود ندارد، پیشنهاد می کنیم به سادگی شناسه مشتری اصلی و نسخه مشتری را که با یک نویسه فاصله یا یک کاراکتر اسلش از هم جدا شده اند، اضافه کنید.
3. قسمت client_states حذف کنید. دیگر لازم نیست.
4. دیگر نیازی به وارد کردن threat_types و فیلدهای مشابه نیست.

تغییرات زیر باید در پاسخ ایجاد شود:

1. قسمت minimum_wait_duration حذف شده است. مشتری همیشه می تواند بر اساس نیاز درخواست جدیدی صادر کند.
2. شی v4 ThreatMatch به شی FullHash ساده شده است.
3. ذخیره سازی به یک مدت زمان کش ساده شده است. رویه های بالا را برای تعامل با حافظه پنهان ببینید.