Skip to content

Debug Options

Warning

Full support for debugging options is not guaranteed.

They may change on both the library side and the product side.

Don't use them in production code.

When creating any scan task, you can specify DebugOptions to configure the sample launch parameters.

ptsandbox.models.api.analysis.DebugOptions

Bases: TypedDict

Description of all available debugging options for very detailed scan configuration

keep_sandbox instance-attribute 

keep_sandbox: NotRequired[bool]

Don't destroy the sandbox after scanning

skip_work instance-attribute 

skip_work: NotRequired[bool]

Perform a scan, skipping the data collection stage for analysis

extract_crashdumps instance-attribute 

extract_crashdumps: NotRequired[bool]

Extract crashdumps from the sandbox

save_debug_files instance-attribute 

save_debug_files: NotRequired[bool]

Save files necessary for debugging (error logs, tcpdump logs, etc)

rules_url instance-attribute 

rules_url: NotRequired[str]

Use the specified normalization and correlation rules The rules are specified as a link to the archive containing the compiled rules

sleep_work instance-attribute 

sleep_work: NotRequired[bool]

Perform a scan, replacing the data collection stage for analysis with an equivalent waiting time

disable_syscall_hooks instance-attribute 

disable_syscall_hooks: NotRequired[bool]

Disable syscall hooks functionality

Read more about these hooks in documentation

disable_dll_hooks instance-attribute 

disable_dll_hooks: NotRequired[bool]

Disable dll hooks functionality

Read more about these hooks in documentation

disable_correlation instance-attribute 

disable_correlation: NotRequired[bool]

Disable the functionality of normalization and correlation of events.

It is useful if the correlation results are not needed anyway.

In this case, all collected artifacts (drops, memdumps, procdumps) will be included in the response, without filtering at the level of correlation rules

custom_syscall_hooks instance-attribute 

custom_syscall_hooks: NotRequired[str]

Use the specified list of system calls to intercept

The list is transmitted as an http link to a file with the names of system calls

Read more about this file in documentation

custom_dll_hooks instance-attribute 

custom_dll_hooks: NotRequired[str]

Use the specified list of system calls to intercept

The list is transmitted as an http link to a file with the names of dll hooks for apimon plugin

Read more about this file in documentation

disable_retries instance-attribute 

disable_retries: NotRequired[bool]

Disable task re-execution in case of a scan error

enable_sanitizers instance-attribute 

enable_sanitizers: NotRequired[bool]

Enable the debugging mechanisms of the sanitizers group

allowed_outbound_connections instance-attribute 

allowed_outbound_connections: NotRequired[list[str]]

Whitelist of IP addresses to which connections from a VM are allowed (backconnect)

payload_completion_event instance-attribute 

payload_completion_event: NotRequired[str]

A regular expression for the raw DRAKVUF event, signaling the end of the useful work of the sample.

If this option is specified, sandbox-worker will calculate and log the PAYLOAD_SCAN_TIME metric.

disable_procdump_on_finish instance-attribute 

disable_procdump_on_finish: NotRequired[bool]

Disable the functionality of removing the memory dump from the sample at the end of the observation

skip_update_time instance-attribute 

skip_update_time: NotRequired[bool]

Do not synchronize the time in the VM with the host

disable_manual_scan_events instance-attribute 

disable_manual_scan_events: NotRequired[bool]

Do not send lifecycle notifications for manual behavioral analysis (console is ready, console is closed, etc.)

bootkitmon_boot_timeout instance-attribute 

bootkitmon_boot_timeout: NotRequired[int]

The maximum waiting time for VM loading in seconds (90 seconds by default)

custom_procdump_exclude instance-attribute 

custom_procdump_exclude: NotRequired[str]

A file with a list of processes for which memory dumps should not be removed.

Each line in the file is a regular expression of the path to the process file on disk.

Read more about this file in documentation

custom_fileextractor_exclude instance-attribute 

custom_fileextractor_exclude: NotRequired[str]

A file with a list of files that should not be extracted

Each line in the file is a regular expression of the path to the file on disk.

Read more about this file in documentation

validate_plugins instance-attribute 

validate_plugins: NotRequired[bool]

Check plugins for at least one event during the entire behavioral analysis

extra_vm_init_url instance-attribute 

extra_vm_init_url: NotRequired[str]

Run this script in the VM immediately before launching the behavioral analysis.

It is useful, for example, to check the network during analysis.

procdump_lightweight_mode instance-attribute 

procdump_lightweight_mode: NotRequired[bool]

Use "light" memory dumps or not

custom_unimon_hooks instance-attribute 

custom_unimon_hooks: NotRequired[str]

Use a special format for hooks (not stable, will changed in the future)

file_type_as_ext instance-attribute 

file_type_as_ext: NotRequired[bool]

Use a file type as an extension for a file

custom_syscall_hooks

Set a custom list of system calls to intercept.

Be careful: hooking a frequently used syscall can slow down the analysis.

cachestat
chdir
fstat
open
read
write

NtQueryKey
NtQueryLicenseValue
NtQueryObject
NtQueryValueKey
NtRaiseException
NtReadFile
NtSetValueKey
NtShutdownSystem
NtSuspendThread

The full list of system calls:

Usecase

You need to check a unique sample, and the sandbox doesn't track the function of interest.

custom_dll_hooks

This is not well-documented, so use it with caution.

format:

<FunctionName>,log,<PARAM1>:<TYPE1>,<PARAM2>:<TYPE2>

AbortSystemShutdownA,log,lpMachineName:lpstr
AbortSystemShutdownW,log,lpMachineName:lpwstr
InitiateShutdownA,log,lpMachineName:lpstr,lpMessage:lpstr,dwGracePeriod:dword,dwShutdownFlags:shutdown_flags,dwReason:shutdown_reason
waveInOpen,log,phwi:lpvoid,uDeviceID:int,pwfx:lpvoid,dwCallback:lpvoid,dwInstance:lpvoid,fdwOpen:dword

Usecase

You need to check a unique sample, and the sandbox doesn't track the function of interest.

custom_procdump_exclude

Use regular expressions to specify processes that will be ignored during a memory dump.

To check that a regular expression is exactly right, use regex101.com and Golang flavor.

^kworker\/\d:\d$
^\/usr\/bin\/.*$

^\\device\\harddiskvolume\d+\\windows\\system32\\csrss\.exe$

Usecase

Speeds up analysis when you need to ignore flooding processes.

custom_fileextractor_exclude

Use regular expressions to specify files that will be ignored during extraction.

^\/etc\/(nsswitch|host|resolv)\.conf$
^\/lib32\/ld-.*\.so$

^.*\\users\\.*\\appdata\\local\\google\\chrome\\user data\\default\\favicons-journal$
^.*\\windows\\prefetch\\.*$

Usecase

Speeds up analysis when you need to ignore flooding files.