EptHook.c File Reference

Implementation of different EPT hidden hooks functions. More...

#include "pch.h"

Functions
_Must_inspect_result_	_Success_ (return==TRUE)
	Check whether the desired PhysicalAddress is already in the g_EptState->HookedPagesList hooks or not.
VOID	EptHookReservePreallocatedPoolsForEptHooks (UINT32 Count)
	Reserve pre-allocated pools for EPT hooks.
VOID	EptHookAllocateExtraHookingPagesForMemoryMonitorsAndExecEptHooks (UINT32 Count)
	Allocate (reserve) extra pages for storing details of page hooks for memory monitor and regular hidden breakpoit exec EPT hooks.
PVOID	ExAllocatePoolWithTagHook (POOL_TYPE PoolType, SIZE_T NumberOfBytes, ULONG Tag)
	Hook function that HooksExAllocatePoolWithTag.
BOOLEAN	EptHookPerformPageHook (VIRTUAL_MACHINE_STATE *VCpu, PVOID TargetAddress, CR3_TYPE ProcessCr3)
	The main function that performs EPT page hook with hidden breakpoint.
BOOLEAN	EptHookPerformHook (PVOID TargetAddress, UINT32 ProcessId, BOOLEAN ApplyDirectlyFromVmxRoot)
	This function invokes a VMCALL to set the hook and broadcast the exiting for the breakpoints on exception bitmap.
BOOLEAN	EptHook (PVOID TargetAddress, UINT32 ProcessId)
	This function invokes a VMCALL to set the hook and broadcast the exiting for the breakpoints on exception bitmap.
BOOLEAN	EptHookFromVmxRoot (PVOID TargetAddress)
	This function invokes a direct VMCALL to setup the hook.
BOOLEAN	EptHookRestoreSingleHookToOriginalEntry (VIRTUAL_MACHINE_STATE *VCpu, SIZE_T PhysicalAddress, UINT64 OriginalEntry)
	Remove and Invalidate Hook in TLB (Hidden Detours and if counter of hidden breakpoint is zero).
VOID	EptHookRestoreAllHooksToOriginalEntry (VIRTUAL_MACHINE_STATE *VCpu)
	Remove and Invalidate Hook in TLB.
VOID	EptHookWriteAbsoluteJump (PCHAR TargetBuffer, SIZE_T TargetAddress)
	Write an absolute x64 jump to an arbitrary address to a buffer.
VOID	EptHookWriteAbsoluteJump2 (PCHAR TargetBuffer, SIZE_T TargetAddress)
	Write an absolute x64 jump to an arbitrary address to a buffer.
BOOLEAN	EptHookInstructionMemory (PEPT_HOOKED_PAGE_DETAIL Hook, CR3_TYPE ProcessCr3, PVOID TargetFunction, PVOID TargetFunctionInSafeMemory, PVOID HookFunction)
	Hook instructions.
BOOLEAN	EptHookPerformPageHookMonitorAndInlineHook (VIRTUAL_MACHINE_STATE *VCpu, PVOID HookingDetails, CR3_TYPE ProcessCr3, UINT32 PageHookMask)
	The main function that performs EPT page hook with hidden detours and monitor.
BOOLEAN	EptHookPerformMemoryOrInlineHook (VIRTUAL_MACHINE_STATE *VCpu, EPT_HOOKS_ADDRESS_DETAILS_FOR_EPTHOOK2 *EptHook2AddressDetails, EPT_HOOKS_ADDRESS_DETAILS_FOR_MEMORY_MONITOR *MemoryAddressDetails, UINT32 ProcessId, BOOLEAN EptHiddenHook2, BOOLEAN ApplyDirectlyFromVmxRoot)
	This function allocates a buffer in VMX Non Root Mode and then invokes a VMCALL to set the hook.
BOOLEAN	EptHookInlineHook (VIRTUAL_MACHINE_STATE *VCpu, PVOID TargetAddress, PVOID HookFunction, UINT32 ProcessId)
	This function applies EPT hook 2 (inline) to the target EPT table.
BOOLEAN	EptHookMonitorHook (VIRTUAL_MACHINE_STATE *VCpu, EPT_HOOKS_ADDRESS_DETAILS_FOR_MEMORY_MONITOR *HookingDetails, UINT32 ProcessId)
	This function applies monitor hooks to the target EPT table.
BOOLEAN	EptHookInlineHookFromVmxRoot (VIRTUAL_MACHINE_STATE *VCpu, PVOID TargetAddress, PVOID HookFunction)
	This function applies EPT inline to the target EPT table.
BOOLEAN	EptHookMonitorFromVmxRoot (VIRTUAL_MACHINE_STATE *VCpu, EPT_HOOKS_ADDRESS_DETAILS_FOR_MEMORY_MONITOR *MemoryAddressDetails)
	This function applies EPT monitor hooks to the target EPT table.
BOOLEAN	EptHookHandleHookedPage (VIRTUAL_MACHINE_STATE *VCpu, EPT_HOOKED_PAGE_DETAIL *HookedEntryDetails, VMX_EXIT_QUALIFICATION_EPT_VIOLATION ViolationQualification, SIZE_T PhysicalAddress, EPT_HOOKS_CONTEXT *LastContext, BOOLEAN *IgnoreReadOrWriteOrExec, BOOLEAN *IsExecViolation)
	Handles page hooks (trigger events).
BOOLEAN	EptHookRemoveEntryAndFreePoolFromEptHook2sDetourList (UINT64 Address)
	Remove the entry from g_EptHook2sDetourListHead in the case of !epthook2 details.
UINT32	EptHookGetCountOfEpthooks (BOOLEAN IsEptHook2)
	get the length of active EPT hooks (!epthook and !epthook2)
BOOLEAN	EptHookUnHookSingleAddressDetoursAndMonitor (PEPT_HOOKED_PAGE_DETAIL HookedEntry, BOOLEAN ApplyDirectlyFromVmxRoot, EPT_SINGLE_HOOK_UNHOOKING_DETAILS *TargetUnhookingDetails)
	Remove single hook of detours type.
VOID	EptHookHandleMonitorTrapFlag (VIRTUAL_MACHINE_STATE *VCpu)
	Handle vm-exits for Monitor Trap Flag to restore previous state.
BOOLEAN	EptHookUnHookSingleAddressHiddenBreakpoint (PEPT_HOOKED_PAGE_DETAIL HookedEntry, UINT64 VirtualAddress, BOOLEAN ApplyDirectlyFromVmxRoot, EPT_SINGLE_HOOK_UNHOOKING_DETAILS *TargetUnhookingDetails)
	Remove single hook of hidden breakpoint type.
BOOLEAN	EptHookPerformUnHookSingleAddress (UINT64 VirtualAddress, UINT64 PhysAddress, UINT64 HookingTag, UINT32 ProcessId, BOOLEAN ApplyDirectlyFromVmxRoot, EPT_SINGLE_HOOK_UNHOOKING_DETAILS *TargetUnhookingDetails)
	Remove single hook from the hooked pages list and invalidate TLB.
BOOLEAN	EptHookUnHookAllByHookingTag (UINT64 HookingTag)
	Remove all hooks from the hooked pages by the given hooking tag.
BOOLEAN	EptHookUnHookSingleHookByHookingTagFromVmxRoot (UINT64 HookingTag, EPT_SINGLE_HOOK_UNHOOKING_DETAILS *TargetUnhookingDetails)
	Remove single hook from the hooked pages by the given hooking tag.
BOOLEAN	EptHookUnHookSingleAddress (UINT64 VirtualAddress, UINT64 PhysAddress, UINT32 ProcessId)
	Remove single hook from the hooked pages list and invalidate TLB.
BOOLEAN	EptHookUnHookSingleAddressFromVmxRoot (UINT64 VirtualAddress, UINT64 PhysAddress, EPT_SINGLE_HOOK_UNHOOKING_DETAILS *TargetUnhookingDetails)
	Remove single hook from the hooked pages list and invalidate TLB.
VOID	EptHookUnHookAll ()
	Remove all hooks from the hooked pages list and invalidate TLB @detailsShould be called from Vmx Non-root.
PVOID	EptHook2GeneralDetourEventHandler (PGUEST_REGS Regs, PVOID CalledFrom)
	routines to generally handle breakpoint hit for detour
BOOLEAN	EptHookModifyInstructionFetchState (VIRTUAL_MACHINE_STATE *VCpu, PVOID PhysicalAddress, BOOLEAN IsUnset)
	Change PML EPT state for execution (execute) @detail should be called from VMX-root.
BOOLEAN	EptHookModifyPageReadState (VIRTUAL_MACHINE_STATE *VCpu, PVOID PhysicalAddress, BOOLEAN IsUnset)
	Change PML EPT state for read @detail should be called from VMX-root.
BOOLEAN	EptHookModifyPageWriteState (VIRTUAL_MACHINE_STATE *VCpu, PVOID PhysicalAddress, BOOLEAN IsUnset)
	Change PML EPT state for write @detail should be called from VMX-root.

Detailed Description

Implementation of different EPT hidden hooks functions.

Author

Sina Karvandi (sina@.nosp@m.hype.nosp@m.rdbg..nosp@m.org)

All the R/W hooks, Execute hooks and hardware register simulators are implemented here

Version

0.1

Date

2020-04-11

Copyright

This project is released under the GNU Public License v3.

Function Documentation

_Success_()

_Must_inspect_result_ _Success_

(

return

= = TRUE

)

Check whether the desired PhysicalAddress is already in the g_EptState->HookedPagesList hooks or not.

Parameters

PhysicalBaseAddress

Returns

PEPT_HOOKED_PAGE_DETAIL if the address was already hooked, or FALSE

{
    LIST_FOR_EACH_LINK(g_EptState->HookedPagesList, EPT_HOOKED_PAGE_DETAIL, PageHookList, CurrEntity)
    {
        if (CurrEntity->PhysicalBaseAddress == PhysicalBaseAddress)
        {
            return CurrEntity;
        }
    }
 
    return NULL;
}

EptHook()

BOOLEAN EptHook	(	PVOID	TargetAddress,
		UINT32	ProcessId )

This function invokes a VMCALL to set the hook and broadcast the exiting for the breakpoints on exception bitmap.

Hook in VMX non-root Mode (hidden breakpoint).

this command uses hidden breakpoints (0xcc) to hook, THIS FUNCTION SHOULD BE CALLED WHEN THE VMLAUNCH ALREADY EXECUTED, it is because, broadcasting to enable exception bitmap for breakpoint is not clear here, if we want to broadcast to enable exception bitmaps on all cores when vmlaunch is not executed then that's ok but a user might call this function when we didn't configure the vmcs, it's a problem! we can solve it by giving a hint to vmcs configure function to make it ok for future configuration but that sounds stupid, I think it's better to not support this feature. Btw, debugger won't use this function in the above mentioned method, so we won't have any problem with this This function should be called from VMX non-root mode

Parameters

TargetAddress	The address of function or memory address to be hooked
ProcessId	The process id to translate based on that process's cr3

Returns

BOOLEAN Returns true if the hook was successful or false if there was an error

This function invokes a VMCALL to set the hook and broadcast the exiting for the breakpoints on exception bitmap.

Parameters

TargetAddress
ProcessId

Returns

BOOLEAN

{
    //
    // Should be called from vmx non-root
    //
    if (VmxGetCurrentExecutionMode() == TRUE)
    {
        return FALSE;
    }
 
    return EptHookPerformHook(TargetAddress, ProcessId, FALSE);
}

EptHook2GeneralDetourEventHandler()

PVOID EptHook2GeneralDetourEventHandler	(	PGUEST_REGS	Regs,
		PVOID	CalledFrom )

routines to generally handle breakpoint hit for detour

Parameters

Regs
CalledFrom

Returns

PVOID

{
    PLIST_ENTRY       TempList    = 0;
    EPT_HOOKS_CONTEXT TempContext = {0};
 
    //
    // The RSP register is the at the RCX and we just added (reverse by stack) to it's
    // values by the size of the GUEST_REGS
    //
    Regs->rsp = (UINT64)Regs - sizeof(GUEST_REGS);
 
    //
    // test
    //
 
    //
    // LogInfo("Hidden Hooked function Called with : rcx = 0x%llx , rdx = 0x%llx , r8 = 0x%llx ,  r9 = 0x%llx",
    //        Regs->rcx,
    //        Regs->rdx,
    //        Regs->r8,
    //        Regs->r9);
    //
 
    //
    // Create temporary context
    //
    TempContext.VirtualAddress  = (UINT64)CalledFrom;
    TempContext.PhysicalAddress = VirtualAddressToPhysicalAddress(CalledFrom);
 
    //
    // Create a temporary VCpu
    //
    VIRTUAL_MACHINE_STATE * VCpu = &g_GuestState[KeGetCurrentProcessorNumberEx(NULL)];
 
    //
    // Set the register for the temporary VCpu
    //
    VCpu->Regs = Regs;
 
    //
    // As the context to event trigger, we send the address of function
    // which is current hidden hook is triggered for it
    //
    DispatchEventHiddenHookExecDetours(VCpu, &TempContext);
 
    //
    // Iterate through the list of hooked pages details to find
    // and return where want to jump after this functions
    //
    TempList = &g_EptHook2sDetourListHead;
 
    while (&g_EptHook2sDetourListHead != TempList->Flink)
    {
        TempList                                          = TempList->Flink;
        PHIDDEN_HOOKS_DETOUR_DETAILS CurrentHookedDetails = CONTAINING_RECORD(TempList, HIDDEN_HOOKS_DETOUR_DETAILS, OtherHooksList);
 
        if (CurrentHookedDetails->HookedFunctionAddress == CalledFrom)
        {
            return CurrentHookedDetails->ReturnAddress;
        }
    }
 
    //
    // If we reach here, means that we didn't find the return address
    // that's an error, generally we can't do anything but as the user
    // might already cleaned the hook and the structures are removed
    // so we just return the original caller address and continue the
    // guest normally
    //
    return CalledFrom;
}

EptHookAllocateExtraHookingPagesForMemoryMonitorsAndExecEptHooks()

VOID EptHookAllocateExtraHookingPagesForMemoryMonitorsAndExecEptHooks

(

UINT32

Count

)

Allocate (reserve) extra pages for storing details of page hooks for memory monitor and regular hidden breakpoit exec EPT hooks.

Parameters

Count

Returns

VOID

{
    ULONG ProcessorsCount;
 
    //
    // Get number of processors
    //
    ProcessorsCount = KeQueryActiveProcessorCount(0);
 
    //
    // Request pages to be allocated for converting 2MB to 4KB pages
    // Each core needs its own splitting page-tables
    //
    PoolManagerCallbackRequestAllocation(sizeof(VMM_EPT_DYNAMIC_SPLIT),
                                         Count * ProcessorsCount,
                                         SPLIT_2MB_PAGING_TO_4KB_PAGE);
 
    //
    // Request pages to be allocated for paged hook details
    //
    PoolManagerCallbackRequestAllocation(sizeof(EPT_HOOKED_PAGE_DETAIL),
                                         Count,
                                         TRACKING_HOOKED_PAGES);
}

EptHookFromVmxRoot()

BOOLEAN EptHookFromVmxRoot

(

PVOID

TargetAddress

)

This function invokes a direct VMCALL to setup the hook.

the caller of this function should make sure to 1) broadcast to all cores to intercept breakpoints (#BPs) and after calling this function 2) the caller should broadcast to all cores to invalidate their EPTPs This function should be called from VMX root-mode

Parameters

TargetAddress

The address of function or memory address to be hooked

Returns

BOOLEAN Returns true if the hook was successful or false if there was an error

Parameters

TargetAddress

Returns

BOOLEAN

{
    //
    // Should be called from VMX root-mode
    //
    if (VmxGetCurrentExecutionMode() == FALSE)
    {
        return FALSE;
    }
 
    return EptHookPerformHook(TargetAddress, NULL_ZERO, TRUE);
}

EptHookGetCountOfEpthooks()

UINT32 EptHookGetCountOfEpthooks

(

BOOLEAN

IsEptHook2

)

get the length of active EPT hooks (!epthook and !epthook2)

Parameters

IsEptHook2

Whether the length should be for !epthook or !epthook2

Returns

UINT32 Count of remained breakpoints

Parameters

return UINT32

{
    UINT32 Count = 0;
 
    LIST_FOR_EACH_LINK(g_EptState->HookedPagesList, EPT_HOOKED_PAGE_DETAIL, PageHookList, HookedEntry)
    {
        if (IsEptHook2)
        {
            if (HookedEntry->IsHiddenBreakpoint == FALSE)
            {
                Count++;
            }
        }
        else
        {
            if (HookedEntry->IsHiddenBreakpoint == TRUE)
            {
                Count++;
            }
        }
    }
 
    return Count;
}

EptHookHandleHookedPage()

BOOLEAN EptHookHandleHookedPage	(	VIRTUAL_MACHINE_STATE *	VCpu,
		EPT_HOOKED_PAGE_DETAIL *	HookedEntryDetails,
		VMX_EXIT_QUALIFICATION_EPT_VIOLATION	ViolationQualification,
		SIZE_T	PhysicalAddress,
		EPT_HOOKS_CONTEXT *	LastContext,
		BOOLEAN *	IgnoreReadOrWriteOrExec,
		BOOLEAN *	IsExecViolation )

Handles page hooks (trigger events).

Handle hooked pages in Vmx-root mode.

Parameters

VCpu	The virtual processor's state
HookedEntryDetails	The entry that describes the hooked page
ViolationQualification	The exit qualification of vm-exit
PhysicalAddress	The physical address that cause this vm-exit
LastContext	The last (current) context of the execution
IgnoreReadOrWriteOrExec	Whether to ignore the event effects or not
IsExecViolation	Whether it's execution violation or not executing the post triggering of the event or not

Returns

BOOLEAN Returns TRUE if the function was hook was handled or returns false if there was an unexpected ept violation

Handles page hooks (trigger events).

Parameters

VCpu
HookedEntryDetails
ViolationQualification
PhysicalAddress
LastContext
IgnoreReadOrWriteOrExec
IsExecViolation

Returns

BOOLEAN

{
    UINT64  ExactAccessedVirtualAddress;
    UINT64  AlignedVirtualAddress;
    UINT64  AlignedPhysicalAddress;
    BOOLEAN IsTriggeringPostEventAllowed = FALSE;
 
    //
    // Get alignment
    //
    AlignedVirtualAddress  = (UINT64)PAGE_ALIGN(HookedEntryDetails->VirtualAddress);
    AlignedPhysicalAddress = (UINT64)PAGE_ALIGN(PhysicalAddress);
 
    //
    // Let's read the exact address that was accessed
    //
    ExactAccessedVirtualAddress = AlignedVirtualAddress + PhysicalAddress - AlignedPhysicalAddress;
 
    //
    // Set the last context
    //
    LastContext->HookingTag      = HookedEntryDetails->HookingTag;
    LastContext->PhysicalAddress = PhysicalAddress;
    LastContext->VirtualAddress  = ExactAccessedVirtualAddress;
 
    if (!ViolationQualification.EptReadable && ViolationQualification.ReadAccess)
    {
        //
        // LogInfo("Guest RIP : 0x%llx tries to read the page at : 0x%llx", GuestRip, ExactAccessedAddress);
        //
 
        //
        // Set last violation
        //
        HookedEntryDetails->LastViolation = EPT_HOOKED_LAST_VIOLATION_READ;
 
        //
        // Trigger the event related to Monitor Read and Monitor Read & Write and
        // Monitor Read & Execute and Monitor Read & Write & Execute
        //
        *IgnoreReadOrWriteOrExec = DispatchEventHiddenHookPageReadWriteExecuteReadPreEvent(VCpu, LastContext, &IsTriggeringPostEventAllowed);
 
        //
        // It's not an execution violation
        //
        *IsExecViolation = FALSE;
    }
    else if (!ViolationQualification.EptWriteable && ViolationQualification.WriteAccess)
    {
        //
        // LogInfo("Guest RIP : 0x%llx tries to write on the page at : 0x%llx", GuestRip, ExactAccessedAddress);
        //
 
        //
        // Set last violation
        //
        HookedEntryDetails->LastViolation = EPT_HOOKED_LAST_VIOLATION_WRITE;
 
        //
        // Trigger the event related to Monitor Write and Monitor Read & Write and
        // Monitor Write & Execute and Monitor Read & Write & Execute
        //
        *IgnoreReadOrWriteOrExec = DispatchEventHiddenHookPageReadWriteExecuteWritePreEvent(VCpu, LastContext, &IsTriggeringPostEventAllowed);
 
        //
        // It's not an execution violation
        //
        *IsExecViolation = FALSE;
    }
    else if (!ViolationQualification.EptExecutable && ViolationQualification.ExecuteAccess)
    {
        //
        // LogInfo("Guest RIP : 0x%llx tries to execute the page at : 0x%llx", GuestRip, ExactAccessedAddress);
        //
 
        //
        // Set last violation
        //
        HookedEntryDetails->LastViolation = EPT_HOOKED_LAST_VIOLATION_EXEC;
 
        //
        // Trigger the event related to Monitor Execute and Monitor Read & Execute and
        // Monitor Write & Execute and Monitor Read & Write & Execute
        //
        *IgnoreReadOrWriteOrExec = DispatchEventHiddenHookPageReadWriteExecuteExecutePreEvent(VCpu, LastContext, &IsTriggeringPostEventAllowed);
 
        //
        // It's an execution violation
        //
        *IsExecViolation = TRUE;
    }
    else
    {
        //
        // triggering post event is not allowed as it's not valid
        //
        HookedEntryDetails->IsPostEventTriggerAllowed = FALSE;
 
        //
        // there was an unexpected ept violation
        //
        return FALSE;
    }
 
    //
    // Set whether the post event trigger is allowed or not
    // If only one event short-circuit a special EPT hook the 'post' mode will be ignored for all of the same events
    //
    if (*IgnoreReadOrWriteOrExec == FALSE)
    {
        HookedEntryDetails->IsPostEventTriggerAllowed = IsTriggeringPostEventAllowed;
    }
    else
    {
        //
        // Ignoring read/write/exec will remove the 'post' event
        //
        HookedEntryDetails->IsPostEventTriggerAllowed = FALSE;
    }
 
    //
    // Means that restore the Entry to the previous state after current
    // instruction executed in the guest
    //
    return TRUE;
}

EptHookHandleMonitorTrapFlag()

VOID EptHookHandleMonitorTrapFlag

(

VIRTUAL_MACHINE_STATE *

VCpu

)

Handle vm-exits for Monitor Trap Flag to restore previous state.

Parameters

VCpu	The virtual processor's state

Returns

VOID

{
    PVOID TargetPage;
    //
    // Pointer to the page entry in the page table
    //
    TargetPage = EptGetPml1Entry(VCpu->EptPageTable, VCpu->MtfEptHookRestorePoint->PhysicalBaseAddress);
 
    //
    // restore the hooked state
    //
    EptSetPML1AndInvalidateTLB(VCpu,
                               TargetPage,
                               VCpu->MtfEptHookRestorePoint->ChangedEntry,
                               InveptSingleContext);
 
    //
    // Check to trigger the post event (for events relating the !monitor command
    // and the emulation hardware debug registers)
    //
    if (VCpu->MtfEptHookRestorePoint->IsPostEventTriggerAllowed)
    {
        if (VCpu->MtfEptHookRestorePoint->LastViolation == EPT_HOOKED_LAST_VIOLATION_READ)
        {
            //
            // This is a "read" hook
            //
            DispatchEventHiddenHookPageReadWriteExecReadPostEvent(VCpu,
                                                                  &VCpu->MtfEptHookRestorePoint->LastContextState);
        }
        else if (VCpu->MtfEptHookRestorePoint->LastViolation == EPT_HOOKED_LAST_VIOLATION_WRITE)
        {
            //
            // This is a "write" hook
            //
            DispatchEventHiddenHookPageReadWriteExecWritePostEvent(VCpu,
                                                                   &VCpu->MtfEptHookRestorePoint->LastContextState);
        }
        else if (VCpu->MtfEptHookRestorePoint->LastViolation == EPT_HOOKED_LAST_VIOLATION_EXEC)
        {
            //
            // This is a "execute" hook
            //
            DispatchEventHiddenHookPageReadWriteExecExecutePostEvent(VCpu,
                                                                     &VCpu->MtfEptHookRestorePoint->LastContextState);
        }
    }
 
    //
    // Check for user-mode attaching mechanisms and callback
    // (we call it here, because this callback might change the EPTP entries and invalidate EPTP)
    //
    VmmCallbackRestoreEptState(VCpu->CoreId);
}

EptHookInlineHook()

BOOLEAN EptHookInlineHook	(	VIRTUAL_MACHINE_STATE *	VCpu,
		PVOID	TargetAddress,
		PVOID	HookFunction,
		UINT32	ProcessId )

This function applies EPT hook 2 (inline) to the target EPT table.

Hook in VMX non-root mode (hidden detours).

this function should be called from VMX non-root mode

Parameters

VCpu	The virtual processor's state
TargetAddress	The address of function or memory address to be hooked
HookFunction	The function that will be called when hook triggered
ProcessId	The process id to translate based on that process's cr3

Returns

BOOLEAN Returns true if the hook was successful or false if there was an error

This function applies EPT hook 2 (inline) to the target EPT table.

Parameters

VCpu
TargetAddress
HookFunction
ProcessId

Returns

BOOLEAN

{
    EPT_HOOKS_ADDRESS_DETAILS_FOR_EPTHOOK2 HookingDetail = {0};
 
    //
    // Should be called from vmx non-root
    //
    if (VmxGetCurrentExecutionMode() == TRUE)
    {
        return FALSE;
    }
 
    //
    // Set the hooking details
    //
    HookingDetail.TargetAddress = TargetAddress;
    HookingDetail.HookFunction  = HookFunction;
 
    return EptHookPerformMemoryOrInlineHook(VCpu,
                                            &HookingDetail,
                                            NULL,
                                            ProcessId,
                                            TRUE,
                                            FALSE);
}

EptHookInlineHookFromVmxRoot()

BOOLEAN EptHookInlineHookFromVmxRoot	(	VIRTUAL_MACHINE_STATE *	VCpu,
		PVOID	TargetAddress,
		PVOID	HookFunction )

This function applies EPT inline to the target EPT table.

Hook in VMX root-mode (hidden detours).

this function should be called from VMX root-mode

Parameters

VCpu	The virtual processor's state
TargetAddress	The address of function or memory address to be hooked
HookFunction	The function that will be called when hook triggered

Returns

BOOLEAN Returns true if the hook was successful or false if there was an error

This function applies EPT inline to the target EPT table.

Parameters

VCpu
TargetAddress
HookFunction

Returns

BOOLEAN

{
    EPT_HOOKS_ADDRESS_DETAILS_FOR_EPTHOOK2 HookingDetail = {0};
 
    //
    // Should be called from vmx root-mode
    //
    if (VmxGetCurrentExecutionMode() == FALSE)
    {
        return FALSE;
    }
 
    //
    // Configure the details
    //
    HookingDetail.TargetAddress = TargetAddress;
    HookingDetail.HookFunction  = HookFunction;
 
    return EptHookPerformMemoryOrInlineHook(VCpu,
                                            &HookingDetail,
                                            NULL,
                                            NULL_ZERO,
                                            TRUE,
                                            TRUE);
}

EptHookInstructionMemory()

BOOLEAN EptHookInstructionMemory	(	PEPT_HOOKED_PAGE_DETAIL	Hook,
		CR3_TYPE	ProcessCr3,
		PVOID	TargetFunction,
		PVOID	TargetFunctionInSafeMemory,
		PVOID	HookFunction )

Hook instructions.

Parameters

Hook	The details of hooked pages
ProcessCr3	The target Process CR3
TargetFunction	Target function that needs to be hooked
TargetFunctionInSafeMemory	Target content in the safe memory (used in Length Disassembler Engine)
HookFunction	The function that will be called when hook triggered

Returns

BOOLEAN Returns true if the hook was successful or returns false if it was not successful

{
    PHIDDEN_HOOKS_DETOUR_DETAILS DetourHookDetails;
    SIZE_T                       SizeOfHookedInstructions;
    SIZE_T                       OffsetIntoPage;
    CR3_TYPE                     Cr3OfCurrentProcess;
 
    OffsetIntoPage = ADDRMASK_EPT_PML1_OFFSET((SIZE_T)TargetFunction);
 
    //
    // Log offset
    //
    // LogInfo("OffsetIntoPage: 0x%llx", OffsetIntoPage);
    //
 
    if ((OffsetIntoPage + 19) > PAGE_SIZE - 1)
    {
        LogError("Err, function extends past a page boundary");
        return FALSE;
    }
 
    //
    // Determine the number of instructions necessary to overwrite using Length Disassembler Engine
    // EPTHOOK2 only supports 64-bit kernel (32-bit LDE is not supported)
    //
    for (SizeOfHookedInstructions = 0;
         SizeOfHookedInstructions < 19;
         SizeOfHookedInstructions += DisassemblerLengthDisassembleEngineInVmxRootOnTargetProcess(
             (PVOID)((UINT64)TargetFunctionInSafeMemory + SizeOfHookedInstructions),
             FALSE))
    {
        //
        // Get the full size of instructions necessary to copy
        //
    }
 
    // for (SizeOfHookedInstructions = 0;
    //      SizeOfHookedInstructions < 19;
    //      SizeOfHookedInstructions += ZydisLde(((UINT64)TargetFunctionInSafeMemory + SizeOfHookedInstructions), TRUE))
    //{
    //     //
    //     // Get the full size of instructions necessary to copy
    //     //
    // }
 
    //
    // For logging purpose
    //
    // LogInfo("Number of bytes of instruction mem: %x", SizeOfHookedInstructions);
 
    //
    // Build a trampoline
    //
 
    //
    // Allocate some executable memory for the trampoline
    //
    Hook->Trampoline = (CHAR *)PoolManagerCallbackRequestPool(EXEC_TRAMPOLINE, TRUE, MAX_EXEC_TRAMPOLINE_SIZE);
 
    if (!Hook->Trampoline)
    {
        LogError("Err, could not allocate trampoline function buffer");
        return FALSE;
    }
 
    //
    // Copy the trampoline instructions in
    //
 
    // Switch to target process
    //
    Cr3OfCurrentProcess = SwitchToProcessMemoryLayoutByCr3(ProcessCr3);
 
    //
    // The following line can't be used in user mode addresses
    // RtlCopyMemory(Hook->Trampoline, TargetFunction, SizeOfHookedInstructions);
    //
    MemoryMapperReadMemorySafe((UINT64)TargetFunction, Hook->Trampoline, SizeOfHookedInstructions);
 
    //
    // Restore to original process
    //
    SwitchToPreviousProcess(Cr3OfCurrentProcess);
 
    //
    // Add the absolute jump back to the original function
    //
    EptHookWriteAbsoluteJump2(&Hook->Trampoline[SizeOfHookedInstructions], (SIZE_T)TargetFunction + SizeOfHookedInstructions);
 
    //
    //
    //
    // LogInfo("Trampoline: 0x%llx", Hook->Trampoline);
    // LogInfo("HookFunction: 0x%llx", HookFunction);
 
    //
    // Let the hook function call the original function
    //
    // *OrigFunction = Hook->Trampoline;
    //
 
    //
    // Create the structure to return for the debugger, we do it here because it's the first
    // function that changes the original function and if our structure is no ready after this
    // function then we probably see BSOD on other cores
    //
    DetourHookDetails                        = (HIDDEN_HOOKS_DETOUR_DETAILS *)PoolManagerCallbackRequestPool(DETOUR_HOOK_DETAILS, TRUE, sizeof(HIDDEN_HOOKS_DETOUR_DETAILS));
    DetourHookDetails->HookedFunctionAddress = TargetFunction;
    DetourHookDetails->ReturnAddress         = Hook->Trampoline;
 
    //
    // Save the address of DetourHookDetails because we want to
    // deallocate it when the hook is finished
    //
    Hook->AddressOfEptHook2sDetourListEntry = (UINT64)DetourHookDetails;
 
    //
    // Insert it to the list of hooked pages
    //
    InsertHeadList(&g_EptHook2sDetourListHead, &(DetourHookDetails->OtherHooksList));
 
    //
    // Write the absolute jump to our shadow page memory to jump to our hook
    //
    EptHookWriteAbsoluteJump(&Hook->FakePageContents[OffsetIntoPage], (SIZE_T)HookFunction);
 
    return TRUE;
}

EptHookModifyInstructionFetchState()

BOOLEAN EptHookModifyInstructionFetchState	(	VIRTUAL_MACHINE_STATE *	VCpu,
		PVOID	PhysicalAddress,
		BOOLEAN	IsUnset )

Change PML EPT state for execution (execute) @detail should be called from VMX-root.

Parameters

VCpu	The virtual processor's state
PhysicalAddress	Target physical address
IsUnset	Is unsetting bit or setting bit

Returns

BOOLEAN

{
    PVOID   PmlEntry    = NULL;
    BOOLEAN IsLargePage = FALSE;
 
    PmlEntry = EptGetPml1OrPml2Entry(VCpu->EptPageTable, (SIZE_T)PhysicalAddress, &IsLargePage);
 
    if (PmlEntry)
    {
        if (IsLargePage)
        {
            if (IsUnset)
            {
                ((PEPT_PML2_ENTRY)PmlEntry)->ExecuteAccess = FALSE;
            }
            else
            {
                ((PEPT_PML2_ENTRY)PmlEntry)->ExecuteAccess = TRUE;
            }
        }
        else
        {
            if (IsUnset)
            {
                ((PEPT_PML1_ENTRY)PmlEntry)->ExecuteAccess = FALSE;
            }
            else
            {
                ((PEPT_PML1_ENTRY)PmlEntry)->ExecuteAccess = TRUE;
            }
        }
    }
    else
    {
        return FALSE;
    }
 
    //
    // Invalidate the EPTP (single-context)
    //
    EptInveptSingleContext(VCpu->EptPointer.AsUInt);
 
    return TRUE;
}

EptHookModifyPageReadState()

BOOLEAN EptHookModifyPageReadState	(	VIRTUAL_MACHINE_STATE *	VCpu,
		PVOID	PhysicalAddress,
		BOOLEAN	IsUnset )

Change PML EPT state for read @detail should be called from VMX-root.

Parameters

VCpu	The virtual processor's state
PhysicalAddress	Target physical address
IsUnset	Is unsetting bit or setting bit

Returns

BOOLEAN

{
    PVOID   PmlEntry    = NULL;
    BOOLEAN IsLargePage = FALSE;
 
    PmlEntry = EptGetPml1OrPml2Entry(VCpu->EptPageTable, (SIZE_T)PhysicalAddress, &IsLargePage);
 
    if (PmlEntry)
    {
        if (IsLargePage)
        {
            if (IsUnset)
            {
                ((PEPT_PML2_ENTRY)PmlEntry)->ReadAccess = FALSE;
            }
            else
            {
                ((PEPT_PML2_ENTRY)PmlEntry)->ReadAccess = TRUE;
            }
        }
        else
        {
            if (IsUnset)
            {
                ((PEPT_PML1_ENTRY)PmlEntry)->ReadAccess = FALSE;
            }
            else
            {
                ((PEPT_PML1_ENTRY)PmlEntry)->ReadAccess = TRUE;
            }
        }
    }
    else
    {
        return FALSE;
    }
 
    //
    // Invalidate the EPTP (single-context)
    //
    EptInveptSingleContext(VCpu->EptPointer.AsUInt);
 
    return TRUE;
}

EptHookModifyPageWriteState()

BOOLEAN EptHookModifyPageWriteState	(	VIRTUAL_MACHINE_STATE *	VCpu,
		PVOID	PhysicalAddress,
		BOOLEAN	IsUnset )

Change PML EPT state for write @detail should be called from VMX-root.

Parameters

VCpu	The virtual processor's state
PhysicalAddress	Target physical address
IsUnset	Is unsetting bit or setting bit

Returns

BOOLEAN

{
    PVOID   PmlEntry    = NULL;
    BOOLEAN IsLargePage = FALSE;
 
    PmlEntry = EptGetPml1OrPml2Entry(VCpu->EptPageTable, (SIZE_T)PhysicalAddress, &IsLargePage);
 
    if (PmlEntry)
    {
        if (IsLargePage)
        {
            if (IsUnset)
            {
                ((PEPT_PML2_ENTRY)PmlEntry)->WriteAccess = FALSE;
            }
            else
            {
                ((PEPT_PML2_ENTRY)PmlEntry)->WriteAccess = TRUE;
            }
        }
        else
        {
            if (IsUnset)
            {
                ((PEPT_PML1_ENTRY)PmlEntry)->WriteAccess = FALSE;
            }
            else
            {
                ((PEPT_PML1_ENTRY)PmlEntry)->WriteAccess = TRUE;
            }
        }
    }
    else
    {
        return FALSE;
    }
 
    //
    // Invalidate the EPTP (single-context)
    //
    EptInveptSingleContext(VCpu->EptPointer.AsUInt);
 
    return TRUE;
}

EptHookMonitorFromVmxRoot()

BOOLEAN EptHookMonitorFromVmxRoot	(	VIRTUAL_MACHINE_STATE *	VCpu,
		EPT_HOOKS_ADDRESS_DETAILS_FOR_MEMORY_MONITOR *	MemoryAddressDetails )

This function applies EPT monitor hooks to the target EPT table.

this function should be called from VMX root-mode

Parameters

VCpu	The virtual processor's state
MemoryAddressDetails	details of the target memory

Returns

BOOLEAN Returns true if the hook was successful or false if there was an error

this function should be called from VMX root-mode

Parameters

VCpu
MemoryAddressDetails

Returns

BOOLEAN

{
    //
    // Should be called from vmx root-mode
    //
    if (VmxGetCurrentExecutionMode() == FALSE)
    {
        return FALSE;
    }
 
    return EptHookPerformMemoryOrInlineHook(VCpu,
                                            NULL,
                                            MemoryAddressDetails,
                                            NULL_ZERO,
                                            FALSE,
                                            TRUE);
}

EptHookMonitorHook()

BOOLEAN EptHookMonitorHook	(	VIRTUAL_MACHINE_STATE *	VCpu,
		EPT_HOOKS_ADDRESS_DETAILS_FOR_MEMORY_MONITOR *	HookingDetails,
		UINT32	ProcessId )

This function applies monitor hooks to the target EPT table.

this function should be called from VMX non-root mode

Parameters

VCpu	The virtual processor's state
HookingDetails	Monitor hooking details
ProcessId	The process id to translate based on that process's cr3

Returns

BOOLEAN Returns true if the hook was successful or false if there was an error

this function should be called from VMX non-root mode

Parameters

VCpu
HookingDetails
ProcessId

Returns

BOOLEAN

{
    //
    // Should be called from vmx non-root
    //
    if (VmxGetCurrentExecutionMode() == TRUE)
    {
        return FALSE;
    }
 
    return EptHookPerformMemoryOrInlineHook(VCpu,
                                            NULL,
                                            HookingDetails,
                                            ProcessId,
                                            FALSE,
                                            FALSE);
}

EptHookPerformHook()

BOOLEAN EptHookPerformHook	(	PVOID	TargetAddress,
		UINT32	ProcessId,
		BOOLEAN	ApplyDirectlyFromVmxRoot )

This function invokes a VMCALL to set the hook and broadcast the exiting for the breakpoints on exception bitmap.

Parameters

TargetAddress	The address of function or memory address to be hooked
ProcessId	The process id to translate based on that process's cr3
ApplyDirectlyFromVmxRoot	should it be directly applied from VMX-root mode or not

Returns

BOOLEAN Returns true if the hook was successful or false if there was an error

{
    if (ApplyDirectlyFromVmxRoot)
    {
        DIRECT_VMCALL_PARAMETERS DirectVmcallOptions = {0};
 
        //
        // Set VMCALL options
        //
        DirectVmcallOptions.OptionalParam1 = (UINT64)TargetAddress;
        DirectVmcallOptions.OptionalParam2 = LayoutGetCurrentProcessCr3().Flags;
 
        //
        // Perform the direct VMCALL
        //
        if (DirectVmcallSetHiddenBreakpointHook(KeGetCurrentProcessorNumberEx(NULL), &DirectVmcallOptions) == STATUS_SUCCESS)
        {
            LogDebugInfo("Hidden breakpoint hook applied from VMX Root Mode");
 
            return TRUE;
        }
    }
    else
    {
        //
        // Broadcast to all cores to enable vm-exit for breakpoints (exception bitmaps)
        //
        BroadcastEnableBreakpointExitingOnExceptionBitmapAllCores();
 
        if (AsmVmxVmcall(VMCALL_SET_HIDDEN_CC_BREAKPOINT,
                         (UINT64)TargetAddress,
                         LayoutGetCr3ByProcessId(ProcessId).Flags,
                         (UINT64)NULL64_ZERO) == STATUS_SUCCESS)
        {
            LogDebugInfo("Hidden breakpoint hook applied from VMX Root Mode");
 
            //
            // Now we have to notify all the core to invalidate their EPT
            //
            BroadcastNotifyAllToInvalidateEptAllCores();
 
            return TRUE;
        }
    }
 
    //
    // sth went wrong as we're here
    //
    return FALSE;
}

EptHookPerformMemoryOrInlineHook()

BOOLEAN EptHookPerformMemoryOrInlineHook	(	VIRTUAL_MACHINE_STATE *	VCpu,
		EPT_HOOKS_ADDRESS_DETAILS_FOR_EPTHOOK2 *	EptHook2AddressDetails,
		EPT_HOOKS_ADDRESS_DETAILS_FOR_MEMORY_MONITOR *	MemoryAddressDetails,
		UINT32	ProcessId,
		BOOLEAN	EptHiddenHook2,
		BOOLEAN	ApplyDirectlyFromVmxRoot )

This function allocates a buffer in VMX Non Root Mode and then invokes a VMCALL to set the hook.

this command uses hidden detours, if it calls from VMX root-mode directly, it should also invalidate EPT caches (by the caller)

Parameters

VCpu	The virtual processor's state
EptHook2AddressDetails	The address details for inline EPT hooks
MemoryAddressDetails	The address details for monitor EPT hooks
ProcessId	The process id to translate based on that process's cr3
EptHiddenHook2	epthook2 style hook
ApplyDirectlyFromVmxRoot	should it be directly applied from VMX-root mode or not

Returns

BOOLEAN Returns true if the hook was successful or false if there was an error

{
    UINT32 PageHookMask        = 0;
    PVOID  HookDetailsToVmcall = NULL;
 
    //
    // Check for the features to avoid EPT Violation problems
    //
    if (MemoryAddressDetails != NULL)
    {
        HookDetailsToVmcall = MemoryAddressDetails;
 
        if (MemoryAddressDetails->SetHookForExec &&
            !g_CompatibilityCheck.ExecuteOnlySupport)
        {
            //
            // In the current design of hyperdbg we use execute-only pages
            // to implement hidden hooks for exec page, so your processor doesn't
            // have this feature and you have to implement it in other ways :(
            //
            return FALSE;
        }
 
        if (!MemoryAddressDetails->SetHookForWrite && MemoryAddressDetails->SetHookForRead)
        {
            //
            // The hidden hook with Write Enable and Read Disabled will cause EPT violation!
            // fixed
            return FALSE;
        }
 
        if (MemoryAddressDetails->SetHookForRead)
        {
            PageHookMask |= PAGE_ATTRIB_READ;
        }
        if (MemoryAddressDetails->SetHookForWrite)
        {
            PageHookMask |= PAGE_ATTRIB_WRITE;
        }
        if (MemoryAddressDetails->SetHookForExec)
        {
            PageHookMask |= PAGE_ATTRIB_EXEC;
        }
    }
    else if (EptHook2AddressDetails != NULL)
    {
        HookDetailsToVmcall = EptHook2AddressDetails;
 
        //
        // Initialize the list of ept hook detours if it's not already initialized
        //
        if (!g_IsEptHook2sDetourListInitialized)
        {
            g_IsEptHook2sDetourListInitialized = TRUE;
 
            InitializeListHead(&g_EptHook2sDetourListHead);
        }
 
        if (EptHiddenHook2)
        {
            PageHookMask |= PAGE_ATTRIB_EXEC_HIDDEN_HOOK;
        }
    }
    else
    {
        //
        // No details provided
        //
        return FALSE;
    }
 
    //
    // Check if mask is valid or not
    //
    if (PageHookMask == 0)
    {
        //
        // nothing to hook
        //
        return FALSE;
    }
 
    if (ApplyDirectlyFromVmxRoot)
    {
        DIRECT_VMCALL_PARAMETERS DirectVmcallOptions = {0};
        DirectVmcallOptions.OptionalParam1           = (UINT64)HookDetailsToVmcall;
        DirectVmcallOptions.OptionalParam2           = PageHookMask;
        DirectVmcallOptions.OptionalParam3           = LayoutGetCurrentProcessCr3().Flags; // Process id is ignored while applied directly
 
        if (DirectVmcallPerformVmcall(VCpu->CoreId, VMCALL_CHANGE_PAGE_ATTRIB, &DirectVmcallOptions) == STATUS_SUCCESS)
        {
            return TRUE;
        }
        else
        {
            return FALSE;
        }
    }
    else
    {
        if (VmxGetCurrentLaunchState())
        {
            if (AsmVmxVmcall(VMCALL_CHANGE_PAGE_ATTRIB,
                             (UINT64)HookDetailsToVmcall,
                             PageHookMask,
                             LayoutGetCr3ByProcessId(ProcessId).Flags) == STATUS_SUCCESS)
            {
                //
                // Test log
                //
                // LogInfo("Hook applied from VMX Root Mode");
                //
 
                if (VmxGetCurrentExecutionMode() == FALSE)
                {
                    //
                    // Now we have to notify all the core to invalidate their EPT
                    //
                    BroadcastNotifyAllToInvalidateEptAllCores();
                }
                else
                {
                    LogInfo("Err, unable to notify all cores to invalidate their TLB "
                            "caches as you called hook on vmx-root mode, however, the "
                            "hook is still works");
                }
 
                return TRUE;
            }
            else
            {
                return FALSE;
            }
        }
        else
        {
            if (EptHookPerformPageHookMonitorAndInlineHook(VCpu,
                                                           HookDetailsToVmcall,
                                                           LayoutGetCr3ByProcessId(ProcessId),
                                                           PageHookMask) == TRUE)
            {
                LogWarning("Hook applied (VM has not launched)");
                return TRUE;
            }
        }
    }
 
    //
    // There was a error, we shouldn't reach here
    //
    LogWarning("Err, hook was not applied");
 
    return FALSE;
}

EptHookPerformPageHook()

BOOLEAN EptHookPerformPageHook	(	VIRTUAL_MACHINE_STATE *	VCpu,
		PVOID	TargetAddress,
		CR3_TYPE	ProcessCr3 )

The main function that performs EPT page hook with hidden breakpoint.

Hook in VMX Root Mode with hidden breakpoints (A pre-allocated buffer should be available).

This function returns false in VMX Non-Root Mode if the VM is already initialized This function have to be called through a VMCALL in VMX Root Mode

Parameters

VCpu	The virtual processor's state
TargetAddress	The address of function or memory address to be hooked
ProcessCr3	The process cr3 to translate based on that process's cr3

Returns

BOOLEAN Returns true if the hook was successful or false if there was an error

The main function that performs EPT page hook with hidden breakpoint.

Parameters

VCpu
TargetAddress
ProcessCr3

Returns

BOOLEAN

{
    SIZE_T                   PhysicalBaseAddress;
    PVOID                    VirtualTarget;
    EPT_HOOKED_PAGE_DETAIL * HookedEntry = NULL;
 
    //
    // Translate the page from a physical address to virtual so we can read its memory.
    // This function will return NULL if the physical address was not already mapped in
    // virtual memory.
    //
    VirtualTarget = PAGE_ALIGN(TargetAddress);
 
    //
    // Here we have to change the CR3, it is because we are in SYSTEM process
    // and if the target address is not mapped in SYSTEM address space (e.g
    // user mode address of another process) then the translation is invalid
    //
 
    //
    // Find cr3 of target core
    //
    PhysicalBaseAddress = (SIZE_T)VirtualAddressToPhysicalAddressByProcessCr3(VirtualTarget, ProcessCr3);
 
    if (!PhysicalBaseAddress)
    {
        VmmCallbackSetLastError(DEBUGGER_ERROR_INVALID_ADDRESS);
        return FALSE;
    }
 
    //
    // Check if the physical address is bigger than 512 GB
    //
    if (PhysicalBaseAddress >= SIZE_512_GB)
    {
        VmmCallbackSetLastError(DEBUGGER_ERROR_CANNOT_PUT_EPT_HOOKS_ON_PHYSICAL_ADDRESS_ABOVE_512_GB);
        return FALSE;
    }
 
    //
    // try to see if we can find the address
    //
 
    HookedEntry = EptHookFindByPhysAddress(PhysicalBaseAddress);
 
    if (HookedEntry != NULL)
    {
        return EptHookUpdateHookPage(TargetAddress, HookedEntry);
    }
    else
    {
        return EptHookCreateHookPage(VCpu, TargetAddress, ProcessCr3);
    }
}

EptHookPerformPageHookMonitorAndInlineHook()

BOOLEAN EptHookPerformPageHookMonitorAndInlineHook	(	VIRTUAL_MACHINE_STATE *	VCpu,
		PVOID	HookingDetails,
		CR3_TYPE	ProcessCr3,
		UINT32	PageHookMask )

The main function that performs EPT page hook with hidden detours and monitor.

Hook in VMX Root Mode with hidden detours and monitor (A pre-allocated buffer should be available).

This function returns false in VMX Non-Root Mode if the VM is already initialized This function have to be called through a VMCALL in VMX Root Mode

Parameters

VCpu	The virtual processor's state
HookingDetails	The address of function or memory address to be hooked
ProcessCr3	The process cr3 to translate based on that process's cr3
PageHookMask	Mask hook of the page

Returns

BOOLEAN Returns true if the hook was successful or false if there was an error

The main function that performs EPT page hook with hidden detours and monitor.

Parameters

VCpu
HookingDetails
ProcessCr3
PageHookMask

Returns

BOOLEAN

{
    ULONG                   ProcessorsCount;
    EPT_PML1_ENTRY          ChangedEntry;
    SIZE_T                  PhysicalBaseAddress;
    PVOID                   AlignedTargetVaOrPa;
    PVOID                   TargetAddress;
    PVOID                   HookFunction;
    UINT64                  TargetAddressInSafeMemory;
    PEPT_PML1_ENTRY         TargetPage;
    PEPT_HOOKED_PAGE_DETAIL HookedPage;
    CR3_TYPE                Cr3OfCurrentProcess;
    PLIST_ENTRY             TempList      = 0;
    PEPT_HOOKED_PAGE_DETAIL HookedEntry   = NULL;
    BOOLEAN                 UnsetExecute  = FALSE;
    BOOLEAN                 UnsetRead     = FALSE;
    BOOLEAN                 UnsetWrite    = FALSE;
    BOOLEAN                 EptHiddenHook = FALSE;
 
    UnsetRead     = (PageHookMask & PAGE_ATTRIB_READ) ? TRUE : FALSE;
    UnsetWrite    = (PageHookMask & PAGE_ATTRIB_WRITE) ? TRUE : FALSE;
    UnsetExecute  = (PageHookMask & PAGE_ATTRIB_EXEC) ? TRUE : FALSE;
    EptHiddenHook = (PageHookMask & PAGE_ATTRIB_EXEC_HIDDEN_HOOK) ? TRUE : FALSE;
 
    //
    // Get number of processors
    //
    ProcessorsCount = KeQueryActiveProcessorCount(0);
 
    //
    // Translate the page from a physical address to virtual so we can read its memory.
    // This function will return NULL if the physical address was not already mapped in
    // virtual memory.
    //
    if (EptHiddenHook)
    {
        TargetAddress = ((EPT_HOOKS_ADDRESS_DETAILS_FOR_EPTHOOK2 *)HookingDetails)->TargetAddress;
    }
    else
    {
        TargetAddress = (PVOID)((EPT_HOOKS_ADDRESS_DETAILS_FOR_MEMORY_MONITOR *)HookingDetails)->StartAddress;
    }
 
    AlignedTargetVaOrPa = PAGE_ALIGN(TargetAddress);
 
    //
    // Here we have to change the CR3, it is because we are in SYSTEM process
    // and if the target address is not mapped in SYSTEM address space (e.g
    // user mode address of another process) then the translation is invalid
    //
 
    if (!EptHiddenHook &&
        ((EPT_HOOKS_ADDRESS_DETAILS_FOR_MEMORY_MONITOR *)HookingDetails)->MemoryType == DEBUGGER_MEMORY_HOOK_PHYSICAL_ADDRESS)
    {
        //
        // The address itself is a physical address, no need for conversion
        //
        PhysicalBaseAddress = (SIZE_T)AlignedTargetVaOrPa;
    }
    else
    {
        //
        // based on the CR3 of target core
        //
        PhysicalBaseAddress = (SIZE_T)VirtualAddressToPhysicalAddressByProcessCr3(AlignedTargetVaOrPa, ProcessCr3);
    }
 
    //
    // Check if the physical address is valid
    //
    if (!PhysicalBaseAddress)
    {
        VmmCallbackSetLastError(DEBUGGER_ERROR_INVALID_ADDRESS);
        return FALSE;
    }
 
    //
    // Check if the physical address is bigger than 512 GB
    //
    if (PhysicalBaseAddress >= SIZE_512_GB)
    {
        VmmCallbackSetLastError(DEBUGGER_ERROR_CANNOT_PUT_EPT_HOOKS_ON_PHYSICAL_ADDRESS_ABOVE_512_GB);
        return FALSE;
    }
 
    //
    // try to see if we can find the address
    //
    TempList = &g_EptState->HookedPagesList;
 
    while (&g_EptState->HookedPagesList != TempList->Flink)
    {
        TempList    = TempList->Flink;
        HookedEntry = CONTAINING_RECORD(TempList, EPT_HOOKED_PAGE_DETAIL, PageHookList);
 
        if (HookedEntry->PhysicalBaseAddress == PhysicalBaseAddress)
        {
            //
            // Means that we find the address and !epthook2 doesn't support
            // multiple breakpoints in on page
            //
            VmmCallbackSetLastError(DEBUGGER_ERROR_EPT_MULTIPLE_HOOKS_IN_A_SINGLE_PAGE);
            return FALSE;
        }
    }
 
    //
    // Save the detail of hooked page to keep track of it
    //
    HookedPage = (EPT_HOOKED_PAGE_DETAIL *)PoolManagerCallbackRequestPool(TRACKING_HOOKED_PAGES, TRUE, sizeof(EPT_HOOKED_PAGE_DETAIL));
 
    if (!HookedPage)
    {
        VmmCallbackSetLastError(DEBUGGER_ERROR_PRE_ALLOCATED_BUFFER_IS_EMPTY);
        return FALSE;
    }
 
    //
    // Save the virtual address
    //
    HookedPage->VirtualAddress = (UINT64)TargetAddress;
 
    //
    // Save the physical address
    //
    HookedPage->PhysicalBaseAddress = PhysicalBaseAddress;
 
    //
    // If it's a monitor hook, then we need to hold the address of the start
    // physical address as well as the end physical address, plus tagging information
    //
    if (!EptHiddenHook)
    {
        //
        // Save the target tag
        //
        HookedPage->HookingTag = ((EPT_HOOKS_ADDRESS_DETAILS_FOR_MEMORY_MONITOR *)HookingDetails)->Tag;
 
        //
        // Save the start of the target physical address
        //
        if (((EPT_HOOKS_ADDRESS_DETAILS_FOR_MEMORY_MONITOR *)HookingDetails)->MemoryType == DEBUGGER_MEMORY_HOOK_PHYSICAL_ADDRESS)
        {
            //
            // Physical address
            //
            HookedPage->StartOfTargetPhysicalAddress = (SIZE_T)(((EPT_HOOKS_ADDRESS_DETAILS_FOR_MEMORY_MONITOR *)HookingDetails)->StartAddress);
        }
        else
        {
            //
            // Virtual address
            //
            HookedPage->StartOfTargetPhysicalAddress = (SIZE_T)VirtualAddressToPhysicalAddressByProcessCr3(
                (PVOID)(((EPT_HOOKS_ADDRESS_DETAILS_FOR_MEMORY_MONITOR *)HookingDetails)->StartAddress),
                ProcessCr3);
        }
 
        if (!HookedPage->StartOfTargetPhysicalAddress)
        {
            PoolManagerCallbackFreePool((UINT64)HookedPage);
 
            VmmCallbackSetLastError(DEBUGGER_ERROR_INVALID_ADDRESS);
            return FALSE;
        }
 
        //
        // Save the end of the target physical address
        //
        if (((EPT_HOOKS_ADDRESS_DETAILS_FOR_MEMORY_MONITOR *)HookingDetails)->MemoryType == DEBUGGER_MEMORY_HOOK_PHYSICAL_ADDRESS)
        {
            //
            // Physical address
            //
            HookedPage->EndOfTargetPhysicalAddress = (SIZE_T)(((EPT_HOOKS_ADDRESS_DETAILS_FOR_MEMORY_MONITOR *)HookingDetails)->EndAddress);
        }
        else
        {
            //
            // Virtual address
            //
            HookedPage->EndOfTargetPhysicalAddress = (SIZE_T)VirtualAddressToPhysicalAddressByProcessCr3(
                (PVOID)(((EPT_HOOKS_ADDRESS_DETAILS_FOR_MEMORY_MONITOR *)HookingDetails)->EndAddress),
                ProcessCr3);
        }
 
        if (!HookedPage->EndOfTargetPhysicalAddress)
        {
            PoolManagerCallbackFreePool((UINT64)HookedPage);
 
            VmmCallbackSetLastError(DEBUGGER_ERROR_INVALID_ADDRESS);
            return FALSE;
        }
    }
 
    //
    // Fake page content physical address
    //
    HookedPage->PhysicalBaseAddressOfFakePageContents = (SIZE_T)VirtualAddressToPhysicalAddress(&HookedPage->FakePageContents[0]) / PAGE_SIZE;
 
    if (EptHiddenHook)
    {
        //
        // Show that entry has hidden hooks for execution
        //
        HookedPage->IsExecutionHook = TRUE;
 
        //
        // Switch to target process
        //
        Cr3OfCurrentProcess = SwitchToProcessMemoryLayoutByCr3(ProcessCr3);
 
        //
        // Copy the content to the fake page
        // The following line can't be used in user mode addresses
        // RtlCopyBytes(&HookedPage->FakePageContents, VirtualTarget, PAGE_SIZE);
        //
        MemoryMapperReadMemorySafe((UINT64)AlignedTargetVaOrPa, &HookedPage->FakePageContents, PAGE_SIZE);
 
        //
        // Restore to original process
        //
        SwitchToPreviousProcess(Cr3OfCurrentProcess);
 
        //
        // Compute new offset of target offset into a safe bufferr
        // It will be used to compute the length of the detours
        // address because we might have a user mode code
        //
        TargetAddressInSafeMemory = EptHookCalcBreakpointOffset(TargetAddress, HookedPage);
 
        //
        // Make sure if handler function is valid or if it's default
        // then we set it to the default handler
        //
        if (((EPT_HOOKS_ADDRESS_DETAILS_FOR_EPTHOOK2 *)HookingDetails)->HookFunction == NULL)
        {
            HookFunction = (PVOID)AsmGeneralDetourHook;
        }
        else
        {
            HookFunction = ((EPT_HOOKS_ADDRESS_DETAILS_FOR_EPTHOOK2 *)HookingDetails)->HookFunction;
        }
 
        //
        // Create Hook
        //
        if (!EptHookInstructionMemory(HookedPage, ProcessCr3, TargetAddress, (PVOID)TargetAddressInSafeMemory, HookFunction))
        {
            PoolManagerCallbackFreePool((UINT64)HookedPage);
 
            VmmCallbackSetLastError(DEBUGGER_ERROR_COULD_NOT_BUILD_THE_EPT_HOOK);
            return FALSE;
        }
    }
 
    for (SIZE_T i = 0; i < ProcessorsCount; i++)
    {
        //
        // We need to split the large page to 4KB page using pre-allocated pools
        //
        if (!EptSplitLargePage(g_GuestState[i].EptPageTable, TRUE, PhysicalBaseAddress))
        {
            PoolManagerCallbackFreePool((UINT64)HookedPage);
 
            //
            // Here also other previous pools should be specified, but we forget it for now
            //
            LogDebugInfo("Err, could not split page for the address : 0x%llx", PhysicalBaseAddress);
            VmmCallbackSetLastError(DEBUGGER_ERROR_EPT_COULD_NOT_SPLIT_THE_LARGE_PAGE_TO_4KB_PAGES);
            return FALSE;
        }
 
        //
        // Pointer to the page entry in the page table
        //
        TargetPage = EptGetPml1Entry(g_GuestState[i].EptPageTable, PhysicalBaseAddress);
 
        //
        // Ensure the target is valid
        //
        if (!TargetPage)
        {
            PoolManagerCallbackFreePool((UINT64)HookedPage);
 
            //
            // Here also other previous pools should be specified, but we forget it for now
            //
 
            VmmCallbackSetLastError(DEBUGGER_ERROR_EPT_FAILED_TO_GET_PML1_ENTRY_OF_TARGET_ADDRESS);
            return FALSE;
        }
 
        //
        // Save the original entry (only one of the page tables as the base original entry
        // is enough)
        //
        HookedPage->OriginalEntry = *TargetPage;
 
        //
        // Save the original permissions of the page
        //
        ChangedEntry = *TargetPage;
 
        //
        // Execution is treated differently
        //
        if (UnsetRead)
            ChangedEntry.ReadAccess = 0;
        else
            ChangedEntry.ReadAccess = 1;
 
        if (UnsetWrite)
            ChangedEntry.WriteAccess = 0;
        else
            ChangedEntry.WriteAccess = 1;
 
        if (UnsetExecute)
            ChangedEntry.ExecuteAccess = 0;
        else
            ChangedEntry.ExecuteAccess = 1;
 
        //
        // If it's Execution hook then we have to set extra fields
        //
        if (EptHiddenHook)
        {
            //
            // In execution hook, we have to make sure to unset read, write because
            // an EPT violation should occur for these cases and we can swap the original page
            //
            ChangedEntry.ReadAccess    = 0;
            ChangedEntry.WriteAccess   = 0;
            ChangedEntry.ExecuteAccess = 1;
 
            //
            // Also set the current pfn to fake page
            //
            ChangedEntry.PageFrameNumber = HookedPage->PhysicalBaseAddressOfFakePageContents;
        }
 
        //
        // Only for the first time execution of the loop, we save these details,
        // it is because after this condition, the hook is applied and by applying
        // the hook, we have to make sure that the address is saved g_EptState->HookedPagesList
        // because the hook might be simultaneously triggered from other cores
        //
        if (i == 0)
        {
            //
            // Save the modified entry
            //
            HookedPage->ChangedEntry = ChangedEntry;
 
            //
            // Add it to the list
            //
            InsertHeadList(&g_EptState->HookedPagesList, &(HookedPage->PageHookList));
        }
 
        //
        // Apply the hook to EPT
        //
        TargetPage->AsUInt = ChangedEntry.AsUInt;
 
        //
        // If it's the current core then we invalidate the EPT
        //
        if (VCpu->CoreId == i && g_GuestState[i].HasLaunched)
        {
            EptInveptSingleContext(VCpu->EptPointer.AsUInt);
        }
    }
 
    return TRUE;
}

EptHookPerformUnHookSingleAddress()

BOOLEAN EptHookPerformUnHookSingleAddress	(	UINT64	VirtualAddress,
		UINT64	PhysAddress,
		UINT64	HookingTag,
		UINT32	ProcessId,
		BOOLEAN	ApplyDirectlyFromVmxRoot,
		EPT_SINGLE_HOOK_UNHOOKING_DETAILS *	TargetUnhookingDetails )

Remove single hook from the hooked pages list and invalidate TLB.

Parameters

VirtualAddress	Virtual address to unhook
PhysAddress	Physical address to unhook (optional)
HookingTag	Hooking tag (optional)
ProcessId	The process id of target process (in unhooking for some hooks only physical address is availables)
ApplyDirectlyFromVmxRoot	should it be directly applied from VMX-root mode or not
TargetUnhookingDetails	Target data for the caller to restore EPT entry and invalidate EPT caches. Only when applied in VMX-root mode directly

Returns

BOOLEAN If unhook was successful it returns true or if it was not successful returns false

{
    SIZE_T PhysicalAddress = NULL64_ZERO;
 
    //
    // Once applied directly from VMX-root mode, the process id should be the same process Id
    // on current process
    //
    if (ApplyDirectlyFromVmxRoot || ProcessId == DEBUGGER_EVENT_APPLY_TO_ALL_PROCESSES || ProcessId == 0)
    {
        ProcessId = HANDLE_TO_UINT32(PsGetCurrentProcessId());
    }
 
    //
    // Check if the physical address is available or not
    //
    if (PhysAddress != NULL64_ZERO)
    {
        PhysicalAddress = (SIZE_T)PAGE_ALIGN(PhysAddress);
    }
    else if (HookingTag == NULL64_ZERO)
    {
        if (ApplyDirectlyFromVmxRoot)
        {
            PhysicalAddress = (SIZE_T)(PAGE_ALIGN(VirtualAddressToPhysicalAddressOnTargetProcess((PVOID)VirtualAddress)));
        }
        else
        {
            PhysicalAddress = (SIZE_T)(PAGE_ALIGN(VirtualAddressToPhysicalAddressByProcessId((PVOID)VirtualAddress,
                                                                                             ProcessId)));
        }
    }
 
    LIST_FOR_EACH_LINK(g_EptState->HookedPagesList, EPT_HOOKED_PAGE_DETAIL, PageHookList, CurrEntity)
    {
        //
        // Check if it's a hidden breakpoint or hidden detours
        //
        if (CurrEntity->IsHiddenBreakpoint)
        {
            //
            // It's a hidden breakpoint
            //
            for (SIZE_T i = 0; i < CurrEntity->CountOfBreakpoints; i++)
            {
                if (CurrEntity->BreakpointAddresses[i] == VirtualAddress)
                {
                    return EptHookUnHookSingleAddressHiddenBreakpoint(CurrEntity,
                                                                      VirtualAddress,
                                                                      ApplyDirectlyFromVmxRoot,
                                                                      TargetUnhookingDetails);
                }
            }
        }
        else
        {
            //
            // It's either a hidden detours or a monitor (read/write/execute) entry
            //
            if ((HookingTag != NULL64_ZERO && CurrEntity->HookingTag == HookingTag) || CurrEntity->PhysicalBaseAddress == PhysicalAddress)
            {
                return EptHookUnHookSingleAddressDetoursAndMonitor(CurrEntity,
                                                                   ApplyDirectlyFromVmxRoot,
                                                                   TargetUnhookingDetails);
            }
        }
    }
 
    //
    // Nothing found, probably the hooking detail is not found
    //
    return FALSE;
}

EptHookRemoveEntryAndFreePoolFromEptHook2sDetourList()

BOOLEAN EptHookRemoveEntryAndFreePoolFromEptHook2sDetourList

(

UINT64

Address

)

Remove the entry from g_EptHook2sDetourListHead in the case of !epthook2 details.

Remove an entry from g_EptHook2sDetourListHead.

Parameters

Address

Address to remove

Returns

BOOLEAN TRUE if successfully removed and false if not found

Remove the entry from g_EptHook2sDetourListHead in the case of !epthook2 details.

Parameters

Address

Returns

BOOLEAN

{
    //
    // Iterate through the list of hooked pages details to find
    // the entry in the list
    //
    LIST_FOR_EACH_LINK(g_EptHook2sDetourListHead, HIDDEN_HOOKS_DETOUR_DETAILS, OtherHooksList, CurrentHookedDetails)
    {
        if (CurrentHookedDetails->HookedFunctionAddress == (PVOID)Address)
        {
            //
            // We found the address, we should remove it and add it for
            // future deallocation
            //
            RemoveEntryList(&CurrentHookedDetails->OtherHooksList);
 
            //
            // Free the pool in next ioctl
            //
            if (!PoolManagerCallbackFreePool((UINT64)CurrentHookedDetails))
            {
                LogError("Err, something goes wrong, the pool not found in the list of previously allocated pools by pool manager");
            }
            return TRUE;
        }
    }
    //
    // No entry found !
    //
    return FALSE;
}

EptHookReservePreallocatedPoolsForEptHooks()

VOID EptHookReservePreallocatedPoolsForEptHooks

(

UINT32

Count

)

Reserve pre-allocated pools for EPT hooks.

Allocate pre-allocated pools for EPT hooks.

Parameters

Count

number of hooks

Returns

VOID

Reserve pre-allocated pools for EPT hooks.

Parameters

Count

number of hooks

Returns

VOID

{
    ULONG ProcessorsCount;
 
    //
    // Get number of processors
    //
    ProcessorsCount = KeQueryActiveProcessorCount(0);
 
    //
    // Request pages to be allocated for converting 2MB to 4KB pages
    // Each core needs its own splitting page-tables
    //
    PoolManagerCallbackRequestAllocation(sizeof(VMM_EPT_DYNAMIC_SPLIT), Count * ProcessorsCount, SPLIT_2MB_PAGING_TO_4KB_PAGE);
 
    //
    // Request pages to be allocated for paged hook details
    //
    PoolManagerCallbackRequestAllocation(sizeof(EPT_HOOKED_PAGE_DETAIL), Count, TRACKING_HOOKED_PAGES);
 
    //
    // Request pages to be allocated for Trampoline of Executable hooked pages
    //
    PoolManagerCallbackRequestAllocation(MAX_EXEC_TRAMPOLINE_SIZE, Count, EXEC_TRAMPOLINE);
 
    //
    // Request pages to be allocated for detour hooked pages details
    //
    PoolManagerCallbackRequestAllocation(sizeof(HIDDEN_HOOKS_DETOUR_DETAILS), Count, DETOUR_HOOK_DETAILS);
}

EptHookRestoreAllHooksToOriginalEntry()

VOID EptHookRestoreAllHooksToOriginalEntry

(

VIRTUAL_MACHINE_STATE *

VCpu

)

Remove and Invalidate Hook in TLB.

Remove all hooks from the hooked pages lists (Should be called in vmx-root).

Warning

This function won't remove entries from LIST_ENTRY, just invalidate the paging, use EptHookUnHookAll instead

Parameters

VCpu	The virtual processor's state

Returns

VOID

Remove and Invalidate Hook in TLB.

Parameters

VCpu

Returns

VOID

{
    PEPT_PML1_ENTRY TargetPage;
 
    //
    // Should be called from vmx-root, for calling from vmx non-root use the corresponding VMCALL
    //
    if (VmxGetCurrentExecutionMode() == FALSE)
    {
        return;
    }
 
    LIST_FOR_EACH_LINK(g_EptState->HookedPagesList, EPT_HOOKED_PAGE_DETAIL, PageHookList, HookedEntry)
    {
        //
        // Pointer to the page entry in the page table
        //
        TargetPage = EptGetPml1Entry(VCpu->EptPageTable, HookedEntry->PhysicalBaseAddress);
 
        //
        // Apply the hook to EPT
        //
        TargetPage->AsUInt = HookedEntry->OriginalEntry.AsUInt;
    }
 
    //
    // Invalidate EPT Cache
    //
    EptInveptSingleContext(VCpu->EptPointer.AsUInt);
}

EptHookRestoreSingleHookToOriginalEntry()

BOOLEAN EptHookRestoreSingleHookToOriginalEntry	(	VIRTUAL_MACHINE_STATE *	VCpu,
		SIZE_T	PhysicalAddress,
		UINT64	OriginalEntry )

Remove and Invalidate Hook in TLB (Hidden Detours and if counter of hidden breakpoint is zero).

Remove a special hook from the hooked pages lists.

Warning

This function won't remove entries from LIST_ENTRY, just invalidate the paging, use EptHookUnHookSingleAddress instead

Parameters

VCpu	The virtual processor's state
PhysicalAddress
OriginalEntry

Returns

BOOLEAN Return false if there was an error or returns true if it was successful

Remove and Invalidate Hook in TLB (Hidden Detours and if counter of hidden breakpoint is zero).

Parameters

VCpu
PhysicalAddress
OriginalEntry

Returns

BOOLEAN

{
    PEPT_PML1_ENTRY TargetPage;
 
    //
    // Should be called from vmx-root, for calling from vmx non-root use the corresponding VMCALL
    //
    if (VmxGetCurrentExecutionMode() == FALSE)
    {
        return FALSE;
    }
    //
    // Pointer to the page entry in the page table
    //
    TargetPage = EptGetPml1Entry(VCpu->EptPageTable, PhysicalAddress);
 
    if (TargetPage != NULL)
    {
        //
        // Apply the hook to EPT
        //
        TargetPage->AsUInt = OriginalEntry;
 
        //
        // Invalidate EPT Cache
        //
        EptInveptSingleContext(VCpu->EptPointer.AsUInt);
 
        return TRUE;
    }
 
    //
    // The PML1 entry not found
    //
    return FALSE;
}

EptHookUnHookAll()

VOID EptHookUnHookAll

(

)

Remove all hooks from the hooked pages list and invalidate TLB @detailsShould be called from Vmx Non-root.

Remove all hooks from the hooked pages lists.

Returns

VOID

Remove all hooks from the hooked pages list and invalidate TLB @detailsShould be called from Vmx Non-root.

Returns

VOID

{
    //
    // Should be called from vmx non-root
    //
    if (VmxGetCurrentExecutionMode() == TRUE)
    {
        return;
    }
 
    //
    // Remove it in all the cores
    //
    KeGenericCallDpc(DpcRoutineRemoveHookAndInvalidateAllEntriesOnAllCores, 0x0);
 
    //
    // In the case of unhooking all pages, we remove the hooked
    // from EPT table in vmx-root and at last, we need to deallocate
    // it from the buffers
    //
 
    LIST_FOR_EACH_LINK(g_EptState->HookedPagesList, EPT_HOOKED_PAGE_DETAIL, PageHookList, CurrEntity)
    {
        //
        // Now that we removed this hidden detours hook, it is
        // time to remove it from g_EptHook2sDetourListHead
        // if the hook is detours
        //
        if (!CurrEntity->IsHiddenBreakpoint)
        {
            EptHookRemoveEntryAndFreePoolFromEptHook2sDetourList(CurrEntity->VirtualAddress);
        }
 
        //
        // As we are in vmx-root here, we add the hooked entry to the list
        // of pools that will be deallocated on next IOCTL
        //
        if (!PoolManagerCallbackFreePool((UINT64)CurrEntity))
        {
            LogError("Err, something goes wrong, the pool not found in the list of previously allocated pools by pool manager");
        }
    }
}

EptHookUnHookAllByHookingTag()

BOOLEAN EptHookUnHookAllByHookingTag

(

UINT64

HookingTag

)

Remove all hooks from the hooked pages by the given hooking tag.

Should be called from Vmx Non-root

Parameters

HookingTag

The hooking tag to unhook

Returns

BOOLEAN If unhook was successful it returns true or if it was not successful returns false

{
    EPT_SINGLE_HOOK_UNHOOKING_DETAILS TargetUnhookingDetails; // not used
    BOOLEAN                           AtLeastOneUnhooked = FALSE;
    BOOLEAN                           UnhookingResult    = FALSE;
 
    //
    // Should be called from vmx non-root
    //
    if (VmxGetCurrentExecutionMode() == TRUE)
    {
        return FALSE;
    }
 
KeepUnhooking:
    UnhookingResult = EptHookPerformUnHookSingleAddress(NULL_ZERO,
                                                        NULL_ZERO,
                                                        HookingTag,
                                                        NULL_ZERO,
                                                        FALSE,
                                                        &TargetUnhookingDetails);
 
    if (UnhookingResult)
    {
        AtLeastOneUnhooked = TRUE;
 
        //
        // Keep unhooking until there is no more hooking details
        //
        goto KeepUnhooking;
    }
 
    return AtLeastOneUnhooked;
}

EptHookUnHookSingleAddress()

BOOLEAN EptHookUnHookSingleAddress	(	UINT64	VirtualAddress,
		UINT64	PhysAddress,
		UINT32	ProcessId )

Remove single hook from the hooked pages list and invalidate TLB.

Remove single hook from the hooked pages list and invalidate TLB From VMX non-root mode.

Should be called from VMX non-root

Parameters

VirtualAddress	Virtual address to unhook
PhysAddress	Physical address to unhook (optional)
ProcessId	The process id of target process

in unhooking for some hooks only physical address is availables

Returns

BOOLEAN If unhook was successful it returns true or if it was not successful returns false

Remove single hook from the hooked pages list and invalidate TLB.

Parameters

VirtualAddress
PhysAddress
ProcessId

Returns

BOOLEAN

{
    EPT_SINGLE_HOOK_UNHOOKING_DETAILS TargetUnhookingDetails; // not used
 
    //
    // Should be called from VMX non-root
    //
    if (VmxGetCurrentExecutionMode() == TRUE)
    {
        return FALSE;
    }
 
    return EptHookPerformUnHookSingleAddress(VirtualAddress,
                                             PhysAddress,
                                             NULL_ZERO,
                                             ProcessId,
                                             FALSE,
                                             &TargetUnhookingDetails);
}

EptHookUnHookSingleAddressDetoursAndMonitor()

BOOLEAN EptHookUnHookSingleAddressDetoursAndMonitor	(	PEPT_HOOKED_PAGE_DETAIL	HookedEntry,
		BOOLEAN	ApplyDirectlyFromVmxRoot,
		EPT_SINGLE_HOOK_UNHOOKING_DETAILS *	TargetUnhookingDetails )

Remove single hook of detours type.

Parameters

HookedEntry	entry detail of hooked address
ApplyDirectlyFromVmxRoot	should it be directly applied from VMX-root mode or not
TargetUnhookingDetails	Target data for the caller to restore EPT entry and invalidate EPT caches. Only when applied in VMX-root mode directly

Returns

BOOLEAN If unhook was successful it returns true or if it was not successful returns false

{
    //
    // Set the unhooking details
    //
    TargetUnhookingDetails->PhysicalAddress = HookedEntry->PhysicalBaseAddress;
    TargetUnhookingDetails->OriginalEntry   = HookedEntry->OriginalEntry.AsUInt;
 
    //
    // If applied directly from VMX-root mode, it's the responsibility of the
    // caller to remove the hook and invalidate EPT caches for the target physical address
    //
    if (ApplyDirectlyFromVmxRoot)
    {
        TargetUnhookingDetails->CallerNeedsToRestoreEntryAndInvalidateEpt = TRUE;
    }
    else
    {
        //
        // Remove it in all the cores
        //
        TargetUnhookingDetails->CallerNeedsToRestoreEntryAndInvalidateEpt = FALSE;
        KeGenericCallDpc(DpcRoutineRemoveHookAndInvalidateSingleEntryOnAllCores, TargetUnhookingDetails);
    }
 
    //
    // Now that we removed this hidden detours hook, it is
    // time to remove it from g_EptHook2sDetourListHead
    //
    if (HookedEntry->IsExecutionHook)
    {
        EptHookRemoveEntryAndFreePoolFromEptHook2sDetourList(HookedEntry->VirtualAddress);
    }
 
    //
    // remove the entry from the list
    //
    RemoveEntryList(&HookedEntry->PageHookList);
 
    //
    // we add the hooked entry to the list
    // of pools that will be deallocated on next IOCTL
    //
    if (!PoolManagerCallbackFreePool((UINT64)HookedEntry))
    {
        LogError("Err, something goes wrong, the pool not found in the list of previously allocated pools by pool manager");
        return FALSE;
    }
 
    return TRUE;
}

EptHookUnHookSingleAddressFromVmxRoot()

BOOLEAN EptHookUnHookSingleAddressFromVmxRoot	(	UINT64	VirtualAddress,
		UINT64	PhysAddress,
		EPT_SINGLE_HOOK_UNHOOKING_DETAILS *	TargetUnhookingDetails )

Remove single hook from the hooked pages list and invalidate TLB.

Remove single hook from the hooked pages list and invalidate TLB From VMX root-mode.

Should be called from VMX root-mode

Parameters

VirtualAddress	Virtual address to unhook
PhysAddress	Physical address to unhook (optional)
TargetUnhookingDetails	Target data for the caller to restore EPT entry and invalidate EPT caches. Only when applied in VMX-root mode directly

Returns

BOOLEAN If unhook was successful it returns true or if it was not successful returns false

Remove single hook from the hooked pages list and invalidate TLB.

Parameters

VirtualAddress
PhysAddress
TargetUnhookingDetails

Returns

BOOLEAN

{
    //
    // Should be called from VMX root-mode
    //
    if (VmxGetCurrentExecutionMode() == FALSE)
    {
        return FALSE;
    }
 
    return EptHookPerformUnHookSingleAddress(VirtualAddress,
                                             PhysAddress,
                                             NULL64_ZERO,
                                             NULL_ZERO,
                                             TRUE,
                                             TargetUnhookingDetails);
}

EptHookUnHookSingleAddressHiddenBreakpoint()

BOOLEAN EptHookUnHookSingleAddressHiddenBreakpoint	(	PEPT_HOOKED_PAGE_DETAIL	HookedEntry,
		UINT64	VirtualAddress,
		BOOLEAN	ApplyDirectlyFromVmxRoot,
		EPT_SINGLE_HOOK_UNHOOKING_DETAILS *	TargetUnhookingDetails )

Remove single hook of hidden breakpoint type.

Parameters

HookedEntry	entry detail of hooked address
VirtualAddress	virtual address to unhook
ApplyDirectlyFromVmxRoot	should it be directly applied from VMX-root mode or not
TargetUnhookingDetails	Target data for the caller to restore EPT entry and invalidate EPT caches. Only when applied in VMX-root mode directly

Returns

BOOLEAN If unhook was successful it returns true or if it was not successful returns false

{
    UINT64 TargetAddressInFakePageContent;
    UINT32 CountOfEntriesWithSameAddr = 0;
 
    //
    // By default, the caller doesn't need to remove #BPs interceptions if directly
    // applied from VMX-root mode
    //
    TargetUnhookingDetails->RemoveBreakpointInterception = FALSE;
 
    //
    // It's a hidden breakpoint (we have to search through an array of addresses)
    // We count it from top to down because if there are two ept hooks at the
    // same address, then the last one has an invalid PreviousByte and this
    // is the HookedEntry that should be remove (not the first one as it has the
    // correct PreviousByte)
    //
    for (SIZE_T i = 0; i < HookedEntry->CountOfBreakpoints; i++)
    {
        if (HookedEntry->BreakpointAddresses[i] == VirtualAddress)
        {
            //
            // Check if it's a single breakpoint
            //
            if (HookedEntry->CountOfBreakpoints == 1)
            {
                //
                // Set the unhooking details
                //
                TargetUnhookingDetails->PhysicalAddress = HookedEntry->PhysicalBaseAddress;
                TargetUnhookingDetails->OriginalEntry   = HookedEntry->OriginalEntry.AsUInt;
 
                //
                // If applied directly from VMX-root mode, it's the responsibility of the
                // caller to remove the hook and invalidate EPT caches for the target physical address
                //
                if (ApplyDirectlyFromVmxRoot)
                {
                    //
                    // The caller is responsible for restoring EPT entry and invalidate caches
                    //
                    TargetUnhookingDetails->CallerNeedsToRestoreEntryAndInvalidateEpt = TRUE;
                }
                else
                {
                    //
                    // Remove the hook entirely on all cores
                    //
                    TargetUnhookingDetails->CallerNeedsToRestoreEntryAndInvalidateEpt = FALSE;
                    KeGenericCallDpc(DpcRoutineRemoveHookAndInvalidateSingleEntryOnAllCores, TargetUnhookingDetails);
                }
 
                //
                // remove the entry from the list
                //
                RemoveEntryList(&HookedEntry->PageHookList);
 
                //
                // we add the hooked entry to the list
                // of pools that will be deallocated on next IOCTL
                //
                if (!PoolManagerCallbackFreePool((UINT64)HookedEntry))
                {
                    LogError("Err, something goes wrong, the pool not found in the list of previously allocated pools by pool manager");
                }
 
                //
                // Check if there is any other breakpoints, if no then we have to disable
                // exception bitmaps on vm-exits for breakpoint, for this purpose, we have
                // to visit all the entries to see if there is any entries
                //
                if (EptHookGetCountOfEpthooks(FALSE) == 0)
                {
                    //
                    // If applied directly from VMX-root mode, it's the responsibility of the
                    // caller to broadcast to disable breakpoint exceptions on all cores
                    //
                    if (ApplyDirectlyFromVmxRoot)
                    {
                        //
                        // Set whether it was the last hook (and the caller if applied from VMX-root needed
                        // to broadcast to disable #BPs interception on exception bitmaps or not)
                        //
                        TargetUnhookingDetails->RemoveBreakpointInterception = TRUE;
                    }
                    else
                    {
                        //
                        // Did not find any entry, let's disable the breakpoints vm-exits
                        // on exception bitmaps
                        //
                        TargetUnhookingDetails->RemoveBreakpointInterception = FALSE;
                        BroadcastDisableBreakpointExitingOnExceptionBitmapAllCores();
                    }
                }
 
                return TRUE;
            }
            else
            {
                //
                // Set 0xcc to its previous value
                //
                TargetAddressInFakePageContent = EptHookCalcBreakpointOffset((PVOID)VirtualAddress, HookedEntry);
 
                //
                // We'll check if there is another hooked address with the same virtual address
                // in the array, then we'll ignore setting the previous bit as previous bit might
                // be modified for the previous command
                //
                for (SIZE_T j = 0; j < HookedEntry->CountOfBreakpoints; j++)
                {
                    if (HookedEntry->BreakpointAddresses[j] == VirtualAddress)
                    {
                        CountOfEntriesWithSameAddr++;
                    }
                }
 
                if (CountOfEntriesWithSameAddr == 1)
                {
                    //
                    // Set the previous value
                    //
                    *(BYTE *)TargetAddressInFakePageContent = HookedEntry->PreviousBytesOnBreakpointAddresses[i];
                }
 
                //
                // Remove just that special entry
                // BTW, No need to remove it, it will be replaced automatically
                //
                HookedEntry->BreakpointAddresses[i]                = NULL64_ZERO;
                HookedEntry->PreviousBytesOnBreakpointAddresses[i] = 0x0;
 
                //
                // all addresses to a lower array index (because one entry is
                // missing and might) be in the middle of the array
                //
                for (SIZE_T j = i /* IndexToRemove */; j < HookedEntry->CountOfBreakpoints - 1; j++)
                {
                    HookedEntry->BreakpointAddresses[j]                = HookedEntry->BreakpointAddresses[j + 1];
                    HookedEntry->PreviousBytesOnBreakpointAddresses[j] = HookedEntry->PreviousBytesOnBreakpointAddresses[j + 1];
                }
 
                //
                // Decrease the count of breakpoints
                //
                HookedEntry->CountOfBreakpoints = HookedEntry->CountOfBreakpoints - 1;
 
                return TRUE;
            }
        }
    }
 
    //
    // If we reach here, sth went wrong
    //
    return FALSE;
}

EptHookUnHookSingleHookByHookingTagFromVmxRoot()

BOOLEAN EptHookUnHookSingleHookByHookingTagFromVmxRoot	(	UINT64	HookingTag,
		EPT_SINGLE_HOOK_UNHOOKING_DETAILS *	TargetUnhookingDetails )

Remove single hook from the hooked pages by the given hooking tag.

Should be called from Vmx root-mode

Parameters

HookingTag

The hooking tag to unhook

Returns

BOOLEAN If unhook was successful it returns true or if it was not successful returns false

{
    //
    // Should be called from VMX root-mode
    //
    if (VmxGetCurrentExecutionMode() == FALSE)
    {
        return FALSE;
    }
 
    return EptHookPerformUnHookSingleAddress(NULL64_ZERO,
                                             NULL64_ZERO,
                                             HookingTag,
                                             NULL_ZERO,
                                             TRUE,
                                             TargetUnhookingDetails);
}

EptHookWriteAbsoluteJump()

VOID EptHookWriteAbsoluteJump	(	PCHAR	TargetBuffer,
		SIZE_T	TargetAddress )

Write an absolute x64 jump to an arbitrary address to a buffer.

Parameters

TargetBuffer
TargetAddress

Returns

VOID

{
    //
    // call $ + 5 ; A 64-bit call instruction is still 5 bytes wide!
    //
 
    TargetBuffer[0] = 0xe8;
    TargetBuffer[1] = 0x00;
    TargetBuffer[2] = 0x00;
    TargetBuffer[3] = 0x00;
    TargetBuffer[4] = 0x00;
 
    //
    // push Lower 4-byte TargetAddress
    //
    TargetBuffer[5] = 0x68;
 
    //
    // Lower 4-byte TargetAddress
    //
    *((PUINT32)&TargetBuffer[6]) = (UINT32)TargetAddress;
 
    //
    // mov [rsp+4],High 4-byte TargetAddress
    //
    TargetBuffer[10] = 0xC7;
    TargetBuffer[11] = 0x44;
    TargetBuffer[12] = 0x24;
    TargetBuffer[13] = 0x04;
 
    //
    // High 4-byte TargetAddress
    //
    *((PUINT32)&TargetBuffer[14]) = (UINT32)(TargetAddress >> 32);
 
    //
    // ret
    //
    TargetBuffer[18] = 0xC3;
}

EptHookWriteAbsoluteJump2()

VOID EptHookWriteAbsoluteJump2	(	PCHAR	TargetBuffer,
		SIZE_T	TargetAddress )

Write an absolute x64 jump to an arbitrary address to a buffer.

Parameters

TargetBuffer
TargetAddress

Returns

VOID

{
    //
    // push Lower 4-byte TargetAddress
    //
    TargetBuffer[0] = 0x68;
 
    //
    // Lower 4-byte TargetAddress
    //
    *((PUINT32)&TargetBuffer[1]) = (UINT32)TargetAddress;
 
    //
    // mov [rsp+4],High 4-byte TargetAddress
    //
    TargetBuffer[5] = 0xC7;
    TargetBuffer[6] = 0x44;
    TargetBuffer[7] = 0x24;
    TargetBuffer[8] = 0x04;
 
    //
    // High 4-byte TargetAddress
    //
    *((PUINT32)&TargetBuffer[9]) = (UINT32)(TargetAddress >> 32);
 
    //
    // ret
    //
    TargetBuffer[13] = 0xC3;
}

ExAllocatePoolWithTagHook()

PVOID ExAllocatePoolWithTagHook	(	POOL_TYPE	PoolType,
		SIZE_T	NumberOfBytes,
		ULONG	Tag )

Hook function that HooksExAllocatePoolWithTag.

Parameters

PoolType
NumberOfBytes
Tag

Returns

PVOID

{
    LogInfo("ExAllocatePoolWithTag Called with : Tag = 0x%x, Number Of Bytes = 0x%x, Pool Type = 0x%x ",
            Tag,
            NumberOfBytes,
            PoolType);
 
    return ExAllocatePoolWithTagOrig(PoolType, NumberOfBytes, Tag);
}