Ud.h File Reference

Header for routines related to user mode debugging. More...

Go to the source code of this file.

Classes
struct	_USERMODE_DEBUGGING_PROCESS_DETAILS
	Description of each active thread in user-mode attaching mechanism. More...

Typedefs
typedef struct _USERMODE_DEBUGGING_PROCESS_DETAILS	USERMODE_DEBUGGING_PROCESS_DETAILS
	Description of each active thread in user-mode attaching mechanism.
typedef struct _USERMODE_DEBUGGING_PROCESS_DETAILS *	PUSERMODE_DEBUGGING_PROCESS_DETAILS

Functions
BOOLEAN	UdInitializeUserDebugger ()
	initialize user debugger
VOID	UdUninitializeUserDebugger ()
	uninitialize user debugger
BOOLEAN	UdHandleInstantBreak (PROCESSOR_DEBUGGING_STATE *DbgState, DEBUGGEE_PAUSING_REASON Reason, PUSERMODE_DEBUGGING_PROCESS_DETAILS ProcessDebuggingDetail)
	Handle cases where we instant break is needed on the user debugger.
VOID	UdApplyHardwareDebugRegister (PVOID TargetAddress)
	Apply hardware debug registers to all cores.
BOOLEAN	UdCheckAndHandleBreakpointsAndDebugBreaks (PROCESSOR_DEBUGGING_STATE *DbgState, DEBUGGEE_PAUSING_REASON Reason, PDEBUGGER_TRIGGERED_EVENT_DETAILS EventDetails)
	Handle #DBs and #BPs for kernel debugger.
BOOLEAN	UdDispatchUsermodeCommands (PDEBUGGER_UD_COMMAND_PACKET ActionRequest, UINT32 ActionRequestInputLength, UINT32 ActionRequestOutputLength)
	Dispatch the user-mode commands.
BOOLEAN	UdCheckForCommand (PROCESSOR_DEBUGGING_STATE *DbgState, PUSERMODE_DEBUGGING_PROCESS_DETAILS ProcessDebuggingDetail)
	Check for the user-mode commands.
BOOLEAN	UdHandleDebugEventsWhenUserDebuggerIsAttached (PROCESSOR_DEBUGGING_STATE *DbgState, BOOLEAN TrapSetByDebugger)
	Handles debug events when user-debugger is attached.
VOID	UdSendFormatsFunctionResult (UINT64 Value)
	Send the result of formats command to the user debugger.

Detailed Description

Header for routines related to user mode debugging.

Author

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

Version

0.1

Date

2022-01-06

Copyright

This project is released under the GNU Public License v3.

Typedef Documentation

PUSERMODE_DEBUGGING_PROCESS_DETAILS

typedef struct _USERMODE_DEBUGGING_PROCESS_DETAILS * PUSERMODE_DEBUGGING_PROCESS_DETAILS

USERMODE_DEBUGGING_PROCESS_DETAILS

typedef struct _USERMODE_DEBUGGING_PROCESS_DETAILS USERMODE_DEBUGGING_PROCESS_DETAILS

Description of each active thread in user-mode attaching mechanism.

Function Documentation

UdApplyHardwareDebugRegister()

VOID UdApplyHardwareDebugRegister

(

PVOID

TargetAddress

)

Apply hardware debug registers to all cores.

Parameters

TargetAddress

Returns

VOID

{
    SetDebugRegisters(DEBUGGER_DEBUG_REGISTER_FOR_STEP_OVER,
                      BREAK_ON_INSTRUCTION_FETCH,
                      FALSE,
                      (UINT64)TargetAddress);
}

UdCheckAndHandleBreakpointsAndDebugBreaks()

BOOLEAN UdCheckAndHandleBreakpointsAndDebugBreaks	(	PROCESSOR_DEBUGGING_STATE *	DbgState,
		DEBUGGEE_PAUSING_REASON	Reason,
		PDEBUGGER_TRIGGERED_EVENT_DETAILS	EventDetails )

Handle #DBs and #BPs for kernel debugger.

This function can be used in vmx-root

Parameters

DbgState	The state of the debugger on the current core
Reason
EventDetails

Returns

BOOLEAN

{
    DEBUGGEE_UD_PAUSED_PACKET           PausePacket;
    ULONG                               ExitInstructionLength   = 0;
    UINT32                              SizeOfSafeBufferToRead  = 0;
    RFLAGS                              Rflags                  = {0};
    PUSERMODE_DEBUGGING_PROCESS_DETAILS ProcessDebuggingDetails = NULL;
    PUSERMODE_DEBUGGING_THREAD_DETAILS  ThreadDebuggingDetails  = NULL;
    UINT64                              LastVmexitRip           = VmFuncGetLastVmexitRip(DbgState->CoreId);
 
    //
    // Breaking only supported  if user-debugger is loaded
    //
    if (!g_UserDebuggerState)
    {
        return FALSE;
    }
 
    //
    // Check entry of paused thread
    //
    ProcessDebuggingDetails = AttachingFindProcessDebuggingDetailsByProcessId(HANDLE_TO_UINT32(PsGetCurrentProcessId()));
 
    if (!ProcessDebuggingDetails)
    {
        //
        // Token not found!
        //
        return FALSE;
    }
 
    //
    // Find the thread entry and if not found, create one for it
    //
    ThreadDebuggingDetails = ThreadHolderFindOrCreateThreadDebuggingDetail(HANDLE_TO_UINT32(PsGetCurrentThreadId()), ProcessDebuggingDetails);
 
    if (!ThreadDebuggingDetails)
    {
        //
        // Sth went wrong!
        //
        return FALSE;
    }
 
    //
    // Check if the thread is already paused or not
    //
    if (ThreadDebuggingDetails->IsPaused)
    {
        //
        // Increase the number of context switches
        //
        ThreadDebuggingDetails->NumberOfBlockedContextSwitches++;
 
        //
        // The thread is already paused, so we don't need to pause it again
        //
        return TRUE;
    }
 
    //
    // Set it as active thread debugging
    //
    ProcessDebuggingDetails->ActiveThreadId = ThreadDebuggingDetails->ThreadId;
 
    //
    // Perform the pre-pausing tasks
    //
    UdPrePausingReasons(DbgState, ThreadDebuggingDetails, Reason, EventDetails);
 
    //
    // *** Fill the pausing structure ***
    //
 
    RtlZeroMemory(&PausePacket, sizeof(DEBUGGEE_UD_PAUSED_PACKET));
 
    //
    // Set the pausing reason
    //
    PausePacket.PausingReason = Reason;
 
    //
    // Set process debugging information
    //
    PausePacket.ProcessId             = HANDLE_TO_UINT32(PsGetCurrentProcessId());
    PausePacket.ThreadId              = HANDLE_TO_UINT32(PsGetCurrentThreadId());
    PausePacket.ProcessDebuggingToken = ProcessDebuggingDetails->Token;
 
    //
    // Set the RIP and mode of execution
    //
    PausePacket.Rip     = LastVmexitRip;
    PausePacket.Is32Bit = KdIsGuestOnUsermode32Bit();
 
    //
    // Set rflags for finding the results of conditional jumps
    //
    Rflags.AsUInt      = VmFuncGetRflags();
    PausePacket.Rflags = Rflags.AsUInt;
 
    //
    // Set the event tag (if it's an event)
    //
    if (EventDetails != NULL)
    {
        PausePacket.EventTag          = EventDetails->Tag;
        PausePacket.EventCallingStage = EventDetails->Stage;
    }
 
    //
    // Read the instruction len
    //
    if (DbgState->InstructionLengthHint != 0)
    {
        ExitInstructionLength = DbgState->InstructionLengthHint;
    }
    else
    {
        //
        // Reading instruction length (VMCS_VMEXIT_INSTRUCTION_LENGTH) proved to
        // provide wrong results, so we won't use it
        //
 
        //
        // Compute the amount of buffer we can read without problem
        //
        SizeOfSafeBufferToRead = (UINT32)(LastVmexitRip & 0xfff);
        SizeOfSafeBufferToRead += MAXIMUM_INSTR_SIZE;
 
        if (SizeOfSafeBufferToRead >= PAGE_SIZE)
        {
            SizeOfSafeBufferToRead = SizeOfSafeBufferToRead - PAGE_SIZE;
            SizeOfSafeBufferToRead = MAXIMUM_INSTR_SIZE - SizeOfSafeBufferToRead;
        }
        else
        {
            SizeOfSafeBufferToRead = MAXIMUM_INSTR_SIZE;
        }
 
        //
        // Set the length to notify debuggee
        //
        ExitInstructionLength = SizeOfSafeBufferToRead;
    }
 
    //
    // Set the reading length of bytes (for instruction disassembling)
    //
    PausePacket.ReadInstructionLen = (UINT16)ExitInstructionLength;
 
    //
    // Find the current instruction
    //
    MemoryMapperReadMemorySafeOnTargetProcess(LastVmexitRip,
                                              &PausePacket.InstructionBytesOnRip,
                                              ExitInstructionLength);
 
    //
    // Send the pause packet, along with RIP and an indication
    // to pause to the user debugger
    //
    LogCallbackSendBuffer(OPERATION_NOTIFICATION_FROM_USER_DEBUGGER_PAUSE,
                          &PausePacket,
                          sizeof(DEBUGGEE_UD_PAUSED_PACKET),
                          TRUE);
 
    //
    // Set the thread debugging details
    //
    UdSetThreadPausingState(ThreadDebuggingDetails,
                            ProcessDebuggingDetails,
                            &PausePacket.InstructionBytesOnRip,
                            ExitInstructionLength);
 
    //
    // Everything was okay
    //
    return TRUE;
}

