Windows Detours library for the people

Microsoft Detours library can be used to attach a hook to system functions invoked by Windows programs. You can write an arbitrary code which will get invoked when a program tries, for example, send something over SSL, or get a current timestamp, and handle it as it pleases you instead of (or in addition to) passing it to standard Windows libraries.

Hopefully notes below will be useful for fellas who, like myself, are not skilled Windows developers, but occasionally get thrown into the Windows world and need to intercept a function call or two.

Getting Detours library to work:

* Download and install MS Visual Studio Express 2010 (http://www.microsoft.com/express/Downloads/)
* Download and install Detours library (http://research.microsoft.com/en-us/projects/detours/)
* Build Detours library. In cmd.exe (on Windows 7 it has to be running as an administrator):
- "\Program Files\Microsoft Visual Studio 10.0\VC\vcvarsall.bat"
- cd "\Program Files\Microsoft Research\Detours Express 2.1"
- nmake
+ it will build libraries and sample programs and places it
under lib\ and bin\ directory
+ on my PC it fails to finish for some reason, but after it
builds lib\ and bin\withdll.exe, so it is ok

Creating project to use with Detours lib:

* In Visual Studio create a Win32 DLL project
* Add paths to Detours library: Project properties / Configuration properties
- C/C++ / Additional Include Directories: add \Program Files\Microsoft Research\Detours Express 2.1\include
- Linker / Additional Library Directories: add \Program Files\Microsoft Research\Detours Express 2.1\lib
* Create source code:
- Copy the content of sample\simple\simple.cpp into dllmain.cpp
- Add two lines to ddlmain.cpp
+ #pragma comment(lib, "detours.lib")
+ #pragma comment(lib, "detoured.lib")
- Customize the remaining code as you need

When you have your DLL, run it with withdll.exe (located under bin/ directory, built in the very beginning of this exercise).

Other useful resources:

* DLL Creation with MinGW (http://sig9.com/node/35)
* Redirecting HTTP traffic (http://portswigger.net/misc/)
* ProcessMonitor tool (http://technet.microsoft.com/en-us/sysinternals/bb896645.aspx)

Many thanks to Axel Meerschaert for his help with making these things work.

Comments

My nmake generates fatal errors at withdll.cpp build section. When I look in the code, I see the following sitting in main:

else {
HMODULE hDetouredDll = DetourGetDetouredMarker();
GetModuleFileName(hDetouredDll,
szDetouredDllPath, arrayof(szDetouredDllPath));
#if 0
if (!SearchPath(NULL, "detoured.dll", NULL,
arrayof(szDetouredDllPath),
szDetouredDllPath,
&pszFilePart)) {
printf("withdll.exe: Couldn't find Detoured.DLL.\n");
return 9006;
}
#endif
}

Seems like we'd need to rip this out as well, right?

I understand you are getting a fatal error when compiling withdll.exe from Detours library itself. I remember I had some problems too, but in the end I have succeeded building the library and withdll executable without ripping out anything.

Perhaps people who specialise in Windows development can help you to fix nmake problem. Try Stack Overflow forum -- easy to post and you are likely to get professional feedback. And don't be afraid to disclose the actual error messages when asking for help ;).

If you figure out how to build Detours library in full please let me know what was the problem. I will update the build instructions on this page.