Skip to main content

Whitelisted files (changes) (TCF-0502)

This service provides a continuous list of samples whose whitelisted status changed; i.e. samples that changed classification from KNOWN to MALICIOUS or SUSPICIOUS.

Every record in the list includes hashes (MD5, SHA1, SHA256) and the platform field associated with the sample. Users can extract samples related to a specific platform based on the value of the platform field.

The feed stores records for the last 365 days.

Continuous Whitelisted Change Feed Query​

This query returns the samples which changed their whitelist status since the requested time. The feed returns up to 1000 records and any surplus records sharing the same timestamp.

To fetch the next batch of records, use the timestamp from the response increased by 1.

If the requested timestamp is not within the last 365 days, the service will respond with the status code 400 Bad Request.

GET /api/feed/whitelisted_change/v1/query/{time_format}/{time_value}[?format=xml|json|tsv][&sample_available=true]

Request format​

  • time_format
    • Time format in which the date and time should be requested. It is possible to choose between utc and timestamp
    • Required
  • time_value
    • Accepts values in the format set by time_format. If the format is set to utc, the value should be expressed in the format YYYY-MM-DDThh:mm:ss. If the format is set to timestamp, the value should be expressed as the number of seconds since 1970-01-01 00:00:00
    • Required
  • format
    • An optional parameter that allows choosing the response format. Supported values are xml, json, tsv (Tab Separated Values, delimiter character t 0x09). The default is xml
    • Optional
  • sample_available
    • Optional parameter. If this parameter is set to true in the request, filtering will be applied and the response will contain only samples that are present in the ReversingLabs storage and available for download. When set to false, the query will return all samples, regardless of their download availability status. The default is false, meaning that if the parameter is not provided in the request, filtering is not applied
    • Optional

To retrieve at most 1000 latest records with changes in their whitelist status, use the following endpoint:

GET /api/feed/whitelisted_change/v1/query/latest[?format=xml|json|tsv]

Response format​

For the requested timestamp, the response contains a list of records. Every record in the list includes hashes (MD5, SHA1, SHA256), the record_on field associated with the time when the record entered the feed, and the platform field associated with the sample. For samples with an undetermined platform, the value of the platform field will be Unknown.

The format of the last_timestamp value should match the requested time format.

    {
       "rl": {
          "whitelisted_change_feed": {
             "time_range": {
                "from": "YYYY-MM-DDTHH:MM:SS", 
                "to": "YYYY-MM-DDTHH:MM:SS"
             },
             "entries": [
                 {
                     "sha1" : "sha1_value",
                     "md5" : "md5_value",
                     "sha256" : "sha256_value",
                     "platform" : "platform_value",
                     "record_on" : "record_on_value"
                 },
                 {...},
             ...],
             "last_timestamp": "YYYY-MM-DDTHH:MM:SS_or_timestamp",
          }
       }
    }

Examples​

1) Retrieving all samples with whitelist changes from 2016-02-09 12:00:00

The examples return responses in XML as the default format, since the response format parameter is not specified.

/api/feed/whitelisted_change/v1/query/timestamp/1455019200
/api/feed/whitelisted_change/v1/query/utc/2016-02-09T12:00:00

2) Retrieving all samples with whitelist changes from 2016-02-09 12:00:00 that are available in the storage

The examples use the timestamp format in the request. The first example returns the response in XML (as the default, not specified in the request), and the second example returns JSON (as requested).

/api/feed/whitelisted_change/v1/query/timestamp/1455019200?sample_available=true
/api/feed/whitelisted_change/v1/query/timestamp/1455019200?sample_available=true&format=json

3) Retrieving all samples with whitelist changes from 2016-02-09 12:00:00 in JSON and XML format

/api/feed/whitelisted_change/v1/query/timestamp/1430485200?format=json
/api/feed/whitelisted_change/v1/query/timestamp/1406203200?format=xml