ud.h File Reference

headers for user-mode debugging routines More...

Go to the source code of this file.

Classes
struct	_ACTIVE_DEBUGGING_PROCESS
	structures related to current thread debugging state More...

Macros
#define	DbgWaitForUserResponse(UserSyncObjectId)
#define	DbgReceivedUserResponse(UserSyncObjectId)

Typedefs
typedef struct _ACTIVE_DEBUGGING_PROCESS	ACTIVE_DEBUGGING_PROCESS
	structures related to current thread debugging state
typedef struct _ACTIVE_DEBUGGING_PROCESS *	PACTIVE_DEBUGGING_PROCESS

Functions
VOID	UdInitializeUserDebugger ()
	initialize user debugger
VOID	UdUninitializeUserDebugger ()
	uninitialize user debugger
VOID	UdRemoveActiveDebuggingProcess (BOOLEAN DontSwitchToNewProcess)
	Remove the current active debugging process (thread)
VOID	UdHandleUserDebuggerPausing (PDEBUGGEE_UD_PAUSED_PACKET PausePacket)
	Handle pause packets from user debugger.
VOID	UdContinueDebuggee (UINT64 ProcessDetailToken)
	Continue the target user debugger.
VOID	UdSendStepPacketToDebuggee (UINT64 ThreadDetailToken, UINT32 TargetThreadId, DEBUGGER_REMOTE_STEPPING_REQUEST StepType)
	Send stepping instructions packet to user debugger.
VOID	UdSetActiveDebuggingProcess (UINT64 DebuggingId, UINT32 ProcessId, UINT32 ThreadId, BOOLEAN Is32Bit, BOOLEAN IsPaused)
	set the current active debugging process (thread)
BOOLEAN	UdSetActiveDebuggingThreadByPidOrTid (UINT32 TargetPidOrTid, BOOLEAN IsTid)
	Set the active debugging thread by process id or thread id.
BOOLEAN	UdShowListActiveDebuggingProcessesAndThreads ()
	Show list of active debugging processes and threads.
BOOL	UdListProcessThreads (DWORD OwnerPID)
	List of threads by owner process id.
BOOLEAN	UdCheckThreadByProcessId (DWORD Pid, DWORD Tid)
	Check if a thread belongs to special process.
BOOLEAN	UdAttachToProcess (UINT32 TargetPid, const WCHAR *TargetFileAddress, const WCHAR *CommandLine, BOOLEAN RunCallbackAtTheFirstInstruction)
	Attach to target process.
BOOLEAN	UdKillProcess (UINT32 TargetPid)
	Kill the target process from kernel.
BOOLEAN	UdDetachProcess (UINT32 TargetPid, UINT64 ProcessDetailToken)
	Detach the target process.
BOOLEAN	UdPauseProcess (UINT64 ProcessDebuggingToken)
	Pause the target process.

Detailed Description

headers for user-mode debugging routines

Author

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

Version

0.1

Date

2021-12-28

Copyright

This project is released under the GNU Public License v3.

Macro Definition Documentation

DbgReceivedUserResponse

#define DbgReceivedUserResponse

(

UserSyncObjectId

)

Value:

    do                                                                 \
    {                                                                  \
        DEBUGGER_SYNCRONIZATION_EVENTS_STATE * SyncronizationObject =  \
            &g_UserSyncronizationObjectsHandleTable[UserSyncObjectId]; \
                                                                       \
        SyncronizationObject->IsOnWaitingState = FALSE;                \
        SetEvent(SyncronizationObject->EventHandle);                   \
    } while (FALSE);

#define DbgReceivedUserResponse(UserSyncObjectId)                      \
    do                                                                 \
    {                                                                  \
        DEBUGGER_SYNCRONIZATION_EVENTS_STATE * SyncronizationObject =  \
            &g_UserSyncronizationObjectsHandleTable[UserSyncObjectId]; \
                                                                       \
        SyncronizationObject->IsOnWaitingState = FALSE;                \
        SetEvent(SyncronizationObject->EventHandle);                   \
    } while (FALSE);

DbgWaitForUserResponse

#define DbgWaitForUserResponse

(

UserSyncObjectId

)

Value:

    do                                                                    \
    {                                                                     \
        DEBUGGER_SYNCRONIZATION_EVENTS_STATE * SyncronizationObject =     \
            &g_UserSyncronizationObjectsHandleTable[UserSyncObjectId];    \
                                                                          \
        SyncronizationObject->IsOnWaitingState = TRUE;                    \
        WaitForSingleObject(SyncronizationObject->EventHandle, INFINITE); \
    } while (FALSE);

#define DbgWaitForUserResponse(UserSyncObjectId)                          \
    do                                                                    \
    {                                                                     \
        DEBUGGER_SYNCRONIZATION_EVENTS_STATE * SyncronizationObject =     \
            &g_UserSyncronizationObjectsHandleTable[UserSyncObjectId];    \
                                                                          \
        SyncronizationObject->IsOnWaitingState = TRUE;                    \
        WaitForSingleObject(SyncronizationObject->EventHandle, INFINITE); \
    } while (FALSE);

