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: 受信任的威胁客户端可通过 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 未使用。下一步：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 编码数据中经过增量编码的条目数。如果只对一个整数进行编码，此值将为 0，并且该单个值将存储在 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 SHA256 格式条目的编码 4 字节前缀，使用 Golomb-Rice 编码。这些哈希值会转换为 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	可能有害的应用威胁类型。