Detours
Detours is a software package for monitoring and instrumenting API calls on Windows. It is distributed in source code form.
Top Related Projects
Clone this repo to build Frida
Fast and lightweight x86/x86-64 disassembler and code generation library
Dynamic Instrumentation Tool Platform
syzkaller is an unsupervised coverage-guided kernel fuzzer
edb is a cross-platform AArch32/x86/x86-64 debugger.
Quick Overview
Microsoft Detours is a software package for monitoring and instrumenting API calls on Windows. It intercepts Win32 functions by re-writing target function images. Detours is widely used for debugging, profiling, and extending existing software.
Pros
- Powerful API hooking capabilities for Windows applications
- Supports both 32-bit and 64-bit processes
- Well-documented and maintained by Microsoft
- Can be used for various purposes, including security, diagnostics, and application extension
Cons
- Limited to Windows platforms
- Can potentially introduce instability if not used carefully
- Learning curve for proper implementation and usage
- May conflict with other hooking libraries or anti-cheat systems
Code Examples
- Hooking a function:
#include <windows.h>
#include <detours.h>
// Original function
static BOOL (WINAPI * TrueCreateProcessA)(
LPCSTR lpApplicationName,
LPSTR lpCommandLine,
// ... other parameters ...
) = CreateProcessA;
// Hook function
BOOL WINAPI HookedCreateProcessA(
LPCSTR lpApplicationName,
LPSTR lpCommandLine,
// ... other parameters ...
) {
// Custom logic before calling the original function
printf("Process creation attempted: %s\n", lpApplicationName);
// Call the original function
return TrueCreateProcessA(lpApplicationName, lpCommandLine, /* ... */);
}
// Attaching the hook
DetourTransactionBegin();
DetourUpdateThread(GetCurrentThread());
DetourAttach(&(PVOID&)TrueCreateProcessA, HookedCreateProcessA);
DetourTransactionCommit();
- Detouring a DLL function:
#include <windows.h>
#include <detours.h>
// Function prototype
typedef BOOL (WINAPI *MESSAGEBOXW)(HWND, LPCWSTR, LPCWSTR, UINT);
// Original function pointer
static MESSAGEBOXW TrueMessageBoxW = MessageBoxW;
// Detoured function
BOOL WINAPI DetourMessageBoxW(HWND hWnd, LPCWSTR lpText, LPCWSTR lpCaption, UINT uType) {
// Modify the message
wchar_t newText[256];
wcscpy_s(newText, L"Detoured: ");
wcscat_s(newText, lpText);
// Call the original function with modified text
return TrueMessageBoxW(hWnd, newText, lpCaption, uType);
}
// Attaching the detour
DetourTransactionBegin();
DetourUpdateThread(GetCurrentThread());
DetourAttach(&(PVOID&)TrueMessageBoxW, DetourMessageBoxW);
DetourTransactionCommit();
Getting Started
- Download and install the Detours library from the GitHub repository.
- Include the Detours header in your project:
#include <detours.h>
- Link against the Detours library in your project settings.
- Use the Detours API to hook functions as shown in the code examples above.
- Compile and run your application with the hooked functions.
Note: Ensure you have the necessary permissions and understand the implications of API hooking before using Detours in your projects.
Competitor Comparisons
Clone this repo to build Frida
Pros of Frida
- Cross-platform support (Windows, macOS, Linux, iOS, Android)
- Dynamic instrumentation with runtime code injection
- Scripting support using JavaScript for easier customization
Cons of Frida
- Steeper learning curve due to its more complex architecture
- Potentially higher overhead for simple hooking tasks
Code Comparison
Detours (C++):
#include <windows.h>
#include <detours.h>
int (WINAPI *TrueMessageBoxW)(HWND, LPCWSTR, LPCWSTR, UINT) = MessageBoxW;
int WINAPI HookedMessageBoxW(HWND hWnd, LPCWSTR lpText, LPCWSTR lpCaption, UINT uType) {
return TrueMessageBoxW(hWnd, L"Hooked!", lpCaption, uType);
}
Frida (JavaScript):
Interceptor.attach(Module.getExportByName(null, 'MessageBoxW'), {
onEnter(args) {
args[1] = Memory.allocUtf16String('Hooked!');
}
});
Both Detours and Frida are powerful tools for hooking and instrumenting code, but they cater to different use cases. Detours is more focused on Windows and offers a simpler API for basic hooking tasks, while Frida provides a more flexible and cross-platform solution with dynamic instrumentation capabilities. The choice between them depends on the specific requirements of your project and the target platforms you need to support.
Fast and lightweight x86/x86-64 disassembler and code generation library
Pros of Zydis
- Specialized in x86/x86-64 disassembly, offering more comprehensive instruction decoding
- Provides detailed information about decoded instructions, including operands and semantic attributes
- Supports multiple output formats, including Intel and AT&T syntax
Cons of Zydis
- Limited to disassembly functionality, while Detours offers broader hooking capabilities
- May have a steeper learning curve for users not specifically focused on disassembly tasks
Code Comparison
Zydis (disassembling instructions):
ZydisDisassembledInstruction instruction;
ZydisDisassembleIntel(ZYDIS_MACHINE_MODE_LONG_64, runtime_address, buffer, length, &instruction);
Detours (hooking a function):
LONG DetourAttach(&(PVOID&)TargetFunc, MyHookFunc);
While both libraries deal with low-level code manipulation, they serve different primary purposes. Zydis excels in disassembly and instruction analysis, whereas Detours focuses on function interception and hooking. The choice between them depends on the specific requirements of your project.
Dynamic Instrumentation Tool Platform
Pros of DynamoRIO
- More comprehensive and powerful runtime code manipulation capabilities
- Cross-platform support (Windows, Linux, macOS)
- Extensive API for fine-grained control over instrumentation
Cons of DynamoRIO
- Steeper learning curve due to its complexity
- Higher performance overhead compared to lightweight hooking solutions
- Requires more setup and configuration for basic use cases
Code Comparison
DynamoRIO example:
dr_emit_flags_t event_basic_block(void *drcontext, void *tag, instrlist_t *bb,
bool for_trace, bool translating) {
instr_t *instr, *next_instr;
for (instr = instrlist_first(bb); instr != NULL; instr = next_instr) {
next_instr = instr_get_next(instr);
// Instrumentation logic here
}
return DR_EMIT_DEFAULT;
}
Detours example:
BOOL WINAPI DllMain(HINSTANCE hinst, DWORD dwReason, LPVOID reserved) {
if (dwReason == DLL_PROCESS_ATTACH) {
DetourTransactionBegin();
DetourUpdateThread(GetCurrentThread());
DetourAttach(&(PVOID&)TrueFunction, MyFunction);
DetourTransactionCommit();
}
return TRUE;
}
syzkaller is an unsupervised coverage-guided kernel fuzzer
Pros of syzkaller
- Focuses on kernel fuzzing and system call testing, providing more specialized functionality for OS-level testing
- Supports multiple operating systems, including Linux, FreeBSD, NetBSD, and Windows
- Includes a powerful crash reporting and reproduction system
Cons of syzkaller
- Steeper learning curve due to its complex architecture and specialized focus
- Requires more setup and configuration compared to Detours
- Limited applicability outside of kernel and system call testing scenarios
Code Comparison
syzkaller (system call definition):
open$dir = open(filename ptr[in, filename], flags flags[open_flags], mode flags[open_mode]) fd
Detours (function hooking):
LONG DetourAttach(PVOID *ppPointer, PVOID pDetour)
Summary
syzkaller is a specialized tool for kernel fuzzing and system call testing across multiple operating systems, offering powerful crash reporting capabilities. However, it has a steeper learning curve and limited applicability outside its specific domain. Detours, on the other hand, is more focused on function hooking and interception, making it easier to use for general-purpose binary instrumentation but less suitable for comprehensive kernel testing.
edb is a cross-platform AArch32/x86/x86-64 debugger.
Pros of edb-debugger
- Full-featured graphical debugger with a user-friendly interface
- Cross-platform support (Linux, FreeBSD, OpenBSD, macOS)
- Extensible plugin architecture for custom functionality
Cons of edb-debugger
- Limited to debugging and analysis, not focused on runtime code modification
- May have a steeper learning curve for users new to debugging tools
Code Comparison
edb-debugger (C++):
IDebugger *debugger = edb::v1::debugger_core;
if (debugger->attach(pid)) {
edb::v1::debugger_core->set_active_thread(tid);
debugger->step();
}
Detours (C):
LONG error = DetourTransactionBegin();
error = DetourUpdateThread(GetCurrentThread());
error = DetourAttach(&(PVOID&)RealFunction, MyFunction);
error = DetourTransactionCommit();
Key Differences
- edb-debugger is a comprehensive debugger, while Detours focuses on API hooking and interception
- edb-debugger provides a GUI, whereas Detours is a library for programmatic use
- Detours is Windows-specific, while edb-debugger supports multiple platforms
- edb-debugger is better suited for analysis and reverse engineering, while Detours excels at runtime code modification
Convert
designs to code with AI
Introducing Visual Copilot: A new AI model to turn Figma designs to high quality code using your components.
Try Visual CopilotREADME
Microsoft Research Detours Package
Detours is a software package for monitoring and instrumenting API calls on Windows. Detours has been used by many ISVs and is also used by product teams at Microsoft. Detours is now available under a standard open source license (MIT). This simplifies licensing for programmers using Detours and allows the community to support Detours using open source tools and processes.
Detours is compatible with the Windows NT family of operating systems: Windows NT, Windows XP, Windows Server 2003, Windows 7, Windows 8, and Windows 10. It cannot be used by Windows Store apps because Detours requires APIs not available to those applications. This repo contains the source code for version 4.0.1 of Detours.
For technical documentation on Detours, see the Detours Wiki. For directions on how to build and run samples, see the samples README.txt file.
Contributing
The Detours
repository is where development is done.
Here are some ways you can participate in the project:
- Answer questions about using Detours.
- Improve the Wiki.
- Submit bugs and help us verify fixes and changes as they are checked in.
- Review source code changes.
Most contributions require you to agree to a Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us the rights to use your contribution. For details, visit https://cla.opensource.microsoft.com.
When you submit a pull request, a CLA bot will automatically determine whether you need to provide a CLA and decorate the PR appropriately (e.g., status check, comment). Simply follow the instructions provided by the bot. You will only need to do this once across all repos using our CLA.
This project has adopted the Microsoft Open Source Code of Conduct. For more information see the Code of Conduct FAQ or contact opencode@microsoft.com with any additional questions or comments.
Issues, questions, and feedback
- Open an issue on GitHub Issues.
Mailing list for announcements
The detours-announce mailing list is a low-traffic email list for important announcements about the project, such as the availability of new versions of Detours. To join it, send an email to listserv@lists.research.microsoft.com with a message body containing only the text SUBSCRIBE DETOURS-ANNOUNCE. To leave it, send an email to listserv@lists.research.microsoft.com with a message body containing only the text UNSUBSCRIBE DETOURS-ANNOUNCE.
License
Copyright (c) Microsoft Corporation. All rights reserved.
Licensed under the MIT License.
Top Related Projects
Clone this repo to build Frida
Fast and lightweight x86/x86-64 disassembler and code generation library
Dynamic Instrumentation Tool Platform
syzkaller is an unsupervised coverage-guided kernel fuzzer
edb is a cross-platform AArch32/x86/x86-64 debugger.
Convert
designs to code with AI
Introducing Visual Copilot: A new AI model to turn Figma designs to high quality code using your components.
Try Visual Copilot