The Collective Defense Cloud has provided a RESTful API to query the status and the results of binaries submitted for CB Inspection.
Example client scripts are included for reference purposes and are implemented in Python.
The Collective Defense Cloud REST API uses a set of HTTP header fields for authentication of all requests. Please refer to the REST API authentication reference for more details on these authentication parameters and how to get access to the API.
Base URL: https://threatintel.bit9.com/api/v1/inspection
The status endpoint returns data about the status of the inspection.
Parameters
in | name | type | required | description |
---|---|---|---|---|
path | hash | string | true | Hex string of either MD5 or SHA256 checksum of submitted binary |
A status object
Schema
Inspection submission not found
Schema
Unexpected error
Schema
Request
import requests
auth_headers = {
"X-Tic-User-Key": "eeacdcc1b-e5e5-f6f6abab-0101010101aad",
"X-Tic-User-Secret": "Kp7B9fkZxm5TloYuXUGb566OC00YWQ5LTkwZjc3NTU2M2Ex"
}
url = "https://threatintel.bit9.com/api/v1/inspection/status/a0a0a0a0a0a0a0a0a0a0a0a0a0a0a0a0"
response = requests.get(url, headers=auth_headers)
if response.status_code == 200:
print (response.json())
Response
{
"analysis_complete": false,
"completed": "2016-10-11T14:49:30",
"eta_to_complete": 3600,
"md5": "a0a0a0a0a0a0a0a0a0a0a0a0a0a0a0a0",
"requested": "2016-10-11T14:49:17",
"results": null,
"sha1": "a0a0a0a0a0a0a0a0a0a0a0a0a0a0a0a0a0a0a0a0",
"sha256": "a0a0a0a0a0a0a0a0a0a0a0a0a0a0a0a0a0a0a0a0a0a0a0a0a0a0a0a0a0a0a0a0",
"status": "submitted"
}
The report endpoint returns both detailed telemetry data and status info of the inspection.
Parameters
in | name | type | required | description |
---|---|---|---|---|
path | hash | string | true | Hex string of either MD5 or SHA256 checksum of submitted binary |
A report object
Schema
Inspection submission not found
Schema
Unexpected error
Schema
Request
import requests
auth_headers = {
"X-Tic-User-Key": "eeacdcc1b-e5e5-f6f6abab-0101010101aad",
"X-Tic-User-Secret": "Kp7B9fkZxm5TloYuXUGb566OC00YWQ5LTkwZjc3NTU2M2Ex"
}
url = "https://threatintel.bit9.com/api/v1/inspection/status/a0a0a0a0a0a0a0a0a0a0a0a0a0a0a0a0"
response = requests.get(url, headers=auth_headers)
if response.status_code == 200:
print (response.json())
Response
{
"metadata": {
"magic": "PE32 executable for MS Windows (native) Intel 80386 32-bit",
"md5": "a0a0a0a0a0a0a0a0a0a0a0a0a0a0a0a0",
"mime": "application/octet-stream",
"name": "2c018e375986cb29a76910850eb83bb0c14ed22c2d00194692e27955f3707f67.exe",
"sha1": "a0a0a0a0a0a0a0a0a0a0a0a0a0a0a0a0a0a0a0a0",
"sha256": "a0a0a0a0a0a0a0a0a0a0a0a0a0a0a0a0a0a0a0a0a0a0a0a0a0a0a0a0a0a0a0a0",
"size": "4134122"
},
"report_url": "https://analysis.carbonblack.com/report/g",
"results": {
"analysis_summary": "bad",
"detonation": {
"data": [
{
"te": {
"CPULevelDetection": "false",
"SuspiciousActivities": {
"SuspiciousEvent": {
"SuspiciousActivity": [
{
"Path": "[low confidence] Behaves like a known malware ( Generic.MALWARE.x )"
}
],
"Type": "SuspiciousActivityEvent"
}
},
"System": {
"OsInfo": "Microsoft Windows 7 32 bit, Office 2003, Office 2007, Adobe Acrobat Reader 9.0, Adobe Flash Player 10, Java SE 1.6.0",
"OsRev": "53",
"OsUID": "7e6fe36e-889e-4c25-8704-56378f0830df",
"Osname": "Windows 7"
},
"reportDate": "Tue Sep 27 10:39:09 2016"
}
},
{
"av": {
"signature_name": ""
}
}
],
"status": "complete"
},
"score": 100,
"score_factors": {
"detonation": {
"score": 8,
"verdict": "suspicious"
},
"strings_analysis": {},
"subfile": {
"score": 100,
"verdict": "bad"
},
"yara": {
"score": 100,
"verdict": "bad"
}
},
"strings_analysis": {
"data": [
{
"generic": {
"ascii_strings": [
"!This program cannot be run in DOS mode."
],
"unicode_strings": [
"jjjjjjjjjj",
"\\System32\\mrt100.dll"
]
}
}
],
"status": "complete"
},
"subfile": {
"data": [
{
"detail": "Found with XOR key 0x41",
"md5": "234e22d3b7bba6c0891de0a19b79d7ea",
"method": "XOR",
"report_url": "https://analysis.carbonblack.com/report/gA1",
"score": 100,
"sha1": "9214239dea04dec5f33fd62602afde720b71d2d2",
"sha256": "30a824155603c2e9d8bfd3adab8660e826d7e0681e28e46d102706a03e23e3a8"
}
],
"status": "complete"
},
"yara": {
"data": [
{
"generic": {
"matches": [
{
"meta": {
"confidence": 8,
"description": "Detects Sauron/Strider/Remsec based on rich trash headers",
"severity": 10
},
"namespace": "production.yar",
"rule": "sauron_strider_trash"
}
]
}
}
],
"status": "complete"
}
},
"status": {
"analysis_summary": "bad",
"completed": "2016-09-27T17:34:38",
"requested": "2016-09-27T17:30:13",
"score": 100,
"status": "complete"
}
}
Schema
data
(array): Yara data results
matches
(array): List of yara rules that matched on this binary
meta
(object): Metadata about Yara rule that fired
condidence
(integer: int32): Confidence factor in Yara ruledescription
(string): Description of Yara ruleseverity
(integer: int32)rule
(string): Name of Yara rulestatus
(string): Status of Yara analysisSchema
data
(array): SubFile data results
detail
(string): details of how subfile was foundmd5
(string): hex string of MD5 checksum of subfilemethod
(string): Method used to detect subfilereport_url
(string): Url to CB Inspection portal for the analyzed sub filescore
(integer: int32): CB Inspection score for sub filesha1
(string): hex string of SHA1 checksum of subfilesha256
(string): hex string of SHA256 checksum of subfilestatus
(string): Status of SubFile analysisSchema
data
(array): List of data sections
te
(object): Emulation telemetry data
System
(object)
OsInfo
(string): Description of OSOsRev
(string): OS Rev of Sandbox environmentOsUID
(string): unique identifier for Sandbox environmentOsname
(string): Name of OS (e.g. Windows 8.1)Activities
(object): Set of activities observed during execution on the sandbox
Command
(array): list of Commands performed during execution
Action
(string): Name of action performed. e.g. QueryKey, Read,CommandName
(string: RegistryEvent, FileSystemEvent, NetworkEvent, SuspiciousActivityEvent, ProcessEvent, NetworkHTTPEvent): Type of command performed. e.g. RegistryEvent, FileSystemEventSuspiciousActivities
(object): Set of behaviours observed during execution on the sandbox
SuspiciousEvent
(object)
Type
(string): type of suspicious activity observed during executionSuspiciousActivity
(array): list of observed behaviours during execution on sandbox
Path
(string)av
(object): Antivirus Scanner Information
signature_name
(string): Malware signature namestatus
(string): Status of DetonationSchema
data
(array): generic object wrapper
ascii_strings
(string): ascii stringsunicode_strings
(string): unicode stringsstatus
(string): Status of StringsAnalysisSchema
detonation
(object): Detonation score information
score
(integer: int32): Score of detonationverdict
(string: good, bad, suspicious, unknown): Enum of verdict from detonationyara
(object): Yara score information
score
(integer: int32): Score of Yaraverdict
(string: good, bad, suspicious, unknown): Enum of verdict from Yaracb_reputation
(object)
score
(integer: int32): Score of CB reputationprevalence
(object): Prevalence
score
(integer: int32): Factor for community prevalenceSchema
eta_to_complete
(integer: int32): Estimated number of seconds remaining to complete inspection. Only populated if status is in submitted state.hash
(object)
md5
(string): hex string of MD5 checksum of binarysha1
(string): hex string of SHA1 checksum of binarysha256
(string): hex string of SHA256 checksum of binaryanalysis_summary
(string: good, bad, suspicoius, unknown): Overall verdict of analysisscore
(integer: int32): Overall score of the inspection result ranging from -100 (trusted) to 100 (malicious).status
(string: complete, error, requested, submitted): Status of inspection.requested
(string: dateTime): Date and time binary was last submitted for inspectioncompleted
(string: dateTime): Date and time binary inspection was last completedSchema
report_url
(string): Link to the CB Inpsection detail pagemetadata
(object): Metadata section
magic
(string): Magic file typemd5
(string): hex string of MD5 checksum of binarysha1
(string): hex string of SHA1 checksum of binarysha256
(string): hex string of SHA256 checksum of binarysize
(integer): size of submitted binary in bytesresults
(object): Results of the Inspection
analysis_summary
(string: good, bad, suspicious, unknown): Summary verdict for the Inspection.score
(integer: int32): Overall score of the inspection result ranging from -100 (trusted) to 100 (malicious).score_factors
ScoreFactorsdetonation
Detonationstrings_analysis
StringsAnalysisyara
Yarasubfile
SubFilestatus
StatusSchema
code
(integer: int32)message
(string)Schema
code
(integer: int32)message
(string)