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 (列舉)

安全瀏覽

安全瀏覽 API 可讓用戶端檢查網頁資源 (最常見的是網址)，將其與 Google 持續更新的不安全網頁資源清單比對。Safe Browsing API (v4) 提供 Update API 和 Lookup API。

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

首先，用戶端會比對本機清單，判斷特定網路資源的狀態 (安全或不安全)。通常，清單會包含黑名單網址運算式的雜湊前置字串。如要檢查網址，用戶端會產生指定網址的雜湊，並檢查本機清單中的前置字串是否有衝突；如果找到相符的前置字串，用戶端會透過 FindFullHashes 方法取得與相符雜湊前置字串相關聯的完整雜湊。接著，用戶端會將本機完整雜湊與傳回的完整雜湊進行比對；如果相符，表示網址不安全。

其次，用戶端會透過 FetchThreatListUpdates 方法取得本機資料庫的更新內容，該方法會採用用戶端的目前狀態，並傳回更新的用戶端狀態，以及用戶端應套用至本機威脅清單的變更。

Lookup API 專為較小的用戶端設計，可讓用戶端透過 FindThreatMatches 方法，直接將資源與 Safe Browsing 威脅清單進行比對。

使用 Update API 或 Lookup API 的用戶端可以透過 ListThreatLists 方法取得可供下載的 Safe Browsing 威脅清單。

{-- 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

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

欄位
client_id	string 用戶端 ID，可 (希望) 明確識別 Safe Browsing API 的用戶端實作項目。
client_version	string 用戶端實作版本。

CompressionType

威脅項目集可壓縮的方式。

列舉
COMPRESSION_TYPE_UNSPECIFIED	未知。
RAW	原始未壓縮資料。
RICE	Rice-Golomb 編碼資料。

FetchThreatListUpdatesRequest

說明 Safe Browsing API 更新要求。用戶端可以在單一要求中要求更新多個清單。如果伺服器沒有該清單的更新內容，可能就不會回應所有要求。注意：欄位索引 2 未使用。NEXT: 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 之間的 2 次方。如果為零，則不會設定更新大小限制。
max_database_entries	int32 設定用戶端願意在指定清單的本機資料庫中保留的項目數量上限。這個值應為 2**10 和 2**20 之間的 2 次方。如果為零，則不會設定資料庫大小限制。
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 已編碼資料中第一個項目的偏移量，或如果只編碼單一整數，則為該單一整數的值。如果欄位為空白或缺少，則假設為零。
rice_parameter	int32 Golomb-Rice 參數，介於 2 到 28 之間的數字。如果 num_entries 為零，則這個欄位會缺少 (也就是零)。
num_entries	int32 在已編碼資料中，差異編碼的項目數量。如果只編碼單一整數，這個值會設為零，而單一值會儲存在 first_value 中。
encoded_data	bytes 使用 Golomb-Rice 編碼器編碼的已編碼差異值。

ThreatEntry

個別威脅，例如惡意網址或其雜湊表示法。請只設定其中一個欄位。

欄位
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 使用 Golomb-Rice 編碼，對 SHA256 格式項目的 4 個位元組前置字元進行編碼。雜湊值會轉換為 uint32，並以遞增順序排序，然後以差分編碼並儲存為 encoded_data。
rice_indices	RiceDeltaEncoding 使用 Golomb-Rice 編碼，將經過編碼的本地字典排序清單索引編碼。用於傳送壓縮的移除索引。移除索引 (uint32) 會以遞增順序排序，然後以差分編碼方式編碼並儲存為 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	可能有害的應用程式威脅類型。