# File Reputation Override API (tca-0102) — Spectra Intelligence

> Override file classifications to malicious, suspicious, or known using Spectra Intelligence tca-0102; manage false positives and list org-wide overrides by hash.

# File reputation override (TCA-0102)

The File Reputation User Override service enables sample classification overrides. Any sample can be overridden to malicious, suspicious, or known. Overrides are visible to all users within the same organization.

The service also supports listing existing overrides.

For more information on classifications, trust factor, threat level, and the ReversingLabs malware naming standard, see the TCA-0101 File Reputation (Malware Presence) documentation.

**This API is rate limited to 10 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**.

## User Override

This query allows classification overrides for one or more sample hashes. 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_presenceuser_overridepost_format" />

### Request

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

- `post_format`
  - Required parameter that defines the POST payload format. Supported options are **xml** and **json**.
  - Required

#### Request body

``` json
{
  "rl": {
    "query": {
      "override_samples": [
        {
          "sha1": "string",
          "md5": "string",
          "sha256": "string",
          "status": "string",
          "trust_factor": 0
        },
        {
          "sha1": "string",
          "md5": "string",
          "sha256": "string",
          "status": "string",
          "threat_level": 0,
          "threat_name": "string"
        }
      ],
      "remove_override": [
        {
          "sha1": "string",
          "md5": "string",
          "sha256": "string"
        }
      ]
    }
  }
}
```

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

One of the following fields, `override_samples` or `remove_override`, must be provided and not empty:

- **override_samples** requires an array of objects with **md5**, **sha1**, **sha256**, and **status**
  - **status** options: MALICIOUS, SUSPICIOUS, KNOWN
    - For KNOWN status:
      - Optional **trust_factor**: integer (0-5), defaults to 0
      - Not accepted: **threat_level** and **threat_name**
    - For MALICIOUS/SUSPICIOUS status:
      - Optional **threat_name**: follows the ReversingLabs malware naming standard, defaults to **Win32.Trojan.Generic**
      - Optional **threat_level**: integer (1-5), auto-determined if not provided
      - Not accepted: **trust_factor**
- **remove_override** must be an array of objects containing `md5`, `sha1`, and `sha256`. These samples will have their classification overrides removed.

For more information on these values, refer to the TCA-0101 File Reputation (Malware Presence) documentation.

The total number of sample overrides to create, update and delete may not exceed 100 in a single request.

In case the request does not pass input validation for any reason, the endpoint will return the `400 Bad Request` status code, the response body will contain a helpful error message, and any overrides, valid or not, will be rejected.

### Response

``` json
{
  "rl": {
    "user_override": {
      "create_override": [
        {
          "status": "string",
          "sha256": "string",
          "sha1": "string",
          "md5": "string",
          "threat_level": 0,
          "threat_name": "string"
        }
      ],
      "replace_override": [
        {
          "status": "string",
          "sha256": "string",
          "sha1": "string",
          "md5": "string",
          "trust_factor": 0
        }
      ],
      "remove_override": [
        {
          "sha256": "string",
          "sha1": "string",
          "md5": "string"
        }
      ]
    }
  }
}
```

- `rl.user_override.create_override` is an array of all newly created classification overrides
- `rl.user_override.replace_override` is an array of all new overrides which will replace existing overrides
- `rl.user_override.remove_override` is an array of all overrides to be removed

There are also additional response fields describing ill-formatted hashes, and hashes not found by the service.

Format of each element within these fields matches the request format.

Requests to TCA-0101 File Reputation (Malware Presence) for overridden samples may still return other metadata such as scanner info, CVE data etc., but will return user-specified classification details, and **user_sample_override** as a reason for the classification.

## List Overrides

The List Overrides Query returns a list of all currently active overrides for the current organization.

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

### Request

```
GET /api/databrowser/malware_presence/user_override/list_hashes/{hash_type}?start_hash=9865c7ecda437034e1513cc43ae9a1f6f334bb7f&format=json|xml&extended=true|false
```

- `hash_type`
  - Specifies which hash type will be used in the request. Supported values: `md5`, `sha1`, `sha256`
  - Required
- `start_hash`
  - When this parameter is present, the API will return up to 1000 hashes with a classification override starting from the `start_hash` value. The format must correspond to the one defined with the `hash_type` parameter.
  - Optional
- `format`
  - Response format. Supported values: `json`, `xml`. Default (none): `xml`.
  - Optional
- `extended`
  - When set to `true`, the response extends `rl.user_override.hash_values` into an array of objects containing hash values and classification metadata. In this case, the `hash_type` parameter affects only the type of the `next_hash` value, as the response entries will nor contain all available hash types.
  - Default (absent or `false`): the response format remains unchanged (array of hash strings).
  - Optional

### Response Format

`rl.user_override.hash_values` is an array of hashes specified by the `hash_type`, or objects if `extended=true`. Hashes in the response are sorted. The response contains up to 1000 entries. 

If there are more than 1000 currently overridden samples, `rl.user_override.next_hash` will be a hash value which can be provided in a subsequent request as a `start_hash` query parameter. 

If this is the last page, or there are no more than 1000 overrides, `next_hash` will be **null**.

**Response Fields**

- `rl.user_override.hash_values`
  - Array of hashes specified by the `hash_type`, or objects if `extended=true`.
- `rl.user_override.next_hash`
  - Hash value which can be provided in a subsequent request as a `start_hash` query parameter.

**Extended Response Fields**

- `rl.user_override.hash_values`
  - Array of objects containing hash values and classification metadata.
  - Each object contains the following fields:
    - `sha1`: SHA1 hash value.
    - `md5`: MD5 hash value.
    - `sha256`: SHA256 hash value.
    - `status`: Classification status (MALICIOUS, SUSPICIOUS, KNOWN).
    - `threat_level`: Threat level (1-5) for MALICIOUS/SUSPICIOUS classification/status.
    - `trust_factor`: Trust factor (0-5) for KNOWN classification/status.
    - `threat_name`: Threat name for MALICIOUS/SUSPICIOUS classification/status.
- `rl.user_override.next_hash`
  - Hash value which can be provided in a subsequent request as a `start_hash` query parameter.

``` json
{
  "rl": {
    "user_override": {
      "hash_values": [
        "string",
        "string",
        "string",
        "string"
      ],
      "next_hash": null
    }
  }
}
```

#### Extended Response Format (`extended=true`)

``` json
{
  "rl": {
    "user_override": {
      "hash_values": [
        {
          "sha1": "28279d17721bdce45111f8d62998dbf04cd943f5",
          "md5": "1e7df4685b1d4a6886215d2b0a8d9370",
          "sha256": "94b4387b9e7e715d1e10f11a5aa664e05b5e6989e5168605ddd2f68905dadb24",
          "status": "SUSPICIOUS",
          "threat_level": 1,
          "threat_name": "Win32.Malware.Generic"
        },
        {
          "sha1": "562527985fa902f778f824951d0d4958ed6447ba",
          "md5": "b918da6cd16de67e2ff4e5029fc5e416",
          "sha256": "4f0d0a1e96e0a3755ed7f6d73083d846176d3b338740e62854fcfaee404e6d77",
          "status": "KNOWN",
          "trust_factor": 0
        }
      ],
      "next_hash": "64ac2597da314420792b42e81b67f377fc083c91"
    }
  }
}
```
