# File Indicators Feed (TCF-0102-0106) — Spectra Intelligence

> Consume TCF-0102-0106 to get platform-filtered malware detections from Spectra Intelligence; separate feeds for Windows, Android, macOS, and other platforms.

# Malware detection feed (platform-filtered) (TCF-0102-0106)

This service provides information about new malware samples with detections in the Spectra Intelligence system. The samples are filtered by platform.

The following criteria defines the types of samples that can enter this feed:

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

Samples will enter the feed only if their platform is detected as one of the supported platforms:

The feed stores records for the last 365 days.

## Malware Detection Platform Feed Query

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

The feed will return at most 1000 records, or a little bit over 1000 if there are multiple records with 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**.

<Button title="View OpenAPI Specification" href="/SpectraIntelligence/API-reference/#tag/malicious-file-indicators/get/api/feed/malware/detection/platform/v1/query/{time_format}/{time_value}" />

### 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. This parameter is optional and can be used to filter the samples by their detected platform value. 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

### 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.
rl \> malware_detection_platform_feed

### Response Examples

``` json
{"rl": {
  "malware_detection_platform_feed: {
    "entries": [
      {
        "md5" : "md5_value",
        "platform"  : "platform_value",
        "record_on" : "YYYY-MM-DDTHH:MM:SS",
        "sample_type" : "sample_type_value",
        "sha1" : "sha1_value",
        "sha256" : "sha256_value",
      },
      {...},
      …
    ],
    "last_timestamp": "YYYY-MM-DDTHH:MM:SS_or_timestamp",
    "time_range": {
      "from": "YYYY-MM-DDTHH:MM:SS", 
      "to": "YYYY-MM-DDTHH:MM:SS"
    },
    }
  }
}
```

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

<Button title="View OpenAPI Specification" href="/SpectraIntelligence/API-reference/#tag/malicious-file-indicators/get/api/feed/malware/detection/platform/v1/query/pull" />

### 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. This optional parameter can be used to filter samples by their detected platform value. 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

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

<Button title="View OpenAPI Specification" href="/SpectraIntelligence/API-reference/#tag/malicious-file-indicators/put/api/feed/malware/detection/platform/v1/query/start/{time_format}/{time_value}" />

### 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
```

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

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

            }
        }
    }
}
```
