package mozilla.safebrowsing

Get desktop application:
View/edit binary Protocol Buffers messages

The expected state of a client's local database.

Used in: FetchThreatListUpdatesResponse.ListUpdateResponse

• optional bytes sha256 = 1

  The SHA256 hash of the client state; that is, of the sorted list of all hashes present in the database.

The client metadata associated with Safe Browsing API requests specific to users of Chrome.

Used in: FetchThreatListUpdatesRequest

• optional ChromeClientInfo.SafeBrowsingReportingPopulation reporting_population = 1

  The reporting population of the user.

Safe Browsing reporting populations in Chrome.

Used in: ChromeClientInfo

• UNSPECIFIED = 0

  Unspecified reporting verbosity.

• OPT_OUT = 1

  Client is opted out of reporting.

• EXTENDED = 2

  Legacy extended reporting population.

• SCOUT = 3

  Scout reporting population.

The client metadata associated with Safe Browsing API requests.

Used in: FetchThreatListUpdatesRequest, FindFullHashesRequest, FindThreatMatchesRequest

• optional string client_id = 1

  A client ID that (hopefully) uniquely identifies the client implementation of the Safe Browsing API.

• optional string client_version = 2

  The version of the client implementation.

The ways in which threat entry sets can be compressed.

Used in: FetchThreatListUpdatesRequest.ListUpdateRequest.Constraints, ThreatEntrySet

• COMPRESSION_TYPE_UNSPECIFIED = 0

  Unknown.

• RAW = 1

  Raw, uncompressed data.

• RICE = 2

  Rice-Golomb encoded data.

Used in: FetchThreatListUpdatesResponse, FindFullHashesResponse, ThreatMatch

• optional int64 seconds = 1

  Signed seconds of the span of time. Must be from -315,576,000,000 to +315,576,000,000 inclusive.

• optional int32 nanos = 2

  Signed fractions of a second at nanosecond resolution of the span of time. Durations less than one second are represented with a 0 `seconds` field and a positive or negative `nanos` field. For durations of one second or more, a non-zero value for the `nanos` field must be of the same sign as the `seconds` field. Must be from -999,999,999 to +999,999,999 inclusive.

Describes a Safe Browsing API update request. Clients can request updates for multiple lists in a single request.

• optional ClientInfo client = 1

  The client metadata.

• repeated FetchThreatListUpdatesRequest.ListUpdateRequest list_update_requests = 3

  The requested threat list updates.

• optional ChromeClientInfo chrome_client_info = 4

  Chrome-specific client information.

A single list update request.

Used in: FetchThreatListUpdatesRequest

• optional ThreatType threat_type = 1

  The type of threat posed by entries present in the list.

• optional PlatformType platform_type = 2

  The type of platform at risk by entries present in the list.

• optional ThreatEntryType threat_entry_type = 5

  The types of entries present in the list.

• optional bytes state = 3

  The current state of the client for the requested list (the encrypted ClientState that was sent to the client from the previous update request).

• optional ListUpdateRequest.Constraints constraints = 4

  The constraints associated with this request.

The constraints for this update.

Used in: ListUpdateRequest

• optional int32 max_update_entries = 1

  The maximum size in number of entries. The update will not contain more entries than this value. This should be a power of 2 between 2**10 and 2**20. If zero, no update size limit is set.

• optional int32 max_database_entries = 2

  Sets the maxmimum number of entries that the client is willing to have in the local database. This should be a power of 2 between 2**10 and 2**20. If zero, no database size limit is set.

• optional string region = 3

  Requests the list for a specific geographic location. If not set the server may pick that value based on the user's IP address. Expects ISO 3166-1 alpha-2 format.

• repeated CompressionType supported_compressions = 4

  The compression types supported by the client.

Response type for threat list update requests.

• repeated FetchThreatListUpdatesResponse.ListUpdateResponse list_update_responses = 1

  The list updates requested by the clients.

• optional Duration minimum_wait_duration = 2

  The minimum duration the client must wait before issuing any update request. If this field is not set clients may update as soon as they want.

An update to an individual list.

Used in: FetchThreatListUpdatesResponse

• optional ThreatType threat_type = 1

  The threat type for which data is returned.

• optional ThreatEntryType threat_entry_type = 2

  The format of the threats.

• optional PlatformType platform_type = 3

  The platform type for which data is returned.

• optional ListUpdateResponse.ResponseType response_type = 4

  The type of response. This may indicate that an action is required by the client when the response is received.

• repeated ThreatEntrySet additions = 5

  A set of entries to add to a local threat type's list. Repeated to allow for a combination of compressed and raw data to be sent in a single response.

• repeated ThreatEntrySet removals = 6

  A set of entries to remove from a local threat type's list. In practice, this field is empty or contains exactly one ThreatEntrySet.

• optional bytes new_client_state = 7

  The new client state, in encrypted format. Opaque to clients.

• optional Checksum checksum = 8

  The expected SHA256 hash of the client state; that is, of the sorted list of all hashes present in the database after applying the provided update. If the client state doesn't match the expected state, the client must disregard this update and retry later.

