Skip to main content
Version: T1000 3.1.0

File reputation (TCA-0101)

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 (goodware, confirmed to be non-malicious), or unknown.

The service supports single and bulk queries. Set the extended parameter to get more data about a sample, such as its trust factor, threat level, and malware family. Set the show_hashes parameter to get the MD5, SHA1, and SHA256 hashes of a sample.

This API is rate limited to 500 requests per second. If you go over the rate limit, or if you reach your daily or monthly quota, the service returns HTTP status code 429. See Response status codes.

Common use cases​

The service looks up the hash in Spectra Intelligence and returns what the system knows about that file. It doesn't analyze the file, and it doesn't execute it.

If Spectra Intelligence has no record of a hash, upload the sample with the File upload (TCA-0202/0203) API. If the antivirus results for a sample are old, request a new scan with the Reanalyze file (TCA-0205) API.

  • Fast malware triage. One lookup returns the classification status. Add extended=true to also get the threat level, the trust factor, the malware family, and the reason for the verdict. This data is usually sufficient to decide if a file needs an analyst.
  • Bulk hash checking. A bulk query takes up to 100 hashes per request, so you can check a long list without sending one request per hash. Such a list can come from an endpoint export, a phishing campaign, or a software inventory. Use query_hash to match each result to your input. Do not use the order of the entries.
  • Enrichment. The reputation fields add context to alerts and indicator records in a SIEM, SOAR, or ticketing system. Use first_seen and last_seen to find how long the system has known the file. Use threat_name and classification for the family labels. Use reason for the basis of the verdict.

Be careful with the UNKNOWN status in all three of these use cases. UNKNOWN means that Spectra Intelligence has no classification for the file. It does not mean that the file is safe. See Sample with malware presence status UNKNOWN.

A classification is not permanent. When more information becomes available, Spectra Intelligence can change a suspicious sample to malicious or to known. An unknown hash also gets a classification after the sample comes into Spectra Intelligence, so a stored verdict can become incorrect.

Query the hashes that are important to you again, and use last_seen to find when the data of the sample last changed. For more information, see Deciding sample priority and Analysis rescans.

The file reputation data is not always sufficient. For the per-scanner detail behind the scanner_* fields, use Multi-AV scan records (TCA-0103). For static and dynamic analysis data, extracted files, and network indicators, use File analysis (TCA-0104).

General information about requests and responses​

  • The service is available at https://data.reversinglabs.com and uses HTTP Basic authentication. See Getting started for credentials and your first request.
  • All requests support the format parameter. It has two options: xml and json.
  • The default response format is xml. For bulk queries, the default response format is the same as the post_format.
  • A bulk request must not contain more than 100 hashes. A request that contains more than 100 hashes returns HTTP status code 413.
  • POST requests must contain an HTTP header field Content-Type: application/octet-stream
  • For the full list of response codes, see Response status codes.

Malware presence​

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

View OpenAPI Specification

Request​

GET /api/databrowser/malware_presence/query/{hash_type}/{hash_value}
  • hash_type
    • Specifies the hash type that the request uses. Supported values: md5, sha1, sha256
    • Required
  • hash_value
    • The hash of the file that you request data for. The value must be a valid hash of the type that the hash_type parameter specifies.
    • Required

Response​

{
  "rl": {
    "malware_presence": {
      "status": "KNOWN",
      "query_hash": {
        "sha1|md5|sha256": "hash_value"
      }
    }
  }
}
  • status
    • Malware presence status designation (UNKNOWN, KNOWN, SUSPICIOUS, or MALICIOUS). KNOWN means the sample is classified as non-malicious (goodware). Read more about the ReversingLabs classification algorithm.
  • query_hash
    • The hash type and value used in the request. Can be md5, sha1, or sha256

Malware presence bulk​

A bulk query returns one response for multiple hashes. Each entry has the same format as the response of a single query. The response can also contain a field for the hashes that have an incorrect format. One request can contain a maximum of 100 hashes.

The service does not return the hashes that it cannot find in a separate field. It returns them in rl.entries with the status UNKNOWN, the same as all other requested hashes.

View OpenAPI Specification

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​

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

Response​

