Package google.security.safebrowsing.v5alpha1

فهرست

مرور ایمن

رابط‌های برنامه‌نویسی کاربردی مرور ایمن (Safe Browsing APIs) به کاربران این امکان را می‌دهند که منابع وب (عمدتاً URLها) را با فهرست‌های دائماً به‌روز شده‌ی گوگل از منابع وب ناامن مقایسه کنند.

لیست‌های دسته‌ای دریافت هش

rpc BatchGetHashLists( BatchGetHashListsRequest ) returns ( BatchGetHashListsResponse )

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

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

این یک روش استاندارد دریافت دسته‌ای است که توسط https://google.aip.dev/231 تعریف شده است و روش HTTP نیز GET است.

دریافت لیست هش

rpc GetHashList( GetHashListRequest ) returns ( HashList )

آخرین محتویات یک لیست هش را دریافت کنید. یک لیست هش ممکن است شامل یک لیست تهدید یا یک لیست غیر تهدید مانند Global Cache باشد.

این یک روش استاندارد Get است که توسط https://google.aip.dev/131 تعریف شده است و روش HTTP نیز GET است.

لیست‌های هش

rpc ListHashLists( ListHashListsRequest ) returns ( ListHashListsResponse )

لیست‌های هش را فهرست کنید.

در API نسخه ۵، گوگل هرگز لیست هشی را که قبلاً توسط این روش برگردانده شده است، حذف نمی‌کند. این امر به کلاینت‌ها این امکان را می‌دهد که از استفاده از این روش صرف نظر کرده و تمام لیست‌های هشی مورد نیاز خود را به سادگی در کدنویسی ثابت (hardcode) کنند.

این یک روش استاندارد List است که توسط https://google.aip.dev/132 تعریف شده است و روش HTTP آن GET است.

هش‌های جستجو

rpc SearchHashes( SearchHashesRequest ) returns ( SearchHashesResponse )

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

این یک روش سفارشی است که توسط https://google.aip.dev/136 تعریف شده است (روش سفارشی به این روش اشاره دارد که دارای نام سفارشی در نامگذاری عمومی توسعه API گوگل است؛ به استفاده از یک روش HTTP سفارشی اشاره ندارد).

آدرس‌های جستجو

rpc SearchUrls( SearchUrlsRequest ) returns ( SearchUrlsResponse )

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

درخواست BatchGetHashLists

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

فیلدها
names[]

string

الزامی. نام‌های فهرست‌های هش خاص. این فهرست می‌تواند یک فهرست تهدید یا فهرست سراسری داده‌ها باشد. نام‌ها نباید شامل موارد تکراری باشند؛ در این صورت، کلاینت با خطا مواجه خواهد شد.

version[]

bytes

نسخه‌هایی از لیست هش که کلاینت از قبل دارد. اگر این اولین باری است که کلاینت لیست‌های هش را دریافت می‌کند، این فیلد باید خالی بماند. در غیر این صورت، کلاینت باید نسخه‌هایی را که قبلاً از سرور دریافت کرده است، ارائه دهد. کلاینت نباید آن بایت‌ها را دستکاری کند.

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

نکته‌ی تاریخی: در نسخه‌ی ۴ از API، این بخش states نام داشت؛ اکنون برای وضوح بیشتر به version تغییر نام داده شده است.

size_constraints

SizeConstraints

محدودیت‌های اندازه در هر لیست. اگر حذف شود، هیچ محدودیتی وجود ندارد. توجه داشته باشید که اندازه‌ها در اینجا برای هر لیست هستند، نه برای همه لیست‌ها.

پاسخ BatchGetHashLists

پاسخی که حاوی چندین لیست هش است.

فیلدها
hash_lists[]

HashList

هش به همان ترتیبی که در درخواست داده شده است، فهرست می‌شود.

فول‌هش

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

فیلدها
full_hash

bytes

