ExecTrap.h File Reference

Header for the user-mode, kernel-mode execution traps' routines. More...

#include "pch.h"

Go to the source code of this file.

Classes
struct	_USER_KERNEL_EXECUTION_TRAP_STATE
	The status user-mode, kernel-mode execution traps for processes. More...

Macros
#define	MAXIMUM_NUMBER_OF_PROCESSES_FOR_USER_KERNEL_EXEC_THREAD   100
	maximum number of processes for a simultaneous user-mode, kernel-mode execution trap

Typedefs
typedef struct _USER_KERNEL_EXECUTION_TRAP_STATE	USER_KERNEL_EXECUTION_TRAP_STATE
	The status user-mode, kernel-mode execution traps for processes.
typedef struct _USER_KERNEL_EXECUTION_TRAP_STATE *	PUSER_KERNEL_EXECUTION_TRAP_STATE

Functions
VOID	ExecTrapHandleCr3Vmexit (VIRTUAL_MACHINE_STATE *VCpu)
	Handle MOV to CR3 vm-exits for hooking mode execution.
VOID	ExecTrapChangeToUserDisabledMbecEptp (VIRTUAL_MACHINE_STATE *VCpu)
	change to user-disabled MBEC EPTP
VOID	ExecTrapChangeToKernelDisabledMbecEptp (VIRTUAL_MACHINE_STATE *VCpu)
	change to kernel-disabled MBEC EPTP
VOID	ExecTrapRestoreToNormalEptp (VIRTUAL_MACHINE_STATE *VCpu)
	restore to normal EPTP
VOID	ExecTrapHandleMoveToAdjustedTrapState (VIRTUAL_MACHINE_STATE *VCpu, DEBUGGER_EVENT_MODE_TYPE TargetMode)
	Restore the execution of the trap to adjusted trap state.
VOID	ExecTrapUninitialize ()
	Uinitialize the needed structure for the reversing machine.
BOOLEAN	ExecTrapInitialize ()
	Initialize the reversing machine based on service request.
BOOLEAN	ExecTrapHandleEptViolationVmexit (VIRTUAL_MACHINE_STATE *VCpu, VMX_EXIT_QUALIFICATION_EPT_VIOLATION *ViolationQualification)
	Handle EPT Violations related to the MBEC hooks.
BOOLEAN	ExecTrapAddProcessToWatchingList (UINT32 ProcessId)
	Add the target process to the watching list.
BOOLEAN	ExecTrapRemoveProcessFromWatchingList (UINT32 ProcessId)
	Remove the target process from the watching list.

Detailed Description

Header for the user-mode, kernel-mode execution traps' routines.

Author

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

Version

0.4

Date

2023-07-05

Copyright

This project is released under the GNU Public License v3.

Macro Definition Documentation

MAXIMUM_NUMBER_OF_PROCESSES_FOR_USER_KERNEL_EXEC_THREAD

#define MAXIMUM_NUMBER_OF_PROCESSES_FOR_USER_KERNEL_EXEC_THREAD   100

maximum number of processes for a simultaneous user-mode, kernel-mode execution trap

Typedef Documentation

PUSER_KERNEL_EXECUTION_TRAP_STATE

typedef struct _USER_KERNEL_EXECUTION_TRAP_STATE * PUSER_KERNEL_EXECUTION_TRAP_STATE

USER_KERNEL_EXECUTION_TRAP_STATE

typedef struct _USER_KERNEL_EXECUTION_TRAP_STATE USER_KERNEL_EXECUTION_TRAP_STATE

The status user-mode, kernel-mode execution traps for processes.

Function Documentation

ExecTrapAddProcessToWatchingList()

BOOLEAN ExecTrapAddProcessToWatchingList

(

UINT32

ProcessId

)

Add the target process to the watching list.

Parameters

ProcessId

Returns

BOOLEAN

{
    return InsertionSortInsertItem(&g_ExecTrapState.InterceptionProcessIds[0],
                                   &g_ExecTrapState.NumberOfItems,
                                   MAXIMUM_NUMBER_OF_PROCESSES_FOR_USER_KERNEL_EXEC_THREAD,
                                   (UINT64)ProcessId);
}

ExecTrapChangeToKernelDisabledMbecEptp()

VOID ExecTrapChangeToKernelDisabledMbecEptp

(

VIRTUAL_MACHINE_STATE *

VCpu

)

change to kernel-disabled MBEC EPTP

Parameters

VCpu	The virtual processor's state

Returns

VOID

{
    //
    // Change EPTP
    //
    __vmx_vmwrite(VMCS_CTRL_EPT_POINTER, g_EptState->ModeBasedKernelDisabledEptPointer.AsUInt);
 
    //
    // It's not on normal EPTP
    //
    VCpu->NotNormalEptp = TRUE;
}

ExecTrapChangeToUserDisabledMbecEptp()

VOID ExecTrapChangeToUserDisabledMbecEptp

(

VIRTUAL_MACHINE_STATE *

VCpu

)

change to user-disabled MBEC EPTP

Parameters

VCpu	The virtual processor's state

Returns

VOID

{
    //
    // Change EPTP
    //
    __vmx_vmwrite(VMCS_CTRL_EPT_POINTER, g_EptState->ModeBasedUserDisabledEptPointer.AsUInt);
 
    //
    // It's not on normal EPTP
    //
    VCpu->NotNormalEptp = TRUE;
}

ExecTrapHandleCr3Vmexit()

VOID ExecTrapHandleCr3Vmexit

(

VIRTUAL_MACHINE_STATE *

VCpu

)

Handle MOV to CR3 vm-exits for hooking mode execution.

Parameters

VCpu	The virtual processor's state

Returns

VOID

{
    BOOLEAN Result;
    UINT32  Index;
 
    //
    // Search the list of processes for the current process's user-execution
    //  trap state
    //
    Result = BinarySearchPerformSearchItem(&g_ExecTrapState.InterceptionProcessIds[0],
                                           g_ExecTrapState.NumberOfItems,
                                           &Index,
                                           (UINT64)PsGetCurrentProcessId());
 
    //
    // Check whether the procerss is in the list of interceptions or not
    //
    if (Result)
    {
        //
        // Enable MBEC to detect execution in user-mode
        //
        HvSetModeBasedExecutionEnableFlag(TRUE);
        VCpu->MbecEnabled = TRUE;
 
        //
        // Trigger the event
        //
        DispatchEventMode(VCpu, DEBUGGER_EVENT_MODE_TYPE_KERNEL_MODE, TRUE);
    }
    else if (VCpu->MbecEnabled)
    {
        //
        // In case, the process is changed, we've disable the MBEC
        //
        HvSetModeBasedExecutionEnableFlag(FALSE);
        VCpu->MbecEnabled = FALSE;
    }
}

ExecTrapHandleEptViolationVmexit()

BOOLEAN ExecTrapHandleEptViolationVmexit	(	VIRTUAL_MACHINE_STATE *	VCpu,
		VMX_EXIT_QUALIFICATION_EPT_VIOLATION *	ViolationQualification )

Handle EPT Violations related to the MBEC hooks.

Parameters

VCpu	The virtual processor's state
ViolationQualification

Returns

BOOLEAN

{
    //
    // Check if this mechanism is use or not
    //
    if (!g_ExecTrapInitialized)
    {
        return FALSE;
    }
 
    if (!ViolationQualification->EptExecutableForUserMode && ViolationQualification->ExecuteAccess)
    {
        //
        // For test purposes
        //
        // LogInfo("Reached to the user-mode of the process (0x%x) is executed address: %llx", PsGetCurrentProcessId(), VCpu->LastVmexitRip);
 
        //
        // Suppress the RIP increment
        //
        HvSuppressRipIncrement(VCpu);
 
        //
        // Trigger the event
        //
        DispatchEventMode(VCpu, DEBUGGER_EVENT_MODE_TYPE_USER_MODE, TRUE);
 
        return TRUE;
    }
    else if (!ViolationQualification->EptExecutable && ViolationQualification->ExecuteAccess)
    {
        //
        // For test purposes
        //
        // LogInfo("Reached to the kernel-mode of the process (0x%x) is executed address: %llx", PsGetCurrentProcessId(), VCpu->LastVmexitRip);
 
        //
        // Suppress the RIP increment
        //
        HvSuppressRipIncrement(VCpu);
 
        //
        // Trigger the event
        //
        DispatchEventMode(VCpu, DEBUGGER_EVENT_MODE_TYPE_KERNEL_MODE, TRUE);
    }
    else
    {
        //
        // Unexpected violation
        //
        return FALSE;
    }
 
    //
    // It successfully handled by MBEC hooks
    //
    return TRUE;
}

ExecTrapHandleMoveToAdjustedTrapState()

VOID ExecTrapHandleMoveToAdjustedTrapState	(	VIRTUAL_MACHINE_STATE *	VCpu,
		DEBUGGER_EVENT_MODE_TYPE	TargetMode )

Restore the execution of the trap to adjusted trap state.

Parameters

VCpu	The virtual processor's state
IsUserMode	Whether the execution event caused by a switch from kernel-to-user or otherwise user-to-kernel

Returns

VOID

{
    if (TargetMode == DEBUGGER_EVENT_MODE_TYPE_USER_MODE)
    {
        //
        // Change EPT to kernel disabled
        //
        ExecTrapChangeToKernelDisabledMbecEptp(VCpu);
    }
    else if (TargetMode == DEBUGGER_EVENT_MODE_TYPE_KERNEL_MODE)
    {
        //
        // Change EPT to user disabled
        //
        ExecTrapChangeToUserDisabledMbecEptp(VCpu);
    }
}

ExecTrapInitialize()

BOOLEAN ExecTrapInitialize

(

)

Initialize the reversing machine based on service request.

Returns

BOOLEAN

{
    //
    // Check if the reversing machine is already initialized
    //
    if (g_ExecTrapInitialized)
    {
        //
        // Already initialized
        //
        return FALSE;
    }
 
    //
    // Check if MBEC supported by this processors
    //
    if (!g_CompatibilityCheck.ModeBasedExecutionSupport)
    {
        LogInfo("Your processor doesn't support Mode-Based Execution Controls (MBEC), which is a needed feature for this functionality :(\n"
                "MBEC is available on processors starting from the 7th generation (Kaby Lake) and onwards");
        return FALSE;
    }
 
    //
    // Read the RAM regions
    //
    ExecTrapReadRamPhysicalRegions();
 
    //
    // Allocate MBEC EPT page-table (user-disabled)
    //
    if (!ExecTrapAllocateUserDisabledMbecEptPageTable())
    {
        //
        // There was an error allocating MBEC page table for EPT tables
        //
        return FALSE;
    }
 
    //
    // Allocate MBEC EPT page-table (kernel-disabled)
    //
    if (!ExecTrapAllocateKernelDisabledMbecEptPageTable())
    {
        //
        // Free the user-disabled page-table buffer
        //
        MmFreeContiguousMemory(g_EptState->ModeBasedUserDisabledEptPageTable);
        g_EptState->ModeBasedUserDisabledEptPageTable = NULL;
 
        //
        // There was an error allocating MBEC page table for EPT tables
        //
        return FALSE;
    }
 
    //
    // Call the function responsible for initializing Mode-based hooks
    //
    if (ModeBasedExecHookInitialize() == FALSE)
    {
        //
        // Free the user-disabled page-table buffer
        //
        MmFreeContiguousMemory(g_EptState->ModeBasedUserDisabledEptPageTable);
        g_EptState->ModeBasedUserDisabledEptPageTable = NULL;
 
        //
        // Free the kernel-disabled page-table buffer
        //
        MmFreeContiguousMemory(g_EptState->ModeBasedKernelDisabledEptPageTable);
        g_EptState->ModeBasedKernelDisabledEptPageTable = NULL;
 
        //
        // The initialization was not successful
        //
        return FALSE;
    }
 
    //
    // Change EPT on all core's to a MBEC supported EPTP
    // (No longer needed as the starting phase of the process uses EPT hooks)
    //
    BroadcastChangeToMbecSupportedEptpOnAllProcessors();
 
    //
    // Indicate that the reversing machine is initialized
    // It should be initialized here BEFORE broadcasting mov 2 cr3 exiting
    // because an EPT violation might be thrown before we enabled it from
    // here
    //
    g_ExecTrapInitialized = TRUE;
 
    //
    // Enable Mode-based execution control by broadcasting MOV to CR3 exiting
    //
    BroadcastEnableMovToCr3ExitingOnAllProcessors();
 
    return TRUE;
}

ExecTrapRemoveProcessFromWatchingList()

BOOLEAN ExecTrapRemoveProcessFromWatchingList

(

UINT32

ProcessId

)

Remove the target process from the watching list.

Parameters

ProcessId

Returns

BOOLEAN

{
    return InsertionSortDeleteItem(&g_ExecTrapState.InterceptionProcessIds[0],
                                   &g_ExecTrapState.NumberOfItems,
                                   (UINT64)ProcessId);
}

ExecTrapRestoreToNormalEptp()

VOID ExecTrapRestoreToNormalEptp

(

VIRTUAL_MACHINE_STATE *

VCpu

)

restore to normal EPTP

Parameters

VCpu	The virtual processor's state

Returns

VOID

{
    //
    // Change EPTP
    //
    __vmx_vmwrite(VMCS_CTRL_EPT_POINTER, VCpu->EptPointer.AsUInt);
 
    //
    // It's on normal EPTP
    //
    VCpu->NotNormalEptp = FALSE;
}

ExecTrapUninitialize()

VOID ExecTrapUninitialize

(

)

Uinitialize the needed structure for the reversing machine.

should be called from vmx non-root mode

Returns

VOID

{
    //
    // Check if it's already initialized
    //
    if (!g_ExecTrapInitialized)
    {
        return;
    }
 
    //
    // Indicate that the uninitialization phase started
    //
    g_ExecTrapUnInitializationStarted = TRUE;
 
    //
    // Disable MOV to CR3 exiting
    //
    BroadcastDisableMovToCr3ExitingOnAllProcessors();
 
    //
    // Restore to normal EPTP
    //
    BroadcastRestoreToNormalEptpOnAllProcessors();
 
    //
    // Uninitialize the mode-based execution controls
    //
    ModeBasedExecHookUninitialize();
 
    //
    // Indicate that the execution traps are disabled
    //
    g_ExecTrapInitialized = FALSE;
 
    //
    // Indicate that the uninitialization phase finished
    //
    g_ExecTrapUnInitializationStarted = FALSE;
 
    //
    // Free Identity Page Table for MBEC hooks (user-disabled)
    //
    if (g_EptState->ModeBasedUserDisabledEptPageTable != NULL)
    {
        MmFreeContiguousMemory(g_EptState->ModeBasedUserDisabledEptPageTable);
        g_EptState->ModeBasedUserDisabledEptPageTable = NULL;
    }
 
    //
    // Free Identity Page Table for MBEC hooks (kernel-disabled)
    //
    if (g_EptState->ModeBasedKernelDisabledEptPageTable != NULL)
    {
        MmFreeContiguousMemory(g_EptState->ModeBasedKernelDisabledEptPageTable);
        g_EptState->ModeBasedKernelDisabledEptPageTable = NULL;
    }
}