Skip to main content

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

imageId

String

No

The ID of the image which will be used to detonate the sample.

detonation

Object

No

The Object has the following structure:

  • type - a String representing the type of information submitted. It may have one of the following values: file - when submitting a binary file, or url - when submitting a URL.

  • detonationProfile - a String containing the detonation profile. This allows you to choose between sandbox detonation throughput and detection accuracy, or to balance them. Possible values are:

    • low - increased Sandbox Analyzer throughput with reduced detonation analysis complexity. The accuracy of the detection remains in acceptable standards.

    • medium - the optimal balance between detonation time and analysis accuracy.

    • high - the best analysis accuracy. The side effect is a less than optimal detonation throughput.

  • url - a String containing the URL to be analyzed. This attribute is optional.

  • fileName - a String representing the name of the file to be shown in console. This attribute is optional. If omitted, //Sandbox Analyzer generates one.

  • archivePassword - a String containing the decryption password. This attribute is optional. If omitted, // will not be able to analyze the contents of an encrypted archive.

detonationOptions

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

commandLineArguments

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.

timeLimit

Number

6 minutes

The maximum number of minutes that a detonation can last.

numberOfReruns

Number

2 reruns

The number of detonation attempts, in case of failure.

preFiltering

Boolean

True

Specifies whether Sandbox Analyzer caches previously analyzed samples (True) or not.

internetAccess

Boolean

True

Sets the internet access of the VM. If True, the VM can access the internet.

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 code

  • message - a String with the response description

  • submissionId - 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 Request

  • 401 Unauthorized

  • 402 Malformed Request

  • 403 Forbidden

  • 404 Not Found

  • 405 Method Not Allowed

  • 429 Too Many Requests

  • 500 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 code

  • message - a String with the description of the error

  • errors - 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"
    ]
}
In this section: