Package google.security.safebrowsing.v4

الفهرس

SafeBrowsing

تتيح واجهات برمجة التطبيقات للتصفح الآمن للعملاء التحقق من موارد الويب (معظم عناوين URL الشائعة) بمقارنتها بقوائم موارد الويب غير الآمنة التي تُحدِّثها Google باستمرار. تتميز واجهات برمجة التطبيقات للتصفح الآمن (الإصدار 4) بواجهة برمجة التطبيقات للتحديث وواجهة برمجة تطبيقات Lookup.

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

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

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

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

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

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

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

البيانات الوصفية للعميل المرتبطة بطلبات واجهة برمجة التطبيقات للتصفح الآمن

الحقول
client_id

string

معرّف عميل (نأمل) يعرّف بشكل فريد تنفيذ العميل لواجهة برمجة تطبيقات التصفح الآمن.
client_version

string

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

CompressionType

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

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

FetchThreatListUpdatesRequest

يصِف طلب تحديث واجهة برمجة التطبيقات للتصفح الآمن. يمكن للعملاء طلب تحديثات لقوائم متعددة في طلب واحد. قد لا يستجيب الخادم لجميع الطلبات في حال لم تتوفر لدى الخادم أي تحديثات لهذه القائمة. ملاحظة: فهرس الحقل 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، ويتم فرزها بترتيب تصاعدي، ثم تشفير دلتا وتخزينها كـ RDFa_data.
rice_indices

RiceDeltaEncoding

فهارس قوائم محلية مرمّزة تم ترتيبها بشكل لغوي، وذلك باستخدام ترميز Golomb-Rice يتم استخدام البيانات لإرسال فهارس إزالة مضغوطة. يتم فرز فهارس الإزالة (uint32) بترتيب تصاعدي، ثم تشفير دلتا وتخزينها كـ RDFa_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 نوع تهديد التطبيق الذي قد يتسبّب بضرر