ON PREMISES SOLUTIONS

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"
}