{
  "rl": {
    "entries": [
      {
        "status": "UNKNOWN",
        "query_hash": {
          "sha1|md5|sha256": "hash_value"
        }
      }
    ],
    "invalid_hashes": [
      "hash_value"
    ]
  }
}
  • entries
    • One entry per requested hash that the service accepted. Items in rl.entries are equivalent to the rl.malware_presence element in the single query response.
    • With extended=true, the entries don't all have the same shape. An entry for a classified sample carries the full extended field set, and an entry for an UNKNOWN hash carries only status and query_hash.
  • invalid_hashes
    • A list of the hashes in the request that have an incorrect format. This includes hashes with an incorrect length and hashes that contain characters that are not hexadecimal.
    • The service omits this field when every hash in the request is well formed. It doesn't return an empty list, so read the field defensively.

Every hash you submit is returned in exactly one of rl.entries or rl.invalid_hashes, so the two lists together account for the whole request.

The service does not return the entries in the order of the hashes in your request. No order is guaranteed. Use query_hash to match each entry to the hash that you requested. If you match the entries by their position in the array, you get the results for the wrong hashes.

Extended malware presence​

Single and bulk queries support the optional query parameter extended. This parameter controls if the response contains the extended classification data for a sample.

Set the parameter to true to get the extended data, or to false to get only the basic data. The default is false.

The extended data includes the trust factor, the threat level, the malware type, the family name, the platform, and the first seen and last seen times.

The response can also give the classification reason for a sample in the optional reason field. The service returns this field only when your request contains the extended parameter. The service calculates this field for some samples only.

The classification reason shows you why a sample has its status. This is most useful for goodware overrides. A goodware override is a whitelist technique that prevents false positives in software packages that have a high level of trust.

If a sample has a valid and trusted certificate, or if it comes from a trusted source, Spectra Intelligence whitelists the sample and all its extracted files. The antivirus results don't change this decision, so a sample with many antivirus detections can still have the KNOWN status. For more information, see Goodware overrides.

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.

{
  "rl": {
    "malware_presence": {
      "status": "MALICIOUS",
      "query_hash": {
        "sha1": "1b6bdd9c100b62514610cb6297ffcd1fd32a2c7c"
      },
      "first_seen": "2020-03-10T20:59:25",
      "last_seen": "2026-09-08T15:22:59",
      "reason": "antivirus",
      "trust_factor": 5,
      "threat_level": 3,
      "scanner_count": 36,
      "scanner_match": 25,
      "scanner_percent": 69.44444274902344,
      "threat_name": "Document-Office.Downloader.Powdow",
      "classification": {
        "is_generic": false,
        "platform": "Document",
        "subplatform": "Office",
        "family_name": "Powdow",
        "type": "Downloader"
      }
    }
  }
}

Not every field appears in every response:

  • status and query_hash are always returned.
  • classification and threat_name are returned for samples classified as SUSPICIOUS or MALICIOUS.
  • reason is returned only if it is calculated for the sample.
  • md5, sha1, and sha256 are returned only with the show_hashes parameter.

