File analysis (goodware) (TCA-0105)

This service provides sample hashes, trust factor, relationships, size, and sources for goodware samples only. If a malicious hash is queried, a 404 (Not Found) HTTP response will be returned. The service supports single or bulk queries against the ReversingLabs file reputation database.

The exact differences between the TCA-0104 - File Analysis and TCA-0105 - File Analysis (Non-Malicious) services are outlined in the table below.

Field	TCA-0104	TCA-0105
hashes	Yes	Yes, except imphash
sample_size	Yes	Yes
trust_factor	No	Yes
AV scanner information	Yes	No
sources	Yes	Yes
relationships	Yes	Yes
Spectra Core analysis	Yes	No
dynamic_analysis	Yes	No

This API is rate limited to 100 requests per second.

General Info about Requests/Responses

• All requests support the format query field which supports two options: xml or json.
• Default response format is xml, except for bulk queries, where default format is the same as the post_format
• All bulk query rules will accept POST payload of the same format (described below).
• The number of hashes in a bulk request must not be larger than a hundred (100).
• POST requests must set the Content-Type: application/octet-stream field in the HTTP header

Single File Analysis

This query returns a response containing all public knowledge about the given sample identified by hash. The response will contain information such as sample sources, AV scanning information etc.

GET /api/databrowser/rldata/goodware/query/{hash_type}/{hash_value}

• hash_type accepts these options: md5, sha1, sha256
• hash_value must be a valid hash defined by the hash_type parameter

Response format

{
  "rl": {
    "sample": {
      "sha1": "string",
      "crc32": "string",
      "md5": "string",
      "sha256": "string",
      "sha384": "string",
      "sha512": "string",
      "pe_sha1": "string",
      "pe_sha256": "string",
      "ssdeep": "string",
      "tlsh": "string",
      "sample_size": 0,
      "trust_factor": 0,
      "relationships": {
        "container_sample_sha1": [
          "string"
        ],
        "parent_sample_sha1": [
          "string"
        ]
      },
      "sources": {
        "entries": [
          {
            "record_time": "string",
            "tag": "string",
            "properties": [],
            "domain": {
              "name": "string"
            }
          }
        ]
      }
    }
  }
}

• sha1
  • SHA1 value of the requested sample. This field is mandatory and can be used as a primary key.
• hashes
  • List of hashes computed for the requested sample, e.g. MD5, SHA256, SHA384, SHA512, Authenticode hashes (PE_SHA1, PE_SHA256), SSDEEP...
• tlsh
  • A hash value which can be used for file similarity comparisons, helping to identify similar, nearly identical, or modified files. TLSH hash is not calculated if SSDEEP is enabled and the file size is either smaller than its minimum size (1024 bytes) or larger than its maximum size (734003200 bytes).
• relationships
  • Parent and container sample lists.
• sources
  • A sequence of source items indicating where the sample came from. These can be different domains, specific uploaders, etc. One sample can have multiple sources. The service returns a list of 10 oldest sources, sorted by timestamp in descending order.

Response code 404 is returned with a message "Requested data was not found" when the requested hash isn't found in the database, or is not goodware.

---

rl.sample.relationships

• container_sample_sha1
  • List of container hashes. Container is the top-level archive/sample that was uploaded to the system and also contains the requested sample. The response will contain up to 5 container sample hashes, sorted by MD5 hash.
• parent_sample_sha1
  • List of samples that directly contain the requested sample. The requested hash is a child to the hashes in this list. The list of children has been acquired by file extraction. The response will contain up to 5 parent sample hashes, sorted by MD5 hash.

Bulk File Analysis

This query retrieves the same data as the single query, but for multiple hashes within a single response. It is more network-efficient compared to several consecutive single queries.

POST /api/databrowser/rldata/goodware/bulk_query/{post_format}

• post_format is a required parameter that defines the POST payload format. Supported formats are xml and json

Request POST format

The following definitions are valid for both formats:

• hash_type value must be one of the following options: md5, sha1, sha256
• hash_value must be a valid hash defined by hash_type

{
  "rl": {
    "query": {
      "hash_type": "string",
      "hashes": [
        "string",
        "string",
        "string"
      ]
    }
  }
}

Response format

{
  "rl": {
    "entries": [
      {}
    ],
    "invalid_hashes": [
      "string"
    ],
    "unknown_hashes": [
      "string"
    ]
  }
}

• item in entries are equivalent to the rl.sample element from the single query
• invalid_hashes: A list of ill-formatted hashes provided in request
• unknown_hashes: A list of hashes from the request that were not found in the database or are not goodware

Examples

Format Query Field - changing the response format

/api/databrowser/rldata/goodware/query/sha1/a25b6db2d363eaa31de348399aedc5651280b52b?format=json
/api/databrowser/rldata/goodware/query/sha1/a25b6db2d363eaa31de348399aedc5651280b52b?format=xml

Single query - changing the hash type

/api/databrowser/rldata/goodware/query/sha1/a25b6db2d363eaa31de348399aedc5651280b52b
/api/databrowser/rldata/goodware/query/sha256/10dbb2b27208c5566d326b47950657bf6b3c9a59e302598a128ad7125d5fb4fd

Bulk query - changing the POST format

/api/databrowser/rldata/goodware/bulk_query/xml
/api/databrowser/rldata/goodware/bulk_query/json

Bulk query - JSON POST format

/api/databrowser/rldata/goodware/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"
    }
  }
}