Skip to main content

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 Request​

This query allows classification overrides for one or more sample hashes. Up to 100 hashes can be submitted in one 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 Format​

Request body:

{
  "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 Format​

{
  "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 Query​

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

Request Format​

GET /api/databrowser/malware_presence/user_override/list_hashes/{hash_type}?start_hash=9865c7ecda437034e1513cc43ae9a1f6f334bb7f&format=json|xml
  • 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

Response Format​

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

rl.user_override.hash_values is an array of hashes specified by the hash_type. Hashes in the response are sorted. The response contains up to 1000 hashes. 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.