Certificate index (TCA-0501)

This service provides a list of samples signed with a particular certificate, specified by its thumbprint.

Samples are listed along with their reputation information and some other properties such as sample size, sample type, download availability, and more. The service also allows filtering the results by sample classification status.

Certificate Query

Retrieve certificate information

This query returns a list of SHA1 hashes for samples signed with the certificate matching the requested thumbprint.

If the extended option is selected, the list of samples will include:

reputation information - classification, threat level, trust factor, malware family name, threat name, malware type, targeted platform and subplatform;

SHA1, MD5, and SHA256 hashes;

sample size, sample type, download availability, first and last seen dates (UTC), as well as the hashes of files containing the sample(s);

certificate validation

The response can be filtered by sample classification status.

Request

GET /api/certificate/index/v1/query/thumbprint/{thumbprint}/page/{next_page}?[format=xml|json]&[classification=MALICIOUS|SUSPICIOUS|KNOWN|UNKNOWN]&[limit={1-100}]&[extended=true|false]

Path parameters:

thumbprint
- The thumbprint (sha1, sha256, md5) of the requested certificate
- Required
next_page
- An optional pagination parameter for retrieving the next page of the results. The pagination value for the next page is provided in the previous request response
- Optional

Query parameters:

format
- Allows choosing between xml (default) and json format for the response
limit
- Maximum number of samples to return in the certificate sample list. It is possible to choose a number between 1 and 100 (100 is the default value)
extended
- Allows choosing between true - extended, and false - non-extended data set (default)
classification
- If this parameter is provided in the request, the query will return a list of only those samples that match the requested classification. Supported values are: KNOWN, SUSPICIOUS, MALICIOUS, UNKNOWN

Response

{
  "rl": {
    "next_page": "string",
    "request": {
      "extended": 0,
      "limit": "string",
      "response_format": "string",
      "thumbprint": "string"
    },
    "samples": {
      "item": [
        "string",
        "string",
        "string"
      ]
    }
  }
}

The query will return a list of limit samples signed with the certificate that matches the requested thumbprint. If the limit value is not provided in the request, 100 records will be returned by default.

Response fields that will be returned depend on the selected data set. If the extended parameter is not set to true, only the list of sample SHA1 hashes will be returned. The next_page response field contains the hash value for the next page. This can be used with the next_page parameter in the following request to retrieve more samples.

rl.request

thumbprint
- Requested thumbprint
limit
- Number of requested samples
response_format
- Output format
extended
- Return extended info for samples instead of just hashes
page
- Page (only if the page is a part of the request)
classification
- Classification (only if classification is a part of the request)

rl.samples[]

{
  "container_sha1": "string",
  "sha1": "string",
  "pe_sha1": "string",
  "threat_level": 0,
  "classification": "string",
  "threat_name": "string",
  "sample_type": "string",
  "validation": [
    "string"
  ],
  "sample_size": 0,
  "sample_available": 0,
  "platform": "string",
  "last_seen": "string",
  "malware_type": "string",
  "first_seen": "string",
  "sha256": "string",
  "pe_sha256": "string",
  "trust_factor": 0,
  "malware_family": "string",
  "md5": "string"
}

sha1
- SHA1
sha256
- SHA256
md5
- MD5
pe_sha1
- SHA1 authentihash of the PE file used in the authenticode signing process
pe_sha256
- SHA256 authentihash of the PE file used in the authenticode signing process
container_sha1
- SHA1 of the sample container
first_seen
- time when the sample was first seen (UTC)
last_seen
- time when the sample was last seen (UTC)
sample_type
- sample type
sample_size
- sample size
sample_available
- whether the sample is available for download
classification
- classification of the sample
platform
- platform targeted by the malware
subplatform
- subplatform targeted by the malware
threat_name
- threat name for malicious samples
malware_type
- malware type for malicious samples
malware_family
- malware family for malicious samples
threat_level
- threat level of the sample
trust_factor
- trust factor of the sample
validation
- list of validation descriptions for a certificate regarding a sample at the time the sample was detected

Examples

Example 1

Retrieving a SHA1 list of 2 samples signed with a certificate with SHA256 thumbprint 86900D438047F6D00ACE379C6E68A9461BA36ACD152C9E82EDDBE87B331F3E4A.

/api/certificate/index/v1/query/thumbprint/86900D438047F6D00ACE379C6E68A9461BA36ACD152C9E82EDDBE87B331F3E4A?limit=2

Example 2

Retrieving a SHA1 list of samples signed with a certificate matching the requested SHA1 thumbprint e1230631000216e59c20ed0e18f8f752b8489bb5.

/api/certificate/index/v1/query/thumbprint/e1230631000216e59c20ed0e18f8f752b8489bb5?limit=2

Example 3

Retrieving a list of 2 samples, with an extended data set in JSON format, signed with a certificate with the SHA256 thumbprint 709df96feede2cab2a5fb803beb599571d18a1d4.

/api/certificate/index/v1/query/thumbprint/709df96feede2cab2a5fb803beb599571d18a1d4?limit=2&extended=true&format=json

Example 4

Retrieving one sample with an extended data set in JSON format, signed with a certificate with the SHA256 thumbprint 86900D438047F6D00ACE379C6E68A9461BA36ACD152C9E82EDDBE87B331F3E4A and MALICIOUS classification.

/api/certificate/index/v1/query/thumbprint/86900D438047F6D00ACE379C6E68A9461BA36ACD152C9E82EDDBE87B331F3E4A?limit=2&extended=true&format=json&classification=malicious

Certificate Query​

Retrieve certificate information​

Request​

Response​

Examples​

Example 1​

Example 2​

Example 3​

Example 4​