Typedef Documentation

ACTIVE_DEBUGGING_PROCESS

typedef struct _ACTIVE_DEBUGGING_PROCESS ACTIVE_DEBUGGING_PROCESS

structures related to current thread debugging state

PACTIVE_DEBUGGING_PROCESS

typedef struct _ACTIVE_DEBUGGING_PROCESS * PACTIVE_DEBUGGING_PROCESS

Function Documentation

UdAttachToProcess()

BOOLEAN UdAttachToProcess	(	UINT32	TargetPid,
		const WCHAR *	TargetFileAddress,
		const WCHAR *	CommandLine,
		BOOLEAN	RunCallbackAtTheFirstInstruction )

Attach to target process.

this function will not check whether the process id is valid or not

Parameters

TargetPid
TargetFileAddress
CommandLine
RunCallbackAtTheFirstInstruction

Returns

BOOLEAN

{
    BOOLEAN                                  Status;
    ULONG                                    ReturnedLength;
    DEBUGGER_ATTACH_DETACH_USER_MODE_PROCESS AttachRequest = {0};
    PROCESS_INFORMATION                      ProcInfo      = {0};
 
    //
    // Check to initialize the user-debugger
    //
    UdInitializeUserDebugger();
 
    //
    // Check if debugger is loaded or not
    //
    AssertShowMessageReturnStmt(g_DeviceHandle, ASSERT_MESSAGE_DRIVER_NOT_LOADED, AssertReturnFalse);
 
    //
    // Check whether it's starting a new process or not
    //
    if (TargetFileAddress == NULL)
    {
        AttachRequest.IsStartingNewProcess = FALSE;
    }
    else
    {
        AttachRequest.IsStartingNewProcess = TRUE;
    }
 
    //
    // Set the state of the debugger for getting the callback at the first instruction
    //
    AttachRequest.CheckCallbackAtFirstInstruction = RunCallbackAtTheFirstInstruction;
 
    //
    // We wanna attach to a remote process
    //
    AttachRequest.Action = DEBUGGER_ATTACH_DETACH_USER_MODE_PROCESS_ACTION_ATTACH;
 
    if (AttachRequest.IsStartingNewProcess)
    {
        //
        // Check if file exists or not
        //
        if (!IsFileExistW(TargetFileAddress))
        {
            ShowMessages("err, unable to start (file not found)\n");
            return FALSE;
        }
 
        //
        // Start the process in suspended state
        //
        UdCreateSuspendedProcess(TargetFileAddress, CommandLine, &ProcInfo);
 
        //
        // Set the process id and thread id
        //
        AttachRequest.ProcessId = ProcInfo.dwProcessId;
        AttachRequest.ThreadId  = ProcInfo.dwThreadId;
    }
    else
    {
        //
        // Set the process id
        //
        AttachRequest.ProcessId = TargetPid;
    }
 
    //
    // Send the request to the kernel
    //
    Status = DeviceIoControl(
        g_DeviceHandle,                                  // Handle to device
        IOCTL_DEBUGGER_ATTACH_DETACH_USER_MODE_PROCESS,  // IO Control
                                                         // code
        &AttachRequest,                                  // Input Buffer to driver.
        SIZEOF_DEBUGGER_ATTACH_DETACH_USER_MODE_PROCESS, // Input buffer length
        &AttachRequest,                                  // Output Buffer from driver.
        SIZEOF_DEBUGGER_ATTACH_DETACH_USER_MODE_PROCESS, // Length of output
                                                         // buffer in bytes.
        &ReturnedLength,                                 // Bytes placed in buffer.
        NULL                                             // synchronous call
    );
 
    if (!Status)
    {
        ShowMessages("ioctl failed with code 0x%x\n", GetLastError());
        return FALSE;
    }
 
    //
    // Check if attaching was successful then we can set the attached to true
    //
    if (AttachRequest.Result == DEBUGGER_OPERATION_WAS_SUCCESSFUL)
    {
        if (!AttachRequest.IsStartingNewProcess)
        {
            //
            // it's a .attach command, no need for further action
            //
            ShowMessages("successfully attached to the target process!\n"
                         "please keep interacting with the process until all the "
                         "threads are intercepted and halted; whenever you execute "
                         "the first command, the thread interception will be stopped\n");
            return TRUE;
        }
 
        // ShowMessages("Base Address : %llx\n", AttachRequest.BaseAddressOfMainModule);
        // ShowMessages("Entrypoint Address : %llx\n", AttachRequest.EntrypoinOfMainModule);
 
        //
        // Resume the suspended process
        //
        if (ProcInfo.hThread != NULL64_ZERO)
        {
            ResumeThread(ProcInfo.hThread);
        }
        else
        {
            //
            // The handle of the target thread is empty
            //
            return FALSE;
        }
 
        //
        // *** Remove the hooks ***
        //
 
        while (TRUE)
        {
            //
            // Send the previous request with removing hook as the action
            //
            AttachRequest.Action = DEBUGGER_ATTACH_DETACH_USER_MODE_PROCESS_ACTION_REMOVE_HOOKS;
 
            //
            // Send the request to the kernel
            //
            Status = DeviceIoControl(
                g_DeviceHandle,                                  // Handle to device
                IOCTL_DEBUGGER_ATTACH_DETACH_USER_MODE_PROCESS,  // IO Control
                                                                 // code
                &AttachRequest,                                  // Input Buffer to driver.
                SIZEOF_DEBUGGER_ATTACH_DETACH_USER_MODE_PROCESS, // Input buffer length
                &AttachRequest,                                  // Output Buffer from driver.
                SIZEOF_DEBUGGER_ATTACH_DETACH_USER_MODE_PROCESS, // Length of output
                                                                 // buffer in bytes.
                &ReturnedLength,                                 // Bytes placed in buffer.
                NULL                                             // synchronous call
            );
 
            if (!Status)
            {
                ShowMessages("ioctl failed with code 0x%x\n", GetLastError());
                return FALSE;
            }
 
            //
            // Check whether the result of removing hooks was successful or we should
            // re-send the request
            //
            if (AttachRequest.Result == DEBUGGER_OPERATION_WAS_SUCCESSFUL)
            {
                //
                // The hook is remove successfully
                //
                break;
            }
            else if (AttachRequest.Result == DEBUGGER_ERROR_UNABLE_TO_REMOVE_HOOKS_ENTRYPOINT_NOT_REACHED)
            {
                //
                // Wait for a while until the Windows call the entrypoint
                //
                // ShowMessages("entrypoint is not reached, continue sending the request...\n");
 
                Sleep(1000);
                continue;
            }
            else
            {
                //
                // An error happened, we should not continue
                //
                ShowErrorMessage((UINT32)AttachRequest.Result);
                return FALSE;
            }
        }
 
        //
        // Store the process id and handle of the latest process
        //
        g_ProcessIdOfLatestStartingProcess = ProcInfo.dwProcessId;
 
        //
        // The operation of attaching was successful
        //
        return TRUE;
    }
    else
    {
        ShowErrorMessage((UINT32)AttachRequest.Result);
        return FALSE;
    }
 
    return FALSE;
}

