Skip to main content

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