# File Reputation API (tca-0101) — Spectra Intelligence

> Query malware status, threat level, trust factor, and malware family for MD5, SHA1, or SHA256 hashes using the Spectra Intelligence tca-0101 File Reputation API.

# File reputation (TCA-0101)

The File Reputation (Malware Presence) service provides information about the malware status of requested samples. The status can be malicious, suspicious, known, or unknown.

The service supports single and bulk queries. It also provides an option to return extended response data that includes even more information about samples, such as their trust factor, threat level, and more. Additionally, it is possible to retrieve MD5, SHA1, and SHA256 hashes for the requested sample(s) using the **show_hashes** parameter.

**This API is rate limited to 500 requests per second.**

## General Info about Requests/Responses

- All requests support the **format** parameter which supports two options: **xml** or **json**.
- Default response format is **xml**, except for bulk queries, where the default response format is the same as the **post_format**.
- The number of hashes in a bulk request must not be greater than **100**.
- POST requests must contain an HTTP header field **Content-Type: application/octet-stream**

## Malware Presence

This query returns information about the malware status of the requested sample.

<Button title="View OpenAPI Specification" href="/SpectraIntelligence/API-reference/#tag/file-threat-intelligence/get/apidatabrowsermalware_presencequeryhash_typehash_value" />

### Request

```
GET /api/databrowser/malware_presence/query/{hash_type}/{hash_value}
```

- `hash_type`
  - Specifies which hash type will be used in the request. Supported values: `md5`, `sha1`, `sha256`
  - Required
- `hash_value`
  - Hash of the file for which the user is requesting data from the service. The value must be a valid hash of the same type specified by the `hash_type` parameter.
  - Required

### Response

``` json
{
  "rl": {
    "malware_presence": {
      "status": "KNOWN",
      "query_hash": {
        "sha1|md5|sha256": "hash_value"
      }
    }
  }
}
```

- `status`
  - Malware presence status designation (UNKNOWN, KNOWN, SUSPICIOUS, or MALICIOUS). Read more about the ReversingLabs [classification algorithm](/General/AnalysisAndClassification/Classification).
- `query_hash`
  - The hash type and value used in the request. Can be `md5`, `sha1`, or `sha256`

## Malware Presence Bulk

A bulk query will return a response of the same format as a single query retrieves, but for multiple hashes in a single response. There are also additional response fields describing ill-formatted hashes, and hashes not found by the service. Up to 100 hashes can be submitted in one request.

<Button title="View OpenAPI Specification" href="/SpectraIntelligence/API-reference/#tag/file-threat-intelligence/post/apidatabrowsermalware_presencebulk_querypost_format" />

### Request

```
POST /api/databrowser/malware_presence/bulk_query/{post_format}
```

- `post_format`
  - Required parameter that defines the POST payload format. Supported options are **xml** and **json**. By default, the response format matches the format defined by this parameter.
  - Required

The following rules apply to both formats (XML and JSON).

- **hash_type** value must be one of the following: `md5`, `sha1`, `sha256`
- **hash_value** must be a valid hash of the same type specified by `hash_type`

#### Request body

``` json
{
  "rl": {
    "query": {
      "hash_type": "hash_type",
      "hashes": [
        "hash_value",
        "hash_value",
        "...",
        "hash_value"
      ]
    }
  }
}
```

### Response

``` json
{
  "rl": {
    "entries": [
      {
        "status": "UNKNOWN",
        "query_hash": {
          "sha1|md5|sha256": "hash_value"
        }
      }
    ],
    "invalid_hashes": [
      "hash_value"
    ]
  }
}
```

Items in `rl.entries` in the **bulk** query response are equivalent to the `rl.malware_presence` element in the **single** query response.

## Extended Malware Presence

Single and bulk queries support an additional query parameter `extended`. This is an optional parameter that specifies whether extended classification metadata for the requested sample(s) should be returned in the response.

