Package google.security.safebrowsing.v5alpha1

Index

SafeBrowsing (interface)
BatchGetHashListsRequest (message)
BatchGetHashListsResponse (message)
FullHash (message)
FullHash.FullHashDetail (message)
GetHashListRequest (message)
HashList (message)
HashListMetadata (message)
HashListMetadata.HashLength (enum)
LikelySafeType (enum)
ListHashListsRequest (message)
ListHashListsResponse (message)
RiceDeltaEncoded128Bit (message)
RiceDeltaEncoded256Bit (message)
RiceDeltaEncoded32Bit (message)
RiceDeltaEncoded64Bit (message)
SearchHashesRequest (message)
SearchHashesResponse (message)
SizeConstraints (message)
ThreatAttribute (enum)
ThreatType (enum)

SafeBrowsing

The Safe Browsing APIs enable clients to check web resources (most commonly URLs) against Google's constantly updated lists of unsafe web resources.

BatchGetHashLists

BatchGetHashLists
`rpc BatchGetHashLists(BatchGetHashListsRequest) returns (BatchGetHashListsResponse)` Get multiple hash lists at once. It is very common for a client to need to get multiple hash lists. Using this method is preferred over using the regular Get method multiple times. This is a standard batch Get method as defined by https://google.aip.dev/231 and the HTTP method is also GET.

rpc BatchGetHashLists(BatchGetHashListsRequest) returns (BatchGetHashListsResponse)

Get multiple hash lists at once.

It is very common for a client to need to get multiple hash lists. Using this method is preferred over using the regular Get method multiple times.

This is a standard batch Get method as defined by https://google.aip.dev/231 and the HTTP method is also GET.

GetHashList

GetHashList
`rpc GetHashList(GetHashListRequest) returns (HashList)` Get the latest contents of a hash list. A hash list may either by a threat list or a non-threat list such as the Global Cache. This is a standard Get method as defined by https://google.aip.dev/131 and the HTTP method is also GET.

rpc GetHashList(GetHashListRequest) returns (HashList)

Get the latest contents of a hash list. A hash list may either by a threat list or a non-threat list such as the Global Cache.

This is a standard Get method as defined by https://google.aip.dev/131 and the HTTP method is also GET.

ListHashLists

ListHashLists
`rpc ListHashLists(ListHashListsRequest) returns (ListHashListsResponse)` List hash lists. In the V5 API, Google will never remove a hash list that has ever been returned by this method. This enables clients to skip using this method and simply hard-code all hash lists they need. This is a standard List method as defined by https://google.aip.dev/132 and the HTTP method is GET.

rpc ListHashLists(ListHashListsRequest) returns (ListHashListsResponse)

List hash lists.

In the V5 API, Google will never remove a hash list that has ever been returned by this method. This enables clients to skip using this method and simply hard-code all hash lists they need.

This is a standard List method as defined by https://google.aip.dev/132 and the HTTP method is GET.

SearchHashes

SearchHashes
`rpc SearchHashes(SearchHashesRequest) returns (SearchHashesResponse)` Search for full hashes matching the specified prefixes. This is a custom method as defined by https://google.aip.dev/136 (the custom method refers to this method having a custom name within Google's general API development nomenclature; it does not refer to using a custom HTTP method).

rpc SearchHashes(SearchHashesRequest) returns (SearchHashesResponse)

Search for full hashes matching the specified prefixes.

This is a custom method as defined by https://google.aip.dev/136 (the custom method refers to this method having a custom name within Google's general API development nomenclature; it does not refer to using a custom HTTP method).

BatchGetHashListsRequest

The request to get multiple hash lists at the same time.

Fields
`names[]`	`string` Required. The names of the particular hash lists. The list MAY be a threat list, or it may be the Global Cache. The names MUST NOT contain duplicates; if they did, the client will get an error.
`version[]`	`bytes` The versions of the hash list that the client already has. If this is the first time the client is fetching the hash lists, the field should be left empty. Otherwise, the client should supply the versions previously received from the server. The client MUST NOT manipulate those bytes. The client need not send the versions in the same order as the corresponding list names. The client may send fewer or more versions in a request than there are names. However the client MUST NOT send multiple versions that correspond to the same name; if it did, the client will get an error. Historical note: in V4 of the API, this was called `states`; it is now renamed to `version` for clarity.
`desired_hash_length`	`HashLength` The desired hash prefix length of the returned hashes in bytes. The server will then return all hash prefixes in this specified length. Different hash lists have different requirements on the acceptable values of `desired_hash_length` field. This can be found in the `supported_hash_lengths` field in `HashListMetadata`. If `desired_hash_length` does not specify a value within `supported_hash_lengths`, an error will be returned to clients. For the `BatchGetHashListsRequest` in particular, it is not possible for clients to specify a different `desired_hash_length` for different lists. If there is a need to do that, the client should split up into multiple `BatchGetHashListsRequest`s.
`size_constraints`	`SizeConstraints` The size constraints on each list. If omitted, there are no constraints. Note that the sizes here are per-list, not aggregated across all lists.

BatchGetHashListsResponse

The response containing multiple hash lists.

Fields

Fields
`hash_lists[]`	`HashList` The hash lists in the same order given in the request.

hash_lists[]

HashList

The hash lists in the same order given in the request.

FullHash

The full hash identified with one or more matches.

Fields

Fields
`full_hash`	`bytes` The matching full hash. This is the SHA256 hash. The length will be exactly 32 bytes.
`full_hash_details[]`	`FullHashDetail` Unordered list. A repeated field identifying the details relevant to this full hash.

full_hash

bytes

The matching full hash. This is the SHA256 hash. The length will be exactly 32 bytes.

full_hash_details[]

FullHashDetail

Unordered list. A repeated field identifying the details relevant to this full hash.

FullHashDetail

Details about a matching full hash.

An important note about forward compatibility: new threat types and threat attributes may be added by the server at any time; those additions are considered minor version changes. It is Google's policy not to expose minor version numbers in APIs (see https://cloud.google.com/apis/design/versioning for the versioning policy), so clients MUST be prepared to receive FullHashDetail messages containing ThreatType enum values or ThreatAttribute enum values that are considered invalid by the client. Therefore, it is the client's responsibility to check for the validity of all ThreatType and ThreatAttribute enum values; if any value is considered invalid, the client MUST disregard the entire FullHashDetail message.

Fields

Fields
`threat_type`	`ThreatType` The type of threat. This field will never be empty.
`attributes[]`	`ThreatAttribute` Unordered list. Additional attributes about those full hashes. This may be empty.

threat_type

ThreatType

The type of threat. This field will never be empty.

attributes[]

ThreatAttribute

Unordered list. Additional attributes about those full hashes. This may be empty.

GetHashListRequest

A request to obtain a hash list, which may be a threat list or a non-threat list such as the Global Cache.

What's new in V5: What was previously called states in V4 is renamed to version for clarity. Lists are now named, platform types and threat entry types are removed. Itt is now possible for multiple lists to have the same threat type, or a single list concerned with multiple threat types. Clients have the new ability to specify a desired hash length. This is part of the answer to V4's variable-length hash prefixes which has caused trouble in many client implementations: all hashes in a list now have a single length, permitting much more efficient client implementations. Constraints have been simplified, and compression type is removed (compression is always applied).

Fields
`name`	`string` Required. The name of this particular hash list. It may be a threat list, or it may be the Global Cache.
`version`	`bytes` The version of the hash list that the client already has. If this is the first time the client is fetching the hash list, this field MUST be left empty. Otherwise, the client SHOULD supply the version previously received from the server. The client MUST NOT manipulate those bytes. What's new in V5: in V4 of the API, this was called `states`; it is now renamed to `version` for clarity.
`desired_hash_length`	`HashLength` The desired hash prefix length of the returned hashes in bytes. The server will then return all hash prefixes in this specified length. Different hash lists have different requirements on the acceptable values of `desired_hash_length` field. This can be found in the `supported_hash_lengths` field in `HashListMetadata`. If `desired_hash_length` does not specify a value within `supported_hash_lengths`, an error will be returned.
`size_constraints`	`SizeConstraints` The size constraints on the list. If omitted, there are no constraints. Constraints are recommended on all devices with limited processing power, bandwidth, or storage.

HashList

A list of hashes identified by its name.

Fields
`name`	`string` The name of the hash list. Note that the Global Cache is also just a hash list and can be referred to here.
`version`	`bytes` The version of the hash list. The client MUST NOT manipulate those bytes.
`partial_update`	`bool` When true, this is a partial diff containing additions and removals based on what the client already has. When false, this is the complete hash list. When false, the client MUST delete any locally stored version for this hash list. This means that either the version possessed by the client is seriously out-of-date or the client data is believed to be corrupt. The `compressed_removals` field will be empty. When true, the client MUST apply an incremental update by applying removals and then additions.
`compressed_removals`	`RiceDeltaEncoded32Bit` The Rice-delta encoded version of removal indices. Since each hash list definitely has less than 2^32 entries, the indices are treated as 32-bit integers and encoded.
`minimum_wait_duration`	`Duration` Clients should wait at least this long to get the hash list again. If omitted or zero, clients SHOULD fetch immediately because it indicates that the server has an additional update to be sent to the client, but could not due to the client-specified constraints.
`metadata`	`HashListMetadata` Metadata about the hash list. This is not populated by the `GetHashList` method, but this is populated by the `ListHashLists` method.
Union field `compressed_additions`. The Rice-delta encoded version of additions. The hash prefix lengths of additions are uniform across all additions in the list. It is either the `desired_hash_length` sent by the client or a value chosen by the server if the client omitted that field. `compressed_additions` can be only one of the following:
`additions_four_bytes`	`RiceDeltaEncoded32Bit` The 4-byte additions.
`additions_eight_bytes`	`RiceDeltaEncoded64Bit` The 8-byte additions.
`additions_sixteen_bytes`	`RiceDeltaEncoded128Bit` The 16-byte additions.
`additions_thirty_two_bytes`	`RiceDeltaEncoded256Bit` The 32-byte additions.
Union field `checksum`. This is the checksum for the sorted list of all hashes present in the database after applying the provided update. This is a "oneof" field to allow multiple hashing algorithms. It is also possible for the server to omit this field (in the case that no updates were provided) to indicate that the client should use the existing checksum. `checksum` can be only one of the following:
`sha256_checksum`	`bytes` The sorted list of all hashes, hashed again with SHA256.

HashListMetadata

Metadata about a particular hash list.

Fields
`threat_types[]`	`ThreatType` Unordered list. If not empty, this specifies that the hash list is a kind of threat list, and this enumerates the kind of threats associated with hashes or hash prefixes in this hash list. May be empty if the entry does not represent a threat, i.e. in the case that it represents a likely safe type.
`likely_safe_types[]`	`LikelySafeType` Unordered list. If not empty, this specifies that the hash list represents a list of likely safe hashes, and this enumerates the ways they are considered likely safe. This field is mutually exclusive with the threat_types field.
`mobile_optimized`	`bool` Whether this list is optimized for mobile devices (Android and iOS).
`description`	`string` A human-readable description about this list. Written in English.
`supported_hash_lengths[]`	`HashLength` The supported hash lengths for this hash list. Each hash list would support at least one length. This field therefore will not be empty.

HashLength

The length of hashes in a hash list.

Enums
`HASH_LENGTH_UNSPECIFIED`	Unspecified length. The server will not return this value in responses to the client (in the `supported_hash_lengths` field), but the client is allowed to send this value to the server (in the `desired_hash_length` field), in which case the server will pick a value automatically. Clients SHOULD let the server pick a value.
`FOUR_BYTES`	Each hash is a four-byte prefix.
`EIGHT_BYTES`	Each hash is an eight-byte prefix.
`SIXTEEN_BYTES`	Each hash is a sixteen-byte prefix.
`THIRTY_TWO_BYTES`	Each hash is a thirty-two-byte full hash.

LikelySafeType

Types of likely-safe sites.

Note that the SearchHashesResponse intentionally does not contain LikelySafeType.

Enums
`LIKELY_SAFE_TYPE_UNSPECIFIED`	Unknown.
`GENERAL_BROWSING`	This site is likely safe enough for general browsing. This is also known as the global cache.
`CSD`	This site is likely safe enough that there is no need to run Client-Side Detection models or password protection checks.
`DOWNLOAD`	This site is likely safe enough that downloads from the site need not be checked.

