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 exec trap based on service request.
VOID	ExecTrapApplyMbecConfiguratinFromKernelSide (VIRTUAL_MACHINE_STATE *VCpu)
	Apply the MBEC configuration from the kernel side.
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.

Variables
volatile LONG	ExecTrapProcessListLock
	The lock for modifying the list of processes for user-mode, kernel-mode execution traps.

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

{
    UINT32  Index;
    BOOLEAN Result;
 
    SpinlockLock(&ExecTrapProcessListLock);
 
    Result = InsertionSortInsertItem(&g_ExecTrapState.InterceptionProcessIds[0],
                                     &g_ExecTrapState.NumberOfItems,
                                     MAXIMUM_NUMBER_OF_PROCESSES_FOR_USER_KERNEL_EXEC_THREAD,
                                     &Index,
                                     (UINT64)ProcessId);
 
    SpinlockUnlock(&ExecTrapProcessListLock);
 
    return Result;
}

ExecTrapApplyMbecConfiguratinFromKernelSide()

VOID ExecTrapApplyMbecConfiguratinFromKernelSide

(

VIRTUAL_MACHINE_STATE *

VCpu

)

Apply the MBEC configuration from the kernel side.

Parameters

VCpu	The virtual processor's state

Returns

VOID

{
    BOOLEAN Result;
    UINT32  Index;
 
    //
    // Acquire the lock for the exec trap process list
    //
    SpinlockLock(&ExecTrapProcessListLock);
 
    //
    // 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());
 
    //
    // Release the lock for the exec trap process list
    //
    SpinlockUnlock(&ExecTrapProcessListLock);
 
    //
    // 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);
    }
    else if (VCpu->MbecEnabled)
    {
        //
        // In case, the process is changed, we've disable the MBEC
        //
        HvSetModeBasedExecutionEnableFlag(FALSE);
        VCpu->MbecEnabled = FALSE;
    }
}

ExecTrapChangeToKernelDisabledMbecEptp()

VOID ExecTrapChangeToKernelDisabledMbecEptp

(

VIRTUAL_MACHINE_STATE *

VCpu

)

change to kernel-disabled MBEC EPTP

Parameters

VCpu	The virtual processor's state

Returns

VOID

{
    //
    // From Intel Manual:
    // [Bit 2] If the "mode-based execute control for EPT" VM - execution control is 0, execute access;
    // indicates whether instruction fetches are allowed from the 2-MByte page controlled by this entry.
    // If that control is 1, execute access for supervisor-mode linear addresses; indicates whether instruction
    // fetches are allowed from supervisor - mode linear addresses in the 2 - MByte page controlled by this entry
    //
 
    //
    // Set execute access for PML4s
    //
    // for (SIZE_T i = 0; i < VMM_EPT_PML4E_COUNT; i++)
    // {
    VCpu->EptPageTable->PML4[0].UserModeExecute = TRUE;
 
    //
    // We only set the top-level PML4 for intercepting kernel-mode execution
    //
    VCpu->EptPageTable->PML4[0].ExecuteAccess = FALSE;
    // }
 
    //
    // Invalidate the EPT cache
    //
    EptInveptSingleContext(VCpu->EptPointer.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

{
    //
    // From Intel Manual:
    // [Bit 2] If the "mode-based execute control for EPT" VM - execution control is 0, execute access;
    // indicates whether instruction fetches are allowed from the 2-MByte page controlled by this entry.
    // If that control is 1, execute access for supervisor-mode linear addresses; indicates whether instruction
    // fetches are allowed from supervisor - mode linear addresses in the 2 - MByte page controlled by this entry
    //
 
    //
    // Set execute access for PML4s
    //
    // for (SIZE_T i = 0; i < VMM_EPT_PML4E_COUNT; i++)
    // {
    VCpu->EptPageTable->PML4[0].UserModeExecute = FALSE;
 
    //
    // We only set the top-level PML4 for intercepting kernel-mode execution
    //
    VCpu->EptPageTable->PML4[0].ExecuteAccess = TRUE;
    // }
 
    //
    // Invalidate the EPT cache
    //
    EptInveptSingleContext(VCpu->EptPointer.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

{
    ExecTrapApplyMbecConfiguratinFromKernelSide(VCpu);
}

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);
    }
    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);
    }
    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);
    }
    else
    {
        LogError("Err, Invalid target mode for execution trap: %x", TargetMode);
    }
}

ExecTrapInitialize()

BOOLEAN ExecTrapInitialize

(

)

Initialize the exec trap based on service request.

Returns

BOOLEAN

{
    //
    // Check if the exec trap is already initialized
    //
    if (g_ExecTrapInitialized)
    {
        //
        // Already initialized
        //
        return TRUE;
    }
 
    //
    // 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;
    }
 
    //
    // Call the function responsible for initializing Mode-based hooks
    //
    if (ModeBasedExecHookInitialize() == FALSE)
    {
        //
        // 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

{
    UINT32  Index;
    BOOLEAN Result;
 
    SpinlockLock(&ExecTrapProcessListLock);
 
    Result = BinarySearchPerformSearchItem(&g_ExecTrapState.InterceptionProcessIds[0],
                                           g_ExecTrapState.NumberOfItems,
                                           &Index,
                                           (UINT64)ProcessId);
 
    if (Result)
    {
        Result = InsertionSortDeleteItem(&g_ExecTrapState.InterceptionProcessIds[0],
                                         &g_ExecTrapState.NumberOfItems,
                                         Index);
    }
 
    SpinlockUnlock(&ExecTrapProcessListLock);
 
    return Result;
}

ExecTrapRestoreToNormalEptp()

VOID ExecTrapRestoreToNormalEptp

(

VIRTUAL_MACHINE_STATE *

VCpu

)

restore to normal EPTP

Parameters

VCpu	The virtual processor's state

Returns

VOID

{
    //
    // Change EPTP
    //
    VmxVmwrite64(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;
}

Variable Documentation

ExecTrapProcessListLock

volatile LONG ExecTrapProcessListLock

The lock for modifying the list of processes for user-mode, kernel-mode execution traps.