The parameter can be set to `true` (include extended metadata) or `false` (default; don't include extended metadata). If the parameter is not provided in the request, it is interpreted as `false` (extended metadata is not returned).

Extended metadata includes information such as trust factor and threat level values; malware type, family name, and platform; first and last seen times, and more.

It may also include information on the classification reason for each sample. This information is conveyed in the optional response field `reason`, which is only returned when the `extended` parameter is included in the request, and only if the field is calculated for the requested sample(s).

Classification reason information helps users understand the logic behind sample classification decisions; particularly in the case of goodware overrides. This is an advanced goodware whitelisting technique designed to prevent and suppress possible false positives within highly trusted software packages. If a sample has a valid and trusted certificate signature, or if it came from a trusted source, the sample and all its extracted files should be whitelisted regardless of the AV results. A common example of this are samples with high AV detection results that have the KNOWN classification status.

### Single Query with Extended Option

```
GET /api/databrowser/malware_presence/query/hash_type/hash_value?extended=true
```

### Bulk Query with Extended Option

```
POST /api/databrowser/malware_presence/bulk_query/post_format?extended=true
```

### Response

The response format is the same for sample nodes in both single and bulk queries.

```json
{
  "rl": {
    "malware_presence": {
      "status": "string",
      "threat_level": 0,
      "scanner_percent": 0,
      "scanner_match": 0,
      "last_seen": "string",
      "reason": "string",
      "scanner_count": 0,
      "query_hash": {
        "sha1": "string"
      },
      "first_seen": "string",
      "trust_factor": 0
    }
  }
}
```

- `status`
  - Malware presence status designation (UNKNOWN, KNOWN, SUSPICIOUS, or MALICIOUS). 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.
- `reason`
  - Optional response field that clarifies the reason why a sample received a particular classification status. This field is presently not calculated for all samples in the Spectra Intelligence system, which means it can be omitted from the response.
  - The value of this field can be one of the following: `analyst_sample_override` (the sample was classified manually after an analysis), `antivirus` (the sample was classified by the ReversingLabs multi-scan algorithm based on aggregated antivirus scan results), `best_certificate` (the sample or its container are signed with a valid and trusted certificate), `best_source` (the sample can be obtained from a trusted source, or it was unpacked from a file originating from a trusted source), `TC_certificate` (the sample is signed with a recognized whitelisted certificate), `next-gen-av` (the sample was classified based on aggregated next-gen antivirus scan results), `sandbox` (classified by the ReversingLabs Cloud Sandbox) (*deprecated*).
- `scanner_count`
  - Number of scanners used in the last scan
- `classification`
  - Malware classification based on the latest analysis of the requested sample, calculated by the ReversingLabs algorithm. See rl > malware_presence > classification for details
- `scanner_percent`
  - Percent of scanners that detected malware in the last scan
- `scanner_match`
  - Number of scanners that detected malware in the last scan
- `threat_name`
  - Detected threat name for the requested sample
- `query_hash`
  - Hash value used in the request; can be md5, sha1, or sha256
- `first_seen`
  - Indicates the date and time when the sample was first uploaded to the system, or when it has received a scan result for the first time
- `last_seen`
  - Indicates the date and time when the sample last received impactful changes to its analysis or classification data
- `threat_level`
  - Threat level value for the requested sample (0 indicates no threat; 1 is the lowest threat value - lowest severity, such as Adware; 5 is the highest threat value, e.g, Trojan)
- `trust_factor`
  - Trust factor value of the sample's sources (0 is the most trusted; 5 is the least trusted)

----------------------------------------------------------------------

`rl.malware_presence.classification`

- `family_name`
  - Malware family name of the detected malware
- `subplatform`
  - Subplatform targeted by the detected malware; can be one of the subplatforms defined in [ReversingLabs malware naming standard](/General/AnalysisAndClassification/MalwareNamingStandard).
- `platform`
  - Platform targeted by the detected malware; can be one of the platforms defined in [ReversingLabs malware naming standard](/General/AnalysisAndClassification/MalwareNamingStandard).
- `is_generic`
  - Select trusted 3rd party AV scanners assigned threat names that, based on their naming conventions suggest the sample was "generically" and/or "heuristically" identified as having characteristics similar to known malicious software. If malware is detected in this way, this field returns a true value
- `cve`
  - If applicable, contains the Common Vulnerabilities and Exposures (CVE) identifier. Additional fields are is_candidate (returns true if the sample is a CVE candidate or false if the sample is an official CVE list entry), CVE number, and CVE year
- `type`
  - Malware type; can be one of the types defined in [ReversingLabs malware naming standard](/General/AnalysisAndClassification/MalwareNamingStandard).

----------------------------------------------------------------------

### Response Examples

#### Sample with Malware Presence Status MALICIOUS

``` json
{
  "rl": {
    "malware_presence": {
      "status": "MALICIOUS",
      "scanner_count": 40,
      "classification": {
        "platform": "Win32",
        "type": "Trojan",
        "is_generic": false,
        "family_name": "Nsis"
      },
      "scanner_percent": 82.5,
      "scanner_match": 33,
      "threat_name": "Win32.Trojan.Nsis",
      "query_hash": {
        "sha1": "1d412db0ac58dd8d8bfae8b18c7b355bd14dab2f"
      },
      "first_seen": "2012-07-12T00:05:00",
      "threat_level": 5,
      "trust_factor": 5,
      "last_seen": "2017-08-09T11:40:00"
    }
  }
}
```

#### Sample with Malware Presence Status SUSPICIOUS

``` json
{
  "rl": {
    "malware_presence": {
      "status": "SUSPICIOUS",
      "scanner_count": 29,
      "classification": {
        "subplatform": "JS",
        "platform": "Script",
        "is_generic": false,
        "family_name": "Trojan-downloader"
      },
      "scanner_percent": 6.8965516090393066,
      "scanner_match": 2,
      "threat_name": "Script-JS.Malware.Trojan-downloader",
      "query_hash": {
        "sha1": "e0c58164cde263904abc07915d7c9d2722e3806c"
      },
      "first_seen": "2017-09-07T01:14:31",
      "threat_level": 0,
      "trust_factor": 5,
      "last_seen": "2017-09-28T09:08:00"
    }
  }
}
```

#### Sample with Malware Presence Status KNOWN

``` json
{
  "rl": {
    "malware_presence": {
      "status": "KNOWN",
      "reason": "TC_certificate",
      "scanner_count": 25,
      "scanner_percent": 76,
      "scanner_match": 19,
      "query_hash": {
        "sha1": "5ff74f670c8a68557bf36955d3e4e2353266d607"
      },
      "first_seen": "2016-06-30T01:17:42",
      "threat_level": 0,
      "trust_factor": 0,
      "last_seen": "2019-10-17T10:03:23"
    }
  }
}
```

#### Sample with Malware Presence Status UNKNOWN

``` json
{
  "rl": {
    "malware_presence": {
      "status": "UNKNOWN",
      "query_hash": {
        "sha1": "e4e8c856c1524ff22b87b29d605ab8fdb1007298"
      }
    }
  }
}
```

## Malware Presence with Available Hashes

Single and bulk queries support an additional request parameter `show_hashes`, which can be set to either `true` or `false`. This optional parameter can be used in combination with the `extended` parameter in the same request.

When set to `true`, the `show_hashes` parameter specifies that MD5, SHA1, and SHA256 hashes should be returned in the response for the requested sample, in addition to the rest of the Malware Presence information. If the parameter is not provided in the request, it is interpreted as `false` (additional hashes are not returned).

### Request

```
GET /api/databrowser/malware_presence/query/hash_type/hash_value?show_hashes=true
```

```
POST /api/databrowser/malware_presence/bulk_query/{post_format}?show_hashes=true
```

### Response

Entries in `rl.entries` in the bulk query response are equivalent to the `rl.malware_presence` element in the single query response.

If both the **extended** and **show_hashes** parameters are set to true then the response will contain both extended malware presence information and MD5, SHA1 and SHA256 hashes.

``` json
{
  "rl": {
    "malware_presence": {
      "status": "KNOWN",
      "query_hash": {
        "sha1|md5|sha256": "hash_value"
      },
      "md5": "md5 hash_value",
      "sha1": "sha1 hash_value",
      "sha256": "sha256 hash_value"
    }
  }
}
```

- `status`
  - Malware presence status designation (UNKNOWN, KNOWN, SUSPICIOUS, or MALICIOUS)
- `query_hash`
  - The hash type and value used in the request; can be MD5, SHA1, or SHA256
- `md5, sha1, sha256`
  - Respective hashes for the requested sample(s).

## Examples

### Single query - changing the response format

```
/api/databrowser/malware_presence/query/sha1/a25b6db2d363eaa31de348399aedc5651280b52b?format=json
/api/databrowser/malware_presence/query/sha1/a25b6db2d363eaa31de348399aedc5651280b52b?format=xml
```

### Single query - changing the hash type

```
/api/databrowser/malware_presence/query/sha1/a25b6db2d363eaa31de348399aedc5651280b52b
/api/databrowser/malware_presence/query/sha256/10dbb2b27208c5566d326b47950657bf6b3c9a59e302598a128ad7125d5fb4fd
/api/databrowser/malware_presence/query/md5/ca083f61113e1fb8f539ecfa7c725fc8
```

### Single query - changing the optional flags

```
/api/databrowser/malware_presence/query/sha1/a25b6db2d363eaa31de348399aedc5651280b52b?extended=true
/api/databrowser/malware_presence/query/sha1/a25b6db2d363eaa31de348399aedc5651280b52b?show_hashes=true
/api/databrowser/malware_presence/query/sha1/a25b6db2d363eaa31de348399aedc5651280b52b?extended=true&show_hashes=true
```

### Bulk query - changing the POST format

```
/api/databrowser/malware_presence/bulk_query/json
/api/databrowser/malware_presence/bulk_query/xml
```

With bulk queries, the response format will default to the request format. If you want a different response format, add the **format** query field:

```
/api/databrowser/malware_presence/bulk_query/xml?format=json
```

### Bulk query - JSON POST format

```
/api/databrowser/malware_presence/bulk_query/json
```

``` json
{
  "rl": {
    "query": {
      "hash_type": "md5",
      "hashes": [
        "4bb64c06b1a72539e6d3476891daf17b",
        "6353de8f339b7dcc6b25356f5fbffa4e",
        "59cb087c4c3d251474ded9e156964d5d",
        "6c2eb9d1a094d362bcc7631f2551f5a4",
        "a82c781ce0f43d06c28fe5fc8ebb1ca9",
        "920f5ba4d08f251541c5419ea5fb3fb3"
      ]
    }
  }
}
```

``` json
{
  "rl": {
    "query": {
      "hash_type": "sha1",
      "hashes": [
        "13e40f38427a55952359bfc5f52b5841ce1b46ba",
        "831fc2b9075b0a490adf15d2c5452e01e6feaa17",
        "42b05278a6f2ee006072af8830c103eab2ce045f"
      ]
    }
  }
}
```

``` json
{
  "rl": {
    "query": {
      "hashes": [
        "0001f757f6b9523707462066100aa543",
        "000202ed4a0fb4c95e68824bc7777a78",
        "00026f63fd5a2600b73a866d7ef08b6f"
      ],
      "hash_type": "md5"
    }
  }
}
```
