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

借助安全浏览 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
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（有望）用于唯一标识安全浏览 API 的客户端实现。
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 之间的 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	潜在有害应用威胁类型。