Skip to main content

Platform-filtered malware detection feeds (TCF-0102-0106)

The platform-filtered malware detection feeds provide a continuous stream of newly detected malware samples, filtered by the platform the malware targets. Feed codes TCF-0102 through TCF-0106 all deliver this data from the same set of endpoints; the code determines which platforms the feed covers, as described in Feed Codes and Platform Coverage. Every record includes the sample's SHA1, SHA256, and MD5 hashes, its detected platform, its sample type, and the time it entered the feed.

The following criteria define the types of samples that can enter these feeds.

  • Samples that have been scanned for the first time
  • Samples that changed their classification to malicious after a rescan (available through the optional rescans_included parameter, excluded by default)
  • Samples that became available for download, meaning their status changed from private to public

The feeds are continuous, and they store records for the last 365 days. Records are returned in XML, JSON, or TSV format.

Feed Codes and Platform Coverage​

Each feed code covers a different platform scope.

The platform values available to you depend on your subscription. TCF-0102 through TCF-0105 each cover a single platform, while TCF-0106 covers all of them and lets you combine several in one query. To check which feeds your account is entitled to, contact your ReversingLabs account team or the Support Team.

TCF-0106 covers the scope of TCF-0102, TCF-0103, TCF-0104, and TCF-0105, plus 14 additional platforms. A TCF-0106 query for platform=Android returns the same records as TCF-0102, because both codes are served by the same endpoint. What differs between the codes is which platforms your subscription covers, not the data the API returns for a given platform.

The following table shows which platform each code delivers and which value to send in the platform request parameter.

Feed codeFeed namePlatform scopeplatform value
TCF-0102New Malware - AndroidAndroid applicationsAndroid
TCF-0103New Malware - MacOSmacOS executables, such as DMG and Mach-O filesMacOS
TCF-0104New Malware - LinuxLinux executables, 32-bit and 64-bitLinux
TCF-0105New Malicious DocumentsDocuments, such as PDF, Microsoft Office, and RTFDocument
TCF-0106New Malware - Platform FilteredAny of the 18 supported platforms, in any combinationAny value listed in Supported Platform Values

Each code uses the same three endpoints, described in the following sections, with its own platform value. The START query takes no platform parameter, because it only sets the starting timestamp for the PULL query, so it's identical for every code.

Supported Platform Values​

A sample enters these feeds only if its detected platform is one of the values in the following table. Platform strings follow the ReversingLabs malware naming standard. The platform parameter is case-insensitive, so platform=android and platform=Android are equivalent. The table uses the casing that the feed returns in the platform response field.

platform valueCoversAvailable in
AndroidApplications for Android OSTCF-0102, TCF-0106
BootBoot sectors and master boot records (MBR)TCF-0106
ByteCodePlatform-independent bytecodeTCF-0106
DocumentDocuments, such as PDF, Microsoft Office, and RTFTCF-0105, TCF-0106
DOSDOS and 16-bit Windows operating systemsTCF-0106
FirmwareBIOS and firmware for embedded devicesTCF-0106
FreeBSDExecutable content for 32-bit and 64-bit FreeBSDTCF-0106
iOSApplications for Apple iOSTCF-0106
LinuxExecutable content for 32-bit and 64-bit LinuxTCF-0104, TCF-0106
MacOSExecutable content for Apple macOS and OS XTCF-0103, TCF-0106
OS2Executable content for IBM OS/2TCF-0106
PalmApplications for the Palm mobile OSTCF-0106
ScriptScriptsTCF-0106
SymbianApplications for Symbian OSTCF-0106
UnixExecutable content for the UNIX platformTCF-0106
UnknownSamples whose target platform could not be determinedTCF-0106
Win32Executable content for 32-bit WindowsTCF-0106
Win64Executable content for 64-bit WindowsTCF-0106

Malware Detection Platform Feed Query​

This query returns a list of malware samples, optionally filtered by platform, since the requested timestamp.

The feed returns at most 1000 records, or slightly more than 1000 if several records share 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 responds with the status code 400 Bad Request.

View OpenAPI Specification

Request​

