task_id

Object execution task ID that you want to restart.

exec_env

Operating system that you want to use as an execution environment.

Available values can be obtained using the exec_env method.

If this parameter is not specified, Kaspersky Threat Intelligence Portal automatically determines the optimal operating system according to the type of uploaded file (Recommended option in web interface).

exec_time

Object execution time in seconds. Available values: 30–500.

If this parameter is not specified, Kaspersky Threat Intelligence Portal automatically determines the optimal execution time according to the type of uploaded file (Recommended option in web interface).

file_name

Object name. Required parameter.

Specify a file name, which Kaspersky Threat Intelligence Portal must use during execution in Kaspersky Sandbox. The specified file name will be assigned to the uploaded file or the file contained in the uploaded archive.

For correct processing of the file, do not specify its extension in the file_name parameter: Kaspersky Threat Intelligence Portal automatically determines the file type, and processes the file accordingly.

The value must not exceed 240 characters.

processing_type

Object execution type. Available values:

exec-only—Object execution is performed.

unzip-and-exec—Object is unpacked before execution.

unzip_password

Password for an archived object.

This parameter is used only when processing_type = unzip-and-exec.

decrypt_https

Boolean parameter. Specifies whether HTTPS traffic generated by the executed object must be decrypted. Available values:

true—HTTPS traffic generated by the object is decrypted.

false—HTTPS traffic generated by the object is not decrypted.

The HTTPS traffic decryption may decrease the malware detection probability.

By default, decrypt_https = true.

The parameter must not be specified, if you specify exec_env=WinXP.

click_on_links

Boolean parameter (optional). Specifies whether the links in the opened documents must be browsed. Available values:

true—Links in the opened documents are browsed.

false—Links in the opened documents are not browsed.

By default, click_on_links=true.

channel

Region or individual country of a network channel that the object uses to access the internet. There are individual countries among the regions through which the executed file can access the internet.

Use the api/sandbox/channels method to obtain all available values.

Parameter values are case-sensitive.

Description of available values:

TOR—Internet channel belongs to any region and directs traffic through the TOR network.

Tarpit—File is executed without access to the internet.

<region or country name>—Internet channel belongs to any region and does not direct traffic through the TOR network (for example, RU, US, GB).

doc_password

Password to open password-protected documents during execution.

cmd_line

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 $sample variable 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 command in the command line must not exceed 1024 characters, otherwise Kaspersky Threat Intelligence Portal shortens it. Depending on the technical constraints of an operating system that is used as an execution environment in the Sandbox, the command may be further shortened.

Command line usage examples are described in the Appendices.

Request example:

To rescan an uploaded and executed file:

curl -u <user name> --cert <full path to the certificate on your computer> -X PUT --header 'Content-Length: 0' 'https://tip.kaspersky.com/api/sandbox/tasks/file/<task ID>'