exec_env

string

Optional

Operating system to be used as execution environment.

You can specify title of any installed execution environments, including successfully deployed custom execution environments.

If an incorrect value is specified, titles of all available environments will be returned in the invalid-param-exec_env error description.

If this parameter is not specified for a file, Kaspersky Research Sandbox automatically determines the optimal operating system according to the type of uploaded file (Auto option in web interface).

exec_time

integer

Optional

Object execution time in seconds.

Available values: 30–1800.

If this parameter is not specified for a file, Kaspersky Research Sandbox automatically determines the optimal execution time according to the type of uploaded file (Auto option in web interface).

For a web address browsing task, the 100 value is specified by default.

file_name

string

Required

For file execution only.

Object name.

If you specify a file name and extension, Kaspersky Research Sandbox does not detect the file type automatically.

To automatically detect the file type during execution, specify only a file name.

The value must not exceed 240 symbols.

url

string

Required

For web address browsing only.

Web address to be browsed in the Sandbox.

The value must not exceed 1000 symbols.

guest_directory

string

Optional

Technical preview.

For file execution only.

Parameter cannot be used with Android execution environment.

Directory where a sample file will be uploaded and executed.

Default value: %USERPROFILE%\Downloads (if supported) or C:\downloads.

If a directory is relative, it will be joined with the default directory.

unpack_password

string

Optional

For file execution only.

Password for unpacking the archive.

Kaspersky Research Sandbox tries to unpack an archive using default passwords.

doc_password

string

Optional

For file execution only.

Password that can be used to open password protected Microsoft Office or PDF documents. This parameter is only work used in Windows execution environments.

decrypt_https

boolean

Optional

Specifies whether HTTPS traffic generated by the executed object must be decrypted.

Available values:

• false—HTTPS traffic must not be decrypted.
• true—HTTPS traffic must be decrypted.

Default value: true.

If a custom environment based on Windows XP is specified, the decrypt_https parameter must not be specified (Windows XP execution environment does not support SSL traffic decryption).

The HTTPS traffic decryption may decrease the probability of malware detection.

channel

string

Optional

Name of the network channel to be used by the object to access the internet.

Available values:

• Tarpit—Emulates network availability during file execution, without real access to the internet. When this value is specified, a connection from the virtual machine to any host is emulated. Tarpit channel allows for simplified emulation of the following protocols: raw TCP/UDP, HTTP(S), ICMP, DNS.
• Other options that were set during Kaspersky Research Sandbox installation.

For automatic channel selection, do not specify this parameter.

If a channel is specified for an image, then an attempt to change it in the task parameters will result in an error. You can change the channel in the image parameters.

debug_report

boolean

Optional

Specifies whether a debug report for the executed file must be generated.

Available values:

• false—Debug report is not generated.
• true—Debug report is generated.

Default value: false.

Diagnostic information about application performance is obtained separately.

click_links

boolean

Optional

For file execution only.

Specifies whether Kaspersky Research Sandbox must browse the links in the documents that are opened in the Sandbox.

Available values:

• false—Application must not browse the links.
• true—Application must browse the links. Specifying this value can increase the detection level of malicious objects and their behavior.

Default value: false.

The click_links parameter is available only if a Microsoft Windows based execution environment is selected. If you specified an execution environment based on Android or Linux (including custom), then the value of this parameter is ignored during file execution.

If this parameter is not specified in the request, Kaspersky Research Sandbox browses the links in the opened documents.

cmd_line

string

Optional

For file execution only.

You can use Windows environment variables by placing the % sign in front of and after the variable name, for example: %SYSTEMROOT%.

By default, the environment variables values are expanded on the user's host, before transferring and executing the object in the Sandbox. To transfer environment variables to the Sandbox as is, without expansion, use the % sign, for example: %SYSTEMROOT%.

The command line may contain a variable $sample that will be replaced in the Sandbox with the actual path to the object in the operating system (for example, <notepad path> /A $sample).

The length of the command line must not exceed 1024 characters, otherwise Kaspersky Research Sandbox shortens it. Depending on the technical constraints of an operating system that is used as an execution environment in the Sandbox, the length of the command line may be further shortened.

Command line usage examples are described in the Appendices.

pre_scan

boolean

Optional

For file execution only.

Specifies whether Kaspersky Research Sandbox performs full (both static and dynamic) object analysis including execution in the Sandbox.

Available values:

• false—Full analysis is performed, the object is executed in the Sandbox.
• true—Only static analysis is performed, the object is not executed in the Sandbox. The report contains information about the executed file, execution parameters, detected objects, and contents of the file if it is a container.

Default value: false.

custom_suricata_rules

string (binary)

Optional

A text file (.txt or .rules) with Suricata rules.

The recommended file size is 5 MB. If the Suricata rule file size exceeds 16 MB, we recommend that you split it into several files (up to 5 MB in size) and upload them to the task sequentially.

apps_close_timeout

integer

Optional

Technical preview.

Timeout in seconds after which the application in which a Microsoft Office document was opened will be closed.

Available values: 10-1800.

Only relevant for Microsoft Office documents sent to Windows environments.

vnc_access

boolean

Optional

Enables VNC access to a virtual machine during a sample detonation process.

Available values:

• true—VNC access is enabled.
• false—VNC access is disabled.

Access to VNC session is only possible from web interface.

If session duration is not specified, it will be set to 1800 seconds.

vnc_start_sample_automatically

boolean

Optional

Allows to start the sample execution in the virtual machine immediately, without additional user actions.

Available values:

• true—Automatic start is enabled.
• false—Automatic start is disabled.

disable_clicker

boolean

Optional

Disables the clicker for the task in Windows environments. Enabling this parameter is recommended when using the VNC mode.

Available values:

• true—Clicker is disabled.
• false—Clicker is enabled.

The click_links parameter is available only when the clicker is enabled (disable_clicker=false).

cURL command sample for file execution:

$ curl --http1.1 --user <user name> --request POST --header "Content-Type:application/octet-stream" --data-binary @'<path and file name>' 'https://<server name>/api/v1/sandbox/tasks?file_name=<file name>'

You will be asked to enter your password. The password is not displayed while you type it.

cURL command sample for web address analysis:

$ curl -v --http1.1 --user <user name> --request POST --header "Content-Type:application/octet-stream" "https://<server name>/api/v1/sandbox/tasks?url=<web address>"

You will be asked to enter your password. The password is not displayed while you type it.

ID

string

ID (GUID) of the created execution task.

200 OK response example:

{

"ID": "5cf8cbb4-1d50-492c-986b-86d5c7596535"

}

code

string

Error ID.

message

string

Error description.

meta

string

Additional information, if available.

Error examples:

Empty file uploaded:

{"code":12,"message":"empty file"}

Incorrect chanel parameter:

{"code":22,"message":"wrong channel"}

Incorrect exec-env parameter:

{"code":33,"message":"invalid exec_env, acceptable values listed in meta field","meta":"Win7_x64,Win10_x64,Android_arm,Android_x86,CentOS7_x64"}

Required parameter (for example, file name) is not specified:

{"code":34,"message":"no file name or url"}

Incorrect exec_time parameter:

{"code":42,"message":"invalid value","meta":"exec_time must be 30...500"}

Incorrect decrypt_https parameter:

{"code":42,"message":"invalid value","meta":"decrypt_https must be true or false"}

Incorrect debug_report parameter:

{"code":42,"message":"invalid value","meta":"debug_report"}