task_id

string

Required

Object execution task ID (GUID).

cURL command sample:

$ curl --user <user name> --request GET 'https://<server name>/api/v1/sandbox/tasks/<task ID>'

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

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.

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.

If an incorrect value is specified, titles of all available environments will be returned in the invalid-param-exec_env error description.

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.

Url

string

Web address browsed in Sandbox.

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 for file example:

{

"Created": "2024-11-07T12:25:48.845463Z",

"Processed": "2024-11-07T12:42:17.656575Z",

"Status": "Malware",

"Zone": "Red",

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

"TaskId": "5dd567...e164f6f9",

"ResultID": "",

"TaskState": "Completed",

"ErrorCode": "",

"ErrorMessage": "",

"OriginalFileName": "file.rar",

"FileName": "file.exe",

"ArchiveSampleName": "file",

"FileExtension": "exe",

"FileType": "exe x32",

"Md5": "86f205f...a2df",

"Sha1": "252be6e...d4530a7",

"Sha256": "a6e226f...0b988",

"SSDeep": "3072:yM1ypc...GQkxVj:yHv6X...IVj",

"VirtualMachineId": "Win10_x64",

"UnpackPassword": "",

"FileSize": 135705,

"EmulationTimeSeconds": 1800,

"Detects": [

{

"IsNotAVirus": false,

"Threat": "Backdoor.Win32.Zebrocy.sb",

"Severity": 800,

"DetectTechnology": "SBscaner"

},

{

"IsNotAVirus": false,

"Threat": "Trojan.Win32.KL_APT_TEST_DETECT.gen",

"Severity": 800,

"DetectTechnology": "SBscaner"

},

{

"IsNotAVirus": false,

"Threat": "Trojan.Win32.Reconyc.sb",

"Severity": 800,

"DetectTechnology": "SBscaner"

}

],

"Screenshots": [

{

"FullName": "0.wnd.scr.png",

"PreviewName": "0.wnd.prv.png"

},

{

"FullName": "1.wnd.scr.png",

"PreviewName": "1.wnd.prv.png"

},

{

"FullName": "2.wnd.scr.png",

"PreviewName": "2.wnd.prv.png"

},

{

"FullName": "3.wnd.scr.png",

"PreviewName": "3.wnd.prv.png"

}

],

"DecryptHttps": true,

"PreScan": false,

"PreScanState":

{

"CalcParam": true,

"AvsScan": true,

"StatPars": false

},

"Channel": "",

"UsedChannel":

{

"ID": 1,

"Name": "Beeline_ODC1_01",

"Available": true,

"Description": "Beeline_ODC1_01"

},

"IsDataAvailable": true,

"DebugReport": false,

"Url": "",

"CmdLineParams": "",

"ClickLinks": false,

"DocsPassword": "",

"SampleType": "single_file_arch",

"CalculatedParams":

{

"ExecEnv": "Win10_x64",

"ExecTime": 1800

},

"ThreatScore": 97,

"AppsCloseTimeout": 0,

"Userscan": {

"Yara": {

"Status": "not scanned",

"Filename": "",

"ScanningTime": null

},

"Suricata": {

"Status": "not scanned",

"Filename": "",

"ScanningTime": null

}

},

"VncAccess": true,

"VncSampleAutostart": true,

"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 task_id parameter:

{"code":6,"message":"task not found"}

Incorrect task_id parameter format:

{"code":29,"message":"bad task id"}