UdCheckThreadByProcessId()

BOOLEAN UdCheckThreadByProcessId	(	DWORD	Pid,
		DWORD	Tid )

Check if a thread belongs to special process.

Parameters

Pid	Process id
Tid	Thread id

Returns

BOOLEAN if the thread belongs to process then return true; otherwise returns false

{
    HANDLE        ThreadSnap = INVALID_HANDLE_VALUE;
    THREADENTRY32 Te32;
    BOOLEAN       Result = FALSE;
 
    //
    // Take a snapshot of all running threads
    //
    ThreadSnap = CreateToolhelp32Snapshot(TH32CS_SNAPTHREAD, 0);
    if (ThreadSnap == INVALID_HANDLE_VALUE)
        return FALSE;
 
    //
    // Fill in the size of the structure before using it
    //
    Te32.dwSize = sizeof(THREADENTRY32);
 
    //
    // Retrieve information about the first thread and exit if unsuccessful
    //
    if (!Thread32First(ThreadSnap, &Te32))
    {
        UdPrintError();          // Show cause of failure
        CloseHandle(ThreadSnap); // Must clean up the snapshot object!
        return FALSE;
    }
 
    //
    // Now walk the thread list of the system, and display information
    // about each thread associated with the specified process
    //
    do
    {
        if (Te32.th32OwnerProcessID == Pid)
        {
            if (Te32.th32ThreadID == Tid)
            {
                //
                // The thread found in target process
                //
                Result = TRUE;
                break;
            }
        }
    } while (Thread32Next(ThreadSnap, &Te32));
 
    //
    // Don't forget to clean up the snapshot object
    //
    CloseHandle(ThreadSnap);
    return Result;
}

UdContinueDebuggee()

VOID UdContinueDebuggee

(

UINT64

ProcessDetailToken

)

Continue the target user debugger.

Parameters

ProcessDetailToken

Returns

VOID

{
    //
    // Send the 'continue' command
    //
    UdSendCommand(ProcessDetailToken,
                  NULL,
                  DEBUGGER_UD_COMMAND_ACTION_TYPE_CONTINUE,
                  TRUE,
                  NULL,
                  NULL,
                  NULL,
                  NULL);
}

UdDetachProcess()

BOOLEAN UdDetachProcess	(	UINT32	TargetPid,
		UINT64	ProcessDetailToken )

Detach the target process.

this function will not check whether the process id and thread id is valid or not

Parameters

TargetPid
ProcessDetailToken

Returns

BOOLEAN

{
    BOOLEAN                                  Status;
    ULONG                                    ReturnedLength;
    DEBUGGER_ATTACH_DETACH_USER_MODE_PROCESS DetachRequest = {0};
 
    //
    // Check if debugger is loaded or not
    //
    AssertShowMessageReturnStmt(g_DeviceHandle, ASSERT_MESSAGE_DRIVER_NOT_LOADED, AssertReturnFalse);
 
    //
    // Send the continue command to the target process as we
    // want to continue the debuggee process before detaching
    //
    UdContinueDebuggee(ProcessDetailToken);
 
    //
    // We wanna detach a process
    //
    DetachRequest.Action = DEBUGGER_ATTACH_DETACH_USER_MODE_PROCESS_ACTION_DETACH;
 
    //
    // Set the process id
    //
    DetachRequest.ProcessId = TargetPid;
 
    //
    // Send the request to the kernel
    //
    Status = DeviceIoControl(
        g_DeviceHandle,                                  // Handle to device
        IOCTL_DEBUGGER_ATTACH_DETACH_USER_MODE_PROCESS,  // IO Control
                                                         // code
        &DetachRequest,                                  // Input Buffer to driver.
        SIZEOF_DEBUGGER_ATTACH_DETACH_USER_MODE_PROCESS, // Input buffer length
        &DetachRequest,                                  // Output Buffer from driver.
        SIZEOF_DEBUGGER_ATTACH_DETACH_USER_MODE_PROCESS, // Length of output
                                                         // buffer in bytes.
        &ReturnedLength,                                 // Bytes placed in buffer.
        NULL                                             // synchronous call
    );
 
    if (!Status)
    {
        ShowMessages("ioctl failed with code 0x%x\n", GetLastError());
        return FALSE;
    }
 
    //
    // Check if detaching was successful or not
    //
    if (DetachRequest.Result == DEBUGGER_OPERATION_WAS_SUCCESSFUL)
    {
        //
        // Remove the current active debugging process (thread)
        //
        UdRemoveActiveDebuggingProcess(FALSE);
 
        //
        // The operation of attaching was successful
        //
        return TRUE;
    }
    else
    {
        ShowErrorMessage((UINT32)DetachRequest.Result);
        return FALSE;
    }
}

UdHandleUserDebuggerPausing()

VOID UdHandleUserDebuggerPausing

(

PDEBUGGEE_UD_PAUSED_PACKET

PausePacket

)

Handle pause packets from user debugger.

Parameters

PausePacket

Returns

VOID

{
    //
    // Set the current active debugging process (thread)
    //
    UdSetActiveDebuggingProcess(PausePacket->ProcessDebuggingToken,
                                PausePacket->ProcessId,
                                PausePacket->ThreadId,
                                PausePacket->Is32Bit,
                                TRUE);
 
    //
    // Perform extra tasks for pausing reasons
    //
    switch (PausePacket->PausingReason)
    {
    case DEBUGGEE_PAUSING_REASON_DEBUGGEE_STARTING_MODULE_LOADED:
 
        ShowMessages("the target module is loaded and a breakpoint is set to the entrypoint\n"
                     "press 'g' to reach to the entrypoint of the main module...\n");
 
        break;
    case DEBUGGEE_PAUSING_REASON_DEBUGGEE_GENERAL_THREAD_INTERCEPTED:
 
        ShowMessages("\nthread: %x from process: %x intercepted\n",
                     PausePacket->ThreadId,
                     PausePacket->ProcessId);
 
        break;
 
    default:
        break;
    }
 
    //
    // Check if the instruction is received completely or not
    //
    if (PausePacket->ReadInstructionLen != MAXIMUM_INSTR_SIZE)
    {
        //
        // We check if the disassembled buffer has greater size
        // than what is retrieved
        //
        if (HyperDbgLengthDisassemblerEngine(PausePacket->InstructionBytesOnRip,
                                             MAXIMUM_INSTR_SIZE,
                                             PausePacket->Is32Bit ? FALSE : TRUE) > PausePacket->ReadInstructionLen)
        {
            ShowMessages("oOh, no! there might be a misinterpretation in disassembling the current instruction\n");
        }
    }
 
    if (!PausePacket->Is32Bit)
    {
        //
        // Show diassembles
        //
        HyperDbgDisassembler64(PausePacket->InstructionBytesOnRip,
                               PausePacket->Rip,
                               MAXIMUM_INSTR_SIZE,
                               1,
                               TRUE,
                               (PRFLAGS)&PausePacket->Rflags);
    }
    else
    {
        //
        // Show diassembles
        //
        HyperDbgDisassembler32(PausePacket->InstructionBytesOnRip,
                               PausePacket->Rip,
                               MAXIMUM_INSTR_SIZE,
                               1,
                               TRUE,
                               (PRFLAGS)&PausePacket->Rflags);
    }
 
    //
    // Unpause the user debugger to get commands
    //
    if (g_UserSyncronizationObjectsHandleTable
            [DEBUGGER_SYNCRONIZATION_OBJECT_USER_DEBUGGER_IS_DEBUGGER_RUNNING]
                .IsOnWaitingState == TRUE)
    {
        DbgReceivedUserResponse(DEBUGGER_SYNCRONIZATION_OBJECT_USER_DEBUGGER_IS_DEBUGGER_RUNNING);
    }
}

UdInitializeUserDebugger()

VOID UdInitializeUserDebugger

(

)

initialize user debugger

this function should be called on vmx non-root

Returns

BOOLEAN

initialize user debugger

Returns

VOID

{
    //
    // Check if it's already initialized or not, we'll ignore it if it's
    // previously initialized
    //
    if (g_UserDebuggerState)
    {
        return TRUE;
    }
 
    //
    // 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();
 
    //
    // Indicate that the user debugger is active
    //
    g_UserDebuggerState = TRUE;
 
    return TRUE;
}

UdKillProcess()

BOOLEAN UdKillProcess

(

UINT32

TargetPid

)

Kill the target process from kernel.

this function will not check whether the process id and thread id is valid or not

Parameters

TargetPid

Returns

BOOLEAN

{
    BOOLEAN                                  Status;
    ULONG                                    ReturnedLength;
    DEBUGGER_ATTACH_DETACH_USER_MODE_PROCESS KillRequest = {0};
 
    //
    // Check if debugger is loaded or not
    //
    AssertShowMessageReturnStmt(g_DeviceHandle, ASSERT_MESSAGE_DRIVER_NOT_LOADED, AssertReturnFalse);
 
    //
    // Check if the process exists
    //
    if (!UdDoesProcessExistByPid(TargetPid))
    {
        return FALSE;
    }
 
    //
    // First, we try to kill the process in user-mode, if not successful,
    // we try to kill it from kernel-mode
    //
    UdTerminateProcessByPid(TargetPid);
 
    //
    // Check again to see if the process exists
    //
    if (!UdDoesProcessExistByPid(TargetPid))
    {
        return TRUE;
    }
 
    //
    // We wanna kill a process
    //
    KillRequest.Action = DEBUGGER_ATTACH_DETACH_USER_MODE_PROCESS_ACTION_KILL_PROCESS;
 
    //
    // Set the process id
    //
    KillRequest.ProcessId = TargetPid;
 
    //
    // Send the request to the kernel
    //
    Status = DeviceIoControl(
        g_DeviceHandle,                                  // Handle to device
        IOCTL_DEBUGGER_ATTACH_DETACH_USER_MODE_PROCESS,  // IO Control
                                                         // code
        &KillRequest,                                    // Input Buffer to driver.
        SIZEOF_DEBUGGER_ATTACH_DETACH_USER_MODE_PROCESS, // Input buffer length
        &KillRequest,                                    // Output Buffer from driver.
        SIZEOF_DEBUGGER_ATTACH_DETACH_USER_MODE_PROCESS, // Length of output
                                                         // buffer in bytes.
        &ReturnedLength,                                 // Bytes placed in buffer.
        NULL                                             // synchronous call
    );
 
    if (!Status)
    {
        ShowMessages("ioctl failed with code 0x%x\n", GetLastError());
        return FALSE;
    }
 
    //
    // Check if killing was successful or not
    //
    if (KillRequest.Result == DEBUGGER_OPERATION_WAS_SUCCESSFUL)
    {
        //
        // Remove the current active debugging process (thread)
        //
        UdRemoveActiveDebuggingProcess(FALSE);
 
        //
        // The operation of attaching was successful
        //
        return TRUE;
    }
    else
    {
        ShowErrorMessage((UINT32)KillRequest.Result);
        return FALSE;
    }
}

UdListProcessThreads()

BOOL UdListProcessThreads

(

DWORD

OwnerPID

)

List of threads by owner process id.

Parameters

OwnerPID

Returns

BOOL if there was an error then returns false, otherwise return true

{
    HANDLE        ThreadSnap = INVALID_HANDLE_VALUE;
    THREADENTRY32 Te32;
 
    //
    // Take a snapshot of all running threads
    //
    ThreadSnap = CreateToolhelp32Snapshot(TH32CS_SNAPTHREAD, 0);
    if (ThreadSnap == INVALID_HANDLE_VALUE)
        return FALSE;
 
    //
    // Fill in the size of the structure before using it
    //
    Te32.dwSize = sizeof(THREADENTRY32);
 
    //
    // Retrieve information about the first thread and exit if unsuccessful
    //
    if (!Thread32First(ThreadSnap, &Te32))
    {
        UdPrintError();          // Show cause of failure
        CloseHandle(ThreadSnap); // Must clean up the snapshot object!
        return FALSE;
    }
    ShowMessages("\nThread's of pid\t= 0x%08X\n", OwnerPID);
 
    //
    // Now walk the thread list of the system, and display information
    // about each thread associated with the specified process
    //
    do
    {
        if (Te32.th32OwnerProcessID == OwnerPID)
        {
            ShowMessages("\n     Thread Id\t= 0x%08X", Te32.th32ThreadID);
            // ShowMessages("\n     base priority  = %x", Te32.tpBasePri);
            // ShowMessages("\n     delta priority = %x", Te32.tpDeltaPri);
        }
    } while (Thread32Next(ThreadSnap, &Te32));
 
    ShowMessages("\n");
 
    //
    // Don't forget to clean up the snapshot object
    //
    CloseHandle(ThreadSnap);
    return TRUE;
}

