winappdbg.breakpoint

This submodule controls breakpoints logic. There are two layers to this API, a lower level and a higher level.

class winappdbg.breakpoint.ApiHook(eventHandler, modName, procName, paramCount=None, signature=None)

Used by EventHandler.

This class acts as an action callback for code breakpoints set at the beginning of a function. It automatically retrieves the parameters from the stack, sets a breakpoint at the return address and retrieves the return value from the function call.

See also

winappdbg.event.EventHandler.apiHooks

Variables:

modName (str) – Module name.
procName (str) – Procedure name.

hook(debug, pid, bpTypeEntry=None, bpTypeReturn=None)

Installs the API hook on a given process and module.

Warning

Do not call from an API hook callback.

Parameters:

debug (Debug) – Debug object.
pid (int) – Process ID.

unhook(debug, pid)

Removes the API hook from the given process and module.

Warning

Do not call from an API hook callback.

Parameters:

debug (Debug) – Debug object.
pid (int) – Process ID.

class winappdbg.breakpoint.Breakpoint(address, size=1, condition=True, action=None)

Base class for breakpoints. Here’s the breakpoints state machine.

Variables:

DISABLED – Disabled -> Enabled, OneShot
ENABLED – Enabled -> Running, Disabled
ONESHOT – OneShot -> Disabled
RUNNING – Running -> Enabled, Disabled
stateNames – User-friendly names for each breakpoint state.
typeName – User friendly breakpoint type string.

disable(aProcess, aThread)

Disables a breakpoint.

Parameters:

aProcess (Process) – Process that contains the breakpoint.
aThread (Thread) – Current thread.

Raises:

RuntimeError – The breakpoint was not in an active state.

enable(aProcess, aThread)

Enables a breakpoint.

Parameters:

aProcess (Process) – Process that contains the breakpoint.
aThread (Thread) – Current thread.

Raises:

RuntimeError – The breakpoint was already enabled.

eval_condition(event)

Evaluate the condition callback for this breakpoint.

Parameters:: event (Event) – Event that triggered this breakpoint.
Return type:: bool
Returns:: True to dispatch the event, False otherwise.

get_action()

Return type:: callable
Returns:: The action callback function for this breakpoint.

get_address()

Return type:: int
Returns:: The target memory address for the breakpoint.

get_condition()

Return type:: callable
Returns:: The condition callback function. Returns True for unconditional breakpoints.

get_size()

Return type:: int
Returns:: Size of breakpoint in bytes.

get_span()

Get the range of memory addresses for this breakpoint.

Return type:: tuple( int, int )
Returns:: Tuple containing the first and last memory addresses.

get_state()

Return type:: int
Returns:: The current state of the breakpoint.

get_state_name()

Return type:: str
Returns:: The user-friendly name for the current state of the breakpoint.

hit(event)

This method is called when the breakpoint is hit. It evaluates the breakpoint’s condition and automatically disables it if it’s a one-shot breakpoint.

Parameters:: event (Event) – Event that triggered this breakpoint.
Raises:: RuntimeError – An unexpected error occurred.

is_automatic()

Return type:: bool
Returns:: True if this breakpoint is automatic.

is_conditional()

Check if this is a conditional breakpoint. A breakpoint is conditional if a callback function was set.

Return type:: bool
Returns:: True if this is a conditional breakpoint.

is_disabled()

Return type:: bool
Returns:: True if the breakpoint is in DISABLED state.

is_enabled()

Return type:: bool
Returns:: True if the breakpoint is in ENABLED state.

is_here(address)

Return type:: bool
Returns:: True if the address is within the range of the breakpoint.

is_interactive()

Return type:: bool
Returns:: True if this breakpoint is interactive.

is_one_shot()

Return type:: bool
Returns:: True if the breakpoint is in ONESHOT state.

is_running()

Return type:: bool
Returns:: True if the breakpoint is in RUNNING state.

is_unconditional()

Return type:: bool
Returns:: True if this is not a conditional breakpoint.

one_shot(aProcess, aThread)

Sets a breakpoint for one shot.

Parameters:

aProcess (Process) – Process that contains the breakpoint.
aThread (Thread) – Current thread.

Raises:

RuntimeError – The breakpoint was already enabled.

run_action(event)

Run the action callback for this breakpoint.

Parameters:: event (Event) – Event that triggered this breakpoint.

running(aProcess, aThread)

Puts the breakpoint in running state. This happens when a breakpoint is hit and it’s condition evaluates to False.

Parameters:

aProcess (Process) – Process that contains the breakpoint.
aThread (Thread) – Current thread.

Raises:

RuntimeError – The breakpoint was not enabled.

set_action(action=None)

Set the action callback function for this breakpoint.

Parameters:: action (callable) – Action callback function.

set_condition(condition=True)

Set the condition callback function for this breakpoint.

Parameters:: condition (callable) – Condition callback function.

exception winappdbg.breakpoint.BreakpointCallbackWarning: This warning is issued when an uncaught exception was raised by a breakpoint’s user-defined callback.

exception winappdbg.breakpoint.BreakpointWarning: This warning is issued when a non-fatal error occurs that’s related to breakpoints.

class winappdbg.breakpoint.BufferWatch(pid, start, end, action=None, oneshot=False)

Returned by watch_buffer().

This object uniquely references a buffer being watched, even if there are multiple watches set on the exact memory region.

Variables:

pid (int) – Process ID.
start (int) – Memory address of the start of the buffer.
end (int) – Memory address of the end of the buffer.
action (callable) – Action callback.
oneshot (bool) – True for one shot breakpoints, False otherwise.

match(address)

Determine if the given memory address lies within the watched buffer.

Parameters:: address (int) – Memory address to check.
Return type:: bool
Returns:: True if the given memory address lies within the watched buffer, False otherwise.

class winappdbg.breakpoint.CodeBreakpoint(address, arch=None, condition=True, action=None)

Code execution breakpoints (using an int3 opcode).

See also

break_at()

disable(aProcess, aThread)

Disables a breakpoint.

Parameters:

aProcess (Process) – Process that contains the breakpoint.
aThread (Thread) – Current thread.

Raises:

RuntimeError – The breakpoint was not in an active state.

enable(aProcess, aThread)

Enables a breakpoint.

Parameters:

aProcess (Process) – Process that contains the breakpoint.
aThread (Thread) – Current thread.

Raises:

RuntimeError – The breakpoint was already enabled.

one_shot(aProcess, aThread)

Sets a breakpoint for one shot.

Parameters:

aProcess (Process) – Process that contains the breakpoint.
aThread (Thread) – Current thread.

Raises:

RuntimeError – The breakpoint was already enabled.

running(aProcess, aThread)

Puts the breakpoint in running state. This happens when a breakpoint is hit and it’s condition evaluates to False.

Parameters:

aProcess (Process) – Process that contains the breakpoint.
aThread (Thread) – Current thread.

Raises:

RuntimeError – The breakpoint was not enabled.

class winappdbg.breakpoint.HardwareBreakpoint_x86(address, triggerFlag=3, sizeFlag=3, condition=True, action=None)

Hardware breakpoint (using debug registers) for x86/x64 architectures.

See also

watch_variable()

Variables:

BREAK_ON_EXECUTION – Break on execution.
BREAK_ON_WRITE – Break on write.
BREAK_ON_ACCESS – Break on read or write.
WATCH_BYTE – Watch a byte.
WATCH_WORD – Watch a word (2 bytes).
WATCH_DWORD – Watch a double word (4 bytes).
WATCH_QWORD – Watch one quad word (8 bytes).
validTriggers – Valid trigger flag values.
validWatchSizes – Valid watch flag values.

disable(aProcess, aThread)

Disables a breakpoint.

Parameters:

aProcess (Process) – Process that contains the breakpoint.
aThread (Thread) – Current thread.

Raises:

RuntimeError – The breakpoint was not in an active state.

enable(aProcess, aThread)

Enables a breakpoint.

Parameters:

aProcess (Process) – Process that contains the breakpoint.
aThread (Thread) – Current thread.

Raises:

RuntimeError – The breakpoint was already enabled.

get_slot()

Return type:: int
Returns:: The debug register slot used by this breakpoint.

get_trigger()

Return type:: int
Returns:: The trigger flag for this breakpoint.

get_watch()

Return type:: int
Returns:: The watch size flag for this breakpoint.

one_shot(aProcess, aThread)

Sets a breakpoint for one shot.

Parameters:

aProcess (Process) – Process that contains the breakpoint.
aThread (Thread) – Current thread.

Raises:

RuntimeError – The breakpoint was already enabled.

running(aProcess, aThread)

Puts the breakpoint in running state. This happens when a breakpoint is hit and it’s condition evaluates to False.

Parameters:

aProcess (Process) – Process that contains the breakpoint.
aThread (Thread) – Current thread.

Raises:

RuntimeError – The breakpoint was not enabled.

class winappdbg.breakpoint.HookFactory(preCB=None, postCB=None, paramCount=None, signature=None, arch=None, preCBArgs=None, postCBArgs=None, bpTypeEntry=None, bpTypeReturn=None)

Factory class to produce hook objects. Used by hook_function() and stalk_function().

When you try to instance this class, one of the architecture specific implementations is returned instead.

Instances act as an action callback for breakpoints set at the beginning of a function. It automatically retrieves the parameters from the stack, sets a breakpoint at the return address and retrieves the return value from the function call.

See also

_Hook_i386, _Hook_amd64, _Hook_arm64

class winappdbg.breakpoint.PageBreakpoint(address, pages=1, condition=True, action=None)

Page access breakpoint (using guard pages).

See also

watch_buffer()

disable(aProcess, aThread)

Disables a breakpoint.

Parameters:

aProcess (Process) – Process that contains the breakpoint.
aThread (Thread) – Current thread.

Raises:

RuntimeError – The breakpoint was not in an active state.

enable(aProcess, aThread)

Enables a breakpoint.

Parameters:

aProcess (Process) – Process that contains the breakpoint.
aThread (Thread) – Current thread.

Raises:

RuntimeError – The breakpoint was already enabled.

get_size_in_pages()

Return type:: int
Returns:: Size of breakpoint in pages.

one_shot(aProcess, aThread)

Sets a breakpoint for one shot.

Parameters:

aProcess (Process) – Process that contains the breakpoint.
aThread (Thread) – Current thread.

Raises:

RuntimeError – The breakpoint was already enabled.

running(aProcess, aThread)

Puts the breakpoint in running state. This happens when a breakpoint is hit and it’s condition evaluates to False.

Parameters:

aProcess (Process) – Process that contains the breakpoint.
aThread (Thread) – Current thread.

Raises:

RuntimeError – The breakpoint was not enabled.