Rescan a downloaded file task (Sandbox)

Expand all | Collapse all

The /sandbox/tasks/file_from_url/{task ID} endpoint is used to repeat a file execution task in Kaspersky Sandbox.

When creating a rescan task, the file will be downloaded again.

Request

Request method: PUT

Endpoint: https://tip.kaspersky.com/api/sandbox/tasks/file_from_url/{task_id}

Query parameters:

Expected parameters

Parameter

Description

task_id

Object execution task ID that you want to restart.

If necessary, you can change the object execution parameters. If the following parameters are not specified, previously specified values are used.

Optional expected parameters

Parameter

Description

url

Web address from which you want to download a file.

Required parameter.

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: 30500.

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_ext

File extension for the object that is to be executed.

Must be specified without the dot, because it is added to the full object file name automatically. The value must not exceed 10 symbols.

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.

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 a downloaded 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_from_url/<task ID>'

Responses

200 OK

401 Unauthorized

403 Forbidden

404 Not Found

451 Unavailable For Legal Reasons

Page top