Package google.security.safebrowsing.v4

الفهرس

SafeBrowsing

تتيح واجهات برمجة تطبيقات "التصفّح الآمن" للعملاء التحقّق من موارد الويب (عادةً عناوين URL) من خلال مقارنتها بقائمة يتم تعديلها باستمرار تضم مصادر الويب غير الآمنة. تتضمّن واجهات برمجة التطبيقات للتصفّح الآمن (الإصدار 4) Update API وLookup API.

تم تصميم Update API للعملاء الأكبر حجمًا، وتتضمّن الطريقتَين FindFullHashes وFetchThreatListUpdates . تتطلّب Update API أن يحتفظ العملاء بقوائم التهديدات التي تم تنزيلها في قاعدة بيانات محلية.

أولاً، تتم مطابقة العملاء مع قوائمهم المحلية لتحديد حالة مصدر ويب معيّن (آمن أو غير آمن). في أغلب الأحيان، تتألف القوائم من بادئات تجزئة لتعابير عناوين URL المُدرَجة في القائمة السوداء. للتحقّق من عنوان URL، ينشئ العملاء تجزئات لعنوان URL معيّن ويتحقّقون من تعارض البادئة في قوائمهم المحلية. وفي حال العثور على مطابقة بادئة، يحصل العميل على التجزئات الكاملة المرتبطة ببادئة التجزئة المطابقة من خلال طريقة FindFullHashes. بعد ذلك، يقارن العميل التجزئة الكاملة المحلية بالتجزئات الكاملة التي تم عرضها، ويشير التطابق إلى أنّ عنوان URL غير آمن.

ثانيًا، يحصل العملاء على تعديلات على قواعد بياناتهم المحلية من خلال طريقة FetchThreatListUpdates التي تأخذ الحالة الحالية للعميل وتُرجع حالة العميل المعدَّلة مع التغييرات التي يجب أن يطبّقها العميل على قوائم التهديدات المحلية.

تم تصميم Lookup API للعملاء الأصغر حجمًا، وتتيح لهم مطابقة الموارد مباشرةً مع قوائم التهديدات في "التصفّح الآمن" من خلال طريقة FindThreatMatches.

يمكن للعملاء الذين يستخدمون Update API أو Lookup API الحصول على قائمة بقوائم التهديدات في ميزة "التصفح الآمن" المتاحة للتنزيل من خلال طريقة ListThreatLists.

{-- TRUSTED_THREAT_REPORTER: يمكن لعميل التهديد الموثوق به إرسال تقارير إلى Google لتحليلها من خلال طريقة SubmitThreatReport. --}

FetchThreatListUpdates

rpc FetchThreatListUpdates(FetchThreatListUpdatesRequest) returns (FetchThreatListUpdatesResponse)

تُستخدَم هذه الوظيفة لجلب آخر تعديلات على قائمة التهديدات. يمكن للعميل طلب تعديلات على قوائم متعددة في آنٍ واحد.
FindFullHashes

rpc FindFullHashes(FindFullHashesRequest) returns (FindFullHashesResponse)

يبحث عن التجزئات الكاملة التي تتطابق مع بادئات التجزئة المطلوبة.
FindThreatMatches

rpc FindThreatMatches(FindThreatMatchesRequest) returns (FindThreatMatchesResponse)

يبحث عن إدخالات التهديدات التي تتطابق مع قوائم "التصفّح الآمن".
ListThreatLists

rpc ListThreatLists(Empty) returns (ListThreatListsResponse)

يعرض هذا القسم قوائم التهديدات في ميزة "التصفّح الآمن" المتاحة للتنزيل.

المجموع الاختباري

الحالة المتوقّعة لقاعدة بيانات العميل المحلية.

الحقول
sha256

bytes

تجزئة SHA256 لحالة العميل، أي القائمة المرتبطة بجميع التجزئات المتوفّرة في قاعدة البيانات

ClientInfo

البيانات الوصفية للعميل المرتبطة بطلبات واجهة برمجة التطبيقات Safe Browsing API

الحقول
client_id

string

رقم تعريف عميل يحدِّد بشكل فريد (على أمل ذلك) تنفيذ العميل لواجهة برمجة التطبيقات Safe Browsing API.
client_version

