Skip to main content

Malware presence change events feed (TCF-0111)

The Malware Presence Change Events Feed provides a continuous list of new malicious samples, false positives (FPs) and malicious samples for which the ReversingLabs threat name changed.

Event types included in the feed:

  • New malicious - event type representing files for which the classification changed to MALICIOUS (including false negatives - FNs)
  • False positive (FP) - event type representing files for which the classification changed from MALICIOUS or SUSPICIOUS to KNOWN
  • Threat name changes - event type representing malicious files for which the threat name changed

By including event_type information in the response, the service enables users to filter records by event and easily get newly discovered samples that ReversingLabs classified as malicious, or information about false positive samples - malicious or suspicious samples for which the classification changed into KNOWN after rescanning.

The service also provides information about threat name changes for malicious samples. The threat_name field is returned in the response for "New malicious" and "Threat name changes" event types.

Threat names follow the ReversingLabs Malware Naming Standard <naming> (platform-subplatform.malware_type.malware_family). The following are examples of threat names formatted according to the standard:

Win32.Ransomware.Teslacrypt Android.Trojan.Smsbot Script-JS.Downloader.Nemucod

By comparing the threat_name fields in the response for the "Threat name changes" event type, users can track malware type changes, malware family changes, as well as changes in the affected platform.

Similarly, based on the threat_name field information in the response for "New malicious" event type, users can compile a list of new malicious samples by specific platform, malware type, or malware family.

The feed stores records for the last 365 days.

ReversingLabs Malware Naming Standard​

The ReversingLabs detection string consists of three main parts separated by dots. All parts of the string will always appear (all three parts are mandatory).

The first part of the string indicates the platform targeted by the malware. If the platform is ByteCode, Document or Script, then there will be an additional subplatform string. Platform and subplatform strings are separated by a hyphen ( - ).

The second part of the detection string describes the malware type. The third part represents the malware family name (one of most common names for that malware).

Examples

If a trojan is designed for the Windows 32 platform and its family name is "Adams", the detection string will look like this:

Win32.Trojan.Adams

If backdoor malware is a PHP script with the family name "Jones", the detection string will look like this:

Script-PHP.Worm.Jones

Supported Detection String Elements​

  • ABAP
  • Archive
  • Binary
  • ByteCode
  • Document
  • Email
  • Image
  • MacOS
  • OS2
  • PDF
  • Script-VBS
  • SunOS
  • Unix
  • WebAssembly
  • WinCE
  • 7ZIP
  • ActiveX
  • AR
  • AutoIt
  • BMP
  • CGI
  • CorelDraw
  • Excel
  • GZIP
  • INI
  • JAR
  • JS
  • Lua
  • Makefile
  • MSG
  • NuGet
  • OTF
  • PHP
  • PowerShell
  • Python
  • RTF
  • Shockwave
  • SWF
  • TIFF
  • Visio
  • WMF
  • XML
  • Adware
  • Certificate
  • Downloader
  • Format
  • Infostealer
  • Malware
  • Phishing
  • Rogue
  • Spyware
  • Worm

PULL with timestamp​

This query returns samples with a newly calculated or changed malware presence classification and threat name, starting from the timestamp provided in the request. The feed will return at most 1000 records, or a little bit over 1000 if there are multiple records with the same timestamp.

To retrieve the next batch of records, the timestamp from the response field last_timestamp should be increased by 1 and used in the subsequent query as the value of the time_value parameter.

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/mwp_change_events/v1/query/{time_format}/{time_value}/[?format=xml|json][&sample_available=false|true][&limit=N]

Request parameters​

  • time_format
    • Format in which the time value will be specified. Supported values are: timestamp - number of seconds since 1970-01-01 00:00:00; utc - UTC date in the YYYY-MM-DDThh:mm:ss format
    • Required
  • time_value
    • Accepts values in the format set by time_format
    • Required
  • format
    • Parameter defining the format in which the resulting data will be returned. Supported values are: xml (default), json, tsv
    • Optional
  • sample_available
    • 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
  • limit
    • The number of records to return in the response. The maximum and default value is 1000. Note that the response may include more records than requested to ensure that all records with the same timestamp are returned.
    • Optional

Response format​

The response contains a list of records matching the requested timestamp. Every record in the list includes the following information:

  • SHA1, MD5, and SHA256 hashes associated with the sample,
  • event type,
  • sample classification,
  • threat name,
  • sample size,
  • sample type,
  • the timestamp of the update.

An empty response is returned if no records for the requested timestamp are available.

Response fields are described in the following table. Example responses can be found further in the document. Fields that do not appear in the response are considered empty. There will be no fields with empty or null values in the response.

  • SHA1
    • SHA1 of the sample
  • SHA256
    • SHA256 of the sample
  • MD5
    • MD5 of the sample
  • event_type
    • The type of event that triggered the record in the feed. Possible values: NEW_MALICIOUS; FP; THREAT_NAME_CHANGE
  • classification
    • Current Malware Presence status designation. The status designation is calculated by a proprietary ReversingLabs algorithm that adapts and improves as new information about the file and the threat is discovered. The algorithm takes the following into account: Spectra Intelligence antivirus scan results, threat and trust factors, parent/child relationships, certificates, and other metadata-specific information.
  • threat_name
    • Sample's detected threat name (platform-subplatform.malware_type.malware_family)
  • sample_size
    • Sample size (in bytes)
  • sample_type
    • Sample type
  • record_on
    • Timestamp of the update, indicating the date and time when the sample record was updated in the feed.