Field descriptions:

  • status
    • Malware presence status designation (UNKNOWN, KNOWN, SUSPICIOUS, or MALICIOUS). KNOWN means that the sample is non-malicious (goodware). A proprietary ReversingLabs algorithm calculates the status. The algorithm adapts and improves when new information about the file and the threat becomes available.
  • query_hash
    • The hash value that the request uses. It can be md5, sha1, or sha256.
  • reason
    • An optional field that gives the reason for the classification status of a sample. Spectra Intelligence doesn't calculate this field for all samples, so the response doesn't always contain it.
    • The value is one of the following:
    • Overrides. These are two different values. The first records the decision of a user, the second the decision of a ReversingLabs analyst.
      • user_sample_override - a user override classified the sample.
      • analyst_sample_override - an analyst classified the sample manually after an analysis.
    • Trusted source, certificate, or signature.
      • best_source - you can get the sample from a trusted source, or the service unpacked the sample from a file that comes from a trusted source.
      • best_certificate - the sample or its container is signed with a valid and trusted certificate.
      • TC_certificate - the sample is signed with a recognized whitelisted certificate.
      • TC_signature - a Spectra Core whitelisted signature matched the sample.
    • Detection.
      • antivirus - the ReversingLabs multi-scan algorithm classified the sample from the aggregated antivirus scan results.
      • next_gen_av - the service classified the sample from the aggregated next-gen antivirus scan results.
    • Legacy.
      • sandbox (deprecated) - the ReversingLabs Cloud Sandbox classified the sample. The service returns this value only for the samples that got this reason before the value became deprecated. For dynamic analysis, use Dynamic analysis submission (TCA-0207).
    • The next_gen_av reason does not mean that the traditional antivirus scanners found nothing. It means that the next-gen antivirus results decided the classification. The response can also contain detections from traditional scanners.
  • classification
    • An object that contains the malware classification of the sample. The ReversingLabs algorithm calculates it from the most recent analysis. The service returns this object for the samples with the SUSPICIOUS or MALICIOUS status. For its fields, see Classification object.
  • threat_name
    • The detected threat name of the requested sample. The service returns it for the samples with the SUSPICIOUS or MALICIOUS status.
    • The service composes the name from the classification fields in this format: platform-subplatform.type.family_name. The subplatform and its hyphen are present only if the sample has a subplatform. For example, Document-Office.Downloader.Powdow has a subplatform, but Win64.Malware.Heuristic does not. The ReversingLabs malware naming standard defines the parts of the name.
  • threat_level
    • The severity value of the requested sample, from 0 to 5. This value is applicable to the samples with the SUSPICIOUS or MALICIOUS status. For the samples with the KNOWN status, read trust_factor.
    • For malicious samples, 1 is the lowest severity (such as adware) and 5 is the highest (such as trojans).
    • Do not interpret 0 as the absence of a threat. On a suspicious sample, 0 means that the classification is provisional and that Spectra Intelligence needs more information about the sample. The risk score table shows how the threat level maps to the risk score for each classification.
  • trust_factor
    • The trust factor value of the sources of the sample, from 0 (most trusted) to 5 (least trusted). This value is applicable to the samples with the KNOWN status. For the samples with the SUSPICIOUS or MALICIOUS status, read threat_level.
    • All values in the range occur. A value of 0 shows a domain or a certificate with a high level of trust. A value of 5 shows a source with a low level of trust and no whitelisted certificates.
  • scanner_count
    • The number of scanners in the last scan
  • scanner_match
    • The number of scanners that detected malware in the last scan
  • scanner_percent
    • The percent of scanners that detected malware in the last scan, as a floating-point number
  • first_seen
    • The date and time when the sample first came into the system, or when the sample first got a scan result. The timestamp uses the ISO 8601 format and has no UTC offset.
  • last_seen
    • The date and time of the last important change to the analysis data or the classification data of the sample. The timestamp uses the ISO 8601 format and has no UTC offset.

An extended response for a classified sample contains both threat_level and trust_factor, whatever its status. Read the value that agrees with the classification, as the field descriptions above show. A sample with the UNKNOWN status has neither field, because Spectra Intelligence holds no data to report. Threat level and trust factor explains how the two scales relate to the risk score.

The scanner_count, scanner_match, and scanner_percent fields describe the last scan. The response does not give the time of that scan. The last_seen field records the last important change to the data of the sample, which is a different thing. If you must know when the service measured these values, record the time of your query with them.

Classification object​

{
  "classification": {
    "platform": "Document",
    "subplatform": "Office",
    "type": "Downloader",
    "family_name": "Powdow",
    "is_generic": false,
    "cve": {
      "is_candidate": false,
      "number": "0001",
      "year": "2024"
    }
  }
}
  • platform
  • subplatform
    • The subplatform that the detected malware attacks. It is one of the subplatforms that the ReversingLabs malware naming standard defines. The service omits this field if the platform of the sample has no subplatform.
  • type
  • family_name
    • The family name of the detected malware
  • is_generic
    • Some trusted third-party antivirus scanners give a threat name that their naming convention shows to be a generic detection or a heuristic detection. Such a detection means that the sample has characteristics similar to known malicious software, but that the scanner did not identify a specific threat. If the scanners detect the malware in this way, this field returns true.
  • cve
    • Contains the Common Vulnerabilities and Exposures (CVE) data of the sample, if such data is applicable. It has these fields:
      • is_candidate - returns true if the sample is a CVE candidate, or false if the sample is an official CVE list entry
      • number - the CVE number
      • year - the CVE year

Response examples​

Sample with malware presence status MALICIOUS​

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

{
  "rl": {
    "malware_presence": {
      "status": "SUSPICIOUS",
      "query_hash": {
        "sha1": "67181c15b4e080d7c16ae93911c50d4db868e128"
      },
      "first_seen": "2026-09-09T09:37:49",
      "last_seen": "2026-09-09T09:42:40",
      "reason": "antivirus",
      "trust_factor": 5,
      "threat_level": 5,
      "scanner_count": 38,
      "scanner_match": 18,
      "scanner_percent": 47.3684196472168,
      "threat_name": "Win64.Trojan.Generic",
      "classification": {
        "is_generic": true,
        "platform": "Win64",
        "family_name": "Generic",
        "type": "Trojan"
      }
    }
  }
}

