detours.h

Go to the documentation of this file.

/*
 * Copyright (c) 2020 Bitdefender
 * SPDX-License-Identifier: Apache-2.0
 */
#ifndef _DETOURS_H_
#define _DETOURS_H_



#include "thread_safeness.h"
#include "handlers.h"

typedef struct _LIX_FN_DETOUR LIX_FN_DETOUR;

#define DET_ARG_REGS(Arg)         (gGuest.Guest64 ? ((DWORD)(Arg) < 16) : ((DWORD)(Arg) < 8))

#define DET_ARG_STACK(Index)      (((DWORD)(Index) << 16) | 0xFFFF)

#define DET_ARG_ON_STACK(Arg)     (((Arg) & 0xFFFF) == 0xFFFF)

#define DET_ARG_STACK_OFFSET(Arg) (((Arg) >> 16) * gGuest.WordSize)

#define DET_ARGS_MAX              8

#define DET_ARGS_DEFAULT_LIX      {.Argc = DET_ARGS_MAX, .Argv = {NDR_RDI, NDR_RSI, NDR_RDX, NDR_RCX, \
                                    NDR_R8, NDR_R9, DET_ARG_STACK(1), DET_ARG_STACK(2)}}

#define DET_ARGS_DEFAULT_WIN64    {.Argc = DET_ARGS_MAX, .Argv = {NDR_RCX, NDR_RDX, NDR_R8, NDR_R9, \
                                    DET_ARG_STACK(5), DET_ARG_STACK(6), DET_ARG_STACK(7), DET_ARG_STACK(8)}}

#define DET_ARGS_DEFAULT_WIN86    {.Argc = DET_ARGS_MAX, \
                                    .Argv = {DET_ARG_STACK(1), DET_ARG_STACK(2), DET_ARG_STACK(3), DET_ARG_STACK(4),\
                                    DET_ARG_STACK(5), DET_ARG_STACK(6), DET_ARG_STACK(7), DET_ARG_STACK(8)}}

typedef struct _DETOUR_ARGS
{
    DWORD Argc;                 
    DWORD Argv[DET_ARGS_MAX];   
} DETOUR_ARGS;

typedef enum
{
    detTagUnknown = 0,
    detTagPoolAlloc,
    detTagPoolFree,
    detTagModuleLoad,
    detTagModuleUnload,
    detTagProcCreate,
    detTagProcTerminate,
    detTagProcInject,
    detTagProcPtrace,
    detTagProcPtraceCompat,
    detTagProcVmRw,
    detTagEarlyProt,
    detTagBugcheck,
    detTagBugcheck2,
    detTagSyscallHook,
    detTagProcCopy,
    detTagException,
    detTagVadInsert,
    detTagVadInsertPriv,
    detTagVadInsertMap,
    detTagVmProtect,
    detTagVaDelete,
    detTagFinishVadDeletion,
    detTagVadDelete,
    detTagVadDeletePartial,
    detTagUnmapSection,
    detTagVadAdjust,
    detTagVadExpandDown,
    detTagPowerState,
    detTagProcThrHijack,
    detTagProcThrHijackWow64,
    detTagTextPoke,
    detTagTextPoke2,
    detTagProcQueueApc,
    detTagCommitCreds,
    detTagProbeKernelWrite,
    detTagSwapgs,
    detTagAccessRemoteVm,

    detTagRtlVirtualUnwind1,
    detTagRtlVirtualUnwind2,
    detTagRtlVirtualUnwind3,
    detTagRtlVirtualUnwind4,
    detTagRtlVirtualUnwind5,
    detTagRtlVirtualUnwind6,
    detTagRtlVirtualUnwind7,
    detTagRtlVirtualUnwind8,
    detTagRtlVirtualUnwindMax,

    detTagCleanupMemDump,
    detTagVadCommit,
    detTagKernelRead,

    detTagMax   
} DETOUR_TAG;

typedef enum
{
    hypercallTypeNone = 0,
    hypercallTypeInt3,
    hypercallTypeVmcall
} HYPERCALL_TYPE;

#define DETOUR_MAX_HANDLER_SIZE     512 
#define DETOUR_MAX_HANDLERS         8   

typedef INTSTATUS (*PFUNC_DetourCallback)(
    _In_ void *Detour
    );

typedef INTSTATUS (*PFUNC_PreDetourCallback)(
    _In_ QWORD FunctionAddress,
    _In_ void *Handler,
    _In_ QWORD HandlerAddress
    );

typedef INTSTATUS (*PFUNC_PostDetourCallback)(
    _In_ void *Handler
    );

#define PUBLIC_DATA_MAX_NAME_SIZE       16
#define PUBLIC_DATA_MAX_DESCRIPTORS     5

typedef struct _API_HOOK_PUBLIC_DATA
{
    CHAR PublicDataName[PUBLIC_DATA_MAX_NAME_SIZE];
    BYTE PublicDataOffset;
    BYTE PublicDataSize;
} API_HOOK_PUBLIC_DATA, *PAPI_HOOK_PUBLIC_DATA;

// Handler code. If the NtBuildNumber is zero, the handler can be used for Windows guests with any NtBuildNumber.
// If the NtBuildNumber is NOT zero, the handler can be used only for Windows guests that have the exact same
// NtBuildNumber. For this reason, the generic handler must be placed the last one: we could have a special handler
// for Windows with NtBuildNumber 10000 for example, and a generic handler that works for all other Windows
// guests.

typedef struct _API_HOOK_HANDLER
{
    DWORD                   MinVersion;
    DWORD                   MaxVersion;
    DWORD                   CodeLength;
    HYPERCALL_TYPE          HypercallType;
    BYTE                    Code[DETOUR_MAX_HANDLER_SIZE];
    BYTE                    HypercallOffset;
    BYTE                    RelocatedCodeOffset;
    API_HOOK_PUBLIC_DATA    PublicDataOffsets[PUBLIC_DATA_MAX_DESCRIPTORS];
    BYTE                    NrPublicDataOffsets;
} API_HOOK_HANDLER, *PAPI_HOOK_HANDLER;

#define DETOUR_MIN_VERSION_ANY          0
#define DETOUR_MAX_VERSION_ANY          0xFFFFFFFF

#define DETOUR_INVALID_HYPERCALL        0xFF

typedef struct _WIN_UNEXPORTED_FUNCTION WIN_UNEXPORTED_FUNCTION;

typedef struct _API_HOOK_DESCRIPTOR
{
    PWCHAR                      ModuleName;
    PCHAR                       FunctionName;
    DWORD                       MinVersion;
    DWORD                       MaxVersion;
    PFUNC_DetourCallback        Callback;
    PFUNC_PreDetourCallback     PreCallback;
    PFUNC_PostDetourCallback    PostCallback;

    DETOUR_TAG                  Tag;
    BOOLEAN                     Exported;
    BOOLEAN                     NotCritical;
    QWORD                       DisableFlags;
    QWORD                       EnableFlags;
    WIN_UNEXPORTED_FUNCTION     *Patterns;
    DETOUR_ARGS                 Arguments;
    DWORD                       HandlersCount;
    API_HOOK_HANDLER            Handlers[DETOUR_MAX_HANDLERS];
} API_HOOK_DESCRIPTOR, *PAPI_HOOK_DESCRIPTOR;


typedef INTSTATUS
(*PFUNC_LixDetourCallback)(
    _In_ void *Detour
    );


typedef struct _LIX_FN_DETOUR
{
    DETOUR_ID                   Id;                     
    char                        *FunctionName;          
    char                        *HijackFunctionName;
    PFUNC_LixDetourCallback     Callback;               
    QWORD                       EnableFlags;            
} LIX_FN_DETOUR;



#define DETOUR_ENABLE_ALWAYS    0xFFFFFFFFFFFFFFFF

typedef struct _DETOUR
{
    LIST_ENTRY              Link;
    PFUNC_DetourCallback    Callback;

    DETOUR_TAG              Tag;

    QWORD                   HypercallAddress;
    QWORD                   FunctionAddress;

    QWORD                   HandlerAddress;
    DWORD                   HandlerSize;

    QWORD                   LixGuestDetour;

    HYPERCALL_TYPE          HypercallType;

    BYTE                    JumpBackOffset;
    BYTE                    HypercallOffset;
    BYTE                    RelocatedCodeOffset;
    BYTE                    RelocatedCodeLength;

    BYTE                    NrPublicDataOffsets;
    API_HOOK_PUBLIC_DATA    PublicDataOffsets[PUBLIC_DATA_MAX_DESCRIPTORS];

    BOOLEAN                 Disabled;
    QWORD                   ModuleBase;

    void                    *FunctionCloakHandle;
    void                    *HandlerCloakHandle;
    QWORD                   HitCount;

    PAPI_HOOK_DESCRIPTOR    Descriptor;
    const LIX_FN_DETOUR     *LixFnDetour;
} DETOUR, *PDETOUR;


INTSTATUS
IntDetSetHook(
    _In_ QWORD FunctionAddress,
    _In_ QWORD ModuleBase,
    _Inout_ API_HOOK_DESCRIPTOR *Descriptor,
    _Inout_ API_HOOK_HANDLER *Handler
    );

INTSTATUS
IntDetSetLixHook(
    _In_ QWORD FunctionAddress,
    _In_ const LIX_FN_DETOUR *FnDetour,
    _Out_ BOOLEAN *MultipleInstructions
    );

INTSTATUS
IntDetSetReturnValue(
    _In_ DETOUR const *Detour,
    _Inout_opt_ IG_ARCH_REGS *Registers,
    _In_ QWORD ReturnValue
    );

INTSTATUS
IntDetCallCallback(
    void
    );

INTSTATUS
IntDetEnableDetour(
    _In_ DETOUR_TAG Tag
    );

INTSTATUS
IntDetDisableDetour(
    _In_ DETOUR_TAG Tag
    );

void
IntDetDisableAllHooks(
    void
    );

void
IntDetUninit(
    void
    );

void
IntDetDumpDetours(
    void
    );

BOOLEAN
IntDetIsPtrInHandler(
    _In_ QWORD Ptr,
    _In_ THS_PTR_TYPE Type,
    _Out_opt_ DETOUR_TAG *Tag
    );

BOOLEAN
IntDetIsPtrInRelocatedCode(
    _In_ QWORD Ptr,
    _Out_opt_ DETOUR_TAG *Tag
    );

QWORD
IntDetRelocatePtrIfNeeded(
    _In_ QWORD Ptr
    );

INTSTATUS
IntDetGetAddrAndTag(
    _In_ QWORD Ptr,
    _Out_ QWORD *Address,
    _Out_ DWORD *Size,
    _Out_ DETOUR_TAG *Tag
    );

INTSTATUS
IntDetGetByTag(
    _In_ DETOUR_TAG Tag,
    _Out_ QWORD *Address,
    _Out_opt_ DWORD *Size
    );

INTSTATUS
IntDetGetArgument(
    _In_ void const *Detour,
    _In_ DWORD Index,
    _In_opt_ BYTE const *StackBuffer,
    _In_ DWORD StackBufferSize,
    _Out_ QWORD *Value
    );

INTSTATUS
IntDetGetArguments(
    _In_ void const *Detour,
    _In_ DWORD Argc,
    _Out_writes_(Argc) QWORD *Argv
    );

INTSTATUS
IntDetPatchArgument(
    _In_ void const *Detour,
    _In_ DWORD Index,
    _In_ QWORD Value
    );

INTSTATUS
IntDetModifyPublicData(
    _In_ DETOUR_TAG Tag,
    _In_ void const *Data,
    _In_ DWORD DataSize,
    _In_ char const *PublicDataName
    );

#endif // _DETOURS_H_