Package google.security.safebrowsing.v5alpha1

索引

安全瀏覽

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

BatchGetHashLists

rpc BatchGetHashLists(BatchGetHashListsRequest) returns (BatchGetHashListsResponse)

一次取得多個雜湊清單。

用戶端通常需要取得多個雜湊清單。建議使用這個方法，而不要多次使用一般 Get 方法。

這是 https://google.aip.dev/231 定義的標準批次 Get 方法，且 HTTP 方法也是 GET。
GetHashList

rpc GetHashList(GetHashListRequest) returns (HashList)

取得雜湊清單的最新內容。雜湊清單可以是威脅清單，也可以是全球快取等非威脅清單。

這是 https://google.aip.dev/131 定義的標準 Get 方法，且 HTTP 方法也是 GET。
ListHashLists

rpc ListHashLists(ListHashListsRequest) returns (ListHashListsResponse)

列出雜湊清單。

在 V5 API 中，Google 絕不會移除這個方法傳回的雜湊清單。這樣一來，用戶端就能略過使用這個方法，只需將所需的所有雜湊清單硬式編碼即可。

這是 https://google.aip.dev/132 定義的標準 List 方法，HTTP 方法為 GET。
SearchHashes

rpc SearchHashes(SearchHashesRequest) returns (SearchHashesResponse)

搜尋與指定前置字串相符的完整雜湊。

這是 https://google.aip.dev/136 定義的自訂方法 (自訂方法是指在 Google 的一般 API 開發命名法中具有自訂名稱的此方法，並非指使用自訂 HTTP 方法)。

BatchGetHashListsRequest

要求同時取得多個雜湊清單。

欄位
names[]

string

必要欄位。特定雜湊清單的名稱。這份清單可能是威脅清單，也可能是全球快取。名稱不得重複，否則用戶端會收到錯誤訊息。
version[]

bytes

用戶端已擁有的雜湊清單版本。如果這是用戶端第一次擷取雜湊清單，則應將欄位留空。否則，用戶端應提供先前從伺服器收到的版本。用戶端絕對不得操縱這些位元組。

用戶端傳送的版本順序不必與對應的清單名稱相同。用戶端在請求中傳送的版本可能多於或少於名稱。不過，用戶端不得傳送多個與相同名稱相對應的版本，否則會收到錯誤。

歷史備註：在 API 的 4 版中，這個值稱為 states；現在已重新命名為 version，以便清楚表示。
desired_hash_length
(deprecated)

HashLength

所需雜湊前置字串長度 (以位元組為單位)。然後，伺服器會傳回所有指定長度的雜湊字首。

不同的雜湊清單對 desired_hash_length 欄位可接受的值有不同的規定。您可以在 HashListMetadata 的 supported_hash_lengths 欄位中找到這項資訊。如果 desired_hash_length 未在 supported_hash_lengths 中指定值，系統會向用戶端傳回錯誤。

具體來說，對於 BatchGetHashListsRequest，用戶端無法為不同的清單指定不同的 desired_hash_length。如果需要這樣做，用戶端應分割成多個 BatchGetHashListsRequest。
size_constraints

SizeConstraints

每個清單的大小限制。如果省略，則沒有任何限制。請注意，這裡的大小是每個清單的大小，並未匯總所有清單的大小。

BatchGetHashListsResponse

回應包含多個雜湊清單。

欄位
hash_lists[]

HashList

請按照要求中提供的順序列出雜湊清單。

FullHash

與一或多個相符項目相符的完整雜湊。

欄位
full_hash

bytes

相符的完整雜湊。這是 SHA256 雜湊。長度會是 32 位元組。
full_hash_details[]

FullHashDetail

未排序的清單。這個重複欄位會識別與此完整雜湊相關的詳細資料。

FullHashDetail

相符的完整雜湊值詳細資料。