string

إصدار تنفيذ العميل.

CompressionType

الطرق التي يمكن بها ضغط مجموعات إدخال التهديدات

عمليات التعداد
COMPRESSION_TYPE_UNSPECIFIED غير معروف.
RAW البيانات الأولية غير المضغوطة
RICE البيانات المشفّرة بترميز Rice-Golomb

FetchThreatListUpdatesRequest

يصف هذا القسم طلب تعديل واجهة برمجة التطبيقات Safe Browsing API. يمكن للعملاء طلب تعديلات على قوائم متعددة في طلب واحد. قد لا يستجيب الخادم لجميع الطلبات إذا لم يكن لديه أي تعديلات لهذه القائمة. ملاحظة: فهرس الحقل 2 غير مستخدَم. التالي: 5

الحقول
client

ClientInfo

البيانات الوصفية للعميل
list_update_requests[]

ListUpdateRequest

يتم تعديل قائمة التهديدات المطلوبة.

ListUpdateRequest

طلب واحد لتعديل قائمة

الحقول
threat_type

ThreatType

نوع التهديد الذي تشكله الإدخالات المتوفّرة في القائمة
platform_type

PlatformType

نوع المنصة المعرضة للخطر حسب الإدخالات المتوفّرة في القائمة
threat_entry_type

ThreatEntryType

أنواع الإدخالات المتوفّرة في القائمة
state

bytes

الحالة الحالية للعميل في القائمة المطلوبة (حالة العميل المشفّرة التي تمّ تلقّيها من آخر تعديل ناجح للقائمة).
constraints

Constraints

القيود المرتبطة بهذا الطلب

القيود

قيود هذا التعديل

الحقول
max_update_entries

int32

الحد الأقصى للحجم حسب عدد الإدخالات لن يحتوي التعديل على إدخالات أكثر من هذه القيمة. يجب أن يكون هذا الرقم ناتجًا عن رفع العدد 2 إلى قوة بين 2**10 و2**20. إذا كان القيمة صفرًا، لن يتم ضبط حد أقصى لحجم التعديل.
max_database_entries

int32

لضبط الحد الأقصى لعدد الإدخالات التي يريد العميل أن يتضمّنها قاعدة البيانات المحلية للقوائم المحدّدة. يجب أن يكون هذا الرقم ناتجًا عن رفع العدد 2 إلى قوة بين 2**10 و2**20. إذا كان القيمة صفر، لا يتم ضبط حد أقصى لحجم قاعدة البيانات.
region

string

تطلب القائمة لموقع جغرافي محدّد. في حال عدم ضبطها، قد يختار الخادم هذه القيمة استنادًا إلى عنوان IP الخاص بالمستخدم. يُفترض أن يكون التنسيق هو ISO 3166-1 alpha-2.
supported_compressions[]

CompressionType

أنواع الضغط المتوافقة مع العميل
language

string

يطلب القوائم بلغة معيّنة. يتوقّع التنسيق ISO 639 alpha-2.
device_location

string

الموقع الجغرافي للعميل، مُعبَّرًا عنه كرمز منطقة وفقًا لمعيار ISO 31166-1 alpha-2

FetchThreatListUpdatesResponse

الحقول
list_update_responses[]

ListUpdateResponse

تعديلات القائمة التي يطلبها العملاء قد يكون عدد الردود هنا أقل من عدد الطلبات التي أرسلها العملاء. يحدث ذلك، على سبيل المثال، إذا لم يكن لدى الخادم أي تعديلات لقائمة معيّنة.
minimum_wait_duration

Duration

الحد الأدنى لمدة الانتظار التي يجب أن ينتظرها العميل قبل إصدار أي طلب تعديل. في حال عدم ضبط هذا الحقل، يمكن للعملاء إجراء التعديلات متى شاؤوا.

ListUpdateResponse

تعديل في قائمة فردية

الحقول
threat_type

ThreatType

نوع التهديد الذي يتم عرض البيانات عنه.
threat_entry_type

ThreatEntryType

تنسيق التهديدات
platform_type

PlatformType

نوع النظام الأساسي الذي يتم عرض البيانات له.
response_type

ResponseType