ListHashListsRequest

The request to list the available hash lists.

Fields

Fields
`page_size`	`int32` The maximum number of hash lists to return. The service may return fewer than this value. If unspecified, the server will choose a page size, which may be larger than the number of hash lists so that pagination is not necessary.
`page_token`	`string` A page token, received from a previous `ListHashLists` call. Provide this to retrieve the subsequent page.

page_size

int32

The maximum number of hash lists to return. The service may return fewer than this value. If unspecified, the server will choose a page size, which may be larger than the number of hash lists so that pagination is not necessary.

page_token

string

A page token, received from a previous ListHashLists call. Provide this to retrieve the subsequent page.

ListHashListsResponse

The response containing metadata about hash lists.

Fields

Fields
`hash_lists[]`	`HashList` The hash lists in an arbitrary order. Only metadata about the hash lists will be included, not the contents.
`next_page_token`	`string` A token, which can be sent as `page_token` to retrieve the next page. If this field is omitted, there are no subsequent pages.

hash_lists[]

HashList

The hash lists in an arbitrary order. Only metadata about the hash lists will be included, not the contents.

next_page_token

string

A token, which can be sent as page_token to retrieve the next page. If this field is omitted, there are no subsequent pages.

RiceDeltaEncoded128Bit

Same as RiceDeltaEncoded32Bit except this encodes 128-bit numbers.

Fields
`first_value_hi`	`uint64` The upper 64 bits of the first entry in the encoded data (hashes). If the field is empty, the upper 64 bits are all zero.
`first_value_lo`	`fixed64` The lower 64 bits of the first entry in the encoded data (hashes). If the field is empty, the lower 64 bits are all zero.
`rice_parameter`	`int32` The Golomb-Rice parameter. This parameter is guaranteed to be between 99 and 126, inclusive.
`entries_count`	`int32` The number of entries that are delta encoded in the encoded data. If only a single integer was encoded, this will be zero and the single value will be stored in `first_value`.
`encoded_data`	`bytes` The encoded deltas that are encoded using the Golomb-Rice coder.

RiceDeltaEncoded256Bit

Same as RiceDeltaEncoded32Bit except this encodes 256-bit numbers.

Fields
`first_value_first_part`	`uint64` The first 64 bits of the first entry in the encoded data (hashes). If the field is empty, the first 64 bits are all zero.
`first_value_second_part`	`fixed64` The 65 through 128th bits of the first entry in the encoded data (hashes). If the field is empty, the 65 through 128th bits are all zero.
`first_value_third_part`	`fixed64` The 129 through 192th bits of the first entry in the encoded data (hashes). If the field is empty, the 129 through 192th bits are all zero.
`first_value_fourth_part`	`fixed64` The last 64 bits of the first entry in the encoded data (hashes). If the field is empty, the last 64 bits are all zero.
`rice_parameter`	`int32` The Golomb-Rice parameter. This parameter is guaranteed to be between 227 and 254, inclusive.
`entries_count`	`int32` The number of entries that are delta encoded in the encoded data. If only a single integer was encoded, this will be zero and the single value will be stored in `first_value`.
`encoded_data`	`bytes` The encoded deltas that are encoded using the Golomb-Rice coder.

RiceDeltaEncoded32Bit

The Rice-Golomb encoded data. Used for either hashes or removal indices. It is guaranteed that every hash or index here has the same length, and this length is exactly 32 bits.

Generally speaking, if we sort all the entries lexicographically, we will find that the higher order bits tend not to change as frequently as lower order bits. This means that if we also take the adjacent difference between entries, the higher order bits have a high probability of being zero. This exploits this high probability of zero by essentially choosing a certain number of bits; all bits more significant than this are likely to be zero so we use unary encoding. See the rice_parameter field.

Historical note: the Rice-delta encoding was first used in V4 of this API. In V5, two significant improvements were made: firstly, the Rice-delta encoding is now available with hash prefixes longer than 4 bytes; secondly, the encoded data are now treated as big-endian so as to avoid a costly sorting step.