UdCheckForCommand()

BOOLEAN UdCheckForCommand	(	PROCESSOR_DEBUGGING_STATE *	DbgState,
		PUSERMODE_DEBUGGING_PROCESS_DETAILS	ProcessDebuggingDetail )

Check for the user-mode commands.

Parameters

DbgState	The state of the debugger on the current core
ProcessDebuggingDetail

Returns

BOOLEAN

{
    PUSERMODE_DEBUGGING_THREAD_DETAILS ThreadDebuggingDetails;
    BOOLEAN                            CommandFound = FALSE;
 
    ThreadDebuggingDetails = ThreadHolderGetProcessThreadDetailsByProcessIdAndThreadId(HANDLE_TO_UINT32(PsGetCurrentProcessId()),
                                                                                       HANDLE_TO_UINT32(PsGetCurrentThreadId()));
 
    if (!ThreadDebuggingDetails)
    {
        return FALSE;
    }
 
    //
    // If we reached here, the current thread is in debugger attached mechanism
    // now we check whether it's paused or not
    //
    if (!ThreadDebuggingDetails->IsPaused)
    {
        return FALSE;
    }
 
    //
    // Here, we're sure that this thread is looking for command, let
    // see if we find anything
    //
    for (SIZE_T i = 0; i < MAX_USER_ACTIONS_FOR_THREADS; i++)
    {
        if (ThreadDebuggingDetails->UdAction[i].ActionType != DEBUGGER_UD_COMMAND_ACTION_TYPE_NONE)
        {
            //
            // We found a command for this thread
            //
            CommandFound = TRUE;
 
            //
            // Perform the command
            //
            UdPerformCommand(DbgState,
                             ProcessDebuggingDetail,
                             ThreadDebuggingDetails,
                             ThreadDebuggingDetails->UdAction[i].ActionType,
                             ThreadDebuggingDetails->UdAction[i].OptionalParam1,
                             ThreadDebuggingDetails->UdAction[i].OptionalParam2,
                             ThreadDebuggingDetails->UdAction[i].OptionalParam3,
                             ThreadDebuggingDetails->UdAction[i].OptionalParam4);
 
            //
            // Remove the command
            //
            ThreadDebuggingDetails->UdAction[i].OptionalParam1 = (UINT64)NULL;
            ThreadDebuggingDetails->UdAction[i].OptionalParam2 = (UINT64)NULL;
            ThreadDebuggingDetails->UdAction[i].OptionalParam3 = (UINT64)NULL;
            ThreadDebuggingDetails->UdAction[i].OptionalParam4 = (UINT64)NULL;
 
            //
            // At last disable it
            //
            ThreadDebuggingDetails->UdAction[i].ActionType = DEBUGGER_UD_COMMAND_ACTION_TYPE_NONE;
 
            //
            // only one command at a time
            //
            break;
        }
    }
 
    //
    // Return whether we found a command or not
    //
    return CommandFound;
}

