task_id

строка

Обязательно

Идентификатор задачи (GUID), которую требуется выполнить повторно.

exec_env

строка

Необязательно

Операционная система, которую вы хотите использовать в качестве среды выполнения.

Можно указать название любой установленной среды выполнения, включая успешно развернутые пользовательские среды выполнения.

Если указано неверное значение, в описании ошибки invalid-param-exec_env будут возвращены названия всех доступных сред выполнения.

Если данный параметр для файла не указан, Kaspersky Research Sandbox автоматически определяет оптимальную операционную систему в соответствии с типом загружаемого файла (параметр Auto в веб-интерфейсе).

exec_time

целое число

Необязательно

Время выполнения объекта в секундах.

Доступные значения: 30–1800.

Если данный параметр для файла не указан, Kaspersky Research Sandbox автоматически определяет оптимальное время выполнения в зависимости от типа загружаемого файла (параметр Auto в веб-интерфейсе).

Для задачи просмотра веб-адресов по умолчанию указано значение 100.

file_name

строка

Необязательно

Только для выполнения файла.

Имя объекта.

Если указать имя файла и расширение, Kaspersky Research Sandbox не будет определять тип файла автоматически.

Для автоматического определения типа файла во время выполнения укажите только имя файла.

Значение не должно содержать более 240 символов.

url

строка

Необязательно

Только для просмотра веб-адресов.

Веб-адрес для просмотра в песочнице.

Значение не должно содержать более 1000 символов.

guest_directory

строка

Необязательно

Технический обзор.

Только для выполнения файла.

Параметр нельзя использовать в среде выполнения Android.

Каталог, куда будет загружен и выполнен файл-образец.

Значение по умолчанию: %USERPROFILE%\Downloads (если поддерживается) или C:\downloads.

Если каталог является относительным, он будет объединен с каталогом по умолчанию.

unpack_password

строка

Необязательно

Только для выполнения файла.

Если не указать этот параметр для архива, защищенного паролем, Kaspersky Research Sandbox попытается распаковать архив, используя пароли по умолчанию.

doc_password

строка

Необязательно

Только для выполнения файла.

Пароль для защищенных документов. Если этот параметр не указан, используется значение null (без пароля).

decrypt_https

логический

Необязательно

Указывает, необходимо ли расшифровывать HTTPS-трафик, генерируемый выполняемым объектом.

Если выбрана пользовательская среда выполнения на базе Windows XP, параметр decrypt_https указывать не нужно (среда выполнения Windows XP не поддерживает расшифровку трафика SSL).

Доступные значения:

• false – HTTPS-трафик не должен расшифровываться;
• true – HTTPS-трафик должен быть расшифрован.

Значение по умолчанию: false.

Расшифровка HTTPS-трафика может снизить вероятность обнаружения вредоносного ПО.

channel

строка

Необязательно

Имя сетевого канала, который будет использоваться объектом для доступа в интернет. Для автоматического выбора канала не указывайте этот параметр.

Доступные значения:

• Tarpit – эмулирует доступность сети во время выполнения файла без реального доступа в интернет.

  При указании этого значения эмулируется подключение виртуальной машины к любому хосту.

  Канал Tarpit обеспечивает упрощенную эмуляцию следующих протоколов: raw TCP/UDP, HTTP(S), ICMP, DNS.

• Другие параметры, которые были заданы при установке Kaspersky Research Sandbox.

Для автоматического выбора канала не указывайте этот параметр.

debug_report

логический

Необязательно

Указывает, следует ли создавать отчет об отладке для выполняемого файла.

Доступные значения:

• false – отчет об отладке не создается;
• true – создается отчет об отладке.

Значение по умолчанию: false.

Диагностическая информация о производительности приложения получается отдельно.

click_links

логический

Необязательно

Только для выполнения файла.

Указывает, должно ли приложение Kaspersky Research Sandbox просматривать ссылки в документах, которые открываются в песочнице.

Доступные значения:

• false – приложение не должно просматривать ссылки;
• true – приложение должно просматривать ссылки. Указание этого значения может повысить уровень обнаружения вредоносных объектов и их поведения.

Значение по умолчанию: false.

Параметр click_links доступен только в том случае, если выбрана среда выполнения на базе Microsoft Windows. Если вы указали среду выполнения на базе Android (включая пользовательские среды), то значение этого параметра игнорируется во время выполнения файла.

Если данный параметр в запросе не указан, Kaspersky Research Sandbox просматривает ссылки в открываемых документах.

cmd_line

строка

Необязательно

Только для выполнения файла.

Вы можете использовать переменные среды выполнения Windows, поместив знак % перед именем переменной и после него, например: %SYSTEMROOT%.

По умолчанию значения переменных среды выполнения развертываются на хосте пользователя перед передачей и выполнением объекта в песочнице. Чтобы перенести переменные среды выполнения в песочницу как есть, без развертывания, используйте знак %, например: %SYSTEMROOT%.

Командная строка может содержать переменную $sample, которая будет заменена в песочнице на фактический путь к объекту в операционной системе (например, <notepad path> /A $sample).

Длина командной строки не должна превышать 1024 символа, в противном случае Kaspersky Research Sandbox ее сократит. В зависимости от технических ограничений операционной системы, используемой в качестве среды выполнения в песочнице, длина командной строки может быть дополнительно сокращена.

Примеры использования командной строки описаны в Приложениях.

pre_scan

логический

Необязательно

Только для выполнения файла.

Указывает, выполняет ли Kaspersky Research Sandbox полный (как статический, так и динамический) анализ объектов, включая выполнение в песочнице.

Доступные значения:

• false – выполняется полный анализ, объект выполняется в песочнице;
• true – выполняется только статический анализ, объект не выполняется в песочнице. Отчет содержит информацию о выполняемом файле, параметрах выполнения, обнаруженных объектах и содержимом файла, если он является контейнером.

Значение по умолчанию: false.

custom_suricata_rules

строка (двоичная)

Необязательно

Текстовый файл (.txt или .rules) с правилами Suricata.

Рекомендуемый размер файла: 5 МБ. Если размер файла правил Suricata превышает 16 МБ, рекомендуется разбить его на несколько файлов (размером до 5 МБ) и последовательно загрузить их в задачу.

apps_close_timeout

целое число

Необязательно

Технический обзор.

Время ожидания в секундах, по истечении которого приложение, в котором был открыт документ Microsoft Office, будет закрыто.

Доступные значения: 10–1800.

Актуально только для документов Microsoft Office, отправляемых в среды выполнения Windows.

vnc_access

логический

Необязательно

Обеспечивает доступ к VNC к виртуальной машине во время процесса запуска образца в песочнице.

Доступные значения:

• true – доступ к VNC включен;
• false – доступ к VNC отключен.

Доступ к сеансу VNC возможен только через веб-интерфейс.

Если продолжительность сеанса не указана, будет установлено значение 1800 секунд.

vnc_start_sample_automatically

логический

Необязательно

Позволяет немедленно запустить выполнение образца на виртуальной машине, без дополнительных действий пользователя.

Доступные значения:

• true – автоматический запуск включен;
• false – автоматический запуск отключен.

disable_clicker

логический

Необязательно

Отключает кликер для задачи в средах выполнения Windows. Рекомендуется активировать этот параметр при использовании режима VNC.

Доступные значения:

• true – кликер отключен;
• false – кликер включен.

Параметр click_links доступен только при включенном кликере (disable_clicker=false).

rescan_yara

логический

Необязательно

Повторно проверяет образец и другие объекты с использованием новых правил YARA. Требуется загрузка нового файла правил.

rescan_suricata

логический

Необязательно

Повторно проверяет трафик, полученный в указанной задаче, с использованием новых правил Suricata. Требуется загрузка нового файла правил.

Пример команды cURL:

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

Вам будет предложено ввести пароль. Пароль не отображается во время ввода.

id

строка

Идентификатор (GUID) вновь создаваемой задачи выполнения.

Пример ответа 200 OK:

{

"id": "5cf8cbb4-1d50-492c-986b-86d5c7596535"

}

code

строка

Идентификатор ошибки.

message

строка

Описание ошибки.

meta

строка

Дополнительная информация, если таковая имеется.

Примеры ошибок:

Неверный параметр task_id:

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

Загружен пустой файл:

{"code":12,"message":"empty file"}

Неверный параметр chanel:

{"code":22,"message":"wrong channel"}

Неверный формат параметра task_id:

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

Неверный параметр exec-env:

{"code":33,"message":"invalid exec_env, acceptable values listed in meta field","meta":"Win7_x64,Win10_x64,Android_arm,Android_x86,CentOS7_x64"}

Не указан обязательный параметр (например, имя файла):

{"code":34,"message":"no file name or url"}

Неверный параметр exec_time:

{"code":42,"message":"invalid value","meta":"exec_time must be 30...500"}

Неверный параметр decrypt_https:

{"code":42,"message":"invalid value","meta":"decrypt_https must be true or false"}

Неверный параметр debug_report:

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