# Functionally Similar Files API (tca-0301) — Spectra Intelligence

> Find functionally similar files using Spectra Intelligence tca-0301 and the RHA1 algorithm; query by SHA1 hash at 25% or 50% precision for PE, MachO, and ELF files.

The [RHA (ReversingLabs Hashing Algorithm)](https://www.reversinglabs.com/technology/reversinglabs-hash-algorithm) identifies code similarity between unknown samples and previously seen malware samples. Files have the same RHA1 hash when they are functionally similar.

This API provides a list of SHA1 hashes of files that are functionally similar to the provided file (SHA1 hash) at the selected precision level (grouped by their RHA1 hash).

Precision level represents the degree to which a file is functionally similar to another file. The following precision levels are supported - **25% and 50% for PE** and **25% for MachO and ELF executable files**. A higher precision level will match fewer files, but the files will have more functional similarity.

The 'extended' option provides SHA1 hashes and related sample reputation information in the response, along with some other properties such as sample size, sample type and download availability.

By using this API, the user can easily get a list of all functionally similar files for the provided file (SHA1 hash) found in the Spectra Intelligence cloud, along with their reputation information.

The user can also filter out results by sample's classification. For example, only malicious files functionally similar to the provided one.

## General Info about Requests/Responses

- This query returns a list containing all the SHA1 hashes for the requested SHA1 and precision level (grouped by the RHA1 hash)
- All requests support the **format** query field, which supports two options: **xml** and **json**
- The default response format is **XML**

## Group By RHA1 Single Query

This query returns a list containing all SHA1 hashes of functionally similar samples for the requested SHA1 sample hash and RHA1 precision level.

If the extended option is selected, each SHA1 hash in the list will be expanded with additional metadata:

- reputation information - classification, threat level, trust factor, malware family name, threat name, malware type, targeted platform and subplatform;
- SHA1, MD5, and SHA256 hashes;
- sample size, sample type, download availability, first and last seen dates (UTC);

<Button title="View OpenAPI Specification" href="/SpectraIntelligence/API-reference/#tag/malware-hunting/get/apigroup_by_rha1v1queryrha1_typehash_valuenext_page_sha1" />

### Request

```
GET /api/group_by_rha1/v1/query/{rha1_type}/{hash_value}[/{next_page_sha1}]?[format=xml|json]&[limit={1-1000}]&[extended=true|false]&[classification=KNOWN|MALICIOUS|SUSPICIOUS|UNKNOWN]
```

#### Path parameters

- `rha1_type`
  - A measure of RHA1 precision level. It represents the degree to which a file is functionally similar to another file. A higher precision level will match fewer files, but the files will have more functional similarity: **pe01**, **elf01**, **machO01** - 25% precision level; **pe02** - 50% precision level
  - Required
- `hash_value`
  - Must be a valid SHA1 file hash
  - Required
- `next_page_sha1`
  - An optional parameter used for pagination. It is the SHA1 hash of the first sample on the next page.
  - Optional

#### Query parameters

- `format`
  - Specifies the response format, with possible values being **xml** (default) and **json**
  - Optional
- `limit`
  - The maximum number of sample SHA1 hashes to return. This value has to be an integer in the range from 1 and 1000 (1000 is the default value)
  - Optional
- `extended`
  - An optional parameter. Supported values are true - extended, and false - non-extended data set (default)
  - Optional
- `classification`
  - If this parameter is provided in the request, the query will return a filtered list of samples that match the requested classification. Supported values are: KNOWN, SUSPICIOUS, MALICIOUS, UNKNOWN
  - Optional

### Response

- The query will return a list of `limit` samples. If the `limit` parameter is not provided in the request, 1000 records will be returned by default.
- Fields in the response depend on the selected data set. If the `extended` parameter is not set to **true**, only the list of sample SHA1 hashes will be returned.
- If the requested hash doesn't exist in the database records, the server will respond with the status response code 404 and the message **"Requested data was not found"**

``` json
{
  "rl": {
    "group_by_rha1": {
      "query_sha1": "string",
      "rha1_type": "string",
      "sha1_list": []
    }
  }
}
```

- `query_sha1`
  - Requested SHA1
- `rha1_type`
  - Requested RHA1 type
- `next_page_sha1`
  - First SHA1 on the next page. This hash value can be used as the next_page parameter in the next request to retrieve the next page of results
- `sha1_list`
  - A list of hashes of functionally similar files

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

`rl.group_by_rha1.sha1_list[]`

```json
{
  "sha1": "string",
  "sha256": "string",
  "md5": "string",
  "classification": "string",
  "sample_type": "string",
  "sample_size": 0,
  "sample_available": 0,
  "trust_factor": 0,
  "threat_level": 0,
  "first_seen": 0,
  "last_seen": 0
}
```

- `sha1`
  - SHA1
- `sha256`
  - SHA256
- `md5`
  - MD5
- `first_seen` (optional)
  - time when the sample was first seen in the ReversingLabs system (UTC)
- `last_seen` (optional)
  - time when the sample last received impactful changes to its analysis or classification data (UTC)
- `sample_type`
  - sample type
- `sample_size`
  - sample size
- `sample_available`
  - sample download availability status
- `classification`
  - sample's classification
- `platform` (optional)
  - platform targeted by the malware
- `subplatform` (optional)
  - subplatform targeted by the malware
- `threat_name` (optional)
  - threat name for malicious samples
- `malware_type` (optional)
  - malware type for malicious samples
- `malware_family` (optional)
  - malware family for malicious samples
- `threat_level` (optional)
  - threat level of the sample
- `trust_factor` (optional)
  - trust factor of the sample

## Examples

### Format query field

These examples request different response formats:

```
/api/group_by_rha1/v1/query/pe01/1b85cbfa30e181c505ba15211db33247c1f8a63f?format=json
/api/group_by_rha1/v1/query/pe01/1b85cbfa30e181c505ba15211db33247c1f8a63f?format=xml
```

### Extended optional parameter used

These examples use different extended parameters:

```
/api/group_by_rha1/v1/query/pe01/1b85cbfa30e181c505ba15211db33247c1f8a63f?extended=true
/api/group_by_rha1/v1/query/pe01/1b85cbfa30e181c505ba15211db33247c1f8a63f?extended=false
```

### Limit query field

These examples use different query response limits:

```
/api/group_by_rha1/v1/query/pe01/1b85cbfa30e181c505ba15211db33247c1f8a63f?limit=1
/api/group_by_rha1/v1/query/pe01/1b85cbfa30e181c505ba15211db33247c1f8a63f?limit=100
```

### Different precision levels (RHA1 type)

These examples request different rha1_type precision levels:

```
/api/group_by_rha1/v1/query/pe01/1b85cbfa30e181c505ba15211db33247c1f8a63f
/api/group_by_rha1/v1/query/pe02/1b85cbfa30e181c505ba15211db33247c1f8a63f
/api/group_by_rha1/v1/query/elf01/8983043176164b960e10b34307f52e88db894b71
/api/group_by_rha1/v1/query/macho01/f1c2712a3881ca795b5eadf65077788198522362
```

### next_page_sha1 query field

These examples use the next page parameter:

```
/api/group_by_rha1/v1/query/pe01/1b85cbfa30e181c505ba15211db33247c1f8a63f/cd3710af6638b99666a19b4f098b8788723397ab
/api/group_by_rha1/v1/query/pe02/1b85cbfa30e181c505ba15211db33247c1f8a63f/cd3710af6638b99666a19b4f098b8788723397ab
```