Response Examples​

{"rl": {
    "mwp_change_events_feed": {
        "time_range": {
            "from": "YYYY-MM-DDTHH:MM:SS",
            "to": "YYYY-MM-DDTHH:MM:SS"
        },
        "entries": [
            {
                "sha1": "21841b32c6165b27dddbd4d6eb3a672defe54271",
                "sha256": "2f6ed...55346",
                "md5": "3133c2231fcee5d6b0b4c988a5201da1",
                "event_type": "FP",
                "classification":"KNOWN",
                "sample_size":"636416",
                "sample_type":"PE/Exe",
                "record_on":"1470221633000"

            },
            {...},
                …
            ],
            "last_timestamp": "YYYY-MM-DDTHH:MM:SS_or_timestamp", -- the format is the same as the requested time format
        }
    }
}
{"rl": {
    "mwp_change_events_feed": {
        "time_range": {
            "from": "YYYY-MM-DDTHH:MM:SS",
            "to": "YYYY-MM-DDTHH:MM:SS"
        },
        "entries": [
            {
                "sha1": "21841b32c6165b27dddbd4d6eb3a672defe54271",
                "sha256": "2f6ed...55346",
                "md5": "3133c2231fcee5d6b0b4c988a5201da1",
                "event_type": "THREAT_NAME_CHANGE",
                "classification":"MALICIOUS",
                "threat_name":"Win32.Trojan.Nsis"
                "sample_size":"636416",
                "sample_type":"PE/Exe",
                "record_on":"1470221633000"

            },
            {...},
                …
            ],
            "last_timestamp": "YYYY-MM-DDTHH:MM:SS_or_timestamp", -- the format is the same as the requested time format
        }
    }
}

PULL without timestamp​

For this query type, ReversingLabs is tracking the user's last query state, so the user doesn’t have to provide a timestamp in the request to retrieve the next batch of records.

PULL Query​

This query returns a list of classification and threat name changes since a particular point in time. The starting point for this query is defined using the START query. If the user has not previously requested this query or called the START query, it will return records starting with the current timestamp. Every subsequent call will continue from the timestamp where the previous call ended. In case that the timestamp of the previous call is older than 365 days, the subsequent call will autocorrect this timestamp to the oldest available (i.e. current - 365 days), and corresponding records will be returned.

Unless the limit parameter is specified, the feed returns up to 1000 records and any surplus records sharing the same timestamp. This ensures that all the records with the same timestamp will be included in the recordset. The limit parameter must not be greater than 1000.

This endpoint is built to be queried by a single thread (single instance). Any concurrent requests will be blocked until the previous one is fulfilled.

Request parameters​

  • format
    • Parameter defining the format in which the resulting data will be returned. Supported values are: xml (default), json
    • Optional
  • sample_available
    • 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
  • limit
    • The number of records to return in the response. The maximum and default value is 1000. Note that the response may include more records than requested to ensure that all the records with the same timestamp are returned.
    • Optional

Response format​

The response format is the same as in the PULL with timestamp.

START Query​

This query sets the starting timestamp for the previously described PULL query.

The starting timestamp must be within the last 365 days, otherwise the service will respond with the status code 400 Bad Request.

PUT /api/feed/mwp_change_events/v1/query/start/[time_format]/[time_value]

Request parameters​

  • time_format
    • Format in which the time value will be specified. Supported values are: timestamp - number of seconds since 1970-01-01 00:00:00; utc - UTC date in the YYYY-MM-DDThh:mm:ss format
    • Required
  • time_value
    • Accepts values in the format set by time_format
    • Required

Response format​

A successful query returns an HTTP 200 OK message with an empty response body.

Examples​

Format query field​

Retrieving all new detections from 2019-05-09T07:25:10

[GET]

/api/feed/mwp_change_events/v1/query/timestamp/1557386701
/api/feed/mwp_change_events/v1/query/utc/2019-05-09T07:25:10

Retrieving all new detections from 2019-05-09T07:25:10 with samples available in the storage

[GET]

/api/feed/mwp_change_events/v1/query/timestamp/1557386701?sample_available=true
/api/feed/mwp_change_events/v1/query/timestamp/1557386701?sample_available=true&format=json

Retrieving all new samples from 2019-05-09T07:25:10 in JSON and XML formats

[GET]

/api/feed/mwp_change_events/v1/query/timestamp/1557386701?format=json
/api/feed/mwp_change_events/v1/query/timestamp/1557386701?format=xml

Setting the initial timestamp to 2017-03-26 10:33:20

[PUT]

/api/feed/mwp_change_events/v1/query/start/timestamp/1557386701

Pulling records from the latest timestamp

[GET]

/api/feed/mwp_change_events/v1/query/pull