Update. Update local Safe Browsing database

The request returns a partial or full update for the local Safe Browsing database. You can get updates for one or more lists depending on the parameters you set.

  1. Request format
  2. Response format
  3. Example

Request format

POST https://sba.yandex.net/v4/threatListUpdates:fetch
 ? key=<API key>
key *

API key value.

key *

API key value.

*  Required

Request body

{ 
  "client": {
  "clientId": "{string}",
  "clientVersion": "{string}"
  },
  "listUpdateRequests": [
    {
      "threatType": "{enum}",
      "platformType": "{enum}",
      "threatEntryType": "{enum}",
      "state": "{string}",
      "constraints": {
        "supportedCompressions": ["{enum}"]
      }
    }
  ]
}
client *

Safe Browsing API user data. This data is used to identify the requests made on behalf of the user.

clientId *

User name.

clientVersion *

Implementation version.

listUpdateRequests *

Parameters that identify the local Safe Browsing list to be updated. Array of objects.

Tip. Send the Get Safe Browsing lists request to get up-to-date information about the Yandex-hosted lists.
threatType *

Type of threat.

Possible values:

  • THREAT_TYPE_UNSPECIFIED: An unknown type of threat.

  • MALWARE: Malicious software.

  • SOCIAL_ENGINEERING: A threat related to social engineering.

  • UNWANTED_SOFTWARE: Unwanted software.

  • POTENTIALLY_HARMFUL_APPLICATION: An application that may pose a threat.

platformType *

A platform susceptible to the threat.

Possible values:

  • PLATFORM_TYPE_UNSPECIFIED: An unknown platform.

  • WINDOWS: A Windows operating system.

  • LINUX: A Linux operating system.

  • ANDROID: An Android operating system.

  • OSX: An OS X operating system.

  • IOS: An iOS operating system.

  • ANY_PLATFORM: At least one platform from the list.

  • ALL_PLATFORMS: All platforms.

  • CHROME: A Chrome platform.

threatEntryType *

The type of object that poses a threat.

Possible values:

  • THREAT_ENTRY_TYPE_UNSPECIFIED: The threat type is unknown.

  • URL: A URL address.

  • EXECUTABLE: An executable program.

state *

The current status of the Safe Browsing list. It corresponds to the value of the newClientState parameter obtained on the latest successful list update.

If this parameter is omitted, the query completely replaces the current list with a new one.

constraints

Additional restrictions.

supportedCompressions *

The type of data compression supported by the client. Array of objects.

Possible values:

  • COMPRESSION_TYPE_UNSPECIFIED: The compression type is unknown.

  • RAW: An uncompressed string.

  • RICE: A string compressed based on Golomb-Rice coding.

* Required

The response format is shown below. The sequence and presence of elements is not guaranteed. The response may contain auxiliary parameters not described in this document.

Response format

{
  "listUpdateResponses": [
    {
      "threatType": "{enum}",
      "threatEntryType": "{enum}",
      "platformType": "{enum}",
      "responseType" : "{enum}",
      "additions": [
        {
          "compressionType": "{enum}",
          "rawHashes": {
            "prefixSize": "{number}",
            "rawHashes": "{string}"
          },
          "riceHashes": {
            "firstValue": "{string}",
            "riceParameter": "{number}",
            "numEntries": "{number}",
            "encodedData": "{string}"
          } 
        }
      ],
      "removals": [
        { 
          "compressionType": "{enum}",
          "rawIndices": {
            "indices": [
              "{number}"
            ] 
          },
          "riceIndices": {
            "firstValue": "{string}",
            "riceParameter": "{number}",
            "numEntries": "{number}",
            "encodedData": "{string}"
          }
        }
      ],
      "newClientState": "{string}",
      "checksum": {
        "sha256": "{string}"
      }     
    }
  ],
  "minimumWaitDuration": "{string}"
}
listUpdateResponses

Parameters of the updated Safe Browsing list. Array of objects.

threatType *

Type of threat.

Possible values:

  • THREAT_TYPE_UNSPECIFIED: An unknown type of threat.

  • MALWARE: Malicious software.

  • SOCIAL_ENGINEERING: A threat related to social engineering.

  • UNWANTED_SOFTWARE: Unwanted software.

  • POTENTIALLY_HARMFUL_APPLICATION: An application that may pose a threat.

threatEntryType *

The type of object that poses a threat.

Possible values:

  • THREAT_ENTRY_TYPE_UNSPECIFIED: The threat type is unknown.

  • URL: A URL address.

  • EXECUTABLE: An executable program.

platformType *

A platform susceptible to the threat.

Possible values:

  • PLATFORM_TYPE_UNSPECIFIED: An unknown platform.

  • WINDOWS: A Windows operating system.

  • LINUX: A Linux operating system.

  • ANDROID: An Android operating system.

  • OSX: An OS X operating system.

  • IOS: An iOS operating system.

  • ANY_PLATFORM: At least one platform from the list.

  • ALL_PLATFORMS: All platforms.

  • CHROME: A Chrome platform.

responseType