A suspicious sample has the classification and threat_name fields, the same as a malicious sample. In this response, is_generic is true and the family name is Generic. This is because the scanners identified the sample heuristically and not as a specific named threat. The platform has no subplatform, so the threat_name has none either.

Sample with malware presence status KNOWN, classified by a goodware override​

In this response, 19 of 25 scanners detected malware, but the sample has the KNOWN status. The reason field gives the explanation: the sample is signed with a recognized whitelisted certificate. This certificate overrides the antivirus results. This is the goodware override that Extended malware presence describes.

{
  "rl": {
    "malware_presence": {
      "status": "KNOWN",
      "reason": "TC_certificate",
      "scanner_count": 25,
      "scanner_percent": 76.0,
      "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 KNOWN, classified by antivirus results​

Not all KNOWN classifications are overrides. In this response, no scanner detected malware, so the antivirus reason records a clean multi-scan result and not a whitelist decision. The classification and threat_name fields are absent, as they are for all samples that are not malicious and not suspicious.

{
  "rl": {
    "malware_presence": {
      "status": "KNOWN",
      "query_hash": {
        "sha1": "ff7ee4e538586794576f8650d27d60c3c8f8cec2"
      },
      "first_seen": "2026-04-03T11:45:00",
      "last_seen": "2026-09-08T10:33:56",
      "reason": "antivirus",
      "trust_factor": 2,
      "threat_level": 0,
      "scanner_count": 36,
      "scanner_match": 0,
      "scanner_percent": 0.0
    }
  }
}

Sample with malware presence status UNKNOWN​

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

UNKNOWN means that Spectra Intelligence has no classification data for the hash. It does not mean that the file is safe. Do not use this status as a verdict when you decide to permit a file. To get a classification, upload the sample with the File upload (TCA-0202/0203) API. To find what other data exists for the hash, use File analysis (TCA-0104).

Malware presence with available hashes​

Single and bulk queries support the optional show_hashes parameter. You can use it together with the extended parameter in the same request.

If you set show_hashes to true, the response gives the MD5, SHA1, and SHA256 hashes of the sample with the other malware presence data. The default is false.

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​

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

If you set both the extended and the show_hashes parameters to true, the response contains the extended malware presence data and the MD5, SHA1, and SHA256 hashes.

{
  "rl": {
    "malware_presence": {
      "status": "KNOWN",
      "query_hash": {
        "sha1|md5|sha256": "hash_value"
      },
      "md5": "md5 hash_value",
      "sha1": "sha1 hash_value",
      "sha256": "sha256 hash_value"
    }
  }
}
  • md5, sha1, sha256
    • The respective hashes of the requested sample.

For status and query_hash, see the field descriptions in the extended response section.

Examples​

Runnable requests with authentication, in curl and Python, are available in the OpenAPI reference for both the single and bulk operations.

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

For bulk queries, the response format is the same as the request format. To get 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
{
  "rl": {
    "query": {
      "hash_type": "md5",
      "hashes": [
        "4bb64c06b1a72539e6d3476891daf17b",
        "6353de8f339b7dcc6b25356f5fbffa4e",
        "59cb087c4c3d251474ded9e156964d5d",
        "6c2eb9d1a094d362bcc7631f2551f5a4",
        "a82c781ce0f43d06c28fe5fc8ebb1ca9",
        "920f5ba4d08f251541c5419ea5fb3fb3"
      ]
    }
  }
}
{
  "rl": {
    "query": {
      "hash_type": "sha1",
      "hashes": [
        "13e40f38427a55952359bfc5f52b5841ce1b46ba",
        "831fc2b9075b0a490adf15d2c5452e01e6feaa17",
        "42b05278a6f2ee006072af8830c103eab2ce045f"
      ]
    }
  }
}
{
  "rl": {
    "query": {
      "hashes": [
        "0001f757f6b9523707462066100aa543",
        "000202ed4a0fb4c95e68824bc7777a78",
        "00026f63fd5a2600b73a866d7ef08b6f"
      ],
      "hash_type": "md5"
    }
  }
}

See also​