關於向前相容性的重點說明：伺服器隨時可能會新增威脅類型和威脅屬性；這些新增項目視為次要版本變更。Google 的政策是不會在 API 中公開子版本號碼 (如需瞭解版本控制政策，請參閱 https://cloud.google.com/apis/design/versioning)，因此用戶端必須準備好接收包含 ThreatType 列舉值或 ThreatAttribute 列舉值的 FullHashDetail 訊息，而這些值會被用戶端視為無效。因此，用戶端必須負責檢查所有 ThreatType 和 ThreatAttribute 列舉值的有效性；如果任何值被視為無效，用戶端就必須忽略整個 FullHashDetail 訊息。

欄位
threat_type

ThreatType

威脅類型。這個欄位永遠不會為空白。
attributes[]

ThreatAttribute

未排序的清單。這些完整雜湊的其他屬性。這個參數可能會是空白。

GetHashListRequest

要求取得雜湊清單，這可能是威脅清單或非威脅清單 (例如全域快取)。

V5 的新功能：為求清楚，V4 中先前稱為 states 的項目已重新命名為 version。清單現在已命名，平台類型和威脅項目類型則已移除。如今，多個清單可以有相同的威脅類型，或是單一清單涉及多種威脅類型。用戶端現在可指定所需的雜湊長度。這是 V4 可變長度雜湊字首的部分解答，這項字首曾導致許多用戶端實作出現問題：清單中的所有雜湊字串現在都只有單一長度，可讓用戶端實作更有效率。限制已簡化，壓縮類型已移除 (一律套用壓縮)。

欄位
name

string

必要欄位。這個特定雜湊清單的名稱。可能是威脅清單，也可能是全球快取。
version

bytes

用戶端已擁有的雜湊清單版本。如果這是用戶端第一次擷取雜湊清單，則此欄位必須留空。否則，用戶端應提供先前從伺服器收到的版本。用戶端絕對不得操縱這些位元組。

第 5 版的新功能：在 API 的 4 版中，這個屬性稱為 states；現在已重新命名為 version，以利區分。
desired_hash_length
(deprecated)

HashLength

所需雜湊前置字串長度 (以位元組為單位)。然後，伺服器會傳回所有指定長度的雜湊字首。

不同的雜湊清單對 desired_hash_length 欄位可接受的值有不同的規定。您可以在 HashListMetadata 的 supported_hash_lengths 欄位中找到這項資訊。如果 desired_hash_length 未在 supported_hash_lengths 中指定值，系統會傳回錯誤。
size_constraints

SizeConstraints

清單的大小限制。如果省略，則沒有任何限制。建議在所有處理能力、頻寬或儲存空間受限的裝置上使用限制。

HashList

以名稱識別的雜湊清單。

欄位
name

string

雜湊清單的名稱。請注意，全域快取也只是一個雜湊清單，可以在此處參照。
version

bytes

雜湊清單的版本。用戶端絕對不得操縱這些位元組。
partial_update

bool

如果為 true，則表示這是部分差異，包含根據用戶端已有內容所加入和移除的項目。如果為 false，則為完整的雜湊清單。

如果為 false，用戶端就必須刪除此雜湊清單的所有本機儲存版本。這表示用戶端擁有的版本嚴重過時，或是用戶端資料疑似損毀。compressed_removals 欄位會是空白。

如果為 true，用戶端就必須先移除再新增，才能套用遞增更新。
compressed_removals

RiceDeltaEncoded32Bit

移除索引的 Rice-delta 編碼版本。由於每個雜湊清單的項目數量絕對少於 2^32，因此系統會將索引視為 32 位元整數並進行編碼。
minimum_wait_duration

Duration

用戶端至少要等待這麼久，才能再次取得雜湊清單。如果省略或為零，用戶端應立即擷取，因為這表示伺服器有其他更新要傳送給用戶端，但因用戶端指定的限制而無法傳送。
sha256_checksum

bytes

經過排序的所有雜湊清單，並再次使用 SHA256 雜湊處理。這是在套用提供的更新後，資料庫中所有雜湊值排序清單的總和檢查碼。如果未提供任何更新，伺服器會略過這個欄位，表示用戶端應使用現有的總和檢查碼。
metadata

HashListMetadata

雜湊清單的中繼資料。這並非由 GetHashList 方法填入，而是由 ListHashLists 方法填入。
聯集欄位 compressed_additions。新增項目的 Rice-delta 編碼版本。新增項目的雜湊前置字串長度，在清單中的所有新增項目都相同。這個值可能是用戶端傳送的 desired_hash_length，也可能是伺服器選擇的值 (如果用戶端省略該欄位)。compressed_additions 只能是下列其中一項：
additions_four_bytes

RiceDeltaEncoded32Bit

4 個位元組的新增項目。
additions_eight_bytes

RiceDeltaEncoded64Bit

8 個位元組的附加項目。
additions_sixteen_bytes

RiceDeltaEncoded128Bit

16 位元組的附加項目。
additions_thirty_two_bytes

RiceDeltaEncoded256Bit

32 位元組的新增項目。

HashListMetadata

特定雜湊清單的中繼資料。

欄位
threat_types[]

ThreatType

未排序的清單。如果不為空白，則表示雜湊清單是一種威脅清單，並列舉與此雜湊清單中的雜湊或雜湊前置字元相關的威脅類型。如果項目不代表威脅 (也就是代表可能安全的類型)，則可能會留空。
likely_safe_types[]

LikelySafeType

未排序的清單。如果不為空白，則表示雜湊清單代表一組可能安全的雜湊，並列舉這些雜湊可能安全的情況。這個欄位與 threat_types 欄位互斥。
description

string

這個清單的使用者可讀說明。以英文撰寫。
supported_hash_lengths[]
(deprecated)

HashLength

此雜湊清單支援的雜湊長度。每個雜湊清單至少支援一個長度。因此這個欄位不會空白。
hash_length

HashLength

此雜湊清單支援的雜湊長度。每個雜湊清單都只支援一個長度。如果針對相同的威脅類型或安全類型引入不同的雜湊長度，系統會以獨立清單的形式引入，並附上不同的名稱和相應的雜湊長度集。

HashLength

雜湊清單中的雜湊長度。

列舉
HASH_LENGTH_UNSPECIFIED 未指定長度。伺服器不會在回應中傳回這個值 (在 supported_hash_lengths 欄位中) 給用戶端，但用戶端可以將這個值傳送給伺服器 (在 desired_hash_length 欄位中)，在這種情況下，伺服器會自動選取值。用戶端應讓伺服器挑選值。
FOUR_BYTES 每個雜湊都是四個位元組的前置字元。
EIGHT_BYTES 每個雜湊都是八個位元組的字首。
SIXTEEN_BYTES 每個雜湊都是十六位元前置字串。
THIRTY_TWO_BYTES 每個雜湊都是 32 位元完整雜湊。

LikelySafeType

可能安全的網站類型。

請注意，SearchHashesResponse 刻意不包含 LikelySafeType。

列舉
LIKELY_SAFE_TYPE_UNSPECIFIED 未知。
GENERAL_BROWSING 這個網站可能足夠安全，可供一般瀏覽。這也稱為全域快取。
CSD 這個網站可能已經足夠安全，因此不需要執行用戶端偵測模型或密碼保護檢查。
DOWNLOAD 這個網站可能相當安全，因此不需要檢查從該網站下載的內容。

ListHashListsRequest

要求列出可用的雜湊清單。

欄位
page_size

int32

要傳回的雜湊清單數量上限。服務傳回的產品數量可能會少於這個值。如果未指定，伺服器會選擇頁面大小，這個數字可能會大於雜湊清單的數量，因此不需要分頁。
page_token

string

從先前 ListHashLists 呼叫收到的網頁權杖。提供此項目即可擷取後續網頁。

ListHashListsResponse

回應中包含雜湊清單的中繼資料。

欄位
hash_lists[]

HashList

雜湊清單以任意順序排列。系統只會納入雜湊清單的中繼資料，而非內容。
next_page_token

string

可做為 page_token 傳送的權杖，用於擷取後續網頁。如果省略這個欄位，就不會有後續頁面。

RiceDeltaEncoded128Bit

與 RiceDeltaEncoded32Bit 相同，但會對 128 位元數值進行編碼。

欄位
first_value_hi

uint64

編碼資料 (雜湊) 中第一個項目的上半 64 位元。如果欄位為空白，則上層 64 位元皆為零。
first_value_lo

fixed64

編碼資料 (雜湊) 中第一個項目的低位元 64 位元。如果欄位為空白，則較低的 64 位元全為零。
rice_parameter

int32

Golomb-Rice 參數。這個參數保證會介於 99 和 126 (含) 之間。
entries_count

int32

在已編碼資料中，差異編碼的項目數量。如果只編碼單一整數，這個值會設為零，而單一值會儲存在 first_value 中。
encoded_data

bytes

使用 Golomb-Rice 編碼器編碼的已編碼差異值。

RiceDeltaEncoded256Bit

與 RiceDeltaEncoded32Bit 相同，但會對 256 位元數字進行編碼。

欄位
first_value_first_part

uint64

已編碼資料 (雜湊) 中第一個項目的前 64 位元。如果欄位為空白，前 64 位元都會是零。
first_value_second_part

fixed64

編碼資料 (雜湊) 中第一個項目的 65 到 128 位元。如果欄位為空白，則第 65 到 128 位元都會是零。
first_value_third_part

fixed64

編碼資料 (雜湊) 中第一個項目的第 129 到 192 位元。如果欄位為空白，則第 129 到 192 位元都會是零。
first_value_fourth_part

fixed64

已編碼資料 (雜湊) 中第一個項目的最後 64 位元。如果欄位為空白，最後 64 位元都會是零。
rice_parameter

int32

Golomb-Rice 參數。這個參數保證會介於 227 和 254 之間 (含首尾)。
entries_count

int32

在已編碼資料中，差異編碼的項目數量。如果只編碼單一整數，這個值會設為零，而單一值會儲存在 first_value 中。
encoded_data

bytes

使用 Golomb-Rice 編碼器編碼的已編碼差異值。

RiceDeltaEncoded32Bit

Rice-Golomb 編碼資料。用於雜湊或移除索引。這可確保每個雜湊或索引的長度都相同，且長度恰好為 32 位元。

一般來說，如果我們依字典順序排序所有項目，會發現高階位元通常不會像低階位元那樣經常變更。也就是說，如果我們也計算項目之間的相鄰差異，較高階位元很可能會為零。這個方法會利用零值的高度機率，基本上會選擇特定位元數量；所有比這更重要的位元都可能為零，因此我們會使用單一編碼。請參閱 rice_parameter 欄位。

歷史註解：Rice-delta 編碼首次用於此 API 的 V4 版。在 V5 中，我們做出了兩項重大改善：首先，現在可使用 Rice-delta 編碼，雜湊前置字串長度超過 4 個位元組；其次，現在會將已編碼資料視為 big-endian，以免進行耗時的排序步驟。

欄位
first_value

uint32

編碼資料 (雜湊或索引) 中的第一個項目，或如果只編碼單一雜湊前置字元或索引，則為該項目的值。如果欄位為空白，則項目為零。
rice_parameter

int32

Golomb-Rice 參數。這個參數保證會介於 3 到 30 (含頭尾) 之間。
entries_count

int32

在已編碼資料中，差異編碼的項目數量。如果只編碼單一整數，這個值會設為零，而單一值會儲存在 first_value 中。
encoded_data

bytes

使用 Golomb-Rice 編碼器編碼的已編碼差異值。

RiceDeltaEncoded64Bit

與 RiceDeltaEncoded32Bit 相同，但會對 64 位元數字進行編碼。

欄位
first_value

uint64

編碼資料 (雜湊) 中的第一個項目，或如果只編碼單一雜湊前置字串，則為該項目的值。如果欄位為空白，則項目為零。
rice_parameter

int32

Golomb-Rice 參數。這個參數保證會介於 35 到 62 之間 (含頭尾)。
entries_count

int32

在已編碼資料中，差異編碼的項目數量。如果只編碼單一整數，這個值會設為零，而單一值會儲存在 first_value 中。
encoded_data

bytes

使用 Golomb-Rice 編碼器編碼的已編碼差異值。

SearchHashesRequest

用戶端提出的搜尋特定雜湊字首要求。

這項設定只會搜尋威脅清單，不會搜尋非威脅清單 (例如 Global Cache)。

V5 的新功能：用戶端不需要在本機資料庫中指定 ClientInfo 或雜湊清單的狀態。這麼做可提升隱私性。此外，用戶端不需要傳送所需的威脅類型。

欄位
hash_prefixes[]

bytes

必要欄位。要查詢的雜湊碼前置字串。用戶端不得傳送超過 1000 個雜湊字首。不過，根據網址處理程序，用戶端不應傳送超過 30 個雜湊字首。

目前，每個雜湊前置字串的長度必須是 4 個位元組。這項限制日後可能會放寬。
filter

string

選用設定。如果客戶想篩選資料，例如只擷取特定類型的威脅，可以指定這項功能。如果省略，系統會傳回所有符合的威脅。強烈建議您略過這項設定，以便獲得安全瀏覽提供的完整防護。

篩選器會使用 Google 一般運算語言指定，相關資訊和一般範例請參閱 https://github.com/google/cel-spec。以下列舉幾個可在此處使用的具體範例：

篩選器 "threat_type == ThreatType.SOCIAL_ENGINEERING" 要求 FullHashDetail 中的威脅類型必須為 SOCIAL_ENGINEERING。識別碼 "threat_type" 代表目前的威脅類型。這個 ID "ThreatType" 是指所有可能的威脅類型集合。

篩選器 "threat_type in [ ThreatType.UNWANTED_SOFTWARE, ThreatType.MALWARE ]" 要求威脅類型必須是 UNWANTED_SOFTWARE 或 MALWARE。

SearchHashesResponse

搜尋威脅雜湊後傳回的回應。

如果找不到任何內容，伺服器會傳回 OK 狀態 (HTTP 狀態碼 200)，並將 full_hashes 欄位設為空白，而不是傳回 NOT_FOUND 狀態 (HTTP 狀態碼 404)。

V5 的新功能：FullHash 和 FullHashDetail 之間有分隔符。如果雜湊代表網站有多個威脅 (例如同時有惡意軟體和社會工程攻擊)，就不需要像 V4 一樣傳送完整雜湊兩次。此外，快取時間長度已簡化為單一 cache_duration 欄位。

欄位
full_hashes[]

FullHash

未排序的清單。找到的完整雜湊值無序清單。
cache_duration

Duration

用戶端快取時間長度。用戶端必須將這個時間長度加到目前時間，才能判斷到期時間。無論回應中傳回多少完整雜湊，過期時間都會套用至用戶端在要求中查詢的每個雜湊前置字串。即使伺服器未針對特定雜湊前置字串傳回完整雜湊，用戶端仍必須將此事實快取。

只有在 full_hashes 欄位為空白時，用戶端才會增加 cache_duration，以便判斷新的到期時間，該時間晚於伺服器指定的時間。無論如何，增加的快取時間不得超過 24 小時。

重要事項：用戶端不得假設伺服器會為所有回應傳回相同的快取時間長度。視情況而定，伺服器可能會為不同的回應選擇不同的快取時間長度。

SizeConstraints

散列清單大小的限制。

欄位
max_update_entries

int32

項目數量上限。更新內容不會超過這個值，但可能會少於這個值。這個值必須至少為 1024。如果省略或為零，則不會設定更新大小限制。
max_database_entries

int32

設定用戶端願意在清單的本機資料庫中保留的項目數量上限。(伺服器可能會導致用戶端儲存的項目數少於這個數量)。如果省略或設為 0，則不會設定資料庫大小限制。

ThreatAttribute

威脅的屬性。這些屬性可能會為特定威脅提供額外意義，但不會影響威脅類型。舉例來說，某個屬性可能會指定較低的可信度，而另一個屬性則可能會指定較高的可信度。日後可能會新增更多屬性。

列舉
THREAT_ATTRIBUTE_UNSPECIFIED 不明屬性。如果這是由伺服器傳回，用戶端應完全忽略內含的 FullHashDetail。
CANARY 表示不應使用 threat_type 進行強制執行。
FRAME_ONLY 指出 threat_type 應僅用於在影格上強制執行。

ThreatType

威脅類型。

列舉
THREAT_TYPE_UNSPECIFIED 不明的威脅類型。如果這是由伺服器傳回，用戶端應完全忽略內含的 FullHashDetail。
MALWARE

惡意軟體威脅類型。只要軟體或行動應用程式會刻意危害電腦、行動裝置、這些裝置執行的軟體或其使用者，就屬於惡意軟體。惡意軟體的危害行為包括：未經使用者同意便擅自安裝軟體，以及安裝病毒等有害軟體。

詳情請參閱這裡。
SOCIAL_ENGINEERING

社交工程威脅類型。社交工程頁面會假冒第三方，意圖誤導觀眾採取行動，而觀眾只會信任第三方的真實代理人。網路釣魚是一種社交工程，會誘騙觀眾執行特定動作，例如提供登入憑證等資訊。

詳情請參閱這裡。
UNWANTED_SOFTWARE 垃圾軟體威脅類型。垃圾軟體是指違反 Google 的軟體規範，但並非惡意軟體的任何軟體。
POTENTIALLY_HARMFUL_APPLICATION Google Play 安全防護用於 Play 商店的可能有害應用程式威脅類型。