Update type. Possible values:

  • RESPONSE_TYPE_UNSPECIFIED: The type of update is unknown.

  • FULL_UPDATE: The current list is completely replaced by the new one. A full update is run when the request contains no state parameter, as well as if the local list is highly outdated or damaged.

  • PARTIAL_UPDATE: The local list is partially updated.

additions

Entries to be added to the local list. The parameter is returned during a full or partial list update. Array of objects.

compressionType

Type of data compression.

Possible values:

  • COMPRESSION_TYPE_UNSPECIFIED: The compression type is unknown.

  • RAW: An uncompressed string.

  • RICE: A string compressed based on Golomb-Rice coding.

rawHashes

Arbitrary length SHA-256 hashes.

This parameter is returned if no compression was used ("compressionType": "RAW").

prefixSize

The length of the hash prefix in bytes. Range of values: from 4 bytes (minimum prefix value) to 32 bytes (fully-qualified hash).

rawHashes

Base64-encoded hashes. They are concatenated to a single string in lexicographical order.

riceHashes

Golomb-Rice-coded minimum-length (4 bytes) SHA-256 hash prefixes.

The parameter is returned if "compressionType": "RICE".

firstValue

Offset of the first entry. If only one entry is added during the list update, the value of this entry is returned.

riceParameter

Golomb-Rice parameter. Possible values: a number between 2 and 28.

It's not returned if "numEntries": 0.

numEntries

Number of entries added. If only one entry is added by the list update, the parameter value is 0.

encodedData

The deltas resulting from the Golomb-Rice compression. A base64-encoded string.

removals

The entries to be deleted from the local list. The parameter is returned only during a partial list update. Array of objects.

compressionType

Type of data compression.

Possible values:

  • COMPRESSION_TYPE_UNSPECIFIED: The compression type is unknown.

  • RAW: An uncompressed string.

  • RICE: A string compressed based on Golomb-Rice coding.

rawIndices

This parameter is returned if no compression was used ("compressionType": "RAW").

indices

The positions of hash values to be deleted in the sorted list of all hash values. Array of objects.

riceIndices

The parameter is returned if "compressionType": "RICE".

firstValue

Offset of the first entry. If only one entry is deleted during the update, the value of this entry is returned.

riceParameter

Golomb-Rice parameter. Possible values: a number between 2 and 28.

It's not returned if "numEntries": 0.

numEntries

The number of entries to be deleted. If only one entry is deleted during the update, the value of the parameter is 0.

encodedData

The deltas resulting from the Golomb-Rice compression. A base64-encoded string.

newClientState
The status of the local Safe Browsing list after the update (base64-encoded). The value is used in the request parameters:
checksum

The expected checksum of the local list after the update. If the actual checksum value doesn't match the expected checksum, cancel the update and re-run the Update. Update local Safe Browsing database request.

Note. Account for minimumWaitDuration when you re-send your request.
sha256

The checksum is the concatenation of all the SHA-256 hashes from the updated Safe Browsing list. A base64-encoded string.

minimumWaitDuration

The minimum time in seconds before sending the next request for a Safe Browsing list update. Specified in the format "minimumWaitDuration": "<time>s". Up to nine decimal digits are supported.

* Required

Example

Request URL:

https://sba.yandex.net/v4/threatListUpdates:fetch?key=2f8...8ea

Request body:

{
  "client": {
    "clientId": "client_name",
    "clientVersion": "1.1.1"
  },
  "listUpdateRequests": [
    {
      "threatType": "MALWARE",
      "platformType": "ANY_PLATFORM",
      "threatEntryType": "URL",
      "state": "",
      "constraints": {
        "supportedCompressions": ["RAW"]
      }
    }
  ]
}

Response:

{
  "listUpdateResponses": [
    {
      "responseType": "FULL_UPDATE",
      "threatType": "MALWARE",
      "newClientState": "NjU3OTRhNzM2MTU4NGU...NTk2ZTZiN=",
      "checksum": {
        "sha256": "cJtIDwizkuJigkPe+uax+1ZYAXI6zP/2NH60/bjp6oY="
      },
      "threatEntryType": "URL",
      "additions": [
        {
          "compressionType": "RAW",
          "rawHashes": {
            "prefixSize": 8,
            "rawHashes": "BpxeY80IjdgMk9zDOTrDdA8tAP...uDTeqvchw=="
          }
        },
        {
          "compressionType": "RAW",
          "rawHashes": {
            "prefixSize": 4,
            "rawHashes": "AAAbtwAAKNYAAD1lAAD7RgABjYMAA...F4ledReTNRUXliXg=="
          }
        },
        {
          "compressionType": "RAW",
          "rawHashes": {
            "prefixSize": 7,
            "rawHashes": "BUI8ZWf1VQWf2ulg27kKW7JaaHHsD7UhE5sBzBit7mQ977U1wQBFu00wTXuBOf1OHQ=="
          }
        }
      ],
      "platformType": "ANY_PLATFORM"
    }
  ],
  "minimumWaitDuration": "300.00s"
}