The type of response sent to the client.

Used in: ListUpdateResponse

• RESPONSE_TYPE_UNSPECIFIED = 0

  Unknown.

• PARTIAL_UPDATE = 1

  Partial updates are applied to the client's existing local database.

• FULL_UPDATE = 2

  Full updates replace the client's entire local database. This means that either the client was seriously out-of-date or the client is believed to be corrupt.

Request to return full hashes matched by the provided hash prefixes.

• optional ClientInfo client = 1

  The client metadata.

• repeated bytes client_states = 2

  The current client states for each of the client's local threat lists.

• optional ThreatInfo threat_info = 3

  The lists and hashes to be checked.

Response type for requests to find full hashes.

• repeated ThreatMatch matches = 1

  The full hashes that matched the requested prefixes.

• optional Duration minimum_wait_duration = 2

  The minimum duration the client must wait before issuing any find hashes request. If this field is not set, clients can issue a request as soon as they want.

• optional Duration negative_cache_duration = 3

  For requested entities that did not match the threat list, how long to cache the response.

Request to check entries against lists.

• optional ClientInfo client = 1

  The client metadata.

• optional ThreatInfo threat_info = 2

  The lists and entries to be checked for matches.

Response type for requests to find threat matches.

• repeated ThreatMatch matches = 1

  The threat list matches.

A collection of lists available for download.

• repeated ThreatListDescriptor threat_lists = 1

  The lists available for download.

Types of platforms.

Used in: FetchThreatListUpdatesRequest.ListUpdateRequest, FetchThreatListUpdatesResponse.ListUpdateResponse, ThreatHit, ThreatInfo, ThreatListDescriptor, ThreatMatch

• PLATFORM_TYPE_UNSPECIFIED = 0

  Unknown platform.

• WINDOWS_PLATFORM = 1

  Threat posed to Windows.

• LINUX_PLATFORM = 2

  Threat posed to Linux.

• ANDROID_PLATFORM = 3

  Threat posed to Android. This cannot be ANDROID because that symbol is defined for android builds here: build/config/android/BUILD.gn line21.

• OSX_PLATFORM = 4

  Threat posed to OSX.

• IOS_PLATFORM = 5

  Threat posed to iOS.

• ANY_PLATFORM = 6

  Threat posed to at least one of the defined platforms.

• ALL_PLATFORMS = 7

  Threat posed to all defined platforms.

• CHROME_PLATFORM = 8

  Threat posed to Chrome.

The uncompressed threat entries in hash format of a particular prefix length. Hashes can be anywhere from 4 to 32 bytes in size. A large majority are 4 bytes, but some hashes are lengthened if they collide with the hash of a popular URL. Used for sending ThreatEntrySet to clients that do not support compression, or when sending non-4-byte hashes to clients that do support compression.

Used in: ThreatEntrySet

• optional int32 prefix_size = 1

  The number of bytes for each prefix encoded below. This field can be anywhere from 4 (shortest prefix) to 32 (full SHA256 hash).

• optional bytes raw_hashes = 2

  The hashes, all concatenated into one long string. Each hash has a prefix size of |prefix_size| above. Hashes are sorted in lexicographic order.

A set of raw indicies to remove from a local list.

Used in: ThreatEntrySet

• repeated int32 indices = 1

  The indicies to remove from a lexicographically-sorted local list.

The Rice-Golomb encoded data. Used for sending compressed 4-byte hashes or compressed removal indices.

Used in: ThreatEntrySet

• optional int64 first_value = 1

  The offset of the first entry in the encoded data, or, if only a single integer was encoded, that single integer's value.

• optional int32 rice_parameter = 2

  The Golomb-Rice parameter which is a number between 2 and 28. This field is missing (that is, zero) if num_entries is zero.

• optional int32 num_entries = 3

  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.

• optional bytes encoded_data = 4

  The encoded deltas that are encoded using the Golomb-Rice coder.

An individual threat; for example, a malicious URL or its hash representation. Only one of these fields should be set.

Used in: ThreatHit, ThreatInfo, ThreatMatch

• optional bytes hash = 1

  A variable-length SHA256 hash with size between 4 and 32 bytes inclusive.

• optional string url = 2

  A URL.

The metadata associated with a specific threat entry. The client is expected to know the metadata key/value pairs associated with each threat type.

Used in: ThreatMatch

• repeated ThreatEntryMetadata.MetadataEntry entries = 1

  The metadata entries.

A single metadata entry.

Used in: ThreatEntryMetadata

• optional bytes key = 1

  The metadata entry key.

• optional bytes value = 2

  The metadata entry value.

A set of threats that should be added or removed from a client's local database.

Used in: FetchThreatListUpdatesResponse.ListUpdateResponse

• optional CompressionType compression_type = 1

  The compression type for the entries in this set.

• optional RawHashes raw_hashes = 2

  The raw SHA256-formatted entries.

• optional RawIndices raw_indices = 3

  The raw removal indices for a local list.