UdPauseProcess()

BOOLEAN UdPauseProcess

(

UINT64

ProcessDebuggingToken

)

Pause the target process.

Parameters

ProcessDebuggingToken

Returns

BOOLEAN

{
    BOOLEAN                                  Status;
    ULONG                                    ReturnedLength;
    DEBUGGER_ATTACH_DETACH_USER_MODE_PROCESS PauseRequest = {0};
 
    //
    // Check if debugger is loaded or not
    //
    AssertShowMessageReturnStmt(g_DeviceHandle, ASSERT_MESSAGE_DRIVER_NOT_LOADED, AssertReturnFalse);
 
    //
    // We wanna pause a process
    //
    PauseRequest.Action = DEBUGGER_ATTACH_DETACH_USER_MODE_PROCESS_ACTION_PAUSE_PROCESS;
 
    //
    // Set the process debugging token
    //
    PauseRequest.Token = ProcessDebuggingToken;
 
    //
    // Send the request to the kernel
    //
    Status = DeviceIoControl(
        g_DeviceHandle,                                  // Handle to device
        IOCTL_DEBUGGER_ATTACH_DETACH_USER_MODE_PROCESS,  // IO Control
                                                         // code
        &PauseRequest,                                   // Input Buffer to driver.
        SIZEOF_DEBUGGER_ATTACH_DETACH_USER_MODE_PROCESS, // Input buffer length
        &PauseRequest,                                   // Output Buffer from driver.
        SIZEOF_DEBUGGER_ATTACH_DETACH_USER_MODE_PROCESS, // Length of output
                                                         // buffer in bytes.
        &ReturnedLength,                                 // Bytes placed in buffer.
        NULL                                             // synchronous call
    );
 
    if (!Status)
    {
        ShowMessages("ioctl failed with code 0x%x\n", GetLastError());
        return FALSE;
    }
 
    //
    // Check if killing was successful or not
    //
    if (PauseRequest.Result == DEBUGGER_OPERATION_WAS_SUCCESSFUL)
    {
        //
        // The operation of attaching was successful
        //
        return TRUE;
    }
    else
    {
        ShowErrorMessage((UINT32)PauseRequest.Result);
        return FALSE;
    }
}

UdRemoveActiveDebuggingProcess()

VOID UdRemoveActiveDebuggingProcess

(

BOOLEAN

DontSwitchToNewProcess

)

Remove the current active debugging process (thread)

Parameters

DontSwitchToNewProcess

Returns

VOID

{
    //
    // Activate the debugging
    //
    g_ActiveProcessDebuggingState.IsActive = FALSE;
}

UdSendStepPacketToDebuggee()

VOID UdSendStepPacketToDebuggee	(	UINT64	ProcessDetailToken,
		UINT32	TargetThreadId,
		DEBUGGER_REMOTE_STEPPING_REQUEST	StepType )

Send stepping instructions packet to user debugger.

Parameters

ProcessDetailToken
TargetThreadId
StepType

Returns

VOID

{
    //
    // Wait until the result of user-input received
    //
    g_UserSyncronizationObjectsHandleTable
        [DEBUGGER_SYNCRONIZATION_OBJECT_USER_DEBUGGER_IS_DEBUGGER_RUNNING]
            .IsOnWaitingState = TRUE;
 
    //
    // Send the 'continue' command
    //
    UdSendCommand(ProcessDetailToken,
                  TargetThreadId,
                  DEBUGGER_UD_COMMAND_ACTION_TYPE_REGULAR_STEP,
                  FALSE,
                  StepType,
                  NULL,
                  NULL,
                  NULL);
 
    WaitForSingleObject(
        g_UserSyncronizationObjectsHandleTable
            [DEBUGGER_SYNCRONIZATION_OBJECT_USER_DEBUGGER_IS_DEBUGGER_RUNNING]
                .EventHandle,
        INFINITE);
}

UdSetActiveDebuggingProcess()

VOID UdSetActiveDebuggingProcess	(	UINT64	DebuggingId,
		UINT32	ProcessId,
		UINT32	ThreadId,
		BOOLEAN	Is32Bit,
		BOOLEAN	IsPaused )

set the current active debugging process (thread)

Parameters

DebuggingId
ProcessId
ThreadId
Is32Bit

Returns

VOID

{
    g_ActiveProcessDebuggingState.ProcessId             = ProcessId;
    g_ActiveProcessDebuggingState.ThreadId              = ThreadId;
    g_ActiveProcessDebuggingState.Is32Bit               = Is32Bit;
    g_ActiveProcessDebuggingState.ProcessDebuggingToken = DebuggingId;
 
    //
    // Set pausing state
    //
    g_ActiveProcessDebuggingState.IsPaused = IsPaused;
 
    //
    // Activate the debugging
    //
    g_ActiveProcessDebuggingState.IsActive = TRUE;
}

UdSetActiveDebuggingThreadByPidOrTid()

BOOLEAN UdSetActiveDebuggingThreadByPidOrTid	(	UINT32	TargetPidOrTid,
		BOOLEAN	IsTid )

Set the active debugging thread by process id or thread id.

Parameters

TargetPidOrTid
IsTid

Returns

BOOLEAN

{
    BOOLEAN                                  Status;
    ULONG                                    ReturnedLength;
    DEBUGGER_ATTACH_DETACH_USER_MODE_PROCESS SwitchRequest = {0};
 
    //
    // Check if debugger is loaded or not
    //
    AssertShowMessageReturnStmt(g_DeviceHandle, ASSERT_MESSAGE_DRIVER_NOT_LOADED, AssertReturnFalse);
 
    //
    // We wanna switch to a process or thread
    //
    SwitchRequest.Action = DEBUGGER_ATTACH_DETACH_USER_MODE_PROCESS_ACTION_SWITCH_BY_PROCESS_OR_THREAD;
 
    //
    // Set the process id or thread id
    //
    if (IsTid)
    {
        SwitchRequest.ThreadId = TargetPidOrTid;
    }
    else
    {
        SwitchRequest.ProcessId = TargetPidOrTid;
    }
 
    //
    // Send the request to the kernel
    //
    Status = DeviceIoControl(
        g_DeviceHandle,                                  // Handle to device
        IOCTL_DEBUGGER_ATTACH_DETACH_USER_MODE_PROCESS,  // IO Control
                                                         // code
        &SwitchRequest,                                  // Input Buffer to driver.
        SIZEOF_DEBUGGER_ATTACH_DETACH_USER_MODE_PROCESS, // Input buffer length
        &SwitchRequest,                                  // Output Buffer from driver.
        SIZEOF_DEBUGGER_ATTACH_DETACH_USER_MODE_PROCESS, // Length of output
                                                         // buffer in bytes.
        &ReturnedLength,                                 // Bytes placed in buffer.
        NULL                                             // synchronous call
    );
 
    if (!Status)
    {
        ShowMessages("ioctl failed with code 0x%x\n", GetLastError());
        return FALSE;
    }
 
    //
    // Check if killing was successful or not
    //
    if (SwitchRequest.Result == DEBUGGER_OPERATION_WAS_SUCCESSFUL)
    {
        //
        // Set the current active debugging process (thread)
        //
        UdSetActiveDebuggingProcess(SwitchRequest.Token,
                                    SwitchRequest.ProcessId,
                                    SwitchRequest.ThreadId,
                                    SwitchRequest.Is32Bit,
                                    SwitchRequest.IsPaused);
 
        //
        // The operation of attaching was successful
        //
        return TRUE;
    }
    else
    {
        ShowErrorMessage((UINT32)SwitchRequest.Result);
        return FALSE;
    }
}

UdShowListActiveDebuggingProcessesAndThreads()

BOOLEAN UdShowListActiveDebuggingProcessesAndThreads

(

)

Show list of active debugging processes and threads.

Returns

BOOLEAN

