BSOD Survivor

Drivers development is a time consuming process. Have you ever been frustrated with the time-consuming process of rebooting your VM or reattaching Windbg again just to fix a BSOD caused by a function call of your driver? Or have you wanted to add a conditional breakpoint without unloading the driver? or just change a line? Look no further! Our project offers a solution to these problems and more.

Our project allows you to update source code and global variables in debugging without unloading the driver or rebooting your VM. You can easily compile the file with the changes you want, link it with the already loaded code in memory, and replace the old functions with the new ones - all at runtime! And with our Bsod Survivor Visual Studio Plugin, you can instruct Windbg which code to change in real time.

Not only that, but our project also allows you to change the program state to be in the state before the current function was called, and jump to a previous line in the function - all while calling the necessary destructors of the function, so you can rerun the code safely!!. And if you need to run expression evaluation from a file, including templates and default parameters, our project has got you covered also.

To see our project in action, take a look at our example. We show you how to fix an infinite loop caused by a function call in just a few simple steps. With our project, debugging has never been easier!

This project is for you!!

Our project is a fork of LLVM 10 and is currently in beta version 0.3.0. It consists of a Visual Studio plugin, Windbg plugin, and changes to LLDB/Clang/LLD.

Example

First we load a driver

as you can see I accidently called a function(realEntry) which doesn't do anything, its run is infinite in fact, and I can't even unload this driver.

so lets fix this:

first I go to Visual Studio to change and activate the dynamic linking in runtime with our driver , by clicking Tools->Linking With Loaded Driver, which will compile the selected file (Main.cpp) and link it dynamically.

This is the result

as you can see I added DriverUnload to the code, and this is not an infinite loop anymore.

Then I return to Windbg and run !return_with (return_with is returning from the current function and calling needed destructors, without continue the function- so it should be safe to be used) in the Windbg command window , in order to return to the previous function and rerun the function which we were inside

we are now after the call to realEntry, but we wants to run realEntry again, so I am jumping to line 14 - using !jump 14

and now I can just step into the function(F11) and continue debugging my new code as a regular code.

but then I remembered that what I really wants is that uniName in line 17 to be \\DosDevices\C:\WINDOWS\example2.txt instead of \\DosDevices\C:\WINDOWS\example.txt, although I can just update line 17, and do the same procedure as I did previously of changing the function, I can also just do this in another way, by evaluating and running an expression which will affect the local variable uniName, only in this run, and not in all the runs, usefull for experiments / code you don't want to run in multiple threads and so on.

!expr c:\temp\a.txt , where I saved in c:\temp\a.txt the following content: RtlInitUnicodeString(&uniName, L" \\\DosDevices\\C:\\WINDOWS\\example2.txt");

UniName as you can see have the value of L" \\\DosDevices\\C:\\WINDOWS\\example2.txt".

and finally let's see how we can continue the program - even if we got BSOD:

First let's get a driver which do a BSOD:

as you can see we accessed variable a where variable a has a value of nullptr, and that caused a BSOD.

lets "survive" this, by using !return_to_frame_with, which returns from frame 0 to the selected frame.

and now we can continue the program as usual by changing the value of a (by windbg command), or we can just do what we did previously and change this function code, and rerun it with the changed code.

Please be noted that I added in advance a breakpoint in nt!KeBugCheck* in order for break the program before it will changed to DISPATCH_LEVEL because of the BSOD, my recommendation is for you to always configure Windbg to break in those functions by "bm nt!KeBugCheck* " command, please See it in the Configure Windbg

Installation

you need to download the msi executable from https://github.com/ykfre/BsodSurvivor

and follow the installation guide in here.

Windbg Commands

• !expr {expression} - This command allows you to evaluate an expression which resides in a file path. You can still use breakpoints as you normally would, so you can break in functions called inside the expression.
• !reload_config - This command reloads the config.json file, allowing you to update your configurations on the fly.
• !return_with - This command returns from the current frame while calling destructors.
• !return_without - This command returns from the current frame without calling destructors.
• !return_to_frame_with - This command returns from the current frame to the selected frame (which you should select by pressing on it in Windbg) while calling destructors.
• !return_to_frame_without - This command returns from the current frame to the selected frame (which you should select by pressing on it in Windbg) without calling destructors.
• !jump {line_num} - This command jumps to a previous line in the same function, including calling any needed destructors..
• !reload_dynamic_modules - This command makes Windbg reload dynamic modules again, which is useful if you have used the .reload /f command and Windbg removed the dynamic modules.
• !reset_saved_files - This command makes Windbg stop showing some version of a cpp file, and makes it use the most updated one in the disk. This should only be used if a bug has somehow appeared.
• !discard_expr - This command discards the current active expression if it exists. This operation does not call any needed destructors.
• !jump_to_most_updated - This command changes the current program counter to an equivalent function to the current function, which is the most updated function, if it is safe to do so.

Build Your Driver

• [ ] In order for the expression evaluator to work correctly even on templates/default arguments you need to add module.modulemap with sdafx.h as there is in the ClangDriverExample dir,(you can just take this file), and place it in the dir of the wanted include, see the structure of ClangDriverExample for better understanding.

  • stdafx.h should contain all the headers which we want their in information in debugging time Usually wdm and your STL types

  • In module.modulemap should be listed only one file.

  • There should be only one module.modulemap file in your entire project.

  • stdafx.h should be the first include in your files, and you shouldn't include any contained include after stdafx.h, for example let's say MyVector.h is inside stdafx.h - you shouldn't do:

    #include stdafx.h #include MyVector.h

• [ ] In order for getting all the above functionality you need to use ${BSOD_SURVIVOR_DIR}\visual studio\BsodSurvivorDriverCommon.props for libs, and ${BSOD_SURVIVOR_DIR}\visual studio\BsodSurvivorDriver.props for drivers when you are compiling your driver. You must builld all your libs, which you want to change at run time and driver code using this compiler.

  BSOD_SURVIVOR_DIR - will be added to your environment variable after the Installation

Configure Windbg

In order for the plugin to work correctly you need to do the following:

• [ ] In {windbg_folder}/amd64/winext/config.json please edit it as the comments there instructing.

• [ ] In Windbg please make sure you are using the following command in order to use correctly the Windbg plugin:

  .load BsodSurvivor;.reload;ed nt!Kd_Default_Mask 8;bm nt!KeBugCheck*"

• [ ] In your first ever plugin run - please let the plugin an access through Windows Defender firewall.

Supported Architectures

Currently it is supported on Windows 7 and Windows 10 without hvci.

For the Windbg plugin - Windbg Preview is required, and will not work correctly on the old one.

For the visual studio plugin - only Visual Studio 2019 is supported.

Limitations And Known Issues

• The project currently only supports debugging one driver at a time, and you will need to specify which driver to use in the configuration file (config.json).
• You won't be able to debug multiple vms nor using multiple instances of the Windbg plugin.
• The vm must be stopped before you run any feature, and you must be sure the operation of the feature ended before you continue your run (There will be an informative log).
• Some Antiviruses may for some reason block some operations of your local Windbg -please add Windbg and the plugin to the white list of those antiviruses if some blocking window appears.

Updating Driver Code In Runtime Limitations

• Changes of functions are taking affect only on the next rerun of a function - meaning if you are already in a function when you debugged, before you linked, you must return from this function/call it again in order for the changes to take affect.

  for that reason I added a stub function like realEntry in ClangDriverExample, which gives me an ability to r