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.

Request format

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

* Required

Request body

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

clientId*	User name.
clientVersion*	Implementation version.

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": "{еnum}",
      "threatEntryType": "{еnum}",
      "platformType": "{еnum}",
      "responseType" : "{еnum}",
      "additions": [
        {
          "compressionType": "{еnum}",
          "rawHashes": {
            "prefixSize": "{number}",
            "rawHashes": "{string}"
          },
          "riceHashes": {
            "firstValue": "{string}",
            "riceParameter": "{number}",
            "numEntries": "{number}",
            "encodedData": "{string}"
          } 
        }
      ],
      "removals": [
        { 
          "compressionType": "{еnum}",
          "rawIndices": {
            "indices": [
              "{number}"
            ] 
          },
          "riceIndices": {
            "firstValue": "{string}",
            "riceParameter": "{number}",
            "numEntries": "{number}",
            "encodedData": "{string}"
          }
        }
      ],
      "newClientState": "{string}",
      "checksum": {
        "sha256": "{string}"
      }     
    }
  ],
  "minimumWaitDuration": "{string}"
}

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 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.

newClientState

The status of the local Safe Browsing list after the update (base64-encoded). The value is used in the request parameters: Update. Updating the local database of SB lists: The state parameter. Update. Hash-based check: The clientStates parameter.

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.

* 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"
}