{
    BOOLEAN                                              Status;
    BOOLEAN                                              CheckCurrentProcessOrThread;
    ULONG                                                ReturnedLength;
    DEBUGGER_ATTACH_DETACH_USER_MODE_PROCESS             QueryCountOfActiveThreadsRequest        = {0};
    USERMODE_DEBUGGING_THREAD_OR_PROCESS_STATE_DETAILS * AddressOfThreadsAndProcessDetails       = NULL;
    UINT32                                               SizeOfBufferForThreadsAndProcessDetails = NULL;
 
    //
    // Check if debugger is loaded or not
    //
    AssertShowMessageReturnStmt(g_DeviceHandle, ASSERT_MESSAGE_DRIVER_NOT_LOADED, AssertReturnFalse);
 
    //
    // Check if user debugger is active or not
    //
    if (!g_IsUserDebuggerInitialized)
    {
        ShowMessages("user debugger is not initialized. Did you use the '.attach' or the '.start' "
                     "command before?\n");
        return FALSE;
    }
 
    //
    // We wanna query the count of active debugging threads
    //
    QueryCountOfActiveThreadsRequest.Action = DEBUGGER_ATTACH_DETACH_USER_MODE_PROCESS_ACTION_QUERY_COUNT_OF_ACTIVE_DEBUGGING_THREADS;
 
    //
    // Send the request to the kernel
    //
    Status = DeviceIoControl(
        g_DeviceHandle,                                  // Handle to device
        IOCTL_DEBUGGER_ATTACH_DETACH_USER_MODE_PROCESS,  // IO Control
                                                         // code
        &QueryCountOfActiveThreadsRequest,               // Input Buffer to driver.
        SIZEOF_DEBUGGER_ATTACH_DETACH_USER_MODE_PROCESS, // Input buffer length
        &QueryCountOfActiveThreadsRequest,               // Output Buffer from driver.
        SIZEOF_DEBUGGER_ATTACH_DETACH_USER_MODE_PROCESS, // Length of output
                                                         // buffer in bytes.
        &ReturnedLength,                                 // Bytes placed in buffer.
        NULL                                             // synchronous call
    );
 
    if (!Status)
    {
        ShowMessages("ioctl failed with code 0x%x\n", GetLastError());
        return FALSE;
    }
 
    //
    // Query was successful
    //
    if (QueryCountOfActiveThreadsRequest.Result == DEBUGGER_OPERATION_WAS_SUCCESSFUL)
    {
        if (QueryCountOfActiveThreadsRequest.CountOfActiveDebuggingThreadsAndProcesses == 0)
        {
            ShowMessages("no active debugging threads!\n");
        }
        else
        {
            //
            // *** We should send another IOCTL and get the list of threads ***
            //
 
            //
            // Allocate the storage for the pull details of threads and processes
            //
            SizeOfBufferForThreadsAndProcessDetails =
                QueryCountOfActiveThreadsRequest.CountOfActiveDebuggingThreadsAndProcesses * SIZEOF_USERMODE_DEBUGGING_THREAD_OR_PROCESS_STATE_DETAILS;
 
            AddressOfThreadsAndProcessDetails = (USERMODE_DEBUGGING_THREAD_OR_PROCESS_STATE_DETAILS *)malloc(SizeOfBufferForThreadsAndProcessDetails);
 
            if (AddressOfThreadsAndProcessDetails == NULL64_ZERO)
            {
                ShowMessages("insufficient space\n");
                return FALSE;
            }
 
            RtlZeroMemory(AddressOfThreadsAndProcessDetails, SizeOfBufferForThreadsAndProcessDetails);
 
            //
            // Send the request to the kernel
            //
            Status = DeviceIoControl(
                g_DeviceHandle,                                   // Handle to device
                IOCTL_GET_DETAIL_OF_ACTIVE_THREADS_AND_PROCESSES, // IO Control
                                                                  // code
                NULL,                                             // Input Buffer to driver.
                0,                                                // Input buffer length.
                AddressOfThreadsAndProcessDetails,                // Output Buffer from driver.
                SizeOfBufferForThreadsAndProcessDetails,          // Length of output buffer in bytes.
                &ReturnedLength,                                  // Bytes placed in buffer.
                NULL                                              // synchronous call
            );
 
            if (!Status)
            {
                ShowMessages("ioctl failed with code 0x%x\n", GetLastError());
                return FALSE;
            }
 
            //
            // Show list of active processes and threads
            //
            for (size_t i = 0; i < QueryCountOfActiveThreadsRequest.CountOfActiveDebuggingThreadsAndProcesses; i++)
            {
                if (AddressOfThreadsAndProcessDetails[i].IsProcess)
                {
                    CheckCurrentProcessOrThread = FALSE;
 
                    if (g_ActiveProcessDebuggingState.IsActive && AddressOfThreadsAndProcessDetails[i].ProcessId == g_ActiveProcessDebuggingState.ProcessId)
                    {
                        CheckCurrentProcessOrThread = TRUE;
                    }
 
                    ShowMessages("%s%04x (process)\n",
                                 CheckCurrentProcessOrThread ? "*" : "",
                                 AddressOfThreadsAndProcessDetails[i].ProcessId);
                }
                else
                {
                    CheckCurrentProcessOrThread = FALSE;
 
                    if (g_ActiveProcessDebuggingState.IsActive && AddressOfThreadsAndProcessDetails[i].ThreadId == g_ActiveProcessDebuggingState.ThreadId)
                    {
                        CheckCurrentProcessOrThread = TRUE;
                    }
                    ShowMessages("\t%s %04x (thread)\n",
                                 CheckCurrentProcessOrThread ? "->" : "  ",
                                 AddressOfThreadsAndProcessDetails[i].ThreadId);
                }
            }
        }
 
        //
        // The operation of attaching was successful
        //
        return TRUE;
    }
    else
    {
        ShowErrorMessage((UINT32)QueryCountOfActiveThreadsRequest.Result);
        return FALSE;
    }
}

UdUninitializeUserDebugger()

VOID UdUninitializeUserDebugger

(

)

uninitialize user debugger

this function should be called on vmx non-root

Returns

VOID

uninitialize user debugger

Returns

VOID

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