# Sample Feed (TCF-0111) — Spectra Intelligence

> Consume TCF-0111 to receive new malicious samples, false positive reclassifications, and threat name changes from the Spectra Intelligence malware presence change events feed.

# 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](/General/AnalysisAndClassification/MalwareNamingStandard) (*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



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

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

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

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](https://www.reversinglabs.com/products/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

``` json
{"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
        }
    }
}
```

``` json
{"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](#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**.

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

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

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