Thursday, December 19, 2013

Getting Started with Windows File System Filters - Hooking Up WinDbg to the VM

Sorry I missed last Thursday, I've been traveling and I didn't get around to post anything.
This post is focused to hooking up WinDBG to a VM. There are multiple ways to do attach debuggers to physical machines, each with it's specific pluses and minuses (please note, however, that this list changes often since Microsoft keeps improving the tools, which is awesome). Also, please note that in most cases you'll use two machines, a target (the machine you want to debug) and a host (the debugger host). If I remember correctly there used to be a way to attach WinDBG to the kernel it was running on, which was useful to inspect various kernel structures, but I don't think that's supported anymore, and anyway with VMs this is easy to do and much more flexible. Anyway, here are the main ways to attach to machines (that I'm aware of at the time of writing this):
  • serial cable connection. This is pretty universal, works on all Windows versions and it's been tested for a very long time. However, not many machine have serial ports anymore, and serial is really slow. But it's really the solution that's most likely to work for all cases.
  • USB connection. I've never actually used this, I think I tried once but gave up for some reason I can't remember (and I was left with the impression that it's quite finicky). This is also only available on Vista and newer.
  • 1394 (or firewire). I've used this a lot, it's really fast and pretty easy to set up. The downside is that it's expensive because it needs specialized hardware (like firewire cards and cables). This is available since XP and I highly recommend it if you need to work with real hardware and a VM won't work for you. 
  • network. I've not used this at all since it's pretty new (Win8+) but it should be pretty awesome since you don't have to be physically connected to the machine you're trying to debug (which limits the usefulness of the other methods, since if you work in a larger group you'll often have to debug things on machines that are not in your office so you'll have to figure out a way to connect to them). 
In general you really want a fast debugger connection because you might end up moving massive amounts of data across from the target to the host (for example, you might decide to capture a dump instead of keep using the machine, so if you'll have to capture all physical memory you'll want the 4, 8 or who knows, maybe even 128 GB to move quickly. I mean, over serial this can last weeks...
However, we're not talking about physical machines here so you should be able to just read the memory of the VM from the host, right ? Well, as it turns out, you can. There is a tool called VirtualKD, that actually does this and it has a couple of features that really help with driver development. There is a tutorial on how to install VirtualKD so please follow the steps there. Once you have everything working (the way I test that it's working is to boot up the VM and then breaking in the debugger. At that point the VM should freeze (please note that it might grab your mouse and you'll need to press some key combination (Ctrl+Alt for VMWare) to release it). Then I return to WinDBG and press F5 to resume running the VM) it's time to build and install a minifilter. This is what WinDBG should look like once it's connected properly and paused and resumed the VM:
One other thing we should set up is some method of copying files between the VM and host. I do this by setting up the Shared Folders feature to always share a certain folder between the host and the VM. Then all I need to do is copy the files I need to that folder on the host and I can access them from the VM (for this machine I used a folder D:\shared). After everything is set up, it's time to start the sequence of steps that will deploy the minifilter on the VM (which will become familiar to you pretty quickly):
  1. So now let's build a minifilter. Using the steps described in the previous post, let's try to build the passThrough minifilter. Try to build the checked version for the platform you've set up your VM to use (basically, for my Win7 x86 VM I'll start the "x86 Checked Build Environment" under the Windows 7 folder and build there). Once it's built I'd like to add a breakpoint in DriverEntry() (which is basically the main() function for drivers) to break in the debugger once the filter loads. So please just add a breakpoint (a call to DbgBreakPoint();) somewhere in DriverEntry() and rebuild the driver (bcz again)).
  2. Now we need to copy two files to the VM. Those two files are the actual driver (objchk_win7_x86\i386\passThrough.sys in my case) and the inf file (passThrough.inf). Put these two in the same directory and copy them to the VM through the shared folder.
  3. And finally we need to install the minifilter on the VM. So now we're switching to the VM. Open the shared folder, find the passThrough folder, right-click on passThrough.inf and select Install (which will require administrator privileges).
  4. Then we need to start an elevated CMD window from where we'll run "fltmc load passThrough".
  5. If everything is fine and the minifilter is loading then we'll trigger the breakpoint, which will freeze the VM. So we'll need to switch back to the debugger and unfreeze it (F5 again or use "g" command to allow execution to continue).
  6. After that we should see passthrough loaded and attached to all the volumes in your VM.
So this is it for today. In the next post I'll talk about some of my configurations and some optimizations I use to make this whole process faster, but that's not going to be until next year, so I wish you Happy Holidays! and a Happy New Year! in the meantime :).

Thursday, December 5, 2013

Getting Started with Windows File System Filters - Installing the Tools

Hello everyone,

It's been a while since I last posted anything. I took a break from file systems (and Windows, for that matter) but now I'm ready to get back. Since I'll be spending some time getting reacquainted with the whole thing I figured it's a good time to start a blog series for absolute beginners to this subject. However, you're expected to know C and understand synchronization (you should know what a mutexes and semaphores are).
So with that, the first step is to try to get the environment set up. We'll need the following tools:
  1. Windows Driver Kit - I'll be installing the 7.1.0 WDK, which should be good for Windows 7, Windows Vista, Windows XP, Windows Server 2008 R2, Windows Server 2008, and Windows Server 2003. The drivers we build should also run on Windows 8 and newer but the 7.1 WDK doesn't include the additional features (new APIs and such) that are available there. I'll cover setting up the newer WDK in a different post. For now, just get the WDK from MSDN.
  2. A Virtual Machine software - Personally I'm a big fan of VMware Workstation, but it's not free. I've used VirtualBox in the past and it's fine for what we need and it's also free so you can get it from here.
So let's get started. Install the WDK anywhere (please note that it's an ISO image so you can either mount it with any tool you like or you can just use a tool like 7zip (or most other decent archivers) to extract the files to a directory. Then just run KitSetup.exe and we're good to go.
This is what I have installed under D:\WinDDK (the red Xs are there because the kit can't find the kit I used so I can't add anything else - just ignore those):

Once the WDK installed you should be able to build a sample. So the steps are:
  1. Start a cmd prompt to build the sample: Start->Windows Driver Kits->WDK 7600.16385.1->Build Environments->Windows 7->x86 Checked Build Environment
  2. type cd src\filesys\miniFilter\nullFilter to get to the simplest minifilter sample
  3. type bcz to build it
  4. now you can go to the output directory (cd objchk_win7_x86\i386) and you should see the nullfilter.sys file, which is the null minifilter sample
At this point you should have the WDK installed properly. Please install VirtualBox on your own and create a new Win7 VM  (or, if you have VMware Workstation, you can just use that) and next week we'll configure the debugger and load the filter and look at it a bit.