Package google.security.safebrowsing.v4

索引

• SafeBrowsing (介面)
• Checksum (訊息)
• ClientInfo (訊息)
• CompressionType (列舉)
• FetchThreatListUpdatesRequest (訊息)
• FetchThreatListUpdatesRequest.ListUpdateRequest (訊息)
• FetchThreatListUpdatesRequest.ListUpdateRequest.Constraints (訊息)
• FetchThreatListUpdatesResponse (訊息)
• FetchThreatListUpdatesResponse.ListUpdateResponse (訊息)
• FetchThreatListUpdatesResponse.ListUpdateResponse.ResponseType (列舉)
• FindFullHashesRequest (訊息)
• FindFullHashesResponse (訊息)
• FindThreatMatchesRequest (訊息)
• FindThreatMatchesResponse (訊息)
• ListThreatListsResponse (訊息)
• PlatformType (列舉)
• RawHashes (訊息)
• RawIndices (訊息)
• RiceDeltaEncoding (訊息)
• ThreatEntry (訊息)
• ThreatEntryMetadata (訊息)
• ThreatEntryMetadata.MetadataEntry (訊息)
• ThreatEntrySet (訊息)
• ThreatEntryType (列舉)
• ThreatInfo (訊息)
• ThreatListDescriptor (訊息)
• ThreatMatch (訊息)
• ThreatType (列舉)

SafeBrowsing

Safe Browsing API 可讓用戶端根據 Google 持續更新的不安全網頁資源清單，檢查網路資源 (最常見的網址)。Safe Browsing API (v4) 提供了 Update API 和 Lookup API。

Update API 是專為大型用戶端設計，內含 FindFullHashes 和 FetchThreatListUpdates 方法。Update API 要求客戶在本機資料庫中維護下載的威脅清單。

首先，用戶端會與本機清單進行比對，藉此判斷特定網路資源的狀態 (安全或不安全)。大多數情況下，清單是由黑名單網址運算式的雜湊前置字元組成。為了檢查網址，用戶端會產生特定網址的雜湊，並檢查本機清單中是否有前置字串衝突；如果找到符合前置字串，用戶端會透過 FindFullHashes 方法 取得與相符雜湊前置字元相關的完整雜湊。接著，用戶端會比較本機完整雜湊與傳回的完整雜湊；如果符合，就代表該網址不安全。

第二，客戶可以使用 FetchThreatListUpdates 方法取得對本機資料庫的更新，此方法會接收用戶端的目前狀態並傳回更新的用戶端狀態，以及用戶端應套用至本機威脅清單的變更。

Lookup API 是專為我們的小型用戶端設計，可讓他們透過 FindThreatmatch 方法，直接將資源與安全瀏覽的威脅清單進行比對。

凡是使用 Update API 或 Lookup API 的用戶端，都可以透過 ListThreatLists 方法取得可供下載的安全瀏覽威脅清單清單。

{-- TRUSTED_THREAT_REPORTER：信任的威脅客戶可以透過提交 ThreatReport 方法向 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

與 Safe Browsing API 要求相關聯的用戶端中繼資料。

欄位
client_id	string 可用來識別 Safe Browsing API 用戶端實作的唯一用戶端 ID。
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**10 和 2**20 之間。如果值為「0」，系統就不會設定更新大小限制。
max_database_entries	int32 針對指定清單，設定用戶端願意在本機資料庫中保留的項目數量上限。這個值應介於 2**10 和 2**20 之間。如果值為「0」，系統就不會設定資料庫的大小限制。
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 與高階 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 用戶端可下載的名單。

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 個位元組，但如果某些雜湊與熱門網址的雜湊值衝突，系統就會增加雜湊值。

用於將 ThreatEntrySet 傳送至不支援壓縮的用戶端，或傳送非 4 位元組雜湊給支援壓縮的用戶端。

欄位
prefix_size	int32 下列編碼每個前置字元的位元組數。這個欄位可以是 4 (最短前置字元) 到 32 (完整 SHA256 雜湊) 之間的任何位置。
raw_hashes	bytes 二進位格式的雜湊，串連為一個長字串。雜湊會依字母順序排序。如果是 JSON API 使用者，雜湊會採用 Base64 編碼。

RawIndices

要從本機清單中移除的一組原始索引。

欄位
indices[]	int32 要從依字母順序排序的本機清單中移除的索引。

RiceDeltaEncoding

Rice-Golomb 編碼的資料。用於傳送壓縮的 4 位元組雜湊或壓縮後移除索引。

欄位
first_value	int64 編碼資料中第一個項目的偏移，如果只編碼一個整數，就是該單一整數的值。如果欄位空白或漏填，請假設為 0。
rice_parameter	int32 Golomb-Rice 參數，是介於 2 與 28 之間的數字。如果 num_entries 為零，則缺少這個欄位 (也就是零)。
num_entries	int32 已編碼資料中經過差異處理的項目數量。如果只編碼了一個整數，這個值將會是零，而單一值也會儲存在 first_value 中。
encoded_data	bytes 使用 Golomb-Rice 編碼器進行編碼的編碼差異。

ThreatEntry

個人威脅；例如惡意 URL 或雜湊表示法。只能設定其中一個欄位。

欄位
hash	bytes 雜湊前置字串，由 SHA256 雜湊中最重要的 4 到 32 個位元組組成。這個欄位採用二進位格式。對於 JSON 要求，雜湊是採用 Base64 編碼。
url	string 網址。
digest	bytes 以 SHA256 格式執行的執行檔摘要。這個 API 同時支援二進位和十六進位摘要。對於 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，依遞增順序排序，接著差異遷移法會編碼並儲存為 encoded_data。
rice_indices	RiceDeltaEncoding 經過編碼的本地依字母順序排序的清單索引，採用 Golomb-Rice 編碼。用於傳送壓縮的移除索引。移除索引 (uint32) 會依遞增順序排序，然後 delta 編碼並儲存為 encoded_data。

ThreatEntryType

造成威脅的項目類型。威脅清單是單一類型的項目集合。

列舉
THREAT_ENTRY_TYPE_UNSPECIFIED	未指明
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	可能有害的應用程式威脅類型。