from

integer

Optional

Specifies the number of entries to skip in the returned task list.

Default value: 0.

count

integer

Optional

Maximum number of entries to return.

Available values: 1–1500 (including limit values).

Default value: 500.

status

string

Optional

Filters entries by task state.

Available values:

• uploading—Returns tasks for which files are currently uploading.
• upload failed—Returns tasks for which file upload failed.
• created—Returns successfully created tasks.
• processing—Returns tasks that are currently processing.
• completed—Returns successfully completed tasks.
• deleted—Returns deleted tasks.
• failed—Returns failed tasks.
• disposed—Returns disposed tasks.

environment

string

Optional

Filters entries by used execution environment.

sort_by

string

Optional

Sorts entries by the following parameters.

Available values:

• size—Sorts tasks by uploaded file sizes.
• created—Sorts tasks by date and time when they were created.
• analyzed—Sorts tasks by date and time when analysis was completed.

descending

boolean

Optional

Sorts entries in descending or ascending order:

• true—Sorts entries in descending order.
• false—Sorts entries in ascending order.

zone

string

Optional

Filters entries by the sample zone.

Available values:

• Red—High danger level, sample is Malware or Dangerous.
• Orange—Medium danger level, sample is Not trusted (for IP addresses, domains and web addresses only).
• Yellow—Medium danger level, sample is Adware and other (for files only).
• Grey—Sample is Not categorized.
• Green—Low danger level. Sample is Clean/Good or No threats detected.

yara

boolean

Optional

Filters entries by the presence of uploaded YARA file.

Available values:

• true—YARA file was uploaded.
• false—YARA file was not uploaded.

suricata

boolean

Optional

Filters entries by the presence of uploaded Suricata file.

Available values:

• true—Suricata file was uploaded.
• false—Suricata file was not uploaded.

vnc

boolean

Optional

Filters entries by VNC mode usage.

Available values:

• true—VNC mode is used.
• false—VNC mode is not used.

extension

string

Optional

Filters entries by the sample extension (exact match). Parameter length must be 1-100 characters.

size_from

integer

Optional

Filters entries by minimum sample size (in bytes).

size_to

integer

Optional

Filters entries by maximum sample size (in bytes).

created_from

integer

Optional

Filters entries by minimum task creation date. Date must be specified in the UNIX time stamp system.

created_to

integer

Optional

Filters entries by maximum task creation date. Date must be specified in the UNIX time stamp system.

search

string

Optional

Searches for a certain string in the sample (file_name, url, md5, sha1, sha256).

cURL command sample:

$ curl --user <user name> --request GET 'https://<server name>/api/v1/sandbox/tasks?from=<from tasks>&count=<count tasks>'

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

Count

integer

Total number of tasks.

Items

array of objects

File execution or web address browsing task details.

Created

string <date-time>

Date and time when the task was created, specified in the ISO 8601:2004 format (YYYY-MM-DDThh:mm:ssZ).

Processed

string <date-time>

Date and time when analysis of results was completed, specified in the ISO 8601:2004 format (YYYY-MM-DDThh:mm:ssZ).

Status

string

Status of the executed file or web address.

Available values:

• Unknown—Execution task is completed; no information about the able.
• Clean—Execution task is completed; sample is not malicious.
• Malware—Execution task is completed; sample is malware (for files only).
• Dangerous—Execution task is completed; sample is dangerous (for web addresses only).
• Not trusted—Execution task is completed; sample is not trusted (for web addresses only).
• NotAVirus—Execution task is completed; sample is legitimate but infected or compromised at the moment of the analysis (Adware and other, for files only).

For tasks with status other than completed, the value unknown is returned.

zone

string

Color of the file or web address zone (Red, Orange, Yellow, Grey, Green).

AvBasesVersion

string <date-time>

Date and time when anti-virus bases were last updated, specified in the ISO 8601:2004 format (YYYY-MM-DDThh:mm:ssZ).

TaskId

string

Task ID (GUID).

ResultID

string

Result ID.

TaskState

string

File execution or web address browsing task state.

Available values:

• Uploading—File is being uploaded.
• Created—Task is created.
• Processing—Task is in progress, the object is still being executed.
• Completed—Task is successfully completed.
• Deleted—Task is deleted.
• Failed—Failed to execute the file or browse the web address.
• UploadFailed—File upload failed (for example, file exceeds the maximum size).
• Disposed—Task is deleted automatically.
• Completed.VNCRecomended—Task is completed, but only static analysis results are available. VNC mode is recommended to obtain more results.
• Completed.StaticAnalysisOnly—Task is completed. Only static analysis results are available.
• Completed.RecommendedImagesIsNotInstalled—Task is completed. Microsoft Windows environment is not installed.
• Completed.FileTypeIsNotAssociated—Task is completed. The sample's file format cannot be processed in the selected environment.
• Completed.VNCIsNotSupported—Task is completed. VNC mode is not supported.

ErrorCode

string

Error code.

Available values:

• ProcessingFailed—Error occurred during object execution.
• WrongPassword—Failed to unzip the archive due to incorrect password.
• InvalidFileSize—Unzipped object exceeds a size limit.
• SandboxBusy—Sandbox is overloaded.
• UnknownFileType—Unknown type of uploaded file.
• UnpackFailed—Failed to unzip the archive.

ErrorMessage

string

Error message.

OriginalFileName

string

Original name of the uploaded file.

FileName

string

Name of the uploaded file.

Url

string

Web address browsed in Sandbox.

ArchiveSampleName

string

Name of the uploaded archive.

FileExtension

string

Extension of the executed file (for example, js).

FileType

string

Automatically detected type of executed file.

Md5

string

MD5 hash of the executed file.

Sha1

string

SHA1 hash of the executed file.

Sha256

string

SHA256 hash of the executed file.

SSDeep

string

SSDeep hash of the executed object.

VirtualMachineId

string

Operating system that was used as an execution environment.

UnpackPassword

string

Password for the archive.

FileSize

integer

Size of the executed file in bytes.

EmulationTimeSeconds

integer

File execution or web address browsing time in seconds.

Detects

array

List of detected objects:

• detectTechnology—Technology that was used to detect the object.
• isNotAVirus—Indicates whether the detected object is malicious.
• severity—Danger level of the detected object.
• threat—Detected object name.

screenshots

array

List of created screenshots.

DecryptHTTPS

boolean

Indicates whether HTTPS traffic generated by the executed file or web address was decrypted.

Available values:

• false—HTTPS traffic was not decrypted.
• true—HTTPS traffic was decrypted.

PreScan

boolean

Indicates whether full (both static and dynamic) object analysis (including execution in the Sandbox) was performed.

Available values:

• false—Full analysis was performed, the object was executed in the Sandbox.
• true—Only static analysis was performed, the object was 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.

PreScanState

boolean

State of the static analysis stage:

• CalcParam—Boolean parameter. Indicates whether the parameters calculation is completed.
• AvsScan—Boolean parameter. Indicates whether the object scan is completed.
• statPars—Boolean parameter. Indicates whether static analysis is completed.

Channel

string

Name of the network channel 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 makes simplified emulation of the following protocols: raw TCP/UDP, HTTP(S), ICMP, DNS.
• Other options that were set during Kaspersky Research Sandbox installation.

UsedChannel

string

Name of the network channel that the object actually used to access the internet (for example, US).

IsDataAvailable

boolean

Indicates whether if there is report data for the task.

DebugReport

boolean

Indicates whether a debug report was generated.

Available values:

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

CmdLineParams

string

Command line parameters used to execute the object in the Sandbox.

ClickLinks

boolean

Indicates whether Kaspersky Research Sandbox browsed the links in the opened documents.

Available values:

• false—Application did not browse the links.
• true—Application browsed the links.

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

However, the task results contain the click_links value that you specified.

DocPassword

string

Password for the protected document. If the password is not specified, the value of this parameter is null.

SampleType

string

Type of a sample.

CalculatedParams

array of objects

Automatically calculated execution parameters:

• ExecEnv—Object execution environment.
• ExecTime—Object execution time.

ThreatScore

integer

