Report Summary API

Retrieve a summary analysis report for local samples

POST /api/samples/v2/list/

Get a summary of the analysis report for a single sample or for multiple samples. The samples must be present on the Spectra Analyze appliance. Sample hashes must be provided using the hash_values parameter in the request.

If the optional fields parameter is not included in the request, all available report fields for the requested sample(s) are returned in the response. The fields “ticore”, “ticloud”, “summary” and “aliases” are returned only if they are explicitly specified in the request.

Request Format

Request Parameters

NAME	REQUIRED	DESCRIPTION	TYPE
hash_values	Required	One or more hashes of samples for which the analysis report should be returned. The samples must be present on the appliance. Supported hash types are SHA1, SHA256, SHA512, MD5. All hashes in a request must be of the same type.	array
fields	Optional	Comma-separated list of report fields to include in the response. When this parameter is not included in the request, all available fields are returned, except “ticore”, “ticloud”, “summary” and “aliases”. Supported values: id, sha1, sha256, sha512, md5, category, file_type, file_subtype, identification_name, identification_version, file_size, extracted_file_count, local_first_seen, local_last_seen, classification_origin, classification_reason, classification_source, classification, riskscore, classification_result, ticore, tags, summary, ticloud, aliases, networkthreatintelligence, domainthreatintelligence, imphash, discussion, proposed_filename, av_scanners, av_scanners_summary Network and domain threat intelligence results won’t be applied unless the parameter include_networkthreatintelligence is set to true.	array
include_networkthreatintelligence	Optional	Include or exclude network or domain threat intelligence. If this is set to true, parameters networkthreatintelligence and domainthreatintelligence have to be included in the fields parameter. Applies only to URLs, not files.	boolean (but inside quotes)
skip_reanalysis	Optional	Whether to reanalyze a file when fetching its report. False by default (if omitted, files will be reanalyzed when their reports are fetched).	boolean (but inside quotes)

Request Examples

cURL

# Add --insecure before the URL if you are using a self-signed SSL certificate
curl -X POST 'https://appliance.example.com/api/samples/v2/list/' \
  --header 'Authorization: Token exampletoken' \
  --header 'Content-Type: application/json' \
  --data '{"hash_values":["9dc5e23c7ab2692b83f0690a736b123a1837ae56", "4b21a49eadac1bc01477eff778041fdb765b8139"]}'

cURL with optional parameters

# Add --insecure before the URL if you are using a self-signed SSL certificate
curl -X POST 'https://a1000.example.com/api/samples/v2/list/' \
  --header 'Authorization: Token exampletoken' \
  --header 'Content-Type: application/json' \
  --data '{"hash_values":["0da28a5159bee9cd930403023230f2e918b0334d"], "fields": ["summary"]}'

Python

import requests

# Change the token
token = "exampletoken"
# Change the hostname in the URL
url = f"https://appliance.example.com/api/samples/v2/list/"

json = {
        "hash_values": ["examplehash1", "examplehash2"],
        "fields": ["sha256", "extracted_file_count"]
}

headers = {'Authorization': f'Token {token}'}

# Add verify=False in the request if you are using a self-signed SSL certificate
response = requests.post(url, headers=headers, json=json)
print(response.text)

Response Format

Response Examples

Default response - all available fields

{
   "count": 1,
   "next": null,
   "previous": null,
   "results": [
      {
            "id": 215590,
            "sha1": "3ecb56536b58d2e2ec0779d1c28a9f20024d6b66",
            "sha256": "eac444d6cddbae6972f0af91da5a89b0eb370c2f7bbe6f9706aaaf1f25f6c0d3",
            "sha512": "5586169dc50e339789b75f469e3 (...)",
            "md5": "6cadcefb80b7e757323aa46fba909d72",
            "imphash": "9612c82b4c865e0bf6797463aa91292a",
            "category": "application",
            "file_type": "PE",
            "file_subtype": "Exe",
            "identification_name": "UPX",
            "identification_version": "0.60-3.x",
            "file_size": 350720,
            "extracted_file_count": 9,
            "local_first_seen": "2017-02-06T18:10:54.594306Z",
            "local_last_seen": "2020-02-27T11:37:37.954472Z",
            "classification_origin": {
               "sha1": "8d0cbc4f10b2aa40f849bda9ee2524146870cc7a",
               "sha256": "cc8698fac45061e5bb1a2cc712d25c5ed5977f3b5b5cc55978562df942777815",
               "sha512": "96bf5eba3dfd04a5bccaeb45 (...)",
               "md5": "cf87a4c0f97ef995221650b4c8116e04",
               "imphash": "fe93401dae4bdb92076a6adf424ffc73"
            },
            "classification_reason": "cloud",
            "classification": "malicious",
            "riskscore": 8,
            "classification_result": "Win32.Backdoor.Prorat",
            "tags": {
               "ticore": [
                  "yara",
                  "indicator-network",
                  "string-http",
                  "capability-execution",
                  "capability-filesystem",
                  "capability-networking",
                  "desktop",
                  "indicator-execution",
                  "indicator-monitor",
                  "arch-x86",
                  "gui",
                  "packed",
                  "entropy-high",
                  "contains-pe",
                  "file-download",
                  "privacy-intrusion",
                  "ftp-use",
                  "compression-nrv",
                  "cloud"
               ],
               "user": [
                  "RSA2016",
                  "testtag1"
               ]
            }
      }
   ]
}

Response for the optional summary field

{
   "count": 1,
   "next": null,
   "previous": null,
   "results": [
      {
         "summary": {
            "id": 215600,
            "sha1": "0da28a5159bee9cd930403023230f2e918b0334d",
            "indicators": [
               {
                     "priority": 7,
                     "category": 22,
                     "description": "Deletes files in Windows system directories."
               },
               {
                     "priority": 7,
                     "category": 11,
                     "description": "Requests permission required to shut down a system."
               }
            ],
            "unpacking_status": {
               "failed": 0,
               "success": 1,
               "partial": 0
            }
         }
      }
   ]
}

Response Fields

FIELD NAME	TYPE
id	integer
sha1	string
sha256	string
md5	string
category	string
file_type	string
file_subtype	string
identification_name	string
identification_version	string
file_size	integer
extracted_file_count	integer
local_first_seen	string
local_last_seen	string
classification_origin	object
classification_reason	string
classification	string
riskscore	integer
classification_result	string
tags	array
aliases	array
summary	Summary object
ticore	corresponds to the ticore object from the Spectra Core Report API
ticloud	Cloud object
imphash	string
classification_source	integer
discussion	array
proposed_filename	string
networkthreatintelligence	object
domainthreatintelligence	object
av_scanners	object
av_scanners_summary	object

FIELD NAME	DATA TYPE
sha1	string
sha256	string
sha512	string
md5	string
imphash	string

FIELD NAME	DATA TYPE
id	integer (sample id)
sha1	string
indicators	array
unpacking_status	string

FIELD NAME	DATA TYPE
classification	string
riskscore	integer
classification_result	string
classification_reason	string
first_seen	string
last_seen	string

Response Status Codes

CODE	DESCRIPTION
200	Returned on successful requests.
400	Malformed hash or invalid field name.
403	Authentication credentials were not provided. / Invalid token.
404	Malformed endpoint.