url

Web address from which you want to download a file.

Required parameter.

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 downloaded file or the file contained in the downloaded 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.

file_ext

File extension for the object that is to be executed.

This parameter is obsolete and left for backward compatibility with previous API versions only. Please use the file_name parameter to specify the object extension.

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).

processing_type

Object execution type.

This parameter is obsolete and left for backward compatibility with previous API versions only. The only value to be accepted is unzip-and-exec (object is unpacked before execution).

unzip_password

Optional parameter. Password for an archived object.

Default passwords can be used to unpack an archive.

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.

For automatic channel selection, do not specify this parameter (Any channel option in web interface).

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).

reset_similarity_thresholds

Specifies whether similarity thresholds for compared samples must be ignored. Available values:

true—Similarity thresholds are ignored.

false—Similarity thresholds are not ignored.

unpack

Specifies whether the contents of the executed file must be unpacked for analysis. Available values:

true—File will be unpacked.

false—File will not be unpacked.

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 download and execute file:

curl -u <user name> --cert <full path to the certificate on your computer> -X POST --header 'Content-Length: 0' 'https://tip.kaspersky.com/api/analysis/tasks/file_from_url?url=heritagemfg.com/aaa/sales-reports/images/certificate_3807.exe&file_name=1'