winappdbg.textio

Functions for text input, logging or text output.

class winappdbg.textio.Color

Colored console output.

classmethod bk_black(): Make the text background color black.

classmethod bk_blue(): Make the text background color blue.

classmethod bk_cyan(): Make the text background color cyan.

classmethod bk_dark(): Make the current background color dark.

classmethod bk_default(): Make the current background color the default.

classmethod bk_green(): Make the text background color green.

classmethod bk_light(): Make the current background color light.

classmethod bk_magenta(): Make the text background color magenta.

classmethod bk_red(): Make the text background color red.

classmethod bk_white(): Make the text background color white.

classmethod bk_yellow(): Make the text background color yellow.

classmethod black(): Make the text foreground color black.

classmethod blue(): Make the text foreground color blue.

classmethod can_use_colors()

Determine if we can use colors.

Colored output only works when the output is a real console, and fails when redirected to a file or pipe. Call this method before issuing a call to any other method of this class to make sure it’s actually possible to use colors.

Returns:: True if it’s possible to output text with color, False otherwise.
Return type:: bool

classmethod cyan(): Make the text foreground color cyan.

classmethod dark(): Make the current foreground color dark.

classmethod default(): Make the current foreground color the default.

classmethod green(): Make the text foreground color green.

classmethod light(): Make the current foreground color light.

classmethod magenta(): Make the text foreground color magenta.

classmethod red(): Make the text foreground color red.

classmethod reset(): Reset the colors to the default values.

classmethod white(): Make the text foreground color white.

classmethod yellow(): Make the text foreground color yellow.

class winappdbg.textio.CrashDump(*argv, **argd)

Static functions for crash dumps.

Variables:: reg_template (str) – Template for the dump_registers() method.

static dump_arm_flags(cpsr)

Dump the ARM64 processor status register flags. The output format is similar to the x86 flags dump. Used by dump_registers().

Parameters:: cpsr (int) – Value of the CPSR register.
Returns:: Text suitable for logging.
Return type:: str

static dump_code(disassembly, pc=None, bLowercase=True, bits=None)

Dump a disassembly. Optionally mark where the program counter is.

Parameters:

disassembly (list[tuple(int, int, str, str)]) – Disassembly dump as returned by disassemble() or disassemble_around_pc().
pc (int) – (Optional) Program counter.
bLowercase (bool) – (Optional) If True convert the code to lowercase.
bits (int) – (Optional) Number of bits of the target architecture. The default is platform dependent. See: address_size

Returns:

Text suitable for logging.

Return type:

str

static dump_code_line(disassembly_line, bShowAddress=True, bShowDump=True, bLowercase=True, dwDumpWidth=None, dwCodeWidth=None, bits=None)

Dump a single line of code. To dump a block of code use dump_code().

Parameters:

disassembly_line (tuple(int, int, str, str)) – Single item of the list returned by disassemble() or disassemble_around_pc().
bShowAddress (bool) – (Optional) If True show the memory address.
bShowDump (bool) – (Optional) If True show the hexadecimal dump.
bLowercase (bool) – (Optional) If True convert the code to lowercase.
dwDumpWidth (int or None) – (Optional) Width in characters of the hex dump.
dwCodeWidth (int or None) – (Optional) Width in characters of the code.
bits (int) – (Optional) Number of bits of the target architecture. The default is platform dependent. See: address_size

Returns:

Text suitable for logging.

Return type:

str

static dump_data_peek(data, base=0, separator=' ', width=16, bits=None)

Dump data from pointers guessed within the given binary data.

Parameters:

data (str) – Dictionary mapping offsets to the data they point to.
base (int) – Base offset.
bits (int) – (Optional) Number of bits of the target architecture. The default is platform dependent. See: address_size

Returns:

Text suitable for logging.

Return type:

str

static dump_memory_map(memoryMap, mappedFilenames=None, bits=None)

Dump the memory map of a process. Optionally show the filenames for memory mapped files as well.

Parameters:

memoryMap (list[win32.MemoryBasicInformation]) – Memory map returned by get_memory_map().
mappedFilenames (dict[int, str]) – (Optional) Memory mapped filenames returned by get_mapped_filenames().
bits (int) – (Optional) Number of bits of the target architecture. The default is platform dependent. See: address_size

Returns:

Text suitable for logging.

Return type:

str

classmethod dump_registers(registers, arch=None)

Dump the x86/x64 processor register values. The output mimics that of the WinDBG debugger.

Parameters:

registers (dict[str, int]) – Dictionary mapping register names to their values.
arch (str) –
Architecture of the machine whose registers were dumped. Defaults to the current architecture.

Currently only the following architectures are supported:
- winappdbg.win32.ARCH_I386
- winappdbg.win32.ARCH_AMD64
- winappdbg.win32.ARCH_ARM64

Returns:

Text suitable for logging.

