索引
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
借助安全浏览 API，客户端可以根据 Google 不断更新的不安全网络资源列表检查网络资源（最常见的是网址）。安全浏览 API (v4) 包含 Update API 和 Lookup API。
Update API 专为大型客户端设计，包含 FindFullHashes 和 FetchThreatListUpdates 方法。Update API 要求客户端在本地数据库中维护下载的威胁列表。
首先，客户端会与其本地列表进行匹配，以确定给定网络资源的状态（安全或不安全）。最常见的是，列表由列入黑名单的网址表达式的哈希前缀组成。如需检查网址，客户端会生成给定网址的哈希值，并检查其本地列表中是否存在前缀冲突；如果发现前缀匹配，客户端会通过 FindFullHashes 方法获取与匹配的哈希前缀关联的完整哈希值。然后，客户端会将本地完整哈希与返回的完整哈希进行比较；如果匹配，则表示网址不安全。
其次，客户端通过 FetchThreatListUpdates 方法获取其本地数据库的更新，该方法会获取客户端的当前状态，并返回更新后的客户端状态以及客户端应应用于其本地威胁列表的更改。
Lookup API 专为小型客户端设计，可让这些客户端通过 FindThreatMatches 方法直接将资源与安全浏览威胁列表进行匹配。
使用 Update API 或 Lookup API 的客户端可以通过 ListThreatLists 方法获取可供下载的安全浏览威胁列表的列表。
{-- TRUSTED_THREAT_REPORTER: 可信威胁客户端可以通过 SubmitThreatReport 方法向 Google 提交报告以供分析。--}
| FetchThreatListUpdates |
|---|
|
提取最新的威胁列表更新。客户端可以一次请求更新多个名单。 |
| FindFullHashes |
|---|
|
查找与请求的哈希前缀匹配的全长哈希。 |
| FindThreatMatches |
|---|
|
查找与安全浏览列表匹配的威胁条目。 |
| ListThreatLists |
|---|
|
列出可供下载的安全浏览威胁列表。 |
校验和
客户端本地数据库的预期状态。
| 字段 | |
|---|---|
sha256 |
客户端状态的 SHA256 哈希；即数据库中存在的所有哈希的排序列表。 |
ClientInfo
与 Safe Browsing API 请求关联的客户端元数据。
| 字段 | |
|---|---|
client_id |
客户端 ID（有望）用于唯一标识安全浏览 API 的客户端实现。 |
client_version |
客户端实现的版本。 |
CompressionType
威胁条目集的压缩方式。
| 枚举 | |
|---|---|
COMPRESSION_TYPE_UNSPECIFIED |
未知。 |
RAW |
原始未压缩数据。 |
RICE |
Rice-Golomb 编码数据。 |
FetchThreatListUpdatesRequest
描述 Safe Browsing API 更新请求。客户端可以在单个请求中请求更新多个列表。如果服务器没有该列表的任何更新，则可能不会响应所有请求。注意：字段编号 2 未使用。下一步：5
| 字段 | |
|---|---|
client |
客户端元数据。 |
list_update_requests[] |
请求的威胁列表更新。 |
ListUpdateRequest
单个列表更新请求。
| 字段 | |
|---|---|
threat_type |
列表中条目所构成的威胁类型。 |
platform_type |
列表中存在的条目所涉及的平台类型。 |
threat_entry_type |
列表中存在的条目类型。 |
state |
请求的列表的客户端当前状态（从上次成功更新列表收到的加密客户端状态）。 |
constraints |
与此请求关联的约束条件。 |
限制条件
此更新的约束条件。
| 字段 | |
|---|---|
max_update_entries |
条目数上限。更新中包含的条目不会超过此值。此值应为 2**10 到 2**20 之间的 2 的幂。如果为零，则表示未设置更新大小上限。 |
max_database_entries |
设置客户端愿意在本地数据库中为指定列表保留的条目数量上限。此值应为 2**10 到 2**20 之间的 2 的幂。如果为零，则表示未设置数据库大小限制。 |
region |
请求特定地理位置的列表。如果未设置，服务器可能会根据用户的 IP 地址选择该值。应采用 ISO 3166-1 alpha-2 格式。 |
supported_compressions[] |
客户端支持的压缩类型。 |
language |
请求特定语言的列表。应采用 ISO 639 alpha-2 格式。 |
device_location |
客户端的实际位置，表示为 ISO 31166-1 alpha-2 地区代码。 |
FetchThreatListUpdatesResponse
| 字段 | |
|---|---|
list_update_responses[] |
客户端请求的列表更新。此处的响应数量可能少于客户端发送的请求数量。例如，如果服务器没有特定列表的更新，就会出现这种情况。 |
minimum_wait_duration |
客户端在发出任何更新请求之前必须等待的最短时长。如果未设置此字段，客户端可以随时更新。 |
ListUpdateResponse
对单个列表的更新。
| 字段 | |
|---|---|
threat_type |
系统要返回数据的威胁类型。 |
threat_entry_type |
威胁的格式。 |
platform_type |
要返回数据的平台类型。 |
response_type |
响应类型。这可能表示客户在收到响应时需要执行操作。 |
additions[] |
要添加到本地威胁类型列表的一组条目。重复，以允许在单个响应中发送压缩数据和原始数据的组合。 |
removals[] |
要从本地威胁类型列表中移除的一组条目。在实践中，此字段为空或仅包含一个 ThreatEntrySet。 |
new_client_state |
新的客户端状态（采用加密格式）。对客户而言不透明。 |
checksum |
客户端状态的预期 SHA256 哈希；即应用所提供更新后数据库中存在的所有哈希的排序列表。如果客户端状态与预期状态不符，则客户端必须忽略此更新，并稍后重试。 |
ResponseType
发送给客户端的响应类型。
| 枚举 | |
|---|---|
RESPONSE_TYPE_UNSPECIFIED |
未知。 |
PARTIAL_UPDATE |
系统会将部分更新应用于客户端的现有本地数据库。 |
FULL_UPDATE |
完整更新会替换客户端的整个本地数据库。这意味着客户端严重过时或被认为已损坏。 |
FindFullHashesRequest
请求返回与所提供的哈希前缀匹配的全长哈希。
| 字段 | |
|---|---|
client |
客户端元数据。 |
client_states[] |
每个客户端的本地威胁列表的当前客户端状态。 |
threat_info |
要检查的列表和哈希。 |
api_client |
与基于客户端实现构建的更高级别 API 的调用方相关联的客户端元数据。 |
FindFullHashesResponse
| 字段 | |
|---|---|
matches[] |
与请求的前缀匹配的完整哈希。 |
minimum_wait_duration |
客户端在发出任何查找哈希请求之前必须等待的最短时长。如果未设置此字段，客户端可以随时发出请求。 |
negative_cache_duration |
对于与威胁列表不匹配的请求实体，响应的缓存时长。 |
FindThreatMatchesRequest
请求对照列表检查条目。
| 字段 | |
|---|---|
client |
客户端元数据。 |
threat_info |
要检查是否匹配的列表和条目。 |
FindThreatMatchesResponse
| 字段 | |
|---|---|
matches[] |
威胁列表匹配。 |
ListThreatListsResponse
| 字段 | |
|---|---|
threat_lists[] |
客户可以下载的列表。 |
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 |
下面编码的每个前缀的字节数。此字段的长度可以介于 4（最短前缀）到 32（完整 SHA256 哈希）之间。 |
raw_hashes |
二进制格式的哈希值连接成一个长字符串。哈希按字典顺序排序。对于 JSON API 用户，哈希值采用 base64 编码。 |
RawIndices
要从本地列表中移除的一组原始索引。
| 字段 | |
|---|---|
indices[] |
要从按字典顺序排序的本地列表中移除的索引。 |
RiceDeltaEncoding
Rice-Golomb 编码数据。用于发送压缩的 4 字节哈希或压缩的移除索引。
| 字段 | |
|---|---|
first_value |
编码数据中第一个条目的偏移量，或者如果仅编码了一个整数，则为该整数的值。如果该字段为空或缺失，则假定为零。 |
rice_parameter |
Golomb-Rice 参数，介于 2 到 28 之间的数字。如果 |
num_entries |
在编码后的数据中采用增量编码的条目数量。如果仅编码了一个整数，则此值将为零，并且单个值将存储在 |
encoded_data |
使用 Golomb-Rice 编码器编码的编码增量。 |
ThreatEntry
单个威胁；例如，恶意网址或其哈希表示法。应仅设置其中一个字段。
| 字段 | |
|---|---|
hash |
哈希前缀，由 SHA256 哈希中最重要的 4 到 32 个字节组成。此字段采用二进制格式。对于 JSON 请求，哈希采用 base64 编码。 |
url |
网址。 |
digest |
可执行文件的摘要，采用 SHA256 格式。该 API 同时支持二进制和十六进制摘要。对于 JSON 请求，摘要采用 base64 编码。 |
ThreatEntryMetadata
与特定威胁条目关联的元数据。客户端应知道与每种威胁类型关联的元数据键值对。
| 字段 | |
|---|---|
entries[] |
元数据条目。 |
MetadataEntry
单个元数据条目。
| 字段 | |
|---|---|
key |
元数据条目键。对于 JSON 请求，键采用 base64 编码。 |
value |
元数据条目值。对于 JSON 请求，该值采用 base64 编码。 |
ThreatEntrySet
应从客户端的本地数据库中添加或移除的一组威胁。
| 字段 | |
|---|---|
compression_type |
此集中条目的压缩类型。 |
raw_hashes |
采用 SHA256 格式的原始条目。 |
raw_indices |
本地列表的原始移除索引。 |
rice_hashes |
使用 Golomb-Rice 编码的 SHA256 格式条目的编码 4 字节前缀。系统会将哈希转换为 uint32，按升序排列，然后进行增量编码并存储为 encoded_data。 |
rice_indices |
使用 Golomb-Rice 编码的编码本地字典顺序列表索引。用于发送压缩的移除索引。删除索引 (uint32) 按升序排序，然后进行增量编码并存储为 encoded_data。 |
ThreatEntryType
构成威胁的条目类型。威胁列表是单一类型条目的集合。
| 枚举 | |
|---|---|
THREAT_ENTRY_TYPE_UNSPECIFIED |
未指定。 |
URL |
网址。 |
EXECUTABLE |
可执行程序。 |
ThreatInfo
客户端在检查威胁列表中的匹配项时提交的与一个或多个威胁相关的信息。
| 字段 | |
|---|---|
threat_types[] |
要检查的威胁类型。 |
platform_types[] |
要检查的平台类型。 |
threat_entry_types[] |
要检查的条目类型。 |
threat_entries[] |
要检查的威胁条目。 |
ThreatListDescriptor
描述单个威胁列表。列表由三个参数定义：所构成的威胁类型、威胁所针对的平台类型，以及列表中的条目类型。
| 字段 | |
|---|---|
threat_type |
列表条目所构成的威胁类型。 |
platform_type |
列表条目定位到的平台类型。 |
threat_entry_type |
列表中包含的条目类型。 |
ThreatMatch
在安全浏览威胁列表中检查威胁条目时出现匹配。
| 字段 | |
|---|---|
threat_type |
与此威胁匹配的威胁类型。 |
platform_type |
与此威胁匹配的平台类型。 |
threat_entry_type |
与此威胁匹配的威胁条目类型。 |
threat |
与此威胁匹配的威胁。 |
threat_entry_metadata |
与此威胁相关联的可选元数据。 |
cache_duration |
返回的匹配项的缓存生命周期。客户端不得将此响应缓存超过此时长，以免出现误报。 |
ThreatType
威胁类型。
| 枚举 | |
|---|---|
THREAT_TYPE_UNSPECIFIED |
未知。 |
MALWARE |
恶意软件威胁类型。 |
SOCIAL_ENGINEERING |
社会工程学威胁类型。 |
UNWANTED_SOFTWARE |
垃圾软件威胁类型。 |
POTENTIALLY_HARMFUL_APPLICATION |
潜在有害应用威胁类型。 |