# Malicious Files Feed (TCF-0101) — Spectra Intelligence

> Consume TCF-0101 to receive a continuous stream of new samples with at least one AV scanner detection, including file hashes, file type, and targeted platform.

# Malware detection feed (TCF-0101)

This service provides a continuous list of new samples with at least one antivirus scanner detection present in the Spectra Intelligence system.

Samples that appear in this feed will not necessarily be classified as malicious by ReversingLabs, since antivirus scanner detections are only one of the components taken into consideration for the final classification verdict.

Each record in the feed, besides hashes of the detected sample, includes some additional information about the samples, such as their file type and targeted platform.

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

- a public sample was scanned for the first time and a threat was detected (by at least one AV scanner)
- a public sample was rescanned and a threat was detected during rescan (by at least one AV scanner)
- a private sample became public and a threat was detected during rescan (by at least one AV scanner)

The feed stores records for the last 365 days.

## Continuous Malware Detection Feed Query

This query returns malware detections from the requested timestamp. 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**.

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

### Request

```
GET /api/feed/malware/detection/v1/query/{time_format}/{time_value}[?format=xml|json|tsv][&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
- `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
- `sample_available`
  - Indicates whether the samples are present in the ReversingLabs storage and are available for download (true) or if they are not available (false). Supported values are **false** (default) and **true**. This field does not update, it shows sample availability at the time of entering the feed.
  - 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

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 the information about the sample's file type and targeted platform.

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, sample_size 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_feed

### Response Examples

``` json
{"rl": {
    "malware_detection_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",
                "sample_type" : "sample_type_value",
                "sample_size" : "sample_size_value",
                "platform"  : "platform_value"
                },
                {...},
                …
            ],
            "last_timestamp": "YYYY-MM-DDTHH:MM:SS_or_timestamp", 
        }
    }   
}
```

## PULL Query

This query returns a list of malware detections since a particular point in time. The starting point for this query is defined using the [START query](#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. That 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 single thread (single instance). Any concurrent requests will be blocked until the previous one is fulfilled.

### Request

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

```
GET /api/feed/malware/detection/v1/query/pull[?format=xml|json|tsv][&limit=N][&sample_available=false|true]
```

- `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 if they are not available (false). Supported values are **false** (default) and **true**.
  - 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 [Continuous Malware Detection Feed Query](#continuous-malware-detection-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**.

### Request

```
PUT /api/feed/malware/detection/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

### Format query field

**Fetching all new detections from 2017-03-26 10:33:20**

```
/api/feed/malware/detection/v1/query/timestamp/1490517200
/api/feed/malware/detection/v1/query/utc/2017-03-26T10:33:20
```

**Fetching all new detections from 2017-03-26 10:33:20 with samples available in the storage**

```
/api/feed/malware/detection/v1/query/timestamp/1490517200?sample_available=true
/api/feed/malware/detection/v1/query/timestamp/1490517200?sample_available=true&format=json
```

**Fetching all new samples from 2017-03-26 10:33:20 in JSON and XML formats**

```
/api/feed/malware/detection/v1/query/timestamp/1490517200?format=json
/api/feed/malware/detection/v1/query/timestamp/1490517200?format=xml
```

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

```
/feed/malware/detection/v1/query/start/timestamp/1490517200
```

**Pulling records from the latest state**

```
/feed/malware/detection/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_feed": {
            "entries": [], 
            "last_timestamp": 1449745851, 
            "time_range": {
                "from": "2017-03-26T10:33:20", 
                "to": "2017-03-26T10:34:20"

            }
        }
    }
}   
```
