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 Single Query
This query returns information about the malware status of the requested sample.
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
- Specifies which hash type will be used in the request. Supported values:
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
- 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
Response Format
{
"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.
query_hash
- The hash type and value used in the request. Can be
md5
,sha1
, orsha256
- The hash type and value used in the request. Can be
Malware Presence Bulk Query
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.
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
Request Format
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
{
"rl": {
"query": {
"hash_type": "hash_type",
"hashes": [
"hash_value",
"hash_value",
"...",
"hash_value"
]
}
}
}
Response Format
{
"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 Query Option
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