Получение списка задач песочницы

from

целое число

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

Указывает количество записей, которые следует пропустить в возвращаемом списке задач.

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

count

целое число

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

Максимальное количество возвращаемых записей.

Доступные значения: 1–1500 (включая предельные значения).

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

status

строка

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

Фильтрует записи по состоянию задачи.

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

• uploading – возвращает задачи, для которых в данный момент выполняется загрузка файлов.
• upload failed – возвращает задачи, для которых не удалось загрузить файлы.
• created – возвращает успешно созданные задачи.
• processing – возвращает задачи, которые в данный момент обрабатываются.
• completed – возвращает успешно завершенные задачи.
• deleted – возвращает удаленные задачи.
• failed – возвращает невыполненные задачи.
• disposed – возвращает устаревшие задачи.

environment

строка

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

Фильтрует записи по используемой среде выполнения.

sort_by

строка

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

Сортирует записи по следующим параметрам.

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

• size – сортирует задачи по размеру загруженных файлов.
• created – сортирует задачи по дате и времени их создания.
• analyzed – сортирует задачи по дате и времени завершения анализа.

descending

логический

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

Сортирует записи в порядке убывания или возрастания:

• true – сортирует записи в порядке убывания.
• false – сортирует записи в порядке возрастания.

zone

строка

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

Фильтрует записи по зоне образца.

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

• Red – высокий уровень опасности, образец имеет статус Malware или Dangerous.
• Orange – средний уровень опасности, образец имеет статус Not trusted (только для IP-адресов, доменов и веб-адресов).
• Yellow – средний уровень опасности, образец имеет статус Adware and other (только для файлов).
• Grey – образец имеет статус Not categorized.
• Green – низкий уровень опасности. Образец имеет статус Clean/Good или No threats detected.

yara

логический

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

Фильтрует записи по наличию загруженного файла YARA.

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

• true – файл YARA был загружен.
• false – файл YARA не был загружен.

suricata

логический

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

Фильтрует записи по наличию загруженного файла Suricata.

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

• true – файл Suricata был загружен.
• false – файл Suricata не был загружен.

vnc

логический

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

Фильтрует записи по использованию режима VNC.

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

• true – режим VNC используется.
• false – режим VNC не используется.

extension

строка

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

Фильтрует записи по расширению образца (точное совпадение). Длина параметра должна составлять от 1 до 100 символов.

size_from

целое число

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

Фильтрует записи по минимальному размеру образца (в байтах).

size_to

целое число

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

Фильтрует записи по максимальному размеру образца (в байтах).

created_from

целое число

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

Фильтрует записи по минимальной дате создания задачи. Дата должна быть указана в системе меток времени UNIX.

created_to

целое число

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

Фильтрует записи по максимальной дате создания задачи. Дата должна быть указана в системе меток времени UNIX.

search

строка

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

Ищет определенные строки в образце (file_name, URL, md5, sha1, sha256).

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

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

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

Count

целое число

Общее количество задач.

Items

массив объектов

Подробности задачи выполнения файла или просмотра веб-адреса.

Created

строка <дата-время>

Дата и время создания задачи, указанные в формате ISO 8601:2004 (ГГГГ-ММ-ДДTчч:мм:ссZ).

Processed

строка <дата-время>

Дата и время завершения анализа результатов, указанные в формате ISO 8601:2004 (ГГГГ-ММ-ДДTчч:мм:ссZ).

Status

строка

Статус выполняемого файла или веб-адреса.

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

• Unknown – задача выполнения завершена; информации о состоянии нет.
• Clean – задача выполнения завершена; образец не является вредоносным.
• Malware – задача выполнения завершена; образец является вредоносным ПО (только для файлов).
• Dangerous – задача выполнения завершена; образец опасен (только для веб-адресов).
• Not trusted – задача выполнения завершена; образец не является доверенным (только для веб-адресов).
• NotAVirus – задача выполнения завершена; образец является легитимным, но заражен или скомпрометирован на момент анализа (Adware and other, только для файлов).

Для задач со статусом, отличным от completed, возвращается значение unknown.

zone

строка

Цвет зоны файла или веб-адреса (Red, Orange, Yellow, Grey, Green).

AvBasesVersion

строка <дата-время>

Дата и время последнего обновления антивирусных баз, указанные в формате ISO 8601:2004 (ГГГГ-ММ-ДДTчч:мм:ссZ).

TaskId

строка

Идентификатор задачи (GUID).

ResultID

строка

Идентификатор результата.

TaskState

строка

Состояние задачи выполнения файла или просмотра веб-адреса.

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

• Uploading – выполняется загрузка файла.
• Created – задача создана.
• Processing – задача выполняется, объект все еще выполняется.
• Completed – задача успешно завершена.
• Deleted – задача удалена.
• Failed – не удалось выполнить файл или просмотр веб-адреса.
• UploadFailed – не удалось загрузить файл (например, размер файла превышает максимальный).
• Disposed – задача удалена автоматически.
• Completed.VNCRecomended – задача завершена, но доступны только результаты статического анализа. Для получения большего количества результатов рекомендуется использовать режим VNC.
• Completed.StaticAnalysisOnly – задача завершена. Доступны только результаты статического анализа.
• Completed.RecommendedImagesIsNotInstalled – задача выполнена. Среда выполнения Microsoft Windows не установлена.
• Completed.FileTypeIsNotAssociated – задача завершена. Формат файла образца не может быть обработан в выбранной среде выполнения.
• Completed.VNCIsNotSupported – задача завершена. Режим VNC не поддерживается.

ErrorCode

строка

Код ошибки.

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

• ProcessingFailed – ошибка во время выполнения объекта.
• WrongPassword – не удалось распаковать архив из-за неверного пароля.
• InvalidFileSize – размер распакованного объекта превышает ограничение.
• SandboxBusy – песочница перегружена.
• UnknownFileType – неизвестный тип загруженного файла.
• UnpackFailed – не удалось распаковать архив.

ErrorMessage

строка

Сообщение об ошибке.

OriginalFileName

строка

Исходное имя загруженного файла.

FileName

строка

Имя загруженного файла.

Url

строка

Веб-адрес, просмотренный в песочнице.

ArchiveSampleName

строка

Имя загруженного архива.

FileExtension

строка

Расширение выполняемого файла (например js).

FileType

строка

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

Md5

строка

MD5-хеш исполняемого файла.

Sha1

строка

SHA1-хеш исполняемого файла.

Sha256

строка

SHA256-хеш исполняемого файла.

SSDeep

строка

SSDeep-хеш выполняемого объекта.

VirtualMachineId

строка

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

UnpackPassword

строка

Пароль для архива.

FileSize

целое число

Размер исполняемого файла в байтах.

EmulationTimeSeconds

целое число

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

Detects

массив

Список обнаруженных объектов:

• detectTechnology – технология, которая использовалась для обнаружения объекта.
• isNotAVirus – указывает, является ли обнаруженный объект вредоносным.
• severity – уровень опасности обнаруженного объекта.
• threat – название обнаруженного объекта.

screenshots

массив

Список созданных снимков экрана.

DecryptHTTPS

логический

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

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

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

PreScan

логический

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

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

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

PreScanState

логический

Состояние этапа статического анализа:

• CalcParam – логический параметр. Указывает, завершен ли расчет параметров.
• AvsScan – логический параметр. Указывает, завершена ли проверка объекта.
• statPars – логический параметр. Указывает, завершен ли статический анализ.

Channel

строка

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

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

• Tarpit – эмулирует доступность сети во время выполнения файла без реального доступа в интернет. При указании этого значения эмулируется подключение виртуальной машины к любому хосту. Канал Tarpit позволяет выполнять упрощенную эмуляцию следующих протоколов: raw TCP/UDP, HTTP(S), ICMP, DNS.
• Другие параметры, которые были заданы при установке Kaspersky Research Sandbox.

UsedChannel

строка

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

IsDataAvailable

логический

Указывает, имеются ли данные отчета для задачи.

DebugReport

логический

Указывает, был ли создан отчет об отладке.

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

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

CmdLineParams

строка

Параметры командной строки, которые использовались для выполнения объекта в песочнице.

ClickLinks

логический

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

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

• false – приложение не просматривало ссылки.
• true – приложение просматривало ссылки.

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

Однако результаты задачи содержат указанное вами значение click_links.

DocPassword

строка

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

SampleType

строка

Тип образца.

CalculatedParams

массив объектов

Автоматически рассчитанные параметры выполнения:

• ExecEnv – среда выполнения объекта.
• ExecTime – время выполнения объекта.

ThreatScore

целое число

Оценка угрозы объектов, основанная на показателях и данных, полученных в ходе выполнения задачи.

AppsCloseTimeout

целое число

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

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

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

Userscan

массив объектов

Статус задачи проверки YARA и Suricata для объекта и его извлеченных файлов:

Yara:

• Status – статус сработавшего правила YARA (см. описание ниже).
• Filename – имя загруженного файла, содержащего правила YARA.
• ScanningTime – дата и время срабатывания правила YARA.

Suricata:

• Status – статус сработавшего правила Suricata, см. описание ниже.
• Filename – имя загруженного файла, содержащего правила Suricata.
• ScanningTime – дата и время срабатывания правила Suricata.

Возможные значения параметра Status для правил YARA и Suricata:

• not scanned – правила не были отправлены.
• created – задача проверки создана.
• scanning – выполняется задача проверки.
• matched – проверка успешно завершена, есть обнаружения.
• truncated – проверка Suricata успешно завершена, есть обнаружения. Некоторые результаты были удалены: осталось не более 50 000 записей, не более 25 совпадений на правило. Этот статус возвращается только для правил Suricata, результаты проверки с использованием правил YARA не фильтруются.
• not matched – проверка успешно завершена, обнаружений нет.
• syntax error – правила не проверяются регулярным выражением.
• processing error – произошла ошибка в процессе проверки с использованием проверенных правил. Могут быть обнаружения.

VncAccess

логический

Указывает, использовался ли для задачи доступ к VNC.

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

• true – доступ к VNC использовался.
• false – доступ к VNC не использовался.

VncSampleAutostart

логический

Указывает, был ли включен автоматический запуск образца в режиме VNC.

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

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

VncStarted

string

Дата и время запуска VNC для задачи.

VncTimeLeft

string

Время до отключения доступа к VNC, в секундах.

VncStatus

логический

Указывает, активен ли в данный момент VNC для задачи.

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

• true – VNC в данный момент активен.
• false – VNC в данный момент неактивен.

DisableClicker

логический

Указывает, был ли отключен кликер в режиме VNC.

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

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

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

{

"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

строка

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

message

строка

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

meta

строка

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

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

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

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

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

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