نوع الردّ. قد يشير ذلك إلى أنّ العميل مطلوب منه اتّخاذ إجراء عند تلقّي الاستجابة.
additions[]

ThreatEntrySet

مجموعة من الإدخالات التي سيتمّ إضافتها إلى قائمة أنواع التهديدات المحلية يتم تكرار هذا الإجراء للسماح بإرسال مجموعة من البيانات المضغوطة والبيانات الأوّلية في ردّ واحد.
removals[]

ThreatEntrySet

مجموعة من الإدخالات التي يجب إزالتها من قائمة أنواع التهديدات المحلية في الممارسة العملية، يكون هذا الحقل فارغًا أو يحتوي على مجموعة ThreatEntrySet واحدة بالضبط.
new_client_state

bytes

حالة العميل الجديدة بتنسيق مشفَّر غير شفافة للعملاء
checksum

Checksum

تجزئة SHA256 المتوقّعة لحالة العميل، أي القائمة المرتبطة بجميع التجزئات المتوفّرة في قاعدة البيانات بعد تطبيق التعديل المقدَّم. إذا لم تتطابق حالة العميل مع الحالة المتوقّعة، على العميل تجاهل هذا التعديل وإعادة المحاولة لاحقًا.

ResponseType

نوع الاستجابة المُرسَلة إلى العميل.

عمليات التعداد
RESPONSE_TYPE_UNSPECIFIED غير معروف.
PARTIAL_UPDATE يتم تطبيق التعديلات الجزئية على قاعدة البيانات المحلية الحالية للعميل.
FULL_UPDATE تستبدل التحديثات الكاملة قاعدة البيانات المحلية بالكامل للعميل. وهذا يعني أنّ العميل كان قديمًا جدًا أو أنّه تعذّر تحميله.

FindFullHashesRequest

طلب عرض التجزئات الكاملة التي تتطابق مع بادئات التجزئة المقدَّمة

الحقول
client

ClientInfo

البيانات الوصفية للعميل
client_states[]

bytes

حالات العميل الحالية لكل قائمة من قوائم التهديدات المحلية للعميل
threat_info

ThreatInfo

القوائم والدوالّ التجزئية التي يجب التحقّق منها
api_client

ClientInfo

البيانات الوصفية للعميل المرتبطة بالمُتصلين بواجهات برمجة التطبيقات ذات المستوى الأعلى والمُنشأة على تنفيذ العميل

FindFullHashesResponse

الحقول
matches[]

ThreatMatch

التجزئات الكاملة التي تطابقت مع البادئات المطلوبة
minimum_wait_duration

Duration

الحد الأدنى للمدة التي يجب أن ينتظرها العميل قبل إصدار أي طلب للعثور على التجزئات. في حال عدم ضبط هذا الحقل، يمكن للعملاء تقديم طلب في أي وقت يرونه مناسبًا.
negative_cache_duration

Duration

مدة تخزين الاستجابة مؤقتًا للكيانات المطلوبة التي لم تتطابق مع قائمة التهديدات

FindThreatMatchesRequest

طلب التحقّق من الإدخالات مقارنةً بالقوائم

الحقول
client

ClientInfo

البيانات الوصفية للعميل
threat_info

ThreatInfo

القوائم والإدخالات التي سيتم التحقّق منها بحثًا عن المطابقات

FindThreatMatchesResponse

الحقول
matches[]

ThreatMatch

تتطابق قائمة التهديدات.

ListThreatListsResponse

الحقول
threat_lists[]

ThreatListDescriptor

القوائم المتاحة للتنزيل من قِبل العميل

PlatformType

أنواع المنصات

عمليات التعداد
PLATFORM_TYPE_UNSPECIFIED منصة غير معروفة
WINDOWS التهديد الذي يشكّله هذا التهديد لنظام التشغيل Windows
LINUX التهديد الذي يشكّله هذا التهديد لنظام التشغيل Linux
ANDROID التهديد الذي يشكّله التطبيق لنظام التشغيل Android
OSX تهديد يشكّله نظام التشغيل OS X
IOS تهديد يواجه نظام التشغيل iOS
ANY_PLATFORM التهديد الذي يشكّله الخطر على نظام أساسي واحد على الأقل من الأنظمة الأساسية المحدّدة
ALL_PLATFORMS التهديد الذي يشكّله المحتوى لجميع المنصات المحدّدة
CHROME التهديد الذي يواجهه Chrome

