Create a file upload and execution task (Sandbox and TAE)

Expand all | Collapse all

The /analysis/tasks/file endpoint is used to create a new execution task for an uploaded file both in Kaspersky Sandbox and Cloud Threat Attribution Engine.

Request

Request method: POST

Endpoint: https://tip.kaspersky.com/api/analysis/tasks/file

Query parameters:

Expected parameters

Parameter

Description

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

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.

Request example:

Upload and execute file:

curl -u <user name> --cert <full path to the certificate on your computer> -X POST -H 'Content-Type: application/octet-stream' --data-binary @'<path and file name>' 'https://tip.kaspersky.com/api/analysis/tasks/file?file_name=<file name>&exec_env=Win7&exec_time=240'

Responses

200 OK

400 Bad Request

401 Unauthorized

403 Forbidden

413 Payload Too Large (previously called "Request Entity Too Large")

451 Unavailable For Legal Reasons

Page top