dbginterface module

class Symbol

Not a real class, a function accepting a Symbol means it can accept:

- A valid windbg symbol (“nt!CreateFile”)

- An address

class dbginterface.LocalKernelDebuggerBase(quiet=True)

Bases: object

get_number_modules()

Get the number of loaded and unloaded modules

Returns:Number of loaded, unloaded modules – int, int

get_module_by_index(i)

Get the base of module number i

get_module_name_by_index(i)

Get the name of module number i

resolve_symbol(symbol)

Return symbol if it’s an int else resolve it using get_symbol_offset()

Used by functions to either accept an int or a windbg Symbol

resolve_type(imodule, itype)

Return imodule and itype if they are an int else

resolve then using respectively get_symbol_offset() and get_type_id()

Used by functions about types to either accept int or windbg Symbol

execute(str, to_string=False)

Execute a windbg command

if to_string is False, use the current output callback

(see example\output_demo.py)

set_output_callbacks(callback)

Register a new output callback, that must respect the interface of

IDebugOutputCallbacks::Output() https://msdn.microsoft.com/en-us/library/windows/hardware/ff550815%28v=vs.85%29.aspx.

(see example\output_demo.py)

get_modules()

Return a list of (currModuleName, currImageName, currLoadedImageName)

reload(module_to_reload='')

Reload a module or all modules if module_to_reload is not specified

detach()

End the Debugging session and detach the COM interface

current_processor()

Returns:The number of the processor we are currently on – int

set_current_processor(proc_nb)

Set the processor we want to be executed on

Parameters:proc_nb (int) – the number of the processor

number_processor()

Returns:The number of processors on the machine – int

on_each_processor()

Iter execution on every processor

Yield:current processor number

get_type_id(module, type_name)

Get the typeid of a type

Parameters:

• module (Symbol) – the module containing the type
• type_name (str) – the name of the type

Return type:

int

get_symbol_type_id(symtype)

Get the module and typeid of a symbol

Parameters:symtype (str) – the name of the type Return type:int, int – module ID, type ID

get_field_offset(module, typeid, field)

Get the offset of a field in a type

Return type:int

get_type_name(module, typeid)

Get the name of a type

Return type:str

get_type_size(module, typeid)

Get the size of a type

Return type:int

get_field_name(module, typeid, fieldindex)

Get the name of a field in a type

Parameters:fieldindex (int) – Index of the field to retrieve Return type:int

get_field_type_and_offset(module, typeid, fieldname)

Get the type and the offset of a field in a type

Parameters:fieldname (str) – The name of the field we want Return type:int, int – type ID, field offset

trim_ulong64_to_address(addr)

Used to convert a symbol ULONG64 to the actual symbol.

Problem is that in a 32bits kernel the kernel address are bit expended

nt in 32bits kernel would not be 0x8xxxxxxx but 0xffffffff8xxxxxxx

expand_address_to_ulong64(addr)

Used to convert a symbol address to an ULONG64 requested by the API.

Problem is that in a 32bits kernel the kernel address are bit expended

nt in 32bits kernel would not be 0x8xxxxxxx but 0xffffffff8xxxxxxx

get_symbol_offset(name)

Get the address of a symbol

Parameters:name (str) – Name of the symbol Return type:int

get_symbol(addr)

Get the symbol and displacement of an address

Parameters:addr (int) – The address to lookup Return type:str, int – symbol name, displacement

symbol_match(symbol_pattern)

<generator>

List of symbol (name, address) that match a symbol pattern

Parameters:symbol_pattern (str) – The symbol pattern (nt!Create*, *!CreateFile, ..) Yield:str, int – symbol name, symbol address

read_virtual_memory(addr, size)

Read the memory at a given virtual address

Parameters:

• addr (Symbol) – The Symbol to read from
• size (int) – The size to read

Returns:

str

write_virtual_memory(addr, data)

Write data to a given virtual address

Parameters:

• addr (Symbol) – The Symbol to write to
• size (str or ctypes.Structure) – The Data to write

Returns:

the size written – int

write_pfv_memory(addr, data)

Write physical memory from virtual address Exactly the same as write_physical(virtual_to_physical(addr), data)

read_virtual_memory_into(addr, struct)

“Read the memory at a given virtual address into a ctypes Structure

Parameters:

• addr (Symbol) – The Symbol to read from
• struct – The structure to fill

Returns:

the size read – int

read_byte(addr)

Read a byte from virtual memory

read_byte_p(addr)

Read a byte from physical memory

read_word(addr)

Read a word from virtual memory

read_word_p(addr)

Read a word from physical memory

read_dword(addr)

Read a dword from virtual memory

read_dword_p(addr)

Read a dword from physical memory

read_qword(addr)

Read a qword from virtual memory

read_qword_p(addr)

Read a qword from physical memory

write_byte(addr, byte)

Read a byte to virtual memory

write_byte_p(addr, byte)

write a byte to physical memory

write_word(addr, word)

write a word to virtual memory

write_word_p(addr, word)

write a word to physical memory

write_dword(addr, dword)

write a dword to virtual memory

write_dword_p(addr, dword)

write a dword to physical memory

write_qword(addr, qword)

write a qword to virtual memory

write_qword_p(addr, qword)

write a qword to physical memory

read_ptr(addr)

Read a pointer from virtual memory

read_ptr_p(addr)

Read a pointer from physical memory

write_ptr(addr, value)

Write a pointer to virtual memory

write_ptr_p(addr, value)

Write a pointer to physical memory

write_msr(msr_id, value)

Write a Model Specific Register

read_msr(msr_id)

Read a Model Specific Register

virtual_to_physical(virtual)

Get the physical address of a virtual one

read_physical_memory(addr, size)

Read the physical memory at a given address

Parameters:

• addr (Symbol) – The Symbol to read from
• size (int) – The size to read

Returns:

str

write_physical_memory(addr, data)

Write data to a given physical address

Parameters:

• addr (Symbol) – The Symbol to write to
• size (str or ctypes.Structure) – The Data to write

Returns:

the size written – int

read_processor_system_data(processor, type)

Returns a DEBUG_PROCESSOR_IDENTIFICATION_X86 if type is DEBUG_DATA_PROCESSOR_IDENTIFICATION

else returns an int

(see ReadProcessorSystemData() https://msdn.microsoft.com/en-us/library/windows/hardware/ff554326%28v=vs.85%29.aspx.)

read_bus_data(datatype, busnumber, slot, offset, size)

Read on bus data, only current known use is to read on the PCI bus.

(see example\simple_pci_exploration.py)

write_bus_data(datatype, busnumber, slot, offset, data)

Write on bus data, only current known use is to write on the PCI bus.

(see example\simple_pci_exploration.py)

read_io(port, size)

Perform an IN operation

might be subject to some restrictions

(see README.md do_in | do_out VS read_io | write_io)

Parameters:

• port (int) – port to read
• size (int - 1, 2 or 4) – size to read

Returns:

the value read – int

write_io(port, value, size=None)

Perform an OUT operation

might be subject to some restrictions

(see README.md do_in | do_out VS read_io | write_io)

Parameters:

• port (int) – port to write
• size (int - 1, 2 or 4) – size to write

Returns:

the number of bytes written – int

kcall(target, *args)

<require upgraded driver>

Call target in kernel mode with given arguments.

KCall respect the calling convention but YOU must

pass the correct number of argument or the kernel

will likely crash.

(see map_page_to_userland()) for an example

Parameters:

• target (Symbol) – the Symbol to call
• args (list of int) – the arguments of the call

Returns:

int

do_in(port, size)

<require upgraded driver>

Perform an IN operation

Parameters:

• port (int) – port to read
• size (int - 1, 2 or 4) – size to read

Returns:

the value read – int

do_out(port, value, size)

<require upgraded driver>

Perform an OUT operation

Parameters:

• port (int) – port to write
• size (int - 1, 2 or 4) – size to write

Returns:

the number of bytes written – int

alloc_memory(size=4096)

<require upgraded driver>

Allocate size of NonPaged kernel memory

map_page_to_userland(virtual_addr, size)

<require upgraded driver>

Map size bytes of kernel memory virtual_addr in the current address space

Parameters:

• virtual_addr (int) – kernel virtual addr
• size (int) – size to map

Returns:

address of the page in current process – int

dbginterface.LocalKernelDebugger(quiet=True)

Check that all conditions to Local Kernel Debugging are met

and return a LKD (subclass of LocalKernelDebuggerBase