• optional RiceDeltaEncoding rice_hashes = 4

  The encoded 4-byte prefixes of SHA256-formatted entries, using a Golomb-Rice encoding.

• optional RiceDeltaEncoding rice_indices = 5

  The encoded local, lexicographically-sorted list indices, using a Golomb-Rice encoding. Used for sending compressed removal indicies.

Types of entries that pose threats. Threat lists are collections of entries of a single type.

Used in: FetchThreatListUpdatesRequest.ListUpdateRequest, FetchThreatListUpdatesResponse.ListUpdateResponse, ThreatInfo, ThreatListDescriptor, ThreatMatch

• THREAT_ENTRY_TYPE_UNSPECIFIED = 0

  Unspecified.

• URL = 1

  A host-suffix/path-prefix URL expression; for example, "foo.bar.com/baz/".

• EXECUTABLE = 2

  An executable program.

• IP_RANGE = 3

  An IP range.

• CHROME_EXTENSION = 4

  Chrome extension.

• FILENAME = 5

  Filename.

• CERT = 6

  CERT.

A hit comprised of multiple resources; one is the threat list entry that was encountered by the client, while others give context as to how the client arrived at the unsafe entry.

• optional ThreatType threat_type = 1

  The threat type reported.

• optional PlatformType platform_type = 2

  The platform type reported.

• optional ThreatEntry entry = 3

  The threat entry responsible for the hit. Full hash should be reported for hash-based hits.

• repeated ThreatHit.ThreatSource resources = 4

  The resources related to the threat hit.

A single resource related to a threat hit.

Used in: ThreatHit

• optional string url = 1

  The URL of the resource.

• optional ThreatSourceType type = 2

  The type of source reported.

• optional string remote_ip = 3

  The remote IP of the resource in ASCII format. Either IPv4 or IPv6.

• optional string referrer = 4

  Referrer of the resource. Only set if the referrer is available.

Types of resources reported by the client as part of a single hit.

Used in: ThreatSource

• THREAT_SOURCE_TYPE_UNSPECIFIED = 0

  Unknown.

• MATCHING_URL = 1

  The URL that matched the threat list (for which GetFullHash returned a valid hash).

• TAB_URL = 2

  The final top-level URL of the tab that the client was browsing when the match occurred.

• TAB_REDIRECT = 3

  A redirect URL that was fetched before hitting the final TAB_URL.

Used in: FindFullHashesRequest, FindThreatMatchesRequest

• repeated ThreatType threat_types = 1

  The threat types to be checked.

• repeated PlatformType platform_types = 2

  The platform types to be checked.

• repeated ThreatEntryType threat_entry_types = 4

  The entry types to be checked.

• repeated ThreatEntry threat_entries = 3

  The threat entries to be checked.

Describes an individual threat list. A list is defined by three parameters: the type of threat posed, the type of platform targeted by the threat, and the type of entries in the list.

Used in: ListThreatListsResponse

• optional ThreatType threat_type = 1

  The threat type posed by the list's entries.

• optional PlatformType platform_type = 2

  The platform type targeted by the list's entries.

• optional ThreatEntryType threat_entry_type = 3

  The entry types contained in the list.

A match when checking a threat entry in the Safe Browsing threat lists.

Used in: FindFullHashesResponse, FindThreatMatchesResponse

• optional ThreatType threat_type = 1

  The threat type matching this threat.

• optional PlatformType platform_type = 2

  The platform type matching this threat.

• optional ThreatEntryType threat_entry_type = 6

  The threat entry type matching this threat.

• optional ThreatEntry threat = 3

  The threat matching this threat.

• optional ThreatEntryMetadata threat_entry_metadata = 4

  Optional metadata associated with this threat.

• optional Duration cache_duration = 5

  The cache lifetime for the returned match. Clients must not cache this response for more than this duration to avoid false positives.

Types of threats.

Used in: FetchThreatListUpdatesRequest.ListUpdateRequest, FetchThreatListUpdatesResponse.ListUpdateResponse, ThreatHit, ThreatInfo, ThreatListDescriptor, ThreatMatch

• THREAT_TYPE_UNSPECIFIED = 0

  Unknown.

• MALWARE_THREAT = 1

  Malware threat type.

• SOCIAL_ENGINEERING_PUBLIC = 2

  Social engineering threat type.

• UNWANTED_SOFTWARE = 3

  Unwanted software threat type.

• POTENTIALLY_HARMFUL_APPLICATION = 4

  Potentially harmful application threat type.

• SOCIAL_ENGINEERING = 5

  Social engineering threat type for internal use.

• API_ABUSE = 6

  API abuse threat type.

• MALICIOUS_BINARY = 7

  Malicious binary threat type.

• CSD_WHITELIST = 8

  Client side detection whitelist threat type.

• CSD_DOWNLOAD_WHITELIST = 9

  Client side download detection whitelist threat type.

• CLIENT_INCIDENT = 10

  Client incident threat type.

• SUBRESOURCE_FILTER = 13

  Patterns to be used for activating the subresource filter. Interstitial will not be shown for patterns from this list.