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

In this section: