Full Report API
Retrieve a detailed analysis report for local samples
POST /api/samples/v2/list/details/
Retrieve all or selected parts of the analysis report - including static, dynamic, and cloud analysis results - for one or more samples in a single request, instead of having to send requests to multiple endpoints. Report parts that can be requested correspond to sidebar sections on the Sample Details page.
Sample hashes must be provided using the hash_values
parameter in the request. The samples must be present on the Spectra Analyze appliance. Response speeds are highly variable based on the information available for each requested file.
The optional fields
parameter can be included in the request to specify which parts of the report should be returned in the response. When this parameter is not provided in the request, all available report fields for the requested sample(s) are returned in the response.
If no data is available for a requested field, it is included in the response as an empty field.
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 additional report fields to include in the response. The default response contains this set of default fields:rl_auxiliary_analysis, av_scanners, av_scanners_summary, cape, cisco_secure_malware_analytics, cuckoo, discussion, joe, fireeye, rl_cloud_sandbox, sources, sample_summary, ticore, tags, ticloud, vmray_tcbase Additional 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, discussion, ticloud, aliases, proposed_filename, networkthreatintelligence, domainthreatintelligence, 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/details/' \
--header 'Authorization: Token exampletoken' \
--header 'Content-Type: application/json' \
--data '{"hash_values":["6cadcefb80b7e757323aa46fba909d72"], "fields": ["classification_result", "sources", "av_scanners_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/details/"
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
{
"count": 1,
"next": null,
"previous": null,
"results": [
{
"av_scanners_summary": {
"scanner_count": 38,
"scanner_match": 36,
"scanner_percent": 94.73684210526315
},
"sources": {
"ticloud_sources": { },
"other_sources": []
},
"classification_result": "Win32.Backdoor.Prorat"
}
]
}
Response Fields
FIELD NAME | DESCRIPTION |
---|---|
ticore | Corresponds to the ticore object from the Spectra Core Report API |
ticloud | Corresponds to the cloud object from the Summary Report API |
rl_cloud_sandbox | Contains dynamic analysis results from ReversingLabs Cloud Sandbox according to the integration configuration on the appliance |
rl_auxiliary_analysis | Contains dynamic analysis results from the RL Auxiliary Analysis service |
joe | Contains dynamic analysis results from Joe Sandbox according to the integration configuration on the appliance |
cisco_secure_malware_analytics | Contains dynamic analysis results from Cisco Secure Malware Analytics according to the integration configuration on the appliance |
cuckoo | Contains dynamic analysis results from Cuckoo according to the integration configuration on the appliance |
fireeye | Contains dynamic analysis results from FireEye according to the integration configuration on the appliance |
cape | Contains dynamic analysis results from CAPE according to the integration configuration on the appliance |
vmray_tcbase | Contains dynamic analysis results from VMRay according to the integration configuration on the appliance |
sources | Groups sources of the file in the ReversingLabs system (Spectra Intelligence sources, external, other) |
av_scanners | Lists detailed results from every AV scanner that scanned the file |
sample_summary | Combines the default response and the summary object of the Summary Report API with the aliases field to return a more complete summary report |
av_scanners_summary | Lists the total number of AV scanners used to scan the file; the number and the percentage of AV scanners out of the total that matched the sample |
tags | Lists labels automatically generated by Spectra Core during analysis based on the sample’s metadata properties (“ticore”) or added by the users on the appliance (“user”) |
discussion | Contains comments attached to the requested sample(s), if there are any |
networkthreatintelligence | Only for URLs |
domainthreatintelligence | Only for URLs |
Response Status Codes
CODE | DESCRIPTION |
---|---|
200 | Returned on successful requests. Also returned for samples that don’t exist on the appliance, and for empty report fields. |
400 | Malformed hash or invalid field name. |
403 | Authentication credentials were not provided. / Invalid token. |
404 | Malformed endpoint. |