SorbSecurity Cloud Sandbox API Reference
SorbSecurity Cloud Sandbox(SCS) provides an Application Programming Interface (API) framework for external applications to access core functions through the REST protocol.
The API is implemented as a RESTful web services API. Each request will require the user’s API key. REST stands for Representational State Transfer. It relies on a stateless, client-server and cacheable communication protocol – HTTP. It is an architecture style for designing networked applications. RESTful applications use HTTP requests to post data (create and/or update), get data (query information) and delete data. Thus, REST uses HTTP for all CRUD (Create/Read/Update/Delete) operations. It is a lightweight alternative to mechanisms like RPC (Remote Procedure Calls) and Web Services such as SOAP and WSDL.
Each organization has limits on request rate and total requests; these limits are laid out in each organization’s terms of service. Unless otherwise specified, there are separate limits for report requests and run requests.
| API | Description |
| File Analysis | Submit a file to analyze, return format is JSON. |
| URL Analysis | Submit a URL to analyze, return format is JSON. |
| File Search | Search MD5, SHA1, SHA256 in the database for sample file info, return format is JSON. |
| File Analysis Task Search | Search MD5, SHA1, SHA256 in the database for file analysis task info, return format is JSON. |
| Advanced Analysis Task Search | Search other parameters in the database for analysis task info, return format is JSON. |
| List Analysis Tasks | View analysis tasks info by searching analysis tasks ID range, return format is JSON. |
| Analysis Task Info | View basic info of a giving analysis task, return format is JSON. |
| Analysis Tasks Status | view analysis status of a giving analysis task, return format is JSON. |
| Analysis Task Summary Report | Download the summary report of an analysis task, return format is JSON. |
| Analysis Task Report | Download the analysis report of an analysis task, return format is JSON. |
| Analysis Task IOCs | View Indicators of Compromises(IOCs) information of an analysis task, return format is JSON. |
| Analysis Task Screenshots | View/Download the virtual execution screenshots of an analysis task, return format is image/jpeg or octet-stream. (.jpg or .tar.bz2). |
| Analysis Task PCAP | Download the virtual execution PCAP file during network analysis, return format is application/vnd.tcpdump.pcap. (.pcap) |
| Analysis Task Dropped Files | Download the virtual execution dropped files of an analysis task, return format is octet-stream. (.tar.bz2) |
| Analysis Task Sample Download | Search and download the file sample of an analysis task through task ID, file MD5/SHA1/SHA256, return format is octet-stream. (.bin) |
1. File Analysis
Submit a file to SorbSecurity Cloud Sandbox analysis, return format is JSON.
How to use
curl -F file=@/path/to/file https://<FQDN>/apineo/<Customer’s API Key>/tasks/create/file/Input
| Parameters | Description |
| API key | User’s API Key |
| File | Path to the file sample for which the analysis is being requested |
Output
| Parameters | Description |
| task_ids | The unique analysis task id that can be used to query the task status and analysis result |
| url | The Web URL generated to track and present the task status and analysis result of the submitted task |
| data | The returned value form system that indicates the status of the API execution (file analysis task submission) |
| error | Response of API execution status. error: false – the task file submission succeeded error: true – the task file submission failed |
| error_value | The reason that you received this error response |
Example
$ curl -F file=@1.exe https://<FQDN>/apineo/3333caedc1e02f99f0441c22775bcece/tasks/create/file/
{
"task_ids": [
"8RT-7-f9Qj3cHEvmgYSOM_MO8Hil93jfK36JFXYLIhQ="
],
"url": [
"https://<IP>/submit/status/8RT-7-f9Qj3cHEvmgYSOM_MO8Hil93jfK36JFXYLIhQ=/"
],
"data": "Task 8RT-7-f9Qj3cHEvmgYSOM_MO8Hil93jfK36JFXYLIhQ= has been created successfully!",
"error": false
}2. File View
Search MD5, SHA1, SHA256 in the SorbSecurity Cloud Sandbox database for sample file info, return format is JSON.
How to use
curl https://<FQDN>/apineo/<Customer’s API Key>/files/view/md5/[md5 hash]/
curl https://<FQDN>/apineo/<Customer’s API Key>/files/view/sha1/[sha1 hash]/
curl https://<FQDN>/apineo/<Customer’s API Key>/files/view/sha256/[sha256 hash]/Input
| Parameters | Description |
| API key | User’s API Key |
| File MD5 hash | The MD5 hash string of the file for which the search is being requested |
| File SHA1 hash | The SHA1 hash string of the file for which the search is being requested |
| File SHA256 hash | The SHA256 hash string of the file for which the search is being requested |
Output
| Parameters | Description |
| sha1 | The SHA1 hash string of the file being searched |
| file_type | The File Type of the file being searched |
| file_size | The size of the file being searched (in Bytes) |
| ssdeep | The ssdeep (Fuzzy hash) hash string of the file being searched |
| sha256 | The SHA256 hash string of the file being searched |
| sha512 | The SHA512 hash string of the file being searched |
| id | The analysis task id of the file sample that is being searched |
| md5 | The MD5 hash string of the file being searched |
| error | Response of API execution status. error: false – the file view succeeded error: true – the file view failed |
| error_value | The reason that you received this error response |
Example
$curl https://<FQDN>/apineo/3333caedc1e02f99f0441c22775bcece/files/view/md5/0272c002492d3c8163b79acd3697aa6c/
{
"data": {
"sha1": "399d23ebb83e33d88fb8748e974361a8ed3a6ee6",
"file_type": "PE32 executable (GUI) Intel 80386, for MS Windows, Nullsoft Installer self-extracting archive",
"file_size": 222010,
"crc32": "057ECF19",
"ssdeep": null,
"sha256": "21bbbd5d502a1119dc503962ba1fb895315d86d8dad28778e036a82a3f2de20e",
"sha512": "e444a239f7dd4ec3f7891abb88ab586d4487c6a6fa213e43580a4c1d7a956ae685343d241a180ba89f2e77457c46811c29224e908ebd4d0235670fbba3a57474",
"id": "Yx1v2dTDsqdGP4D86fYu09BvmqStAO6K6_zVd9bjwXM=",
"md5": "0272c002492d3c8163b79acd3697aa6c"
},
"error": false
}3. File Analysis Task Search
Search MD5, SHA1, SHA256 in the SorbSecurity Cloud Sandbox database for file analysis task info, return format is JSON.
How to use
curl https://<FQDN>/apineo/<Customer’s API Key>/tasks/search/md5/[md5 hash]/
curl https://<FQDN>/apineo/<Customer’s API Key>/tasks/search/sha1/[sha1 hash]/
curl https://<FQDN>/apineo/<Customer’s API Key>/tasks/search/sha256/[sha256 hash]/Input
| Parameters | Description |
| API key | User’s API Key |
| File MD5 hash | The MD5 hash string of the file for which the search is being requested |
| File SHA1 hash | The SHA1 hash string of the file for which the search is being requested |
| File SHA256 hash | The SHA256 hash string of the file for which the search is being requested |
Output
| Parameters | Description |
| id | The analysis task id of the file sample that is being searched |
| target | The analysis target (i.e, filename) of the file sample being searched |
| completed_on | The analysis completion time of the file sample being searched |
| added_on | The time that the analysis task has been added to the analysis queue |
| started_on | The analysis start time of the file sample being searched |
| error | Response of API execution status. error: false – the file analysis task search succeeded error: true – the file analysis task search failed |
| error_value | The reason that you received this error response |
Example
$ curl https://<FQDN>/apineo/3333caedc1e02f99f0441c22775bcece/tasks/search/md5/0272c002492d3c8163b79acd3697aa6c/
{
"data": [
{
"id": "uUbgdpvBtmGCYPT2H0GUT-2lIn-6zfJENEol01_pSJg=",
"target": "1.exe",
"completed_on": "2018-02-04 09:31:23",
"added_on": "2018-02-04 09:28:17",
"started_on": "2018-02-04 09:28:19"
}
],
"error": false
}4. Analysis Task Info
Request basic info of a given analysis task, return format is JSON.
How to use
curl https://<FQDN>/apineo/<Customer’s API Key>/tasks/view/[task id]/Input
| Parameters | Description |
| API key | User’s API Key |
| task id | The analysis task id of the file sample that is being searched |
Output
| Parameters | Description |
| id | The analysis task id of the file sample that is being searched |
| completed_on | The analysis completion time of the file sample being searched |
| added_on | The time that the analysis task has been added to the analysis queue |
| started_on | The analysis start time of the file sample being searched |
| error | Response of API execution status. error: false – the analysis task view succeeded error: true – the analysis task view failed |
| error_value | The reason that you received this error response |
Example
$ curl https://<FQDN>/apineo/3333caedc1e02f99f0441c22775bcece/tasks/view/uUbgdpvBtmGCYPT2H0GUT-2lIn-6zfJENEol01_pSJg=/
{
"data": {
"id": "mlJ_h8MxrznCG6QCgSEkFWoWHZivninicO_wnon0TRk=",
"completed_on": "2018-02-04 09:31:23",
"added_on": "2018-02-04 09:28:17",
"started_on": "2018-02-04 09:28:19"
},
"error": false
}5. Analysis Tasks Status
Request analysis status of a given analysis task, return format is JSON.
How to use
curl https://<FQDN>/apineo/<Customer’s API Key>/tasks/status/[task id]/Input
| Parameters | Description |
| API key | User’s API Key |
| task id | The analysis task id of the file sample that is being searched |
Output
| Parameters | Description |
| data | The returned value form system that indicates the status of the API execution (the status of the analysis task, i.e, reported, pending, reporting, etc.) |
| error | Response of API execution status. error: false – the analysis task status check succeeded error: true – the analysis task status check failed |
| error_value | The reason that you received this error response |
Example
$ curl https://<FQDN>/apineo/3333caedc1e02f99f0441c22775bcece/tasks/status/uUbgdpvBtmGCYPT2H0GUT-2lIn-6zfJENEol01_pSJg=/
{
"data": "reported",
"error": false
}6. Analysis Task Summary Report
Request the summary report of an analysis task, return format is JSON.
How to use
curl https://<FQDN>/apineo/<Customer’s API Key>/tasks/get/simple_report/[task id]/Input
| Parameters | Description |
| API key | User’s API Key |
| task id | The analysis task id of the file sample that is being searched |
Output
| Parameters | Description |
| malfamily | Malware Family (malfamily) defines the malware or virus categories that the sample fall into, and it helps user to understand the behavior category of the malicious sample. |
| malscore | Threat Score (malscore) usually represents the probability a sample is considered malicious or not. Malscore between 0 and 2, is normally considered as clean or safe; Malscore between 2 and 6, is normally considered as suspicious; Malscore between 6 and 10, is normally considered as dangerous or malicious, which may carry virus payload or lead to malicious behaviors on the system. |
| task_id | The unique analysis task id that can be used to query the task status and analysis result |
| error | Response of API execution status. error: false – the analysis summary report succeeded error: true – the analysis summary report failed |
| error_value | The reason that you received this error response |
Example
$ curl https://<FQDN>/apineo/3333caedc1e02f99f0441c22775bcece/tasks/get/simple_report/uUbgdpvBtmGCYPT2H0GUT-2lIn-6zfJENEol01_pSJg=/
{
“malfamily”: “”,
“malscore”: 10.0,
“task_id”: “uUbgdpvBtmGCYPT2H0GUT-2lIn-6zfJENEol01_pSJg=”
}
7. Analysis Task Screenshots
Request the virtual execution screenshots of an analysis task, return format is image/jpeg or octet-stream. (.jpg or .tar.bz2).
How to use
curl https://<FQDN>/apineo/<Customer’s API Key>/tasks/get/screenshot/[task id]/ (Downloads all screenshots)
curl https://<FQDN>/apineo/<Customer’s API Key>/tasks/get/screenshot/[task id]/[screenshot number]/Input
| Parameters | Description |
| API key | User’s API Key |
| task id | The analysis task id of the file sample that is being searched |
| screenshot number | The sequential number of the analysis task screenshot |
Output
| Parameters | Description |
| error | Response of API execution status. error: false – the analysis task screenshots request succeeded error: true – the analysis task screenshots request failed |
| error_value | The reason that you received this error response |
Example
$ curl https://<FQDN>/apineo/3333caedc1e02f99f0441c22775bcece/tasks/get/simple_report/uUbgdpvBtmGCYPT2H0GUT-2lIn-6zfJENEol01_pSJg=/
{
"malfamily": "",
"malscore": 10.0,
"task_id": "uUbgdpvBtmGCYPT2H0GUT-2lIn-6zfJENEol01_pSJg="
}Click HERE to see the samples.