Fields
`first_value`	`uint32` The first entry in the encoded data (hashes or indices), or, if only a single hash prefix or index was encoded, that entry's value. If the field is empty, the entry is zero.
`rice_parameter`	`int32` The Golomb-Rice parameter. This parameter is guaranteed to be between 3 and 30, inclusive.
`entries_count`	`int32` The number of entries that are delta encoded in the encoded data. If only a single integer was encoded, this will be zero and the single value will be stored in `first_value`.
`encoded_data`	`bytes` The encoded deltas that are encoded using the Golomb-Rice coder.

RiceDeltaEncoded64Bit

Same as RiceDeltaEncoded32Bit except this encodes 64-bit numbers.

Fields
`first_value`	`uint64` The first entry in the encoded data (hashes), or, if only a single hash prefix was encoded, that entry's value. If the field is empty, the entry is zero.
`rice_parameter`	`int32` The Golomb-Rice parameter. This parameter is guaranteed to be between 35 and 62, inclusive.
`entries_count`	`int32` The number of entries that are delta encoded in the encoded data. If only a single integer was encoded, this will be zero and the single value will be stored in `first_value`.
`encoded_data`	`bytes` The encoded deltas that are encoded using the Golomb-Rice coder.

SearchHashesRequest

A request that the client issues to search for specific hash prefixes.

This is designed to only searches threat lists, and does not search non-threat lists such as the Global Cache.

What's new in V5: Clients don't need to specify a ClientInfo or the states of the hash lists in their local database. This is for improved privacy. Furthermore, clients don't need to send which threat types they are interested in.

Fields

Fields
`hash_prefixes[]`	`bytes` Required. The hash prefixes to be looked up. Clients MUST NOT send more than 1000 hash prefixes. However, following the URL processing procedure, clients SHOULD NOT need to send more than 30 hash prefixes. Currently each hash prefix is required to be exactly 4 bytes long. This MAY be relaxed in the future.
`filter`	`string` Optional. If the client is interested in filtering, such as only retrieving specific kinds of threats, this can be specified. If omitted, all matching threats are returned. It is highly recommended to omit this to get the most complete protection Safe Browsing can offer. The filter is specified using Google Common Expression Language, which can be found at https://github.com/google/cel-spec along with general examples. Here are some specific examples that can be used here: The filter `"threat_type == ThreatType.SOCIAL_ENGINEERING"` requires that the within `FullHashDetail` the threat type must be `SOCIAL_ENGINEERING`. The identifier `"threat_type"` refers to the current threat type. The identifier `"ThreatType"` refers to the collection of all possible threat types. The filter `"threat_type in [ ThreatType.UNWANTED_SOFTWARE, ThreatType.MALWARE ]"` requires that the threat type must be either `UNWANTED_SOFTWARE` or `MALWARE`.

hash_prefixes[]

bytes

Required. The hash prefixes to be looked up. Clients MUST NOT send more than 1000 hash prefixes. However, following the URL processing procedure, clients SHOULD NOT need to send more than 30 hash prefixes.

Currently each hash prefix is required to be exactly 4 bytes long. This MAY be relaxed in the future.

filter

string

Optional. If the client is interested in filtering, such as only retrieving specific kinds of threats, this can be specified. If omitted, all matching threats are returned. It is highly recommended to omit this to get the most complete protection Safe Browsing can offer.

The filter is specified using Google Common Expression Language, which can be found at https://github.com/google/cel-spec along with general examples. Here are some specific examples that can be used here:

The filter "threat_type == ThreatType.SOCIAL_ENGINEERING" requires that the within FullHashDetail the threat type must be SOCIAL_ENGINEERING. The identifier "threat_type" refers to the current threat type. The identifier "ThreatType" refers to the collection of all possible threat types.

The filter "threat_type in [ ThreatType.UNWANTED_SOFTWARE, ThreatType.MALWARE ]" requires that the threat type must be either UNWANTED_SOFTWARE or MALWARE.

SearchHashesResponse

The response returned after searching threat hashes.

If nothing is found, the server will return an OK status (HTTP status code 200) with the full_hashes field empty, rather than returning a NOT_FOUND status (HTTP status code 404).

