ducky.debugging module

Virtual machine debugging tools - break points, watch points, etc.

Create “point” that’s triggered when a condition is satisfied (e.g. processor executes instruction on specified address, memory at specified address was modified, etc. Then, create “action” (e.g. suspend core), and bind both pieces together - when point gets triggered, execute list of actions.

class ducky.debugging.Action(logger)

Bases: object

Base class of all debugging actions.

Parameters:logger (logging.Logger) – logger instance used for logging.

act(core, point)

This method is called when “action” is executed. Implement it in child classes to give child actions a functionality.

Parameters:

• core (ducky.cpu.CPUCore) – CPU core where point was triggered.
• point (ducky.debugging.Point) – point that was triggered.

class ducky.debugging.BreakPoint(debugging_set, ip, *args, **kwargs)

Bases: ducky.debugging.Point

static create_from_config(debugging_set, config, section)

is_triggered(core)

class ducky.debugging.DebuggingSet(core)

Bases: object

add_point(p, chain)

post_memory(address=None, read=None)

post_step()

pre_memory(address=None, read=None)

pre_step()

remove_point(p, chain)

class ducky.debugging.LogMemoryContentAction(logger, address, size)

Bases: ducky.debugging.LogValueAction

When triggered, logs content of a specified location in memory.

Parameters:

• logger (logging.Logger) – logger instance used for logging.
• address (u32_t) – memory location.
• size (int) – size of logged number, in bytes.

static create_from_config(debugging_set, config, section)

get_message(core, point)

get_values(core, point)

class ducky.debugging.LogRegisterContentAction(logger, registers)

Bases: ducky.debugging.LogValueAction

When triggered, logs content of a specified register.

Parameters:

• logger (logging.Logger) – logger instance used for logging.
• registers (list) – list of register names.

static create_from_config(debugging_set, config, section)

get_message(core, point)

get_values(core, point)

class ducky.debugging.LogValueAction(logger, size)

Bases: ducky.debugging.Action

This is the base class for actions that log a numerical values.

Parameters:

• logger (logging.Logger) – logger instance used for logging.
• size (int) – size of logged number, in bytes.

act(core, point)

get_message(core, point)

Return message that, formatted with output of get_values(), will be shown to user.

Parameters:

• core (ducky.cpu.CPUCore) – core point was triggered on.
• point (ducky.debugging.Point) – triggered point.

Return type:

string

Returns:

information message.

get_values(core, point)

Prepare dictionary with values for message that will be shown to the user.

Parameters:

• core (ducky.cpu.CPUCore) – core point was triggered on.
• point (ducky.debugging.Point) – triggered point.

Return type:

dict

Returns:

dictionary that will be passed to message format() method.

class ducky.debugging.MemoryWatchPoint(debugging_set, address, read, *args, **kwargs)

Bases: ducky.debugging.Point

static create_from_config(debugging_set, config, section)

is_triggered(core, address=None, read=None)

class ducky.debugging.Point(debugging_set, active=True, countdown=0)

Bases: object

Base class of all debugging points.

Parameters:

• debugging_set (ducky.debugging.DebuggingSet) – debugging set this point belongs to.
• active (bool) – if not True, point is not active and will not trigger.
• countdown (int) – if greater than zero, point has to trigger countdown times before its actions are executed for the first time.

is_triggered(core, *args, **kwargs)

Test point’s condition.

Parameters:core (ducky.cpu.CPUCore) – core requesting the test. Return type:bool Returns:True if condition is satisfied.

class ducky.debugging.SuspendCoreAction(logger)

Bases: ducky.debugging.Action

If executed, this action will suspend the CPU core that triggered its parent point.

act(core, point)

static create_from_config(debugging_set, config, section)

class ducky.debugging.VMDebugInterrupt(machine)

Bases: ducky.interfaces.IVirtualInterrupt

run(core)

class ducky.debugging.VMDebugOperationList

Bases: enum.Enum

LOGGER_VERBOSITY = <VMDebugOperationList.LOGGER_VERBOSITY: 0>

class ducky.debugging.VMVerbosityLevels

Bases: enum.Enum

DEBUG = <VMVerbosityLevels.DEBUG: 0>

ERROR = <VMVerbosityLevels.ERROR: 3>

INFO = <VMVerbosityLevels.INFO: 1>

WARNING = <VMVerbosityLevels.WARNING: 2>

ducky.debugging.cmd_bp_active(console, cmd)

Toggle “active” flag for a breakpoint: bp-active <id>

ducky.debugging.cmd_bp_add_breakpoint(console, cmd)

Create new breakpoint: bp-break <#cpuid:#coreid> <address> [active] [countdown]

ducky.debugging.cmd_bp_add_memory_watchpoint(console, cmd)

Create new memory watchpoint: bp-mwatch <#cpuid:#coreid> <address> [rw] [active] [countdown]’

ducky.debugging.cmd_bp_list(console, cmd)

List existing breakpoints

ducky.debugging.cmd_bp_remove(console, cmd)

Remove breakpoint: bp-remove <id>