هش کامل منطبق. این هش SHA256 است. طول آن دقیقاً ۳۲ بایت خواهد بود.

full_hash_details[]

FullHashDetail

لیست نامرتب. یک فیلد تکراری که جزئیات مربوط به این هش کامل را مشخص می‌کند.

جزئیات کامل

جزئیات مربوط به یک هش کامل منطبق.

نکته‌ای مهم در مورد سازگاری رو به جلو: انواع تهدیدها و ویژگی‌های تهدید جدید ممکن است در هر زمانی توسط سرور اضافه شوند؛ این تغییرات جزئی نسخه در نظر گرفته می‌شوند. سیاست گوگل این است که شماره نسخه‌های جزئی را در APIها افشا نکند (برای سیاست نسخه‌بندی به https://cloud.google.com/apis/design/versioning مراجعه کنید)، بنابراین کلاینت‌ها باید آماده دریافت پیام‌های FullHashDetail حاوی مقادیر ThreatType enum یا ThreatAttribute enum باشند که توسط کلاینت نامعتبر تلقی می‌شوند. بنابراین، مسئولیت کلاینت است که اعتبار تمام مقادیر ThreatType و ThreatAttribute enum را بررسی کند. اگر هر مقداری نامعتبر تلقی شود، کلاینت باید کل پیام FullHashDetail را نادیده بگیرد.

فیلدها
threat_type

ThreatType

نوع تهدید. این فیلد هرگز خالی نخواهد بود.

attributes[]

ThreatAttribute

لیست نامرتب. ویژگی‌های اضافی در مورد آن هش‌های کامل. این ممکن است خالی باشد.

درخواست GetHashList

درخواستی برای دریافت فهرست هش، که می‌تواند یک فهرست تهدید یا یک فهرست غیرتهدید مانند فهرست سراسری کش باشد.

ویژگی‌های جدید در نسخه ۵ : آنچه قبلاً در نسخه ۴ به عنوان states شناخته می‌شد، برای وضوح بیشتر به version ۵ تغییر نام داده شده است. لیست‌ها اکنون نامگذاری شده‌اند، انواع پلتفرم و انواع ورودی تهدید حذف شده‌اند. اکنون می‌توان چندین لیست را با یک نوع تهدید یا یک لیست واحد با چندین نوع تهدید مرتبط کرد. برخلاف پیشوندهای هش با طول متغیر نسخه ۴ که در بسیاری از پیاده‌سازی‌های کلاینت مشکل ایجاد کرده بود: اکنون همه هش‌های موجود در یک لیست دارای یک طول واحد هستند که امکان پیاده‌سازی‌های کلاینت بسیار کارآمدتر را فراهم می‌کند. محدودیت‌ها ساده شده‌اند و نوع فشرده‌سازی حذف شده است (فشرده‌سازی همیشه اعمال می‌شود).

فیلدها
name

string

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

version

bytes

نسخه‌ای از لیست هش که کلاینت از قبل دارد. اگر این اولین باری است که کلاینت لیست هش را دریافت می‌کند، این فیلد باید خالی بماند. در غیر این صورت، کلاینت باید نسخه‌ای را که قبلاً از سرور دریافت کرده است، ارائه دهد. کلاینت نباید آن بایت‌ها را دستکاری کند.

ویژگی‌های جدید نسخه ۵ : در نسخه ۴ این API، این states نام داشت؛ اکنون برای وضوح بیشتر، به version تغییر نام داده شده است.

size_constraints

SizeConstraints

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

هش‌لیست

فهرستی از هش‌هایی که با نامشان مشخص شده‌اند.

فیلدها
name

string

نام لیست هش. توجه داشته باشید که Global Cache نیز فقط یک لیست هش است و می‌توان به آن در اینجا اشاره کرد.

version

bytes

نسخه لیست هش. کلاینت نباید آن بایت‌ها را دستکاری کند.

partial_update

bool

وقتی درست باشد، این یک تفاضل جزئی است که شامل اضافه کردن‌ها و حذف‌ها بر اساس آنچه کلاینت از قبل دارد، می‌شود. وقتی نادرست باشد، این لیست هش کامل است.

وقتی مقدار false باشد، کلاینت باید هر نسخه ذخیره شده محلی را برای این لیست هش حذف کند. این بدان معناست که یا نسخه‌ای که کلاینت در اختیار دارد به طور جدی قدیمی است یا داده‌های کلاینت خراب تلقی می‌شوند. فیلد compressed_removals خالی خواهد بود.

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

compressed_removals

RiceDeltaEncoded32Bit

نسخه کدگذاری شده Rice-delta از شاخص‌های حذف. از آنجایی که هر لیست هش قطعاً کمتر از 2^32 ورودی دارد، شاخص‌ها به عنوان اعداد صحیح 32 بیتی در نظر گرفته شده و کدگذاری می‌شوند.

minimum_wait_duration

Duration

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

sha256_checksum

bytes

لیست مرتب‌شده‌ی تمام هش‌ها، که دوباره با SHA256 هش شده است. این مجموع مقابله‌ای (checksum) برای لیست مرتب‌شده‌ی تمام هش‌های موجود در پایگاه داده پس از اعمال به‌روزرسانی ارائه شده است. در صورتی که هیچ به‌روزرسانی ارائه نشده باشد، سرور این فیلد را حذف می‌کند تا نشان دهد که کلاینت باید از مجموع مقابله‌ای موجود استفاده کند.

metadata

HashListMetadata

متادیتای مربوط به لیست هش. این توسط متد GetHashList پر نمی‌شود، اما توسط متد ListHashLists پر می‌شود.

فیلد اتحادیه compressed_additions . نسخه کدگذاری شده Rice-delta از جمع‌ها. طول پیشوند هش جمع‌ها در تمام جمع‌های موجود در لیست یکسان است. compressed_additions فقط می‌تواند یکی از موارد زیر باشد:
additions_four_bytes

RiceDeltaEncoded32Bit

جمع‌های ۴ بایتی.

additions_eight_bytes

RiceDeltaEncoded64Bit

اضافات ۸ بایتی.

additions_sixteen_bytes

RiceDeltaEncoded128Bit

اضافات ۱۶ بایتی.

additions_thirty_two_bytes

RiceDeltaEncoded256Bit

اضافات ۳۲ بایتی.

هش‌لیستفراداده

فراداده درباره یک فهرست درهم‌سازی خاص.

فیلدها
threat_types[]

ThreatType

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

likely_safe_types[]

LikelySafeType

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

description

string

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

hash_length

HashLength

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

طول هش

طول هش‌ها در یک لیست هش.

انوم‌ها
HASH_LENGTH_UNSPECIFIED طول نامشخص.
FOUR_BYTES هر هش یک پیشوند چهار بایتی است.
EIGHT_BYTES هر هش یک پیشوند هشت بایتی است.
SIXTEEN_BYTES هر هش یک پیشوند شانزده بایتی است.
THIRTY_TWO_BYTES هر هش، یک هش کامل سی و دو بایتی است.

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

انواع سایت‌های احتمالاً امن.

توجه داشته باشید که SearchHashesResponse عمداً شامل LikelySafeType نمی‌شود.

انوم‌ها
LIKELY_SAFE_TYPE_UNSPECIFIED ناشناخته.
GENERAL_BROWSING این سایت احتمالاً برای مرور عمومی به اندازه کافی امن است. این به عنوان حافظه پنهان سراسری نیز شناخته می‌شود.
CSD این سایت احتمالاً به اندازه کافی ایمن است که نیازی به اجرای مدل‌های تشخیص سمت کلاینت یا بررسی‌های محافظت از رمز عبور ندارد.
DOWNLOAD این سایت احتمالاً به اندازه کافی امن است که دانلودهای آن نیازی به بررسی نداشته باشند.

درخواست لیست هش لیست‌ها

درخواست برای فهرست کردن فهرست‌های هش موجود.

فیلدها
page_size

int32

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

page_token

string

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

پاسخ ListHashLists

پاسخی که شامل فراداده‌هایی در مورد فهرست‌های درهم‌سازی است.

فیلدها
hash_lists[]

HashList

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

next_page_token

string

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

RiceDeltaEncoded128Bit

همانند RiceDeltaEncoded32Bit است، با این تفاوت که این عددها را ۱۲۸ بیتی رمزگذاری می‌کند.

فیلدها
first_value_hi

uint64

۶۴ بیت بالایی اولین ورودی در داده‌های رمزگذاری شده (هش‌ها). اگر فیلد خالی باشد، ۶۴ بیت بالایی همگی صفر هستند.

first_value_lo

fixed64

۶۴ بیت پایینی اولین ورودی در داده‌های رمزگذاری شده (هش‌ها). اگر فیلد خالی باشد، ۶۴ بیت پایینی همگی صفر هستند.

rice_parameter

int32

پارامتر Golomb-Rice. این پارامتر تضمین می‌شود که بین ۹۹ تا ۱۲۶ باشد.

entries_count

int32

تعداد ورودی‌هایی که در داده‌های کدگذاری‌شده با روش دلتا کدگذاری شده‌اند. اگر فقط یک عدد صحیح کدگذاری شده باشد، این مقدار صفر خواهد بود و آن مقدار در first_value ذخیره می‌شود.

encoded_data

bytes

دلتاهای کدگذاری شده که با استفاده از کدگذار Golomb-Rice کدگذاری شده‌اند.

RiceDeltaEncoded256Bit

همانند RiceDeltaEncoded32Bit است، با این تفاوت که این عددها را ۲۵۶ بیتی رمزگذاری می‌کند.

فیلدها
first_value_first_part

uint64

۶۴ بیت اول از اولین ورودی در داده‌های رمزگذاری شده (هش‌ها). اگر فیلد خالی باشد، ۶۴ بیت اول همگی صفر هستند.

first_value_second_part

fixed64

بیت‌های ۶۵ تا ۱۲۸ام اولین ورودی در داده‌های رمزگذاری شده (هش‌ها). اگر فیلد خالی باشد، بیت‌های ۶۵ تا ۱۲۸ام همگی صفر هستند.

first_value_third_part

fixed64

بیت‌های ۱۲۹ تا ۱۹۲ام از اولین ورودی در داده‌های رمزگذاری شده (هش‌ها). اگر فیلد خالی باشد، بیت‌های ۱۲۹ تا ۱۹۲ام همگی صفر هستند.

first_value_fourth_part

fixed64

۶۴ بیت آخر اولین ورودی در داده‌های رمزگذاری شده (هش‌ها). اگر فیلد خالی باشد، ۶۴ بیت آخر همگی صفر هستند.

rice_parameter

int32

پارامتر Golomb-Rice. این پارامتر تضمین می‌شود که بین ۲۲۷ تا ۲۵۴ باشد.

entries_count

int32

تعداد ورودی‌هایی که در داده‌های کدگذاری‌شده با روش دلتا کدگذاری شده‌اند. اگر فقط یک عدد صحیح کدگذاری شده باشد، این مقدار صفر خواهد بود و آن مقدار در first_value ذخیره می‌شود.

encoded_data

bytes

دلتاهای کدگذاری شده که با استفاده از کدگذار Golomb-Rice کدگذاری شده‌اند.

RiceDeltaEncoded32Bit

داده‌های کدگذاری شده‌ی Rice-Golomb. برای هش‌ها یا شاخص‌های حذف استفاده می‌شود. تضمین می‌شود که هر هش یا شاخص در اینجا طول یکسانی دارد و این طول دقیقاً ۳۲ بیت است.

به طور کلی، اگر همه ورودی‌ها را به صورت لغوی مرتب کنیم، متوجه خواهیم شد که بیت‌های مرتبه بالاتر به اندازه بیت‌های مرتبه پایین‌تر تغییر نمی‌کنند. این بدان معناست که اگر اختلاف مجاورت بین ورودی‌ها را نیز در نظر بگیریم، بیت‌های مرتبه بالاتر احتمال بالایی برای صفر شدن دارند. این روش با انتخاب تعداد مشخصی از بیت‌ها، از این احتمال بالای صفر شدن بهره‌برداری می‌کند. همه بیت‌های مهم‌تر از این احتمالاً صفر هستند، بنابراین از کدگذاری یکانی استفاده می‌کنیم. به فیلد rice_parameter مراجعه کنید.

نکته تاریخی: کدگذاری Rice-delta اولین بار در نسخه ۴ این API استفاده شد. در نسخه ۵، دو بهبود قابل توجه ایجاد شد: اولاً، کدگذاری Rice-delta اکنون با پیشوندهای هش طولانی‌تر از ۴ بایت در دسترس است؛ ثانیاً، داده‌های کدگذاری شده اکنون به عنوان big-endian در نظر گرفته می‌شوند تا از یک مرحله مرتب‌سازی پرهزینه جلوگیری شود.

فیلدها
first_value

uint32

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

rice_parameter

int32

پارامتر Golomb-Rice. این پارامتر تضمین می‌شود که بین ۳ تا ۳۰ باشد.

entries_count

int32

تعداد ورودی‌هایی که در داده‌های کدگذاری‌شده با روش دلتا کدگذاری شده‌اند. اگر فقط یک عدد صحیح کدگذاری شده باشد، این مقدار صفر خواهد بود و آن مقدار در first_value ذخیره می‌شود.

encoded_data

bytes

دلتاهای کدگذاری شده که با استفاده از کدگذار Golomb-Rice کدگذاری شده‌اند.

RiceDeltaEncoded64Bit

همانند RiceDeltaEncoded32Bit است، با این تفاوت که این عددها را ۶۴ بیتی رمزگذاری می‌کند.

فیلدها
first_value

uint64

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

rice_parameter

int32

پارامتر گولومب-رایس. این پارامتر تضمین می‌شود که بین ۳۵ تا ۶۲ باشد.

entries_count

int32

تعداد ورودی‌هایی که در داده‌های کدگذاری‌شده با روش دلتا کدگذاری شده‌اند. اگر فقط یک عدد صحیح کدگذاری شده باشد، این مقدار صفر خواهد بود و آن مقدار در first_value ذخیره می‌شود.

encoded_data

bytes

دلتاهای کدگذاری شده که با استفاده از کدگذار Golomb-Rice کدگذاری شده‌اند.

درخواست جستجوهش‌ها

درخواستی که کلاینت برای جستجوی پیشوندهای هش خاص صادر می‌کند.

این ابزار فقط برای جستجو در فهرست‌های تهدید طراحی شده است و فهرست‌های غیرتهدید مانند Global Cache را جستجو نمی‌کند.

ویژگی‌های جدید در نسخه ۵ : کلاینت‌ها نیازی به مشخص کردن ClientInfo یا وضعیت لیست‌های هش در پایگاه داده محلی خود ندارند. این برای بهبود حریم خصوصی است. علاوه بر این، کلاینت‌ها نیازی به ارسال نوع تهدید مورد نظر خود ندارند.

فیلدها
hash_prefixes[]

bytes

الزامی. پیشوندهای هش مورد جستجو. کلاینت‌ها نباید بیش از ۱۰۰۰ پیشوند هش ارسال کنند. با این حال، طبق روال پردازش URL، کلاینت‌ها نباید بیش از ۳۰ پیشوند هش ارسال کنند.

در حال حاضر، هر پیشوند هش باید دقیقاً ۴ بایت طول داشته باشد. این ممکن است در آینده کمتر شود.

filter

string

اختیاری. اگر کلاینت به فیلتر کردن علاقه‌مند باشد، مثلاً فقط انواع خاصی از تهدیدها را بازیابی کند، می‌توان این مورد را مشخص کرد. در صورت حذف، تمام تهدیدهای منطبق بازگردانده می‌شوند. اکیداً توصیه می‌شود برای بهره‌مندی از کامل‌ترین محافظتی که مرور ایمن می‌تواند ارائه دهد، این مورد را حذف کنید.

این فیلتر با استفاده از زبان عبارات رایج گوگل (Google Common Expression Language) مشخص شده است که می‌توانید آن را به همراه مثال‌های کلی در آدرس https://github.com/google/cel-spec پیدا کنید. در اینجا چند مثال خاص که می‌توانند در اینجا استفاده شوند، آورده شده است:

فیلتر "threat_type == ThreatType.SOCIAL_ENGINEERING" ایجاب می‌کند که نوع تهدید در FullHashDetail باید SOCIAL_ENGINEERING باشد. شناسه "threat_type" به نوع تهدید فعلی اشاره دارد. شناسه "ThreatType" به مجموعه‌ای از تمام انواع تهدیدهای ممکن اشاره دارد.

فیلتر "threat_type in [ ThreatType.UNWANTED_SOFTWARE, ThreatType.MALWARE ]" ایجاب می‌کند که نوع تهدید یا UNWANTED_SOFTWARE باشد یا MALWARE .

پاسخ جستجوهش‌ها

این پاسخ پس از جستجوی هش‌های تهدید بازگشت.

اگر چیزی پیدا نشود، سرور به جای بازگرداندن وضعیت NOT_FOUND (کد وضعیت HTTP 404)، وضعیت OK (کد وضعیت HTTP 200) را با فیلد full_hashes خالی برمی‌گرداند.

چه چیزهایی در نسخه ۵ جدید است : بین FullHash و FullHashDetail جدایی وجود دارد. در صورتی که یک هش نشان دهنده سایتی با چندین تهدید باشد (مثلاً هم بدافزار و هم مهندسی اجتماعی)، نیازی نیست که هش کامل مانند نسخه ۴ دو بار ارسال شود. علاوه بر این، مدت زمان کش به یک فیلد cache_duration ساده شده است.

فیلدها
full_hashes[]

FullHash

لیست نامرتب. لیست نامرتب هش‌های کامل یافت شده.

cache_duration

Duration

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

اگر و فقط اگر فیلد full_hashes خالی باشد، کلاینت می‌تواند cache_duration افزایش دهد تا انقضای جدیدی را تعیین کند که دیرتر از مدت زمان تعیین شده توسط سرور باشد. در هر صورت، مدت زمان افزایش یافته کش نباید بیش از ۲۴ ساعت باشد.

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

درخواست آدرس‌های جستجو

درخواستی که کلاینت برای جستجوی تهدیدهایی که با URLهای مشخص‌شده مطابقت دارند، صادر می‌کند.

این ابزار فقط برای جستجو در فهرست‌های تهدید طراحی شده است و فهرست‌های غیرتهدید مانند Global Cache را جستجو نمی‌کند.

فیلدها
urls[]

string

الزامی. آدرس‌های اینترنتی (URL) که باید جستجو شوند. کلاینت‌ها نباید بیش از ۵۰ آدرس اینترنتی ارسال کنند.

آدرس‌های جستجوپاسخ

این پاسخ پس از جستجوی تهدیدهایی که با URL های مشخص شده مطابقت دارند، بازگردانده شد.

اگر چیزی پیدا نشود، سرور به جای بازگرداندن وضعیت NOT_FOUND (کد وضعیت HTTP 404)، وضعیت OK (کد وضعیت HTTP 200) را با فیلد threats خالی برمی‌گرداند.

فیلدها
threats[]

ThreatUrl

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

cache_duration

Duration

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

اگر و فقط اگر فیلد threats خالی باشد، کلاینت می‌تواند cache_duration افزایش دهد تا یک انقضای جدید دیرتر از آنچه توسط سرور مشخص شده است، تعیین کند. در هر صورت، مدت زمان افزایش یافته‌ی کش نباید بیش از ۲۴ ساعت باشد.

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

محدودیت‌های اندازه

محدودیت‌های مربوط به اندازه لیست‌های هش.

فیلدها
max_update_entries

int32

حداکثر اندازه در تعداد ورودی‌ها. به‌روزرسانی شامل ورودی‌های بیشتری از این مقدار نخواهد بود، اما ممکن است تعداد ورودی‌های به‌روزرسانی کمتر از این مقدار باشد. این مقدار باید حداقل ۱۰۲۴ باشد. اگر حذف شود یا صفر باشد، هیچ محدودیتی برای اندازه به‌روزرسانی تعیین نشده است.

max_database_entries

int32

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

ویژگی تهدید

ویژگی‌های تهدیدها. این ویژگی‌ها ممکن است معنای بیشتری به یک تهدید خاص بدهند، اما بر نوع تهدید تأثیری نخواهند گذاشت. برای مثال، یک ویژگی ممکن است اطمینان کمتری را مشخص کند در حالی که یک ویژگی متفاوت ممکن است اطمینان بالاتری را مشخص کند. ممکن است در آینده ویژگی‌های بیشتری اضافه شوند.

انوم‌ها
THREAT_ATTRIBUTE_UNSPECIFIED ویژگی ناشناخته. اگر این توسط سرور برگردانده شود، کلاینت باید FullHashDetail محصور شده را به طور کلی نادیده بگیرد.
CANARY نشان می‌دهد که نباید از threat_type برای اعمال قانون استفاده شود.
FRAME_ONLY نشان می‌دهد که threat_type فقط باید برای اعمال محدودیت روی فریم‌ها استفاده شود.

نوع تهدید

انواع تهدید.

انوم‌ها
THREAT_TYPE_UNSPECIFIED نوع تهدید ناشناخته. اگر این مورد توسط سرور برگردانده شود، کلاینت باید FullHashDetail را که در بر دارد، به طور کلی نادیده بگیرد.
MALWARE

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

اطلاعات بیشتر را می‌توانید اینجا پیدا کنید.

SOCIAL_ENGINEERING

نوع تهدید مهندسی اجتماعی. صفحات مهندسی اجتماعی به دروغ ادعا می‌کنند که از طرف شخص ثالث عمل می‌کنند، با این هدف که بینندگان را گیج کنند تا عملی را انجام دهند که بیننده فقط به یک عامل واقعی آن شخص ثالث اعتماد می‌کند. فیشینگ نوعی مهندسی اجتماعی است که بیننده را فریب می‌دهد تا عمل خاصی مانند ارائه اطلاعات، مانند اعتبارنامه‌های ورود به سیستم را انجام دهد.

اطلاعات بیشتر را می‌توانید اینجا پیدا کنید.

UNWANTED_SOFTWARE نوع تهدید نرم‌افزاری ناخواسته. نرم‌افزار ناخواسته هر نرم‌افزاری است که به اصول نرم‌افزاری گوگل پایبند نیست اما بدافزار نیست.
POTENTIALLY_HARMFUL_APPLICATION نوع تهدید برنامه بالقوه مضر که توسط Google Play Protect برای فروشگاه Play استفاده می‌شود .

آدرس تهدید

یک URL که با یک یا چند تهدید مطابقت دارد.

فیلدها
url

string

آدرس اینترنتی (URL) درخواستی که با یک یا چند تهدید مطابقت داشته است.

threat_types[]

ThreatType

فهرست نامرتب. فهرست نامرتب تهدیدهایی که URL به عنوان آنها طبقه‌بندی شده است.