RawHashes

إدخالات التهديدات غير المضغوطة بتنسيق تجزئة بطول بادئة معيّن يمكن أن يتراوح حجم السلسلة المحوَّلة إلى رمز بين 4 و32 بايت. وغالبًا ما تكون 4 بايت، ولكن يتم إطالة بعض التجزئات إذا تطابقت مع تجزئة عنوان URL شائع.

تُستخدَم لإرسال ThreatEntrySet إلى العملاء الذين لا يتيحون ميزة الضغط، أو عند إرسال تجزئات غير تجزئات 4 بايت إلى العملاء الذين يتيحون ميزة الضغط.

الحقول
prefix_size

int32

عدد البايتات لكل بادئة تم ترميزها أدناه. يمكن أن يتراوح طول هذا الحقل بين 4 (أقصر بادئة) و32 (تجزئة SHA256 الكاملة).
raw_hashes

bytes

التجزئات بتنسيق ثنائي، والتي تم تجميعها في سلسلة طويلة واحدة يتم ترتيب العلامات التجزئية بترتيب أبجدي. بالنسبة إلى مستخدمي واجهة برمجة التطبيقات JSON API، يتم ترميز التجزئات باستخدام ترميز base64.

RawIndices

مجموعة من الفهارس الأوّلية المطلوب إزالتها من قائمة محلية

الحقول
indices[]

int32

الفهرس المطلوب إزالته من قائمة محلية مرتبة أبجديًا

RiceDeltaEncoding

البيانات المشفّرة بترميز Rice-Golomb تُستخدَم لإرسال تجزئات مضغوطة من 4 بايت أو مؤشرات إزالة مضغوطة.

الحقول
first_value

int64

فهرس الإدخال الأول في البيانات المشفَّرة، أو قيمة هذا العدد الصحيح الفردي في حال تم ترميز عدد صحيح واحد فقط. إذا كان الحقل فارغًا أو غير متوفّر، افترض القيمة صفر.
rice_parameter

int32

مَعلمة Golomb-Rice، وهي عدد يتراوح بين 2 و28 لا يتوفّر هذا الحقل (أي القيمة صفر) إذا كانت num_entries تساوي صفرًا.
num_entries

int32

عدد الإدخالات التي تم تشفيرها باستخدام ترميز دلتا في البيانات المشفَّرة. إذا تم ترميز عدد صحيح واحد فقط، سيكون هذا العنصر هو الصفر وسيتم تخزين القيمة الواحدة في first_value.
encoded_data

bytes

القيم المتزايدة التي تم ترميزها باستخدام ترميز Golomb-Rice

ThreatEntry

تهديد فردي، مثل عنوان URL ضار أو تمثيل التجزئة يجب ضبط حقل واحد فقط من هذه الحقول.

الحقول
hash

bytes

بادئة تجزئة تتألف من 4 إلى 32 بايتًا الأكثر أهمية من تجزئة SHA256 هذا الحقل بتنسيق ثنائي. بالنسبة إلى طلبات JSON، يتم ترميز التجزئات بترميز base64.
url

string

عنوان URL
digest

bytes

الملخّص الخاص بملف قابل للتنفيذ بتنسيق SHA256 تتيح واجهة برمجة التطبيقات كلاً من الملخّصات الثنائية والسادسة عشرية. بالنسبة إلى طلبات JSON، يتم ترميز الملخّصات بترميز base64.

ThreatEntryMetadata

البيانات الوصفية المرتبطة بإدخال تهديد معيّن من المتوقّع أن يعرف العميل أزواج مفتاح/قيمة البيانات الوصفية المرتبطة بكل نوع من أنواع التهديدات.

الحقول
entries[]

MetadataEntry

إدخالات البيانات الوصفية

MetadataEntry

إدخال بيانات وصفية واحد

الحقول
key

bytes

مفتاح إدخال البيانات الوصفية بالنسبة إلى طلبات JSON، يتم ترميز المفتاح بترميز base64.
value

bytes

