# Certificate Report API (TCA-0501) — Spectra Intelligence

> Submit a certificate thumbprint to TCA-0501 and receive a list of signed samples with reputation data, metadata, classification, and download availability.

# 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

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.

<Button title="View OpenAPI Specification" href="/SpectraIntelligence/API-reference/#tag/certificate-threat-intelligence/get/apicertificateindexv1querythumbprintthumbprint" />

### 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

```json
{
  "rl": {
    "next_page": "string",
    "request": {
      "extended": 0,
      "limit": 3,
      "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[]`

```json
{
  "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`
  - The last time when the sample received impactful changes that updated its threat intelligence report. (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
```