UdDispatchUsermodeCommands()

BOOLEAN UdDispatchUsermodeCommands	(	PDEBUGGER_UD_COMMAND_PACKET	ActionRequest,
		UINT32	ActionRequestInputLength,
		UINT32	ActionRequestOutputLength )

Dispatch the user-mode commands.

Parameters

ActionRequest
ActionRequestInputLength
ActionRequestOutputLength

Returns

BOOLEAN

{
    PUSERMODE_DEBUGGING_PROCESS_DETAILS ProcessDebuggingDetails;
    BOOLEAN                             Result;
 
    //
    // Find the thread debugging detail of the thread
    //
    ProcessDebuggingDetails = AttachingFindProcessDebuggingDetailsByToken(ActionRequest->ProcessDebuggingDetailToken);
 
    if (!ProcessDebuggingDetails)
    {
        //
        // Token not found!
        //
        ActionRequest->Result = DEBUGGER_ERROR_INVALID_THREAD_DEBUGGING_TOKEN;
 
        return FALSE;
    }
 
    //
    // Check if this command needs the action request to be waited for completion or not
    //
    if (ActionRequest->WaitForEventCompletion)
    {
        //
        // Set the command event buffer
        //
        g_UserDebuggerWaitingCommandBuffer = (PVOID)ActionRequest;
 
        //
        // Set the input command buffer length
        //
        g_UserDebuggerWaitingCommandInputBufferLength = ActionRequestInputLength;
 
        //
        // Set the output command buffer length
        //
        g_UserDebuggerWaitingCommandOutputBufferLength = ActionRequestOutputLength;
    }
 
    //
    // Apply the command to all threads or just one thread
    //
    Result = ThreadHolderApplyActionToPausedThreads(ProcessDebuggingDetails, ActionRequest);
 
    //
    // Check if we need to wait for the command event completion or not
    //
    if (Result && ActionRequest->WaitForEventCompletion)
    {
        //
        // Wait for the command to be completed
        //
        SynchronizationWaitForEvent(&g_UserDebuggerWaitingCommandEvent);
    }
 
    //
    // Since the command is applied successfully, we can set the result
    // Note that if the command contains another layer of optional buffers
    // the result of that optional buffer might be different than this result
    // this one is just for applying the command itself
    //
    if (Result)
    {
        //
        // If we are not waiting for the event completion, we should set the
        // result of the action request here as we successfully applied the command
        //
        ActionRequest->Result = DEBUGGER_OPERATION_WAS_SUCCESSFUL;
    }
    else
    {
        ActionRequest->Result = DEBUGGER_ERROR_UNABLE_TO_APPLY_COMMAND_TO_THE_TARGET_THREAD;
    }
 
    return Result;
}

UdHandleDebugEventsWhenUserDebuggerIsAttached()

BOOLEAN UdHandleDebugEventsWhenUserDebuggerIsAttached	(	PROCESSOR_DEBUGGING_STATE *	DbgState,
		BOOLEAN	TrapSetByDebugger )

Handles debug events when user-debugger is attached.

Parameters

DbgState	The state of the debugger on the current core
TrapSetByDebugger	Shows whether a trap set by debugger or not

Returns

BOOLEAN

{
    UNREFERENCED_PARAMETER(TrapSetByDebugger);
 
    if (UdHandleInstantBreak(DbgState,
                             DEBUGGEE_PAUSING_REASON_DEBUGGEE_GENERAL_DEBUG_BREAK,
                             NULL))
    {
        //
        // Handled by user debugger
        //
        return TRUE;
    }
    else
    {
        //
        // Not handled by user debugger
        //
        return FALSE;
    }
}

UdHandleInstantBreak()

BOOLEAN UdHandleInstantBreak	(	PROCESSOR_DEBUGGING_STATE *	DbgState,
		DEBUGGEE_PAUSING_REASON	Reason,
		PUSERMODE_DEBUGGING_PROCESS_DETAILS	ProcessDebuggingDetail )

Handle cases where we instant break is needed on the user debugger.

Parameters

DbgState	The state of the debugger on the current core
Reason	The reason of the pausing
ProcessDebuggingDetail