قيمة إدخال البيانات الوصفية بالنسبة إلى طلبات JSON، يتم ترميز القيمة باستخدام base64.

ThreatEntrySet

مجموعة من التهديدات التي يجب إضافتها أو إزالتها من قاعدة بيانات العميل المحلية

الحقول
compression_type

CompressionType

نوع الضغط للعناصر في هذه المجموعة.
raw_hashes

RawHashes

الإدخالات الأولية بتنسيق SHA256
raw_indices

RawIndices

مؤشرات الإزالة الأوّلية لقائمة محلية
rice_hashes

RiceDeltaEncoding

البادئات المشفّرة المكونة من 4 بايت للعناصر بتنسيق SHA256، باستخدام ترميز Golomb-Rice يتم تحويل التجزئات إلى uint32، ويتم ترتيبها بترتيب تصاعدي، ثم يتم ترميزها باستخدام ترميز delta وتخزينها كـ encoded_data.
rice_indices

RiceDeltaEncoding

مؤشرات القوائم المحلية المرمّزة والمرتَّبة أبجديًا باستخدام ترميز Golomb-Rice يُستخدَم لإرسال مؤشرات الإزالة المضغوطة. يتم ترتيب مؤشرات الإزالة (uint32) بترتيب تصاعدي، ثم يتم ترميزها باستخدام ترميز delta وتخزينها كـ encoded_data.

ThreatEntryType

أنواع الإدخالات التي تشكل تهديدات قوائم التهديدات هي مجموعات من الإدخالات من نوع واحد.

عمليات التعداد
THREAT_ENTRY_TYPE_UNSPECIFIED غير محدد
URL عنوان URL
EXECUTABLE برنامج قابل للتنفيذ

ThreatInfo

المعلومات المتعلّقة بتهديد واحد أو أكثر يرسلها العميل عند البحث عن المطابقات في قوائم التهديدات

الحقول
threat_types[]

ThreatType

أنواع التهديدات المطلوب التحقّق منها
platform_types[]

PlatformType

أنواع المنصات المطلوب التحقّق منها
threat_entry_types[]

ThreatEntryType

أنواع الإدخالات المطلوب التحقّق منها
threat_entries[]

ThreatEntry

إدخالات التهديدات المطلوب التحقّق منها

ThreatListDescriptor

يصف قائمة تهديدات فردية. يتم تحديد القائمة من خلال ثلاث مَعلمات: نوع التهديد الذي يشكّله، ونوع المنصة التي يستهدفها التهديد، ونوع الإدخالات في القائمة.

الحقول
threat_type

ThreatType

نوع التهديد الذي تشكله إدخالات القائمة
platform_type

PlatformType

نوع المنصة المستهدَف ببيانات القائمة.
threat_entry_type

ThreatEntryType

أنواع الإدخالات الواردة في القائمة

ThreatMatch

تطابق عند التحقّق من إدخال تهديد في قوائم التهديدات في ميزة "التصفّح الآمن"

الحقول
threat_type

ThreatType

نوع التهديد المطابق لهذا التهديد
platform_type

PlatformType

نوع المنصة الذي يتطابق مع هذا التهديد
threat_entry_type

ThreatEntryType

نوع إدخال التهديد الذي يتطابق مع هذا التهديد.
threat

ThreatEntry

التهديد المطابق لهذا التهديد
threat_entry_metadata

ThreatEntryMetadata

بيانات وصفية اختيارية مرتبطة بهذه التهديد
cache_duration

Duration

مدة التخزين المؤقت للمطابقة التي تم عرضها. يجب ألا يخزِّن العملاء هذا الردّ في ذاكرة التخزين المؤقت لأكثر من هذه المدة لتجنُّب النتائج الإيجابية الزائفة.

ThreatType

أنواع التهديدات

عمليات التعداد
THREAT_TYPE_UNSPECIFIED غير معروف.
MALWARE نوع تهديد البرامج الضارة
SOCIAL_ENGINEERING نوع التهديد الناتج عن الهندسة الاجتماعية
UNWANTED_SOFTWARE نوع التهديد بالبرامج غير المرغوب فيها
POTENTIALLY_HARMFUL_APPLICATION نوع التهديد الذي يمثله التطبيق الذي قد يتسبّب بضرر