File analysis (goodware)

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",
      "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...
• 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"
    }
  }
}