Hook headers. More...

Classes
struct	_HIDDEN_HOOKS_DETOUR_DETAILS
	Details of detours style EPT hooks. More...

Macros
#define	IS_SYSRET_INSTRUCTION(Code)
	As we have just on sysret in all the Windows, we use the following variable to hold its address this way, we're not force to check for the instruction so we remove the memory access to check for sysret in this case.
#define	IS_SYSCALL_INSTRUCTION(Code)
#define	IMAGE_DOS_SIGNATURE 0x5A4D
	Special signatures.
#define	IMAGE_OS2_SIGNATURE 0x454E
#define	IMAGE_OS2_SIGNATURE_LE 0x454C
#define	IMAGE_VXD_SIGNATURE 0x454C
#define	IMAGE_NT_SIGNATURE 0x00004550
#define	MAX_EXEC_TRAMPOLINE_SIZE 100
	Maximum number of supported execution trampoline.

Typedefs
typedef struct _HIDDEN_HOOKS_DETOUR_DETAILS	HIDDEN_HOOKS_DETOUR_DETAILS
	Details of detours style EPT hooks.
typedef struct _HIDDEN_HOOKS_DETOUR_DETAILS *	PHIDDEN_HOOKS_DETOUR_DETAILS

Functions
VOID	SyscallHookConfigureEFER (VIRTUAL_MACHINE_STATE *VCpu, BOOLEAN EnableEFERSyscallHook)
	This function enables or disables EFER syscall hoo.
BOOLEAN	SyscallHookHandleUD (_Inout_ VIRTUAL_MACHINE_STATE *VCpu)
BOOLEAN	SyscallHookEmulateSYSRET (_Inout_ VIRTUAL_MACHINE_STATE *VCpu)
BOOLEAN	SyscallHookEmulateSYSCALL (_Inout_ VIRTUAL_MACHINE_STATE *VCpu)
BOOLEAN	EptHookPerformPageHook (VIRTUAL_MACHINE_STATE *VCpu, PVOID TargetAddress, CR3_TYPE ProcessCr3)
	Hook in VMX Root Mode with hidden breakpoints (A pre-allocated buffer should be available).
BOOLEAN	EptHookPerformPageHookMonitorAndInlineHook (VIRTUAL_MACHINE_STATE *VCpu, PVOID HookingDetails, CR3_TYPE ProcessCr3, UINT32 PageHookMask)
	Hook in VMX Root Mode with hidden detours and monitor (A pre-allocated buffer should be available).
BOOLEAN	EptHook (PVOID TargetAddress, UINT32 ProcessId)
	Hook in VMX non-root Mode (hidden breakpoint).
BOOLEAN	EptHookFromVmxRoot (PVOID TargetAddress)
	This function invokes a direct VMCALL to setup the hook.
BOOLEAN	EptHookInlineHook (VIRTUAL_MACHINE_STATE *VCpu, PVOID TargetAddress, PVOID HookFunction, UINT32 ProcessId)
	Hook in VMX non-root mode (hidden detours).
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)
	Hook in VMX root-mode (hidden detours).
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)
	Handle hooked pages in Vmx-root mode.
BOOLEAN	EptHookRestoreSingleHookToOriginalEntry (VIRTUAL_MACHINE_STATE *VCpu, SIZE_T PhysicalAddress, UINT64 OriginalEntry)
	Remove a special hook from the hooked pages lists.
VOID	EptHookRestoreAllHooksToOriginalEntry (VIRTUAL_MACHINE_STATE *VCpu)
	Remove all hooks from the hooked pages lists (Should be called in vmx-root).
VOID	EptHookUnHookAll ()
	Remove all hooks from the hooked pages lists.
BOOLEAN	EptHookUnHookAllByHookingTag (UINT64 HookingTag)
	Remove all hooks 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 From VMX non-root mode.
BOOLEAN	EptHookUnHookSingleHookByHookingTagFromVmxRoot (UINT64 HookingTag, EPT_SINGLE_HOOK_UNHOOKING_DETAILS *TargetUnhookingDetails)
	Remove single hook from the hooked pages by the given hooking tag.
BOOLEAN	EptHookUnHookSingleAddressFromVmxRoot (UINT64 VirtualAddress, UINT64 PhysAddress, EPT_SINGLE_HOOK_UNHOOKING_DETAILS *TargetUnhookingDetails)
	Remove single hook from the hooked pages list and invalidate TLB From VMX root-mode.
UINT32	EptHookGetCountOfEpthooks (BOOLEAN IsEptHook2)
	get the length of active EPT hooks (!epthook and !epthook2)
BOOLEAN	EptHookRemoveEntryAndFreePoolFromEptHook2sDetourList (UINT64 Address)
	Remove an entry from g_EptHook2sDetourListHead.
PVOID	EptHook2GeneralDetourEventHandler (PGUEST_REGS Regs, PVOID CalledFrom)
	routines to generally handle breakpoint hit for detour
VOID	EptHookAllocateExtraHookingPagesForMemoryMonitorsAndExecEptHooks (UINT32 Count)
	Allocate (reserve) extra pages for storing details of page hooks for memory monitor and regular hidden breakpoit exec EPT hooks.
VOID	EptHookReservePreallocatedPoolsForEptHooks (UINT32 Count)
	Allocate pre-allocated pools for EPT hooks.
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.
VOID	EptHookHandleMonitorTrapFlag (VIRTUAL_MACHINE_STATE *VCpu)
	Handle vm-exits for Monitor Trap Flag to restore previous state.

Variables
POOL_TYPE	PoolType
POOL_TYPE SIZE_T	NumberOfBytes
POOL_TYPE SIZE_T ULONG	Tag

Detailed Description

Hook headers.

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

Version: 0.1

Date: 2020-04-11

Copyright: This project is released under the GNU Public License v3.

Macro Definition Documentation

◆ IMAGE_DOS_SIGNATURE

#define IMAGE_DOS_SIGNATURE 0x5A4D

Special signatures.

◆ IMAGE_NT_SIGNATURE

#define IMAGE_NT_SIGNATURE 0x00004550

◆ IMAGE_OS2_SIGNATURE

#define IMAGE_OS2_SIGNATURE 0x454E

◆ IMAGE_OS2_SIGNATURE_LE

#define IMAGE_OS2_SIGNATURE_LE 0x454C

◆ IMAGE_VXD_SIGNATURE

#define IMAGE_VXD_SIGNATURE 0x454C

◆ IS_SYSCALL_INSTRUCTION

#define IS_SYSCALL_INSTRUCTION ( Code )

Value:

(*((PUINT8)(Code) + 0) == 0x0F && \

*((PUINT8)(Code) + 1) == 0x05)

PUINT8

unsigned char * PUINT8

Definition BasicTypes.h:52

#define IS_SYSCALL_INSTRUCTION(Code)  \
    (*((PUINT8)(Code) + 0) == 0x0F && \
     *((PUINT8)(Code) + 1) == 0x05)

◆ IS_SYSRET_INSTRUCTION

#define IS_SYSRET_INSTRUCTION ( Code )

Value:

(*((PUINT8)(Code) + 0) == 0x48 && \
 *((PUINT8)(Code) + 1) == 0x0F && \
 *((PUINT8)(Code) + 2) == 0x07)

As we have just on sysret in all the Windows, we use the following variable to hold its address this way, we're not force to check for the instruction so we remove the memory access to check for sysret in this case.

Check for instruction sysret and syscall

#define IS_SYSRET_INSTRUCTION(Code)   \
    (*((PUINT8)(Code) + 0) == 0x48 && \
     *((PUINT8)(Code) + 1) == 0x0F && \
     *((PUINT8)(Code) + 2) == 0x07)

◆ MAX_EXEC_TRAMPOLINE_SIZE

#define MAX_EXEC_TRAMPOLINE_SIZE 100

Maximum number of supported execution trampoline.

Typedef Documentation

◆ HIDDEN_HOOKS_DETOUR_DETAILS

typedef struct _HIDDEN_HOOKS_DETOUR_DETAILS HIDDEN_HOOKS_DETOUR_DETAILS

Details of detours style EPT hooks.

◆ PHIDDEN_HOOKS_DETOUR_DETAILS

typedef struct _HIDDEN_HOOKS_DETOUR_DETAILS * PHIDDEN_HOOKS_DETOUR_DETAILS

Function Documentation

◆ EptHook()

BOOLEAN EptHook	(	PVOID	TargetAddress,
		UINT32	ProcessId )

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

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

Parameters

TargetAddress
ProcessId

Returns: BOOLEAN

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

{
    //
    // 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.

Parameters

TargetAddress

Returns: BOOLEAN

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

{
    //
    // 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

return UINT32

Parameters

IsEptHook2 Whether the length should be for !epthook or !epthook2

Returns: UINT32 Count of remained breakpoints

{
    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 )

Handle hooked pages in Vmx-root mode.

Handles page hooks (trigger events).

Parameters

VCpu
HookedEntryDetails
ViolationQualification
PhysicalAddress
LastContext
IgnoreReadOrWriteOrExec
IsExecViolation

Returns: BOOLEAN

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

{
    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 )

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

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

Parameters

VCpu
TargetAddress
HookFunction
ProcessId

Returns: BOOLEAN

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

{
    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 )

Hook in VMX root-mode (hidden detours).

This function applies EPT inline to the target EPT table.

Parameters

VCpu
TargetAddress
HookFunction

Returns: BOOLEAN

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

{
    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);
}

◆ 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
MemoryAddressDetails

Returns: BOOLEAN

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

{
    //
    // 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
HookingDetails
ProcessId

Returns: BOOLEAN

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

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

◆ EptHookPerformPageHook()

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

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

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

Parameters

VCpu
TargetAddress
ProcessCr3

Returns: BOOLEAN

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

{
    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 )

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

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

Parameters

VCpu
HookingDetails
ProcessCr3
PageHookMask

Returns: BOOLEAN

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

{
    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;
}

◆ EptHookRemoveEntryAndFreePoolFromEptHook2sDetourList()

BOOLEAN EptHookRemoveEntryAndFreePoolFromEptHook2sDetourList ( UINT64 Address )

Remove an entry from g_EptHook2sDetourListHead.

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

Parameters

Address

Returns: BOOLEAN

Remove an entry from g_EptHook2sDetourListHead.

Parameters

Address Address to remove

Returns: BOOLEAN TRUE if successfully removed and false if not found

{
    //
    // 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 )

Allocate pre-allocated pools for EPT hooks.

Reserve pre-allocated pools for EPT hooks.

Parameters

Count number of hooks

Returns: VOID

Allocate 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 all hooks from the hooked pages lists (Should be called in vmx-root).

Remove and Invalidate Hook in TLB.

Parameters

VCpu

Returns: VOID

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

{
    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 a special hook from the hooked pages lists.

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

Parameters

VCpu
PhysicalAddress
OriginalEntry

Returns: BOOLEAN

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

{
    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 lists.

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

Returns: VOID

Remove all hooks from the hooked pages lists.

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 From VMX non-root mode.

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

Parameters

VirtualAddress
PhysAddress
ProcessId

Returns: BOOLEAN

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

{
    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);
}

◆ EptHookUnHookSingleAddressFromVmxRoot()

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

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

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

Parameters

VirtualAddress
PhysAddress
TargetUnhookingDetails

Returns: BOOLEAN

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

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

◆ 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);
}

◆ SyscallHookConfigureEFER()

VOID SyscallHookConfigureEFER	(	VIRTUAL_MACHINE_STATE *	VCpu,
		BOOLEAN	EnableEFERSyscallHook )

This function enables or disables EFER syscall hoo.

This function should be called for the first time that we want to enable EFER hook because after calling this function EFER MSR is loaded from GUEST_EFER instead of loading from the regular EFER MSR.

Parameters

VCpu	The virtual processor's state
EnableEFERSyscallHook	Determines whether we want to enable syscall hook or disable syscall hook

Returns: VOID

{
    IA32_EFER_REGISTER      MsrValue;
    IA32_VMX_BASIC_REGISTER VmxBasicMsr     = {0};
    UINT32                  VmEntryControls = 0;
    UINT32                  VmExitControls  = 0;
 
    //
    // Reading IA32_VMX_BASIC_MSR
    //
    VmxBasicMsr.AsUInt = CpuReadMsr(IA32_VMX_BASIC);
 
    //
    // Read previous VM-Entry and VM-Exit controls
    //
    VmxVmread32P(VMCS_CTRL_VMENTRY_CONTROLS, &VmEntryControls);
    VmxVmread32P(VMCS_CTRL_PRIMARY_VMEXIT_CONTROLS, &VmExitControls);
 
    MsrValue.AsUInt = CpuReadMsr(IA32_EFER);
 
    if (EnableEFERSyscallHook)
    {
        MsrValue.SyscallEnable = FALSE;
 
        //
        // Set VM-Entry controls to load EFER
        //
        VmxVmwrite32(VMCS_CTRL_VMENTRY_CONTROLS, HvAdjustControls(VmEntryControls | IA32_VMX_ENTRY_CTLS_LOAD_IA32_EFER_FLAG, VmxBasicMsr.VmxControls ? IA32_VMX_TRUE_ENTRY_CTLS : IA32_VMX_ENTRY_CTLS));
 
        //
        // Set VM-Exit controls to save EFER
        //
        VmxVmwrite32(VMCS_CTRL_PRIMARY_VMEXIT_CONTROLS, HvAdjustControls(VmExitControls | IA32_VMX_EXIT_CTLS_SAVE_IA32_EFER_FLAG, VmxBasicMsr.VmxControls ? IA32_VMX_TRUE_EXIT_CTLS : IA32_VMX_EXIT_CTLS));
 
        //
        // Set the GUEST EFER to use this value as the EFER
        //
        VmxVmwrite64(VMCS_GUEST_EFER, MsrValue.AsUInt);
 
        //
        // also, we have to set exception bitmap to cause vm-exit on #UDs
        //
        HvSetExceptionBitmap(VCpu, EXCEPTION_VECTOR_UNDEFINED_OPCODE);
    }
    else
    {
        MsrValue.SyscallEnable = TRUE;
 
        //
        // Set VM-Entry controls to load EFER
        //
        VmxVmwrite32(VMCS_CTRL_VMENTRY_CONTROLS, HvAdjustControls(VmEntryControls & ~IA32_VMX_ENTRY_CTLS_LOAD_IA32_EFER_FLAG, VmxBasicMsr.VmxControls ? IA32_VMX_TRUE_ENTRY_CTLS : IA32_VMX_ENTRY_CTLS));
 
        //
        // Set VM-Exit controls to save EFER
        //
        VmxVmwrite32(VMCS_CTRL_PRIMARY_VMEXIT_CONTROLS, HvAdjustControls(VmExitControls & ~IA32_VMX_EXIT_CTLS_SAVE_IA32_EFER_FLAG, VmxBasicMsr.VmxControls ? IA32_VMX_TRUE_EXIT_CTLS : IA32_VMX_EXIT_CTLS));
 
        //
        // Set the GUEST EFER to use this value as the EFER
        //
        VmxVmwrite64(VMCS_GUEST_EFER, MsrValue.AsUInt);
 
        //
        // Because we're not save or load EFER on vm-exits so
        // we have to set it manually
        //
        CpuWriteMsr(IA32_EFER, MsrValue.AsUInt);
 
        //
        // unset the exception to not cause vm-exit on #UDs
        //
        ProtectedHvRemoveUndefinedInstructionForDisablingSyscallSysretCommands(VCpu);
    }
}

◆ SyscallHookEmulateSYSCALL()

BOOLEAN SyscallHookEmulateSYSCALL ( _Inout_ VIRTUAL_MACHINE_STATE * VCpu )

◆ SyscallHookEmulateSYSRET()

BOOLEAN SyscallHookEmulateSYSRET ( _Inout_ VIRTUAL_MACHINE_STATE * VCpu )

◆ SyscallHookHandleUD()

BOOLEAN SyscallHookHandleUD ( _Inout_ VIRTUAL_MACHINE_STATE * VCpu )

Variable Documentation

◆ NumberOfBytes

POOL_TYPE SIZE_T NumberOfBytes

◆ PoolType

POOL_TYPE PoolType

◆ Tag

POOL_TYPE SIZE_T ULONG Tag

Classes

Macros

Typedefs

Functions

Variables

Detailed Description

Macro Definition Documentation

◆ IMAGE_DOS_SIGNATURE

◆ IMAGE_NT_SIGNATURE

◆ IMAGE_OS2_SIGNATURE

◆ IMAGE_OS2_SIGNATURE_LE

◆ IMAGE_VXD_SIGNATURE

◆ IS_SYSCALL_INSTRUCTION

◆ IS_SYSRET_INSTRUCTION

◆ MAX_EXEC_TRAMPOLINE_SIZE

Typedef Documentation

◆ HIDDEN_HOOKS_DETOUR_DETAILS

◆ PHIDDEN_HOOKS_DETOUR_DETAILS

Function Documentation

◆ EptHook()

◆ EptHook2GeneralDetourEventHandler()

◆ EptHookAllocateExtraHookingPagesForMemoryMonitorsAndExecEptHooks()

◆ EptHookFromVmxRoot()

◆ EptHookGetCountOfEpthooks()

◆ EptHookHandleHookedPage()

◆ EptHookHandleMonitorTrapFlag()

◆ EptHookInlineHook()

◆ EptHookInlineHookFromVmxRoot()

◆ EptHookModifyInstructionFetchState()

◆ EptHookModifyPageReadState()

◆ EptHookModifyPageWriteState()

◆ EptHookMonitorFromVmxRoot()

◆ EptHookMonitorHook()

◆ EptHookPerformPageHook()

◆ EptHookPerformPageHookMonitorAndInlineHook()

◆ EptHookRemoveEntryAndFreePoolFromEptHook2sDetourList()

◆ EptHookReservePreallocatedPoolsForEptHooks()

◆ EptHookRestoreAllHooksToOriginalEntry()

◆ EptHookRestoreSingleHookToOriginalEntry()

◆ EptHookUnHookAll()

◆ EptHookUnHookAllByHookingTag()

◆ EptHookUnHookSingleAddress()

◆ EptHookUnHookSingleAddressFromVmxRoot()

◆ EptHookUnHookSingleHookByHookingTagFromVmxRoot()

◆ SyscallHookConfigureEFER()

◆ SyscallHookEmulateSYSCALL()

◆ SyscallHookEmulateSYSRET()

◆ SyscallHookHandleUD()

Variable Documentation

◆ NumberOfBytes

◆ PoolType

◆ Tag