Sandbox
Note
This section refers to Sandbox Analyzer On-premises, a legacy product.
Sandbox Analyzer API retrieves metadata related to the Sandbox Analyzer instances, images and submissions.
getSandboxAnalyzerInstancesList
: lists Sandbox Analyzer instances.getImagesList
: lists images for a instance.getSubmissionStatus
: returns the status of a submission.getDetonationDetails
: returns the details of a submission.
API url: https://YOUR-HOSTNAME/api/v1.0/jsonrpc/sandbox
getSandboxAnalyzerInstancesList
This method lists the instances in the Infrastructure menu.
Parameters
Parameter | Type | Optional | Description |
---|---|---|---|
| Number | Yes | The results page. Default value: |
| Number | Yes | The number of items displayed per page. The upper limit is 100 items per page. Default value: |
Return value
This method returns an Object containing information regarding the [SandboxAnalyzer] instances. The object has the following structure:
page
- the current page displayedpagesCount
- the total number of available pagesperPage
- the number of returned items per pageitems
- the list of [SandboxAnalyzer] instances. Each item has the following fields:sandboxId
, the ID of the [SandboxAnalyzer] instance.name
, the name of the [SandboxAnalyzer] instance.ip
, the IP address of the [SandboxAnalyzer] instance.macs
, the MAC addresses of the [SandboxAnalyzer] instance.ssid
, the Active Directory SID of the [SandboxAnalyzer] instance.detonatedSamples
, the overall number of samples analyzed by the [SandboxAnalyzer] instance.diskUsage
, the percentage of the disk space that [SandboxAnalyzer] occupies in the datastore.installationStatus
, the status of the [SandboxAnalyzer] installation process. It can have one of the following values:0
- Not installed1
- Installed2
- Installing3
- Installation failed
lastSeen
, the date of the last synchronization with Control Center.configuredConcurrentDetonations
, the number of virtual machines allocated to detonate samples.maximumConcurrentDetonations
, the maximum number of virtual machines that the [SandboxAnalyzer] instance can create to detonate samples.submissionUrl
, the URL for submitting files for analysis.
total
- the total number of items
Example
Request:
{ "method": "getSandboxAnalyzerInstancesList", "params": { "page": 1, "perPage": 20 }, "jsonrpc": "2.0", "id": "91d6430d-bfd4-494f-8d4d-4947406d21a7" }
Response:
{ "id": "91d6430d-bfd4-494f-8d4d-4947406d21a7", "jsonrpc": "2.0", "result": { "page": 1, "pagesCount": 1, "perPage": 20, "total": 1, "items": [ { "sandboxId": "5c419e6e26df3d367c49de18", "name": "sandbox1", "ip": "10.10.20.1", "macs": [ "00-14-22-01-23-45" ], "ssid": "", "detonatedSamples": 0, "diskUsage": 250, "installationStatus": 1, "lastSeen": "2019-01-18T11:37:50", "configuredConcurrentDetonations": 0, "maximumConcurrentDetonations": 10, "submissionUrl":"https://10.10.20.1:443/api/v1/upload" } ] } }
getImagesList
This method lists all images available on a [SandboxAnalyzer] instance.
Parameters
Parameter | Type | Optional | Description |
---|---|---|---|
| String | No | The ID of the Sandbox Analyzer instance for which the images list will be returned. |
| Number | Yes | The results page number. Default value: |
| Number | Yes | The number of items displayed in a page. The upper limit is 100 items per page. Default value: |
Return value
This method returns an Object containing information regarding the images. The object has the following structure:
page
- the current page displayedpagesCount
- the total number of available pagesperPage
- the total number of returned items per pageitems
- the list of images. Each item in the list has the following fields:id
, the ID of the image.name
, the name of the image.status
, the status of the image. It can have one of the following values:1
- New2
- Failed3
- Ready
operatingSystem
, the operating system of the image.dateAdded
, the date on which the image was added.isDefault
, a Boolean which has the valueTrue
when the image is set as default.False
otherwise.actionInProgress
, a Boolean which has the valueTrue
when there is an action in progress for this image.
total
- the total number of items
Example
Request:
{ "method": "getImagesList", "params": { "sandboxId": "5c419e6e26df3d367c49de18", "page": 1, "perPage": 20 }, "jsonrpc": "2.0", "id": "91d6430d-bfd4-494f-8d4d-4947406d21a7" }
Response:
{ "id": "91d6430d-bfd4-494f-8d4d-4947406d21a7", "jsonrpc": "2.0", "result": { "page": 1, "pagesCount": 1, "perPage": 20, "total": 1, "items": [ { "id": "924cca0d49cc7e350a44502b0bb9026a", "name": "image1", "status": 1, "operatingSystem": "Windows 10", "dateAdded": "2019-01-18T09:20:50", "isDefault": true, "actionInProgress": false } ] } }
getSubmissionStatus
Returns the final status of the detonation.
Parameters
Parameter | Type | Optional | Description |
---|---|---|---|
| String | No | The ID of the submission for which the status should be retrieved. |
Return value
This method returns an Object containing the status:
status
- an Integer representing the final status. It can have one of the following values:1
- completed, if the detonation was successful2
- pending, if the detonation is currently in progress3
- failed, if the detonation failed4
- not supported, if the file cannot be detonated
Example
Request:
{ "id": "787b5e36-89a8-4353-88b9-6b7a32e9c87f", "jsonrpc": "2.0", "method": "getSubmissionStatus", "params": { "submissionId": "sp02_1547807011_936_e5" } }
Response:
{ "id": "787b5e36-89a8-4353-88b9-6b7a32e9c87f", "jsonrpc": "2.0", "result": { "status": 1 } }
getDetonationDetails
The method returns the details of a submission, including a URL pointing to the HTML report.
Parameters
Parameter | Type | Optional | Description |
---|---|---|---|
| String | No | The ID of the submission for which the detonation details should be retrieved. |
Return value
This method returns an Object containing the details of a completed detonation. The object has the following structure:
detailsReportUrl
- a String containing the URL from where the HTML report is available for download.score
- an Integer in the range 0-100 representing the severity of the threat, if any.verdict
- an Integer having one of the following values:0, if clean.
1, if infected.
2, if unsupported.
mitreTags
- an Array of Objects with the following structure:category
a String holding the MITRE category.techniques
an Array of Strings holding the MITRE techniques.
Example
Request:
{ "id": "787b5e36-89a8-4353-88b9-6b7a32e9c87f", "jsonrpc": "2.0", "method": "getDetonationDetails", "params": { "submissionId": "sp02_1547807011_936_e5" } }
Response:
{ "id": "787b5e36-89a8-4353-88b9-6b7a32e9c87f", "jsonrpc": "2.0", "result": { "detailsReportUrl":"https://10.10.20.1:443/api/v1/report?report_id=asd", "score": 30, "verdict": 0, "mitreTags": [ { "category": "Defense Evasion", "techniques": [ "Modify Registry", ] }, { "category": "Persistence", "techniques": [ ".bash_profile and .bashrc", "Account Manipulation", ] }, ] } }