What's new in V5: There is a separation between FullHash and FullHashDetail. In the case when a hash represents a site having multiple threats (e.g. both MALWARE and SOCIAL_ENGINEERING), the full hash does not need to be sent twice as in V4. Furthermore, the cache duration has been simplified into a single cache_duration field.

Fields

Fields
`full_hashes[]`	`FullHash` Unordered list. The unordered list of full hashes found.
`cache_duration`	`Duration` The client-side cache duration. The client MUST add this duration to the current time to determine the expiration time. The expiration time then applies to every hash prefix queried by the client in the request, regardless of how many full hashes are returned in the response. Even if the server returns no full hashes for a particular hash prefix, this fact MUST also be cached by the client. If and only if the field `full_hashes` is empty, the client MAY increase the `cache_duration` to determine a new expiration that is later than that specified by the server. In any case, the increased cache duration must not be longer than 24 hours. Important: the client MUST NOT assume that the server will return the same cache duration for all responses. The server MAY choose different cache durations for different responses depending on the situation.

full_hashes[]

FullHash

Unordered list. The unordered list of full hashes found.

cache_duration

Duration

The client-side cache duration. The client MUST add this duration to the current time to determine the expiration time. The expiration time then applies to every hash prefix queried by the client in the request, regardless of how many full hashes are returned in the response. Even if the server returns no full hashes for a particular hash prefix, this fact MUST also be cached by the client.

If and only if the field full_hashes is empty, the client MAY increase the cache_duration to determine a new expiration that is later than that specified by the server. In any case, the increased cache duration must not be longer than 24 hours.

Important: the client MUST NOT assume that the server will return the same cache duration for all responses. The server MAY choose different cache durations for different responses depending on the situation.

SizeConstraints

The constraints on the sizes of the hash lists.

Fields

Fields
`max_update_entries`	`int32` The maximum size in number of entries. The update will not contain more entries than this value, but it is possible that the update will contain fewer entries than this value. This MUST be at least 1024. If omitted or zero, no update size limit is set.
`max_database_entries`	`int32` Sets the maximum number of entries that the client is willing to have in the local database for the list. (The server MAY cause the client to store less than this number of entries.) If omitted or zero, no database size limit is set.

max_update_entries

int32

The maximum size in number of entries. The update will not contain more entries than this value, but it is possible that the update will contain fewer entries than this value. This MUST be at least 1024. If omitted or zero, no update size limit is set.

max_database_entries

int32

Sets the maximum number of entries that the client is willing to have in the local database for the list. (The server MAY cause the client to store less than this number of entries.) If omitted or zero, no database size limit is set.

ThreatAttribute

Attributes of threats. These attributes may confer additional meaning to a particular threat but will not affect the threat type. For example, an attribute may specify a lower confidence while a different attribute may specify higher confidence. More attributes may be added in the future.

Enums
`THREAT_ATTRIBUTE_UNSPECIFIED`	Unknown attribute. If this is returned by the server, the client shall disregard the enclosing `FullHashDetail` altogether.
`CANARY`	Indicates that the threat_type should not be used for enforcement.
`FRAME_ONLY`	Indicates that the threat_type should only be used for enforcement on frames.

ThreatType

Types of threats.

Enums
`THREAT_TYPE_UNSPECIFIED`	Unknown threat type. If this is returned by the server, the client shall disregard the enclosing `FullHashDetail` altogether.
`MALWARE`	Malware threat type. Malware is any software or mobile application specifically designed to harm a computer, a mobile device, the software it's running, or its users. Malware exhibits malicious behavior that can include installing software without user consent and installing harmful software such as viruses. More information can be found here.
`SOCIAL_ENGINEERING`	Social engineering threat type. Social engineering pages falsely purport to act on behalf of a third party with the intention of confusing viewers into performing an action with which the viewer would only trust a true agent of that third party. Phishing is a type of social engineering that tricks the viewer into performing the specific action of providing information, such as login credentials. More information can be found here.
`UNWANTED_SOFTWARE`	Unwanted software threat type. Unwanted software is any software that does not adhere to Google's Software Principles but isn't malware.
`POTENTIALLY_HARMFUL_APPLICATION`	Potentially harmful application threat type as used by Google Play Protect for the Play Store.