Sandbox Portal
Note
This section refers to Sandbox Analyzer On-premises, a legacy product.
The Sandbox Portal API exposes functionality for working directly with the Bitdefender Sandbox Analyzer. While the other Sandbox APIs expose metadata for the detonations, the purpose of the Sandbox Portal API is to submit samples and to download the detailed report of the analysis.
The authorization is made using the same API key used for the GravityZone Sandbox APIs.
sample submission
: submit sample for detonation.report
: retrieve the detailed report for a detonation.
API URL: https://SANDBOX_IP/api/v1/
Note
The Sandbox Analyzer Portal API is hosted on the Sandbox Analyzer virtual appliance.
Sample Submission
This API endpoint makes a submission to .
Submission URL: https://SANDBOX_IP/api/v1/upload
The API endpoint expects a HTTP multipart request, which contains a JSON with detonation options and a binary file. When making a submission via URL, a binary file should not be included in the request.
Options in JSON format
Field | Type | Optional | Description |
---|---|---|---|
| String | No | The ID of the image which will be used to detonate the sample. |
detonation | Object | No | The Object has the following structure:
|
| Object | Yes | An Object containing detonation options. You can find the options described in the next section. |
Detonation options
All options are optional. If an option is omitted, Sandbox Analyzer uses the default value.
Option | Type | Default | Description |
---|---|---|---|
| String | No arguments provided. | The list of command line arguments that Sandbox Analyzer uses when detonating the sample. This option is available only for file submissions. |
| Number | 6 minutes | The maximum number of minutes that a detonation can last. |
| Number | 2 reruns | The number of detonation attempts, in case of failure. |
| Boolean | True | Specifies whether Sandbox Analyzer caches previously analyzed samples ( |
| Boolean | True | Sets the internet access of the VM. If |
For example, the JSON for a sample with an encrypted archive, to be detonated with command lines arguments, on a VM without internet access, should look like this:
{ "imageId": "1787b5e3689a8435388b96b7a32e9c87f", "detonation": { "type": "file", "detonationProfile": "medium", "fileName: "infected.zip", "archivePassword": "123infected" }, "detonationOptions": { "commandLineArguments": "--extraParam 41", "internetAccess": false } }
Next sample is a JSON for a URL submission without options.
{ "imageId": "1787b5e3689a8435388b96b7a32e9c87f", "detonation": { "type": "url", "detonationProfile": "medium", "url": "http://storage.infected.info/images/test.php" } }
Return value
This method returns an Object containing information regarding the submission. It has the following structure:
code
- an Integer representing the HTTP status codemessage
- a String with the response descriptionsubmissionId
- the ID allocated to the submitted sample. Omitted in case of error.errors
- an Array of Strings in case of bad request. This attribute is returned only in case of error.
Example
Request:
Given that Sandbox Portal API for making submissions is not JSON RPC, but rather HTTP multipart request, we'll also provide a couple of cURL examples.
The following examples show how the authorization header is set using the API key: UjlMS+0m1l9IUZjpjWyJG8gbnv2Mta4T
.
Read detonation options from file:
curl -X POST \ https://{sandbox_ip}:9090/api/v1/upload \ -H 'Authorization: Basic \ VWpsTVMrMG0xbDlJVVpqcGpXeUpHOGdibnYyTXRhNFQ=' \ -F 'options=@{/path/to/json_with_detonation_options}' \ -F 'upload_file=@{/path/to/binary_file}'
Note
The first part of the request has to be a JSON containing detonation options, otherwise the submission will fail.
The name of the multipart field associated with the submitted file has to be upload_file
, otherwise the submission will fail.
Generate detonation options on-the-fly:
curl -X POST \ https://{sandbox_ip}:9090/api/v1/upload \ -H 'Authorization: Basic \ VWpsTVMrMG0xbDlJVVpqcGpXeUpHOGdibnYyTXRhNFQ=' \ -F 'options={ "imageId": "1787b5e3689a8435388b96b7a32e9c87f", "detonation": { "type": "url", "detonationProfile": "medium", "url": "http://www.infected.info/test.php" } }'
Response:
{ "code": 200, "message": "Ok", "submissionId": "sp02_1547807011_936_e5", "file": "infected.zip" }
Report
This API endpoint retrieves an HTML report from Sandbox Analyzer.
Report URL: https://SANDBOX_IP/api/v1/report?report_id=REPORT_ID
The endpoint returns a deflatable GZIP archive containing the HTML file in case of success (HTTP status code 200), or a JSON in case of error.
Note
report_id
is passed as a GET variable to the API endpoint.
Error Handling
In case of error, the Sandbox Portal replies with a relevant HTTP status code. The list of possible status codes is, but not limited to:
400
Bad Request401
Unauthorized402
Malformed Request403
Forbidden404
Not Found405
Method Not Allowed429
Too Many Requests500
Internal Server Error
In addition to the HTTP status code, the body of the response contains a JSON describing the error.
The JSON has the following fields:
code
- an Integer representing the HTTP status codemessage
- a String with the description of the errorerrors
- an Array of Strings which provide additional information about the error. This field is optional.
Example of a response when trying to submit a URL with invalid options:
{ "code": 400, "message": "Failed validating request", "errors": [ "Invalid URL provided", "Invalid detonation object", "Invalid detonation options object" ] }