Windbg automation and extensions

Introduction : Windbg provides many ways to extend its functionality via its command line options ,Windbg scripts , extensions and 3rd party automation script libraries. Initially, I will show how to simply automate using bat files and command line options, And then I will show further ways of scripting and extensions :

  1. Driving Windbg in command line
  2. Driving CDB in command line
  3. Driving Windbg in command line with a 3rd party Powershell library
  4. Windbg scripts , official way
  5. Windbg Javascripting , official way
  6. Windbg Python scripting , 3rd party
  7. Windbg extensions and creating your own commands

1. Driving Windbg in command line :  I picked automating attaching to processes as first easy example. Attaching to processes is what you need to do if you are working with services/daemons or developing shared objects/DLLs. In Linux systems, it is quite typical  and nice to write bash files driving GDB as it accepts command line arguments.  However on Windows, if you are working with Visual Studio sometimes it can be disturbing to re-open “Attach to process” with Ctrl-P and finding your process again and again.

As for the command line options supported by Windbg , you can see :

https://msdn.microsoft.com/en-us/library/windows/hardware/ff561306(v=vs.85).aspx

Below you can see the the script file and the batch file I have created while automatedly debugging PHP7 by attaching to FastCGI process . The script file initially loads 2 symbol files , then sets 7 breakpoints and finally shows all call stacks per thread as this is the first thing I want to see in a debug session :

ld php_sqlsrv
ld php7
bp php_sqlsrv!zif_sqlsrv_connect
bp php_sqlsrv!zif_sqlsrv_prepare
bp php_sqlsrv!zif_sqlsrv_fetch_array
bp php_sqlsrv!zif_sqlsrv_field_metadata
bp php_sqlsrv!zif_sqlsrv_query
bp php_sqlsrv!zif_sqlsrv_free_stmt
bp php_sqlsrv!zif_sqlsrv_close
~*k

The batch file :

“C:\Program Files (x86)\Windows Kits\10\Debuggers\x86\windbg.exe” -pn php-cgi.exe -W SQLSRV -c “$<%~dp0windbg_script.txt”

-pn specifies the name of the process

-W specifies the workspace name if you are using Windbg

-c specifies commands. In order to execute a file we also use $< inside the quotations.

Now you can see how the Windbg looks after double-clicking on the batch file :

windbg

Sometimes you might need to get in as soon as the process starts and it might not be easy to catch it. Therefore , changing the bat file as below will allow us to do that as it will only try attaching when the process is available :

Alternatively , you can also use Gflags which comes with Windows SDK installation as which is described here : http://bugslasher.net/2011/03/26/how-to-debug-a-process-as-soon-as-it-starts-with-windbg-or-visual-studio-2010/

2. Driving CDB in command line : “Debugging Tools for Windows” does not ship only Windbg but other command line debuggers which use the same engine and which accept same commands. Therefore you can also automate CDB and NTSD :

https://msdn.microsoft.com/en-us/library/windows/hardware/hh406272(v=vs.85).aspx

For example when you work with QTCreator on Windows , QT Creator IDE ( which needs “Debugging Tools for Windows” ) talks with cdb.exe to allow debugging on Windows. The code below attaches to a target executable and display callstack information :

3.  Driving Windbg in commnad line, Powershell based automation ( 3rd Party ): There is also a Powershell module which automates connecting to Windbg and sending commands to Windbg :

http://powerdbg.codeplex.com/

4. Windbg scripting ( Official ): Besides automating start of Windbg you can also automate your Windbg debugging sessions. One of two official ways to do is Windbg scripts :

https://msdn.microsoft.com/en-us/library/windows/hardware/ff560137(v=vs.85).aspx

For a nice introduction and tutorial , here is a guide for C++ developers :

http://www.dumpanalysis.org/WCDA/WCDA-Sample-Chapter.pdf

5. Windbg Javascript scripting ( Official ) : The second official way of Windbg scripting is using  Javascript. You can see debugger objects exposed to Windbg in the link below :

https://msdn.microsoft.com/library/windows/hardware/A8E12564-D083-43A7-920E-22C4D627FEE8.aspx

And you can see some example scripts in the link below :

https://msdn.microsoft.com/library/windows/hardware/F477430B-10C7-4039-9C5F-25556C306643.aspx

The below example script displays information about MS C++ runtime library`s malloc and free calls. In order to use it , you need to run commands as below :

.load jsprovider.dll
.scriptload memdump.js
bp MSVCR120D!free “.scriptrun memdump.js”
bp MSVCR120D!malloc “.scriptrun memdump.js”

The first two command will load the JSscript interpreter extension and then load the script. The following two commands are required to place breakpoints and invoke Invoke method of memdump.js :

6. Windbg Python scripting ( 3rd party ) : As GDB has an embedded Python interpreter , on Windbg side , there is an unofficial Python extension :

http://pykd.codeplex.com/

You can see an example Python script which dumps C++ objects on the heap :

http://blogs.microsoft.co.il/sasha/2013/08/05/searching-and-displaying-c-heap-objects-in-windbg/

7. Windbg extensions and creating your own commands :  You can develop DLL extensions for Windbg  , deploy it to ext directory under Windbg directory ( x86 and x64 separately) and then use .load command to load your extension. Here is a skeleton code for a Windbg extension :

After compiling , you can copy the result DLL into ext directory of Windbg. Then you can load the extension :

.load skeletal_extension

And eventually call the exposed command :

!extension_command

Regarding what you can do with Windbg extensions is actually limitless. Some examples :

Links

MSDN Windbg command line options https://msdn.microsoft.com/en-us/library/windows/hardware/ff561306(v=vs.85).aspx

Debugging with NTSD/CDB :https://msdn.microsoft.com/en-us/library/windows/hardware/hh406272(v=vs.85).aspx

Driving CDB with BAT files : http://www.debuginfo.com/tools/cdbbatch.html

Powershell module to automate Windbg : http://powerdbg.codeplex.com/

MSDN Windbg scripts  https://msdn.microsoft.com/en-us/library/windows/hardware/ff560137(v=vs.85).aspx

Dmitry Vostokov`s guide to Windbg scripts :  http://dumpanalysis.org/WCDA/WCDA-Sample-Chapter.pdf

MSDN Windbg Javascript script examples : https://msdn.microsoft.com/library/windows/hardware/F477430B-10C7-4039-9C5F-25556C306643.aspx

Python extension for Windbg : http://pykd.codeplex.com/

Windbg extensions collection by Sasha Goldshtein : https://github.com/goldshtn/windbg-extensions

Advertisements

1 thought on “Windbg automation and extensions”

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Google+ photo

You are commenting using your Google+ account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s