pykd/docs/en/tutorial.md

Introduction

Step 1: Getting Started

It is best to use the automatic installer for installation. It will install pykd in the correct location and also install and register all necessary components.

If the installation completes without errors, it is time to get acquainted with pykd. To do this, start WinDbg and begin a debugging session (open a process, dump file, or establish a connection with a kernel debugger). Now, you can load pykd by running the following command:

.load pykd.pyd

If any errors occur during loading, WinDbg will display a message. The absence of any messages indicates that the extension has been successfully loaded.

Now, you can start working. Execute the following command:

!pycmd

After running this command, the debugger will enter user input mode. All user input will be processed by the Python interpreter.

0:000> !pycmd
Python 2.6.6 (r266:84297, Aug 24 2010, 18:13:38) [MSC v.1500 64 bit (AMD64)] on win32
Type "help", "copyright", "credits" or "license" for more information.
(InteractiveConsole)
>>> print "Hello world!"
Hello world!
>>>

Now is a good time to get familiar with Python syntax if you haven’t already. Python is very easy to learn.

Let's recall some basic syntax of Python:

>>> def printHello():
...     i = 0
...     while i < 4:
...         print "Hello #%d" % i
...         i += 1
...
>>> printHello()
Hello #0
Hello #1
Hello #2
Hello #3
>>>

Note: The indentation of blocks is determined by leading spaces, which is a "signature" feature of Python. For now, this knowledge will be sufficient. Let’s move on.

Step 2: Accessing Registers

Any debugger should provide three basic capabilities: reading processor registers, reading memory, and controlling debugging mode. Let’s start with registers. With pykd, this is quite simple:

>>> print hex(reg("eip"))
0x778ecb60
>>> print hex(reg("esp"))
0x1ef0e0
>>> print hex(reg("esp")+4)
0x1ef0e4

In this case, we use the PYKD function reg. It reads processor registers by name. A curious reader might ask: how do we use functions from PYKD without explicitly importing the module? In reality, the module must be imported. However, PYKD automatically does this when constructing the Python console.

Let's write a small example to check where the current instruction pointer is pointing:

>>> print findSymbol(reg("eip"))
ntdll!LdrpDoDebuggerBreak+30

The findSymbol function attempts to find a debug symbol for a given address. In this case, we see that the instruction pointer is at offset 0x30 within the function LdrpDoDebuggerBreak, which is located in the ntdll module. We can determine this because we have debugging information for ntdll.dll (the corresponding pdb file). If symbols are not displaying for some reason, check your symbol path settings in WinDbg.

Step 3: Accessing Memory

PYKD provides a large set of functions for accessing memory, which can be divided into three categories:

1. Reading values from memory:

• ptrByte
• ptrWord
• ptrDWord
• ptrQWord

There are other functions as well; the full set can be found in the PYKD 0.2 API Reference. All functions take an address as a parameter and return the value stored at that address.

2. Reading arrays

• loadBytes
• loadWords
• loadDWords
• loadQWords

All functions take a pointer to the beginning of an array and its length in elements as parameters. They return a list object containing the array elements.

3. Reading strings

• loadCStr
• loadWStr

These functions read null-terminated strings from memory and return Python strings.

Let’s modify the previous example to display function arguments. We assume that the function follows the stdcall calling convention and that its parameters are addressed by the ebp register.

>>> def printFunc():
...     print findSymbol( reg("eip") )
...     params = [  ptrDWord( reg("ebp") + 4*(i+1) ) for i in range(0,3) ]
...     print "var1: %x  var2: %x  var3:  %x" % ( params[0], params[1], params[2] )
...
>>> print printFunc()
ntdll32!LdrpDoDebuggerBreak+2c
var1: 774b1383  var2: fffdd000  var3:  fffde000
None
>>>

Pay attention to this construct:

params = [  ptrDWord( reg("ebp") + 4*(i+1) ) for i in range(0,3) ]

This is a list comprehension—a special Python construct that simplifies list initialization. It is equivalent to:

 [  ptrDWord( reg("ebp") + 4) ),  ptrDWord( reg("ebp") + 8) ), ptrDWord( reg("ebp") + 0xC) ) ]

Step 4: Accessing Memory with Type Information

When debugging programs, we often work with typed variables. PYKD has powerful capabilities for accessing variables while preserving type information. This is one of the key features of the project: accessing struct and class fields in a way similar to source code.

For example, consider the following C code:

struct STRUCT_A {
  int  field1;
  char field2;
};

STRUCT_A a = { 100, 2 }

Now, during debugging, we want to check the state of variable a using PYKD:

   a = typedVar( "module!STRUCT_A",  getOffset("module!a") )
   if a.field1 != 100 or a.field2 != 2:       
       print "ERROR! a is not properly initialized!"