Threat score of objects, which is based on metrics and data obtained during task execution.

AppsCloseTimeout

integer

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.

Userscan

array of objects

The status of the YARA and Suricata scan task of the object and its extracted files:

Yara:

• Status—Status of the triggered YARA rule (see description below).
• Filename—Name of the uploaded file that contains YARA rules.
• ScanningTime—Date and time when the YARA rule triggered.

Suricata:

• Status—Status of the triggered Suricata rule (see description below).
• Filename—Name of the uploaded file that contains Suricata rules.
• ScanningTime—Date and time when the Suricata rule triggered.

Possible Status values for YARA and Suricata rules:

• not scanned—Rules were not submitted.
• created—Scan task created.
• scanning—Scan task is in progress.
• matched—Scan completed successfully, there are detections.
• truncated—Suricata scan completed successfully, there are detections. Some results have been removed: no more than 50,000 records remain, no more than 25 hits per rule. This status is returned for Suricata rules only, YARA rule scan results are not filtered.
• not matched—Scan completed successfully, there are no detections.
• syntax error—Rules are not validated by regular expression.
• processing error—Error occurred during scan process with validated rules. There may be detections.

VncAccess

boolean

Indicates whether the VNC access was used for the task.

Available values:

• true—VNC access was used.
• false—VNC access was not used.

VncSampleAutostart

boolean

Indicates whether automatic sample start was enabled in the VNC mode.

Available values:

• true—Automatic sample start was enabled.
• false—Automatic sample start was not enabled.

VncStarted

string

Date and time when VNC was started for the task.

VncTimeLeft

string

Time till the VNC access will be disabled, in seconds.

VncStatus

boolean

Indicates if VNC is currently active for the task.

Available values:

• true—VNC is currently active.
• false—VNC is currently inactive.

DisableClicker

boolean

Indicates whether clicker was disabled in the VNC mode.

Available values:

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

200 OK response example:

{

"Created": "2024-11-07T12:07:01.782394Z",

"Processed": null,

"Status": "Unknown",

"Zone": "Grey",

"AvBasesVersion": "2024-11-06T10:41:00Z",

"TaskId": "f84e985f-...-94d83721a465",

"ResultID": "",

"TaskState": "Processing",

"ErrorCode": "",

"ErrorMessage": "",

"OriginalFileName": "original-file.rar",

"FileName": "original-file.exe",

"ArchiveSampleName": "original-file",

"FileExtension": "exe",

"FileType": "exe x32",

"Md5": "86f...a2df",

"Sha1": "252...530a7",

"Sha256": "a6e226fa06...fd0b988",

"SSDeep": "3072:yM...pcs...GQkxVj:yHv...Vj",

"VirtualMachineId": "Win10_x64",

"UnpackPassword": "",

"FileSize": 135705,

"EmulationTimeSeconds": 1800,

"Detects": [],

"Screenshots": null,

"DecryptHttps": true,

"PreScan": false,

"PreScanState": {

"CalcParam": true,

"AvsScan": true,

"StatPars": true

},

"Channel": "",

"UsedChannel": {

"ID": 0,

"Name": "",

"Available": false,

"Description": ""

},

"IsDataAvailable": true,

"DebugReport": false,

"Url": "",

"CmdLineParams": "",

"ClickLinks": false,

"DocsPassword": "",

"SampleType": "single_file_arch",

"CalculatedParams": {

"ExecEnv": "Win10_x64",

"ExecTime": 1800

},

"ThreatScore": 0,

"AppsCloseTimeout": 0,

"Userscan": {

"Yara": {

"Status": "not scanned",

"Filename": "",

"ScanningTime": null

},

"Suricata": {

"Status": "not scanned",

"Filename": "",

"ScanningTime": null

}

},

"VncAccess": true,

"VncSampleAutostart": false,

"VncStarted": null,

"VncTimeLeft": 0,

"VncStatus": 0,

"DisableClicker": true

}

code

string

Error ID.

message

string

Error description.

meta

string

Additional information, if available.

Error examples:

Incorrect count parameter:

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

Incorrect from parameter:

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