GET /api/feed/malware/detection/platform/v1/query/{time_format}/{time_value}?platform={platform_name}&[platform={platform_name}...]&[format=xml|json|tsv][&rescans_included=false|true][&sample_available=false|true][&limit=N]
  • 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
  • platform
    • The parameter accepts one or more values from the list of supported platform names, and filters the samples by their detected platform value. Repeat the parameter to request several platforms in one query. When the parameter is omitted, no platform filtering is applied and the feed returns records for all available platforms. Values are case-insensitive. Supported values are: Android, Boot, ByteCode, Document, DOS, Firmware, FreeBSD, iOS, Linux, MacOS, OS2, Palm, Script, Symbian, Unix, Unknown, Win32, Win64
    • Optional
  • format
    • Specifies the format in which the resulting data will be returned. Supported values are: xml (default), json, tsv (Tab Separated Values, delimiter character t 0x09)
    • Optional
  • rescans_included
    • If this parameter is set to true, the response will be expanded to include any samples that changed their classification to malicious after a rescan.
    • 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

The following examples show the request each feed code uses.

Android Malware (TCF-0102)​

Newly detected Android malware samples, with at least one new antivirus scanner detection. Use this feed to monitor mobile threats targeting Android devices and to enrich mobile app reputation checks.

GET /api/feed/malware/detection/platform/v1/query/{time_format}/{time_value}?platform=Android

macOS Malware (TCF-0103)​

Newly detected macOS malware samples, including DMG images and Mach-O executables. Use this feed to monitor threats targeting macOS endpoints.

GET /api/feed/malware/detection/platform/v1/query/{time_format}/{time_value}?platform=MacOS

Linux Malware (TCF-0104)​

Newly detected Linux malware samples, with at least one new antivirus scanner detection. Use this feed to monitor threats targeting Linux servers, containers, and cloud workloads.

GET /api/feed/malware/detection/platform/v1/query/{time_format}/{time_value}?platform=Linux

Malicious Documents (TCF-0105)​

Newly detected malicious document samples, such as PDF, Microsoft Office, and RTF files. Use this feed to monitor the document formats most often used in phishing and initial-access campaigns.

GET /api/feed/malware/detection/platform/v1/query/{time_format}/{time_value}?platform=Document

Platform-Filtered Malware (TCF-0106)​

Newly detected malware for any of the supported platforms. This is the code that covers Windows malware (Win32, Win64), and the only one that can combine platforms: repeat the platform parameter for each platform you want, as in ?platform=Linux&platform=FreeBSD&platform=Unix. The following request shows a Windows-only query.

GET /api/feed/malware/detection/platform/v1/query/{time_format}/{time_value}?platform=Win32&platform=Win64

Response​

For the requested timestamp, the response contains a list of records. Every item in the list includes SHA1, MD5, and SHA256 hashes associated with the malware sample, as well as information about the sample's file type. The record_on field is a timestamp that indicates when the sample has entered the feed, based on the feed criteria configured at that time. Every item also has the targeted platform for the sample.

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

  • time_range
    • The from/to time range of results
  • entries
    • A list of records, each returned as a separate item, containing SHA1, MD5, SHA256, sample_type, record_on and targeted platform
  • last_timestamp
    • The timestamp of the last result. Increase by 1 in the next query to retrieve the next batch of results. The format will be the same as the requested time format.

Response Examples​

{
  "rl": {
    "malware_detection_platform_feed": {
      "time_range": {
        "from": "2024-01-22T12:15:03",
        "to": "2024-01-22T12:15:59"
      },
      "entries": [
        {
          "sha1": "003614d9c5fc5bd46b8367495d8b1056786ad7d4",
          "md5": "14169e86f460c6c5b45b3fbd7f4c40fe",
          "sha256": "844980f04943ae23d895d74c11f7eb96914be298202e10bd2324e1e93799301d",
          "sample_type": "PE32 executable (GUI) Intel 80386 (stripped to external PDB), for MS Windows, UPX compressed, 4 sections",
          "platform": "Win32",
          "record_on": "2024-01-22T12:15:06"
        }
      ],
      "last_timestamp": 1705925759
    }
  }
}

PULL Query​

This query returns the list of malware samples optionally filtered by platform 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, nor has the START query been called, 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 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 request is fulfilled.

View OpenAPI Specification

Request​

GET /api/feed/malware/detection/platform/v1/query/pull?platform={platform_name}&[platform={platform_name}...]&[format=xml|json|tsv][&sample_available=false|true][&rescans_included=false|true][&limit=N]
  • platform
    • The parameter accepts one or more values from the list of supported platform names, and filters the samples by their detected platform value. Repeat the parameter to request several platforms in one query. When the parameter is omitted, no platform filtering is applied and the feed returns records for all available platforms. Values are case-insensitive. Supported values are: Android, Boot, ByteCode, Document, DOS, Firmware, FreeBSD, iOS, Linux, MacOS, OS2, Palm, Script, Symbian, Unix, Unknown, Win32, Win64
    • Optional
  • format
    • Specifies the response format. The following values are supported: xml - default; json; tsv (Tab Separated Values, delimiter character t 0x09)
    • Optional
  • sample_available
    • Indicates whether the samples are present in the ReversingLabs storage and are available for download (true) or not (false). Supported values are false (default) and true.
    • Optional
  • rescans_included
    • If this parameter is set to true, the response will be expanded to include any samples that changed their classification to malicious after a rescan.
    • Optional
  • limit
    • Number of records to return in the response. The maximum and default value is 1000. Note that the response may include a little more than the requested number of records to ensure that all the records with the same timestamp are returned.
    • Optional

The following examples show the PULL request each feed code uses.

GET /api/feed/malware/detection/platform/v1/query/pull?platform=Android
GET /api/feed/malware/detection/platform/v1/query/pull?platform=MacOS
GET /api/feed/malware/detection/platform/v1/query/pull?platform=Linux
GET /api/feed/malware/detection/platform/v1/query/pull?platform=Document
GET /api/feed/malware/detection/platform/v1/query/pull?platform=Win32&platform=Win64

Response​

The response format is the same as in the feed_query.

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.

View OpenAPI Specification

Request​

PUT /api/feed/malware/detection/platform/v1/query/start/[time_format]/[time_value]
  • 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​

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

Examples​

Retrieving all new malware samples from 2020-05-01 10:33:20 with platform Android and iOS:

/api/feed/malware/detection/platform/v1/query/timestamp/1588329200?platform=Android&platform=iOS
/api/feed/malware/detection/platform/v1/query/utc/2020-05-01T10:33:20?platform=Android&platform=iOS

Retrieving all new malware samples for the platform Win32 from 2020-05-01 10:33:20 that are available for download:

/api/feed/malware/detection/platform/v1/query/timestamp/1588329200?sample_available=true&platform=Win32
/api/feed/malware/detection/platform/v1/query/timestamp/1588329200?sample_available=true&platform=Win32&format=json

Retrieving all new malware samples for the platform Win32 from 2020-05-01 10:33:20, and any malware samples that changed their classification to malicious following a rescan:

/api/feed/malware/detection/platform/v1/query/timestamp/1588329200?rescans_included=true&platform=Win32

Retrieving all new malware samples for the platform Win32 from 2020-05-01 10:33:20 in JSON and XML format:

/api/feed/malware/detection/platform/v1/query/timestamp/1588329200?platform=Win32&format=json
/api/feed/malware/detection/platform/v1/query/timestamp/1588329200?platform=Win32&format=xml

Retrieving new malicious documents and scripts in a single query:

/api/feed/malware/detection/platform/v1/query/timestamp/1588329200?platform=Document&platform=Script&format=json

Setting the initial timestamp for the PULL query to 2020-05-01 10:33:20:

/api/feed/malware/detection/platform/v1/query/start/timestamp/1588329200

Pulling records since the latest state:

/api/feed/malware/detection/platform/v1/query/pull

Empty Response Example​

An empty response is returned if no records for the requested timestamp are available. To return the next batch of records, use the last_timestamp value incremented by 1.

JSON

{
  "rl": {
    "malware_detection_platform_feed": {
      "entries": [],
      "last_timestamp": 1588329200,
      "time_range": {
        "from": "2020-05-01T10:33:20",
        "to": "2020-05-01T10:34:20"
      }
    }
  }
}

See Also​