Returns

BOOLEAN

{
    //
    // Check if the process debugging details is available or not
    //
    if (ProcessDebuggingDetail == NULL)
    {
        //
        // If the process debugging detail is not available, we should
        // find it by the current process id
        //
        ProcessDebuggingDetail = AttachingFindProcessDebuggingDetailsByProcessId(HANDLE_TO_UINT32(PsGetCurrentProcessId()));
 
        if (ProcessDebuggingDetail == NULL)
        {
            //
            // If we reached here, it means that the process debugging detail is not found
            // so, we should return FALSE to indicate that we couldn't handle the instant break
            //
            return FALSE;
        }
    }
 
    //
    // Add the process to the watching list to be able to intercept the threads
    //
    if (AttachingConfigureInterceptingThreads(ProcessDebuggingDetail->Token, TRUE))
    {
        //
        // Since the adding it to the watching list will take effect from the next
        // CR3 vm-exit, we should change the state of the core to prevent further execution
        //
        ConfigureExecTrapApplyMbecConfiguratinFromKernelSide(DbgState->CoreId);
 
        //
        // Handling state through the user-mode debugger
        //
        return UdCheckAndHandleBreakpointsAndDebugBreaks(DbgState,
                                                         Reason,
                                                         NULL);
    }
 
    //
    // If we reached here, it means that we couldn't add the process to the
    //
    return FALSE;
}

UdInitializeUserDebugger()

BOOLEAN UdInitializeUserDebugger

(

)

initialize user debugger

this function should be called on vmx non-root

Returns

BOOLEAN

{
    //
    // Check if it's already initialized or not, we'll ignore it if it's
    // previously initialized
    //
    if (g_UserDebuggerState)
    {
        return TRUE;
    }
 
    //
    // Configure the exec-trap on all processors
    //
    if (!ConfigureInitializeExecTrapOnAllProcessors())
    {
        return FALSE;
    }
 
    //
    // Check if we have functions we need for attaching mechanism
    //
    if (g_PsGetProcessPeb == NULL || g_PsGetProcessWow64Process == NULL || g_ZwQueryInformationProcess == NULL)
    {
        LogError("Err, unable to find needed functions for user-debugger");
        // return FALSE;
    }
 
    //
    // Start the seed of user-mode debugging thread
    //
    g_SeedOfUserDebuggingDetails = DebuggerThreadDebuggingTagStartSeed;
 
    //
    // Initialize the thread debugging details list
    //
    InitializeListHead(&g_ProcessDebuggingDetailsListHead);
 
    //
    // Enable vm-exit on Hardware debug exceptions and breakpoints
    // so, intercept #DBs and #BP by changing exception bitmap (one core)
    //
    BroadcastEnableDbAndBpExitingAllCores();
 
    //
    // Request to allocate buffers for thread holder of threads
    //
    ThreadHolderAllocateThreadHoldingBuffers();
 
    //
    // Initialize command waiting event
    //
    SynchronizationInitializeEvent(&g_UserDebuggerWaitingCommandEvent);
 
    //
    // Indicate that the user debugger is active
    //
    g_UserDebuggerState = TRUE;
 
    return TRUE;
}

UdSendFormatsFunctionResult()

VOID UdSendFormatsFunctionResult

(

UINT64

Value

)

Send the result of formats command to the user debugger.

Parameters

Value

Returns

VOID

{
    g_UserDebuggerFormatsResultPacket.Result = DEBUGGER_OPERATION_WAS_SUCCESSFUL;
    g_UserDebuggerFormatsResultPacket.Value  = Value;
}

UdUninitializeUserDebugger()

VOID UdUninitializeUserDebugger

(

)

uninitialize user debugger

this function should be called on vmx non-root

Returns

VOID

{
    if (g_UserDebuggerState)
    {
        //
        // Indicate that the user debugger is not active
        //
        g_UserDebuggerState = FALSE;
 
        //
        // Uninitialize the exec-trap on all processors
        //
        ConfigureUninitializeExecTrapOnAllProcessors();
 
        //
        // Free and deallocate all the buffers (pools) relating to
        // thread debugging details
        //
        AttachingRemoveAndFreeAllProcessDebuggingDetails();
    }
}