KNSoft.SlimDetours 1.0.0-beta

<br>

KNSoft.SlimDetours

SlimDetours is an improved Windows API hooking library base on Microsoft Detours.

Feature

Compared to the original Detours, the advantages are:

• New feature
  • Support delay hook (set hooks automatically when target DLL loaded) 🔗 TechWiki: Implement Delay Hook
  • Automatically update threads when set hooks 🔗 TechWiki: Update Threads Automatically When Applying Inline Hooks
• Improved
  • Avoid deadlocks when updating threads 🔗 TechWiki: Avoid Deadlocking on The Heap When Updating Threads
  • Avoid occupying system reserved memory region 🔗 TechWiki: Avoid Occupying System Reserved Region When Allocating Trampoline
  • Other bug fixes and code improvements
• Lite
  • Depends on Ntdll.dll only
  • Retain API hooking functions only
  • Remove support for ARM (ARM32), IA64, WinXP, GNUC
  • Smaller binary size
• Out-of-the-box
  • NuGet package is released

Usage

TL;DR

KNSoft.SlimDetours package contains both of SlimDetours and the original Microsoft Detours.

Include header SlimDetours.h for KNSoft.SlimDetours, or header detours.h for the original Microsoft Detours, then link compiled library KNSoft.SlimDetours.lib.

NuGet package KNSoft.SlimDetours is out-of-the-box, install to project and the compiled library will be linked automatically.

#include <KNSoft/SlimDetours/SlimDetours.h> // KNSoft.SlimDetours
#include <KNSoft/SlimDetours/detours.h>     // Microsoft Detours

If your project configuration name is neither "Release" nor "Debug", MSBuild sheet in NuGet package cannot link compiled library automatically, link manually is required, for example:

#pragma comment(lib, "Debug/KNSoft.SlimDetours.lib")

Usage is similiar to the original Microsoft Detours, but:

• Function name begin with "SlimDetours", most of return values are NTSTATUS, use NT_SUCCESS macro to check them.
• Threads are updated automatically, DetourUpdateThread is removed.

Status = SlimDetoursTransactionBegin();
if (!NT_SUCCESS(Status))
{
    return Status;
}
Status = SlimDetoursAttach((PVOID*)&g_pfnXxx, Hooked_Xxx);
if (!NT_SUCCESS(Status))
{
    SlimDetoursTransactionAbort();
    return Status;
}
return SlimDetoursTransactionCommit();

Delay Hook

"Delay Hook" will set hooks automatically when target DLL loaded.

For example, call SlimDetoursDelayAttach to hook a.dll!FuncXxx automatically when a.dll loaded:

SlimDetoursDelayAttach((PVOID*)&g_pfnFuncXxx,
                       Hooked_FuncXxx,
                       L"a.dll",
                       L"FuncXxx",
                       NULL,
                       NULL);

Demo: DelayHook.c

Compatibility

Project building: only support for the latest MSVC generation tools and SDKs is considered, but it is generally more widely backward compatible.

Artifact integration: it is widely backward compatible with MSVC generation tools and different compilation configurations (e.g., /MD, /MT).

Runtime environment: NT6 or above OS, x86/x64/ARM64 platform.

[!CAUTION] In beta stage, should be used with caution.

License

KNSoft.SlimDetours is licensed under the MPL-2.0 license.

Source is based on Microsoft Detours which is licensed under the MIT license.

Also uses KNSoft.NDK to access low-level Windows NT APIs and its Unit Test Framework.