Package google.security.safebrowsing.v4

فهرست مطالب

مرور ایمن

APIهای مرور ایمن به مشتریان این امکان را می‌دهند که منابع وب (معمولاً URLها) را در برابر فهرست‌های دائماً به‌روز شده منابع وب ناامن Google بررسی کنند. APIهای Safe Browsing (v4) دارای 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: مشتریان تهدید مورد اعتماد می توانند گزارش هایی را برای تجزیه و تحلیل از طریق روش SubmitThreatReport به Google ارسال کنند. --}

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

فراداده مشتری مرتبط با درخواست های API مرور ایمن.

زمینه های
client_id

string

شناسه سرویس گیرنده ای که (امیدواریم) به طور منحصر به فرد اجرای سرویس گیرنده Safe Browsing API را مشخص می کند.

client_version

string

نسخه اجرای مشتری.

نوع فشرده سازی

روش هایی که می توان مجموعه های ورودی تهدید را فشرده کرد.

Enums
COMPRESSION_TYPE_UNSPECIFIED ناشناخته.
RAW داده های خام و فشرده نشده
RICE داده های رمزگذاری شده Rice-Golomb.

FetchThreatListUpdatesRequest

یک درخواست به‌روزرسانی 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 قالب آلفا-2.

supported_compressions[]

CompressionType

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

language

string

لیست ها را برای یک زبان خاص درخواست می کند. انتظار می رود ISO 639 آلفا-2 فرمت.

device_location

string

مکان فیزیکی مشتری، که به عنوان کد منطقه آلفا-2 ISO 31166-1 بیان شده است.

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 از حالت کلاینت؛ یعنی لیست مرتب شده همه هش های موجود در پایگاه داده پس از اعمال به روز رسانی ارائه شده. اگر حالت سرویس گیرنده با وضعیت مورد انتظار مطابقت نداشته باشد، مشتری باید این به‌روزرسانی را نادیده بگیرد و بعداً دوباره امتحان کند.

نوع پاسخ

نوع پاسخ ارسال شده به مشتری

Enums
RESPONSE_TYPE_UNSPECIFIED ناشناخته.
PARTIAL_UPDATE به روز رسانی های جزئی در پایگاه داده محلی موجود مشتری اعمال می شود.
FULL_UPDATE به روز رسانی کامل جایگزین کل پایگاه داده محلی مشتری می شود. این به این معنی است که یا مشتری به طور جدی منسوخ شده است یا اینکه مشتری فاسد است.

FindFullHashesRequest

درخواست برای بازگرداندن هش های کامل مطابق با پیشوندهای هش ارائه شده.

زمینه های
client

ClientInfo

فراداده مشتری

client_states[]

bytes

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

threat_info

ThreatInfo

لیست ها و هش هایی که باید بررسی شوند.

api_client

ClientInfo

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

FindFullHashesResponse

زمینه های
matches[]

ThreatMatch

هش کامل که با پیشوندهای درخواستی مطابقت دارد.

minimum_wait_duration

Duration

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

negative_cache_duration

Duration

برای نهادهای درخواستی که با لیست تهدید مطابقت ندارند، چه مدت باید پاسخ را در حافظه پنهان نگه دارید.

FindThreatMatchesRequest

درخواست بررسی ورودی ها در برابر لیست ها.

زمینه های
client

ClientInfo

فراداده مشتری

threat_info

ThreatInfo

لیست ها و مدخل هایی که باید برای مطابقت بررسی شوند.

FindThreatMatchesResponse

زمینه های
matches[]

ThreatMatch

لیست تهدید مطابقت دارد.

ListThreatListsResponse

زمینه های
threat_lists[]

ThreatListDescriptor

لیست های موجود برای دانلود توسط مشتری.

نوع پلتفرم

انواع پلتفرم ها.

Enums
PLATFORM_TYPE_UNSPECIFIED پلت فرم ناشناخته
WINDOWS تهدیدی برای ویندوز
LINUX تهدیدی برای لینوکس
ANDROID تهدیدی برای اندروید
OSX تهدیدی برای OS X.
IOS تهدیدی برای iOS
ANY_PLATFORM حداقل یکی از پلتفرم های تعریف شده را تهدید می کند.
ALL_PLATFORMS تهدیدی برای همه پلتفرم های تعریف شده ایجاد می شود.
CHROME تهدیدی برای Chrome

RawHashs

تهدیدهای فشرده نشده در قالب هش با طول پیشوند خاص وارد می شود. اندازه هش ها می تواند از 4 تا 32 بایت باشد. اکثریت بزرگ 4 بایت هستند، اما برخی از هش ها در صورت برخورد با هش URL محبوب، طولانی تر می شوند.

برای ارسال ThreatEntrySet به کلاینت هایی که از فشرده سازی پشتیبانی نمی کنند یا هنگام ارسال هش های غیر 4 بایتی به کلاینت هایی که از فشرده سازی پشتیبانی می کنند استفاده می شود.

زمینه های
prefix_size

int32

تعداد بایت ها برای هر پیشوند در زیر کدگذاری شده است. این فیلد می تواند از 4 (کوتاه ترین پیشوند) تا 32 (هش کامل SHA256) باشد.

raw_hashes

bytes

هش ها، در قالب باینری، به یک رشته طولانی متصل می شوند. هش ها به ترتیب واژگانی مرتب شده اند. برای کاربران JSON API، هش ها با پایه 64 کدگذاری می شوند.

شاخص های خام

مجموعه ای از شاخص های خام برای حذف از یک لیست محلی.

زمینه های
indices[]

int32

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

RiceDeltaEncoding

داده های رایس-گلومب رمزگذاری شده است. برای ارسال هش های فشرده 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، هش‌ها با پایه ۶۴ کدگذاری می‌شوند.

url

string

یک URL.

digest

bytes

خلاصه یک فایل اجرایی با فرمت SHA256. API از هر دو هضم باینری و هگز پشتیبانی می کند. برای درخواست‌های JSON، خلاصه‌ها با پایه 64 کدگذاری می‌شوند.

ThreatEntryMetadata

فراداده مرتبط با یک ورودی تهدید خاص. از مشتری انتظار می رود جفت های کلید/مقدار فراداده مرتبط با هر نوع تهدید را بداند.

زمینه های
entries[]

MetadataEntry

ورودی های فراداده

ورود فراداده

یک ورودی ابرداده واحد.

زمینه های
key

bytes

کلید ورود فراداده برای درخواست های JSON، کلید با پایه 64 کدگذاری شده است.

value

bytes

مقدار ورودی فراداده برای درخواست‌های JSON، مقدار با پایه 64 کدگذاری می‌شود.

ThreatEntrySet

مجموعه ای از تهدیدات که باید از پایگاه داده محلی مشتری اضافه یا حذف شوند.

زمینه های
compression_type

CompressionType

نوع فشرده سازی برای ورودی های این مجموعه.

raw_hashes

RawHashes

ورودی های خام با قالب SHA256.

raw_indices

RawIndices

شاخص های حذف خام برای یک لیست محلی.

rice_hashes

RiceDeltaEncoding

پیشوندهای کدگذاری شده 4 بایتی ورودی های با فرمت SHA256، با استفاده از رمزگذاری Golomb-Rice. هش ها به uint32 تبدیل می شوند، به ترتیب صعودی مرتب می شوند، سپس دلتا کدگذاری می شوند و به عنوان encoded_data ذخیره می شوند.

rice_indices

RiceDeltaEncoding

فهرست‌های محلی رمزگذاری‌شده، واژگانی مرتب‌شده، با استفاده از رمزگذاری Golomb-Rice. برای ارسال شاخص های حذف فشرده استفاده می شود. شاخص های حذف (uint32) به ترتیب صعودی مرتب می شوند، سپس دلتا کدگذاری می شوند و به عنوان encoded_data ذخیره می شوند.

ThreatEntryType

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

Enums
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

انواع تهدید.

Enums
THREAT_TYPE_UNSPECIFIED ناشناخته.
MALWARE نوع تهدید بدافزار
SOCIAL_ENGINEERING نوع تهدید مهندسی اجتماعی
UNWANTED_SOFTWARE نوع تهدید نرم افزار ناخواسته
POTENTIALLY_HARMFUL_APPLICATION نوع تهدید برنامه بالقوه مضر