Return type:

str

static dump_registers_peek(registers, data, separator=' ', width=16)

Dump data pointed to by the given registers, if any.

Parameters:

registers (dict[str, int]) – Dictionary mapping register names to their values. This value is returned by get_context().
data (dict[str, str]) – Dictionary mapping register names to the data they point to. This value is returned by peek_pointers_in_registers().

Returns:

Text suitable for logging.

Return type:

str

static dump_stack_peek(data, separator=' ', width=16, arch=None)

Dump data from pointers guessed within the given stack dump.

Parameters:

data (str) – Dictionary mapping stack offsets to the data they point to.
separator (str) – Separator between the hexadecimal representation of each character.
width (int) – (Optional) Maximum number of characters to convert per text line. This value is also used for padding.
arch (str) – Architecture of the machine whose registers were dumped. Defaults to the current architecture.

Returns:

Text suitable for logging.

Return type:

str

static dump_stack_trace(stack_trace, bits=None)

Dump a stack trace, as returned by get_stack_trace() with the bUseLabels parameter set to False.

Parameters:

stack_trace (list[tuple(int, int, str)]) – Stack trace as a list of tuples of ( return address, frame pointer, module filename )
bits (int) – (Optional) Number of bits of the target architecture. The default is platform dependent. See: address_size

Returns:

Text suitable for logging.

Return type:

str

static dump_stack_trace_with_labels(stack_trace, bits=None)

Dump a stack trace, as returned by get_stack_trace_with_labels().

Parameters:

stack_trace (list[tuple(int, str)]) – Stack trace as a list of tuples of ( return address, frame pointer, module filename )
bits (int) – (Optional) Number of bits of the target architecture. The default is platform dependent. See: address_size

Returns:

Text suitable for logging.

Return type:

str

static dump_x86_flags(efl)

Dump the x86 processor flags. The output mimics that of the WinDBG debugger. Used by dump_registers().

Parameters:: efl (int) – Value of the eFlags register.
Returns:: Text suitable for logging.
Return type:: str

class winappdbg.textio.DebugLog(*argv, **argd)

Static functions for debug logging.

classmethod log_event(event, text=None)

Log lines of text associated with a debug event.

Parameters:

event (Event) – Event object.
text (str) – (Optional) Text to log. If no text is provided the default is to show a description of the event itself.

Returns:

Log line.

Return type:

str

static log_text(text)

Log lines of text, inserting a timestamp.

Parameters:: text (str) – Text to log.
Returns:: Log line.
Return type:: str

class winappdbg.textio.HexDump(*argv, **argd)

Static functions for hexadecimal dumps.

Variables:

integer_size (int) – Size in characters of an outputted integer. This value is platform dependent.
address_size (int) – Size in characters of an outputted address. This value is platform dependent.

classmethod address(address, bits=None)

Parameters:

address (int) – Memory address.
bits (int) – (Optional) Number of bits of the target architecture. The default is platform dependent. See: address_size

Returns:

Text output.

Return type:

str

static hexa_dword(data, separator=' ')

Convert binary data to a string of hexadecimal DWORDs.

Parameters:

data (str) – Binary data.
separator (str) – Separator between the hexadecimal representation of each DWORD.

Returns:

Hexadecimal representation.

Return type:

str

static hexa_qword(data, separator=' ')

Convert binary data to a string of hexadecimal QWORDs.

Parameters:

data (str) – Binary data.
separator (str) – Separator between the hexadecimal representation of each QWORD.

Returns:

Hexadecimal representation.

Return type:

str

static hexa_word(data, separator=' ')

Convert binary data to a string of hexadecimal WORDs.

Parameters:

data (str) – Binary data.
separator (str) – Separator between the hexadecimal representation of each WORD.

Returns:

Hexadecimal representation.

Return type:

str

static hexadecimal(data, separator='')

Convert binary data to a string of hexadecimal numbers.

Parameters:

data (str) – Binary data.
separator (str) – Separator between the hexadecimal representation of each character.

Returns:

Hexadecimal representation.

Return type:

str

classmethod hexblock(data, address=None, bits=None, separator=' ', width=8)

Dump a block of hexadecimal numbers from binary data. Also show a printable text version of the data.

Parameters:

data (str) – Binary data.
address (str) – Memory address where the data was read from.
bits (int) – (Optional) Number of bits of the target architecture. The default is platform dependent. See: address_size
separator (str) – Separator between the hexadecimal representation of each character.
width (int) – (Optional) Maximum number of characters to convert per text line.

Returns:

Multiline output text.

Return type:

str

classmethod hexblock_byte(data, address=None, bits=None, separator=' ', width=16)

Dump a block of hexadecimal BYTEs from binary data.

Parameters:

data (str) – Binary data.
address (str) – Memory address where the data was read from.
bits (int) – (Optional) Number of bits of the target architecture. The default is platform dependent. See: address_size
separator (str) – Separator between the hexadecimal representation of each BYTE.
width (int) – (Optional) Maximum number of BYTEs to convert per text line.

Returns:

Multiline output text.

Return type:

str

classmethod hexblock_cb(callback, data, address=None, bits=None, width=16, cb_args=(), cb_kwargs={})

Dump a block of binary data using a callback function to convert each line of text.

Parameters:

callback (function) – Callback function to convert each line of data.
data (str) – Binary data.
address (str) – (Optional) Memory address where the data was read from.
bits (int) – (Optional) Number of bits of the target architecture. The default is platform dependent. See: address_size
cb_args (str) – (Optional) Arguments to pass to the callback function.
cb_kwargs (str) – (Optional) Keyword arguments to pass to the callback function.
width (int) – (Optional) Maximum number of bytes to convert per text line.

Returns:

Multiline output text.

Return type:

str

classmethod hexblock_dword(data, address=None, bits=None, separator=' ', width=4)

Dump a block of hexadecimal DWORDs from binary data.

Parameters:

data (str) – Binary data.
address (str) – Memory address where the data was read from.
bits (int) – (Optional) Number of bits of the target architecture. The default is platform dependent. See: address_size
separator (str) – Separator between the hexadecimal representation of each DWORD.
width (int) – (Optional) Maximum number of DWORDs to convert per text line.

Returns:

Multiline output text.

Return type:

str

classmethod hexblock_qword(data, address=None, bits=None, separator=' ', width=2)

Dump a block of hexadecimal QWORDs from binary data.

Parameters:

data (str) – Binary data.
address (str) – Memory address where the data was read from.
bits (int) – (Optional) Number of bits of the target architecture. The default is platform dependent. See: address_size
separator (str) – Separator between the hexadecimal representation of each QWORD.
width (int) – (Optional) Maximum number of QWORDs to convert per text line.

Returns:

Multiline output text.

Return type:

str

classmethod hexblock_word(data, address=None, bits=None, separator=' ', width=8)

Dump a block of hexadecimal WORDs from binary data.

Parameters:

data (str) – Binary data.
address (str) – Memory address where the data was read from.
bits (int) – (Optional) Number of bits of the target architecture. The default is platform dependent. See: address_size
separator (str) – Separator between the hexadecimal representation of each WORD.
width (int) – (Optional) Maximum number of WORDs to convert per text line.

Returns:

Multiline output text.

Return type:

str

classmethod hexline(data, separator=' ', width=None)

Dump a line of hexadecimal numbers from binary data.

Parameters:

data (str) – Binary data.
separator (str) – Separator between the hexadecimal representation of each character.
width (int) – (Optional) Maximum number of characters to convert per text line. This value is also used for padding.

Returns:

Multiline output text.

Return type:

str

classmethod integer(integer, bits=None)

Parameters:

integer (int) – Integer.
bits (int) – (Optional) Number of bits of the target architecture. The default is platform dependent. See: integer_size

Returns:

Text output.

Return type:

str

static printable(data)

Replace unprintable characters with dots.

Parameters:: data (str) – Binary data.
Returns:: Printable text.
Return type:: str

class winappdbg.textio.HexInput(*argv, **argd)

Static functions for user input parsing. The counterparts for each method are in the HexOutput class.

static address(token)

Convert numeric strings into memory addresses.

Parameters:: token (str) – String to parse.
Returns:: Parsed integer value.
Return type:: int

static get_pattern_length(token)

Determine the byte length of the given hexadecimal pattern to be used with pattern().

Parameters:: token (str) – String to parse.
Returns:: Length in bytes.
Return type:: int

static hexadecimal(token)

Convert a strip of hexadecimal numbers into binary data.

Parameters:: token (str) – String to parse.
Returns:: Parsed string value.
Return type:: bytes

static integer(token)

Convert numeric strings into integers.

Parameters:: token (str) – String to parse.
Returns:: Parsed integer value.
Return type:: int

classmethod integer_list_file(filename)

Read a list of integers from a file.

The file format is:

# anywhere in the line begins a comment

leading and trailing spaces are ignored

empty lines are ignored

integers can be specified as:

decimal numbers (“100” is 100)

hexadecimal numbers (“0x100” is 256)

binary numbers (“0b100” is 4)

octal numbers (“0100” is 64)

Parameters:: filename (str) – Name of the file to read.
Returns:: List of integers read from the file.
Return type:: list[int]

static is_pattern(token)

Determine if the given argument is a valid hexadecimal pattern to be used with pattern().

Parameters:: token (str) – String to parse.
Returns:: True if it’s a valid hexadecimal pattern, False otherwise.
Return type:: bool

classmethod mixed_list_file(filename)

Read a list of mixed values from a file.

The file format is:

# anywhere in the line begins a comment

leading and trailing spaces are ignored

empty lines are ignored

strings cannot span over a single line

integers can be specified as:

decimal numbers (“100” is 100)

hexadecimal numbers (“0x100” is 256)

binary numbers (“0b100” is 4)

octal numbers (“0100” is 64)

Parameters:: filename (str) – Name of the file to read.
Returns:: List of integers and strings read from the file.
Return type:: list

static pattern(token)

Convert an hexadecimal search pattern into a POSIX regular expression.

For example, the following pattern:

"B8 0? ?0 ?? ??"

Would match the following data:

"B8 0D F0 AD BA"    # mov eax, 0xBAADF00D

Parameters:: token (str) – String to parse.
Returns:: Parsed string value.
Return type:: bytes

classmethod string_list_file(filename)

Read a list of string values from a file.

The file format is:

# anywhere in the line begins a comment

leading and trailing spaces are ignored

empty lines are ignored

strings cannot span over a single line

Parameters:: filename (str) – Name of the file to read.
Returns:: List of integers and strings read from the file.
Return type:: list[str]

class winappdbg.textio.HexOutput(*argv, **argd)

Static functions for user output parsing. The counterparts for each method are in the HexInput class.

Variables:

integer_size (int) – Default size in characters of an outputted integer. This value is platform dependent.
address_size (int) – Default Number of bits of the target architecture. This value is platform dependent.

classmethod address(address, bits=None)

Parameters:

address (int) – Memory address.
bits (int) – (Optional) Number of bits of the target architecture. The default is platform dependent. See: address_size

Returns:

Text output.

Return type:

str

static hexadecimal(data)

Convert binary data to a string of hexadecimal numbers.

Parameters:: data (str) – Binary data.
Returns:: Hexadecimal representation.
Return type:: str

classmethod integer(integer, bits=None)

Parameters:

integer (int) – Integer.
bits (int) – (Optional) Number of bits of the target architecture. The default is platform dependent. See: integer_size

Returns:

Text output.

Return type:

str

classmethod integer_list_file(filename, values, bits=None)

Write a list of integers to a file. If a file of the same name exists, it’s contents are replaced.

See integer_list_file() for a description of the file format.

Parameters:

filename (str) – Name of the file to write.
values (list[int]) – List of integers to write to the file.
bits (int) – (Optional) Number of bits of the target architecture. The default is platform dependent. See: integer_size

classmethod mixed_list_file(filename, values, bits)

Write a list of mixed values to a file. If a file of the same name exists, it’s contents are replaced.

See mixed_list_file() for a description of the file format.

Parameters:

filename (str) – Name of the file to write.
values (list) – List of mixed values to write to the file.
bits (int) – (Optional) Number of bits of the target architecture. The default is platform dependent. See: integer_size

classmethod string_list_file(filename, values)

Write a list of strings to a file. If a file of the same name exists, it’s contents are replaced.

See string_list_file() for a description of the file format.

Parameters:

filename (str) – Name of the file to write.
values (list[str]) – List of strings to write to the file.

class winappdbg.textio.Logger(logfile=None, verbose=True)

Logs text to standard output and/or a text file.

Variables:

logfile (str or None) – Append messages to this text file.
verbose (bool) – True to print messages to standard output.
fd (file) – File object where log messages are printed to. None if no log file is used.

is_enabled()

Determines if the logger will actually print anything when the log_* methods are called.

This may save some processing if the log text requires a lengthy calculation to prepare. If no log file is set and stdout logging is disabled, there’s no point in preparing a log text that won’t be shown to anyone.

Returns:: True if a log file was set and/or standard output logging is enabled, or False otherwise.
Return type:: bool

log_event(event, text=None)

Log lines of text associated with a debug event.

Parameters:

event (Event) – Event object.
text (str) – (Optional) Text to log. If no text is provided the default is to show a description of the event itself.

log_exc(): Log lines of text associated with the last Python exception.

log_text(text)

Log lines of text, inserting a timestamp.

Parameters:: text (str) – Text to log.

class winappdbg.textio.Table(sep=' ')

Text based table. The number of columns and the width of each column is automatically calculated.

addRow(*row)

Add a row to the table. All items are converted to strings.

Parameters:: row (tuple) – Each argument is a cell in the table.

getOutput()

Get the text output for the table.

Returns:: Text output.
Return type:: str

getWidth()

Get the width of the text output for the table.

Returns:: Width in characters for the text output, including the newline character.
Return type:: int

justify(column, direction)

Make the text in a column left or right justified.

Parameters:

column (int) – Index of the column.
direction (int) – -1 to justify left, 1 to justify right.

Raises:

IndexError – Bad column index.
ValueError – Bad direction value.

show(): print(the text output for the table.)

yieldOutput()

Generate the text output for the table.

Returns:: Text output.
Return type:: generator of str