Attaching.h File Reference

Header for attaching and detaching for debugging user-mode processes. More...

Go to the source code of this file.

Macros
#define	MAX_USER_ACTIONS_FOR_THREADS   3
	Maximum actions in paused threads storage.
#define	MAX_THREADS_IN_A_PROCESS_HOLDER   100
	Maximum threads that a process thread holder might have.

Functions
BOOLEAN	AttachingInitialize ()
	Initialize the attaching mechanism.
BOOLEAN	AttachingCheckThreadInterceptionWithUserDebugger (UINT32 CoreId)
	Check thread interceptions with user-mode debugger.
BOOLEAN	AttachingConfigureInterceptingThreads (UINT64 ProcessDebuggingToken, BOOLEAN Enable)
	Enable or disable the thread intercepting phase.
VOID	AttachingTargetProcess (PDEBUGGER_ATTACH_DETACH_USER_MODE_PROCESS Request)
	Dispatch and perform attaching tasks.
VOID	AttachingHandleEntrypointInterception (PROCESSOR_DEBUGGING_STATE *DbgState)
	Handle the interception of finding the entrypoint on attaching to user-mode process.
VOID	AttachingRemoveAndFreeAllProcessDebuggingDetails ()
	Remove and deallocate all thread debuggig details.
PUSERMODE_DEBUGGING_PROCESS_DETAILS	AttachingFindProcessDebuggingDetailsByToken (UINT64 Token)
	Find user-mode debugging details for threads by token.
PUSERMODE_DEBUGGING_PROCESS_DETAILS	AttachingFindProcessDebuggingDetailsByProcessId (UINT32 ProcessId)
	Find user-mode debugging details for threads by process Id.
BOOLEAN	AttachingQueryDetailsOfActiveDebuggingThreadsAndProcesses (PVOID BufferToStoreDetails, UINT32 BufferSize)
	Query details of active debugging threads.
BOOLEAN	AttachingCheckUnhandledEptViolation (UINT32 CoreId, UINT64 ViolationQualification, UINT64 GuestPhysicalAddr)
	handling unhandled EPT violations
BOOLEAN	AttachingReachedToValidLoadedModule (PROCESSOR_DEBUGGING_STATE *DbgState, PUSERMODE_DEBUGGING_PROCESS_DETAILS ProcessDebuggingDetail)
	Handle cases where we reached to the valid loaded module The main module should be loaded once we reach to this function.

Detailed Description

Header for attaching and detaching for debugging user-mode processes.

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

MAX_THREADS_IN_A_PROCESS_HOLDER

#define MAX_THREADS_IN_A_PROCESS_HOLDER   100

Maximum threads that a process thread holder might have.

MAX_USER_ACTIONS_FOR_THREADS

#define MAX_USER_ACTIONS_FOR_THREADS   3

Maximum actions in paused threads storage.

Function Documentation

AttachingCheckThreadInterceptionWithUserDebugger()

BOOLEAN AttachingCheckThreadInterceptionWithUserDebugger

(

UINT32

CoreId

)

Check thread interceptions with user-mode debugger.

Parameters

CoreId

Returns

BOOLEAN if TRUE show that the thread interceptin is handled otherwise FALSE

{
    PROCESSOR_DEBUGGING_STATE *         DbgState = &g_DbgState[CoreId];
    PUSERMODE_DEBUGGING_PROCESS_DETAILS ProcessDebuggingDetail;
 
    //
    // Check whether user-debugger is initialized or not
    //
    if (!g_UserDebuggerState)
    {
        return FALSE;
    }
 
    ProcessDebuggingDetail = AttachingFindProcessDebuggingDetailsByProcessId(HANDLE_TO_UINT32(PsGetCurrentProcessId()));
 
    //
    // Check if the process debugging detail is found
    //
    if (!ProcessDebuggingDetail)
    {
        //
        // not related to user debugger
        //
        return FALSE;
    }
 
    //
    // Check if thread is in the intercepting phase
    //
    if (ProcessDebuggingDetail->IsOnThreadInterceptingPhase)
    {
        //
        // Handling state through the user-mode debugger
        //
        if (UdCheckAndHandleBreakpointsAndDebugBreaks(DbgState,
                                                      DEBUGGEE_PAUSING_REASON_DEBUGGEE_GENERAL_THREAD_INTERCEPTED,
                                                      NULL))
        {
            //
            // Check for possible commands that need to be executed
            //
            UdCheckForCommand(DbgState, ProcessDebuggingDetail);
 
            return TRUE;
        }
    }
 
    //
    // this thread is not in intercepting phase
    //
    return FALSE;
}

AttachingCheckUnhandledEptViolation()

BOOLEAN AttachingCheckUnhandledEptViolation	(	UINT32	CoreId,
		UINT64	ViolationQualification,
		UINT64	GuestPhysicalAddr )

handling unhandled EPT violations

Parameters

CoreId
ViolationQualification
GuestPhysicalAddr

Returns

BOOLEAN

{
    UNREFERENCED_PARAMETER(CoreId);
    UNREFERENCED_PARAMETER(ViolationQualification);
    UNREFERENCED_PARAMETER(GuestPhysicalAddr);
 
    //
    // Not handled here
    //
    return FALSE;
}

AttachingConfigureInterceptingThreads()

BOOLEAN AttachingConfigureInterceptingThreads	(	UINT64	ProcessDebuggingToken,
		BOOLEAN	Enable )

Enable or disable the thread intercepting phase.

this function should be called in vmx non-root

Parameters

ProcessDebuggingToken
Enable

Returns

BOOLEAN

{
    PUSERMODE_DEBUGGING_PROCESS_DETAILS ProcessDebuggingDetail;
 
    //
    // Get the current process debugging detail
    //
    ProcessDebuggingDetail = AttachingFindProcessDebuggingDetailsByToken(ProcessDebuggingToken);
 
    if (!ProcessDebuggingDetail)
    {
        return FALSE;
    }
 
    //
    // If the thread is already in intercepting phase, we should return,
    //
    if (Enable && ProcessDebuggingDetail->IsOnThreadInterceptingPhase)
    {
        LogError("Err, thread is already in intercepting phase");
        return FALSE;
    }
 
    //
    // We're or we're not in thread intercepting phase now
    //
    ProcessDebuggingDetail->IsOnThreadInterceptingPhase = Enable;
 
    //
    // Intercepting threads is enabled
    //
    if (Enable)
    {
        //
        // Add the process to the watching list to be able to intercept the threads
        //
        ConfigureExecTrapAddProcessToWatchingList(ProcessDebuggingDetail->ProcessId);
    }
    else
    {
        //
        // Unpause the threads of the target process
        //
        ThreadHolderUnpauseAllThreadsInProcess(ProcessDebuggingDetail);
 
        //
        // Remove the process from the watching list
        //
        ConfigureExecTrapRemoveProcessFromWatchingList(ProcessDebuggingDetail->ProcessId);
    }
 
    return TRUE;
}

AttachingFindProcessDebuggingDetailsByProcessId()

PUSERMODE_DEBUGGING_PROCESS_DETAILS AttachingFindProcessDebuggingDetailsByProcessId

(

UINT32

ProcessId

)

Find user-mode debugging details for threads by process Id.

Parameters

ProcessId

Returns

PUSERMODE_DEBUGGING_PROCESS_DETAILS

{
    LIST_FOR_EACH_LINK(g_ProcessDebuggingDetailsListHead, USERMODE_DEBUGGING_PROCESS_DETAILS, AttachedProcessList, ProcessDebuggingDetails)
    {
        //
        // Check if we found the target thread and if it's enabled
        //
        if (ProcessDebuggingDetails->ProcessId == ProcessId && ProcessDebuggingDetails->Enabled)
        {
            return ProcessDebuggingDetails;
        }
    }
 
    return NULL;
}

AttachingFindProcessDebuggingDetailsByToken()

PUSERMODE_DEBUGGING_PROCESS_DETAILS AttachingFindProcessDebuggingDetailsByToken

(

UINT64

Token

)

Find user-mode debugging details for threads by token.

Parameters

Token

Returns

PUSERMODE_DEBUGGING_PROCESS_DETAILS

{
    LIST_FOR_EACH_LINK(g_ProcessDebuggingDetailsListHead, USERMODE_DEBUGGING_PROCESS_DETAILS, AttachedProcessList, ProcessDebuggingDetails)
    {
        //
        // Check if we found the target thread and if it's enabled
        //
        if (ProcessDebuggingDetails->Token == Token && ProcessDebuggingDetails->Enabled)
        {
            return ProcessDebuggingDetails;
        }
    }
 
    return NULL;
}

AttachingHandleEntrypointInterception()

VOID AttachingHandleEntrypointInterception

(

PROCESSOR_DEBUGGING_STATE *

DbgState

)

Handle the interception of finding the entrypoint on attaching to user-mode process.

Parameters

DbgState

The state of the debugger on the current core

Returns

VOID

{
    PUSERMODE_DEBUGGING_PROCESS_DETAILS ProcessDebuggingDetail = NULL;
    PAGE_FAULT_EXCEPTION                PageFaultErrorCode     = {0};
 
    //
    // Not increment the RIP register as no instruction is intended to go
    //
    VmFuncSuppressRipIncrement(DbgState->CoreId);
 
    ProcessDebuggingDetail = AttachingFindProcessDebuggingDetailsByProcessId(HANDLE_TO_UINT32(PsGetCurrentProcessId()));
 
    //
    // Check to only break on the target process id and thread id and when
    // the entrypoint is not called, if the thread debugging detail is found
    //
    if (ProcessDebuggingDetail != NULL)
    {
        if (g_IsWaitingForUserModeProcessEntryToBeCalled)
        {
            //
            // Show a message that we reached to the entrypoint
            //
            // Log("Reached to the main module entrypoint (%016llx)\n", VmFuncGetLastVmexitRip(DbgState->CoreId));
 
            //
            // Not waiting for these event anymore
            //
            g_IsWaitingForUserModeProcessEntryToBeCalled = FALSE;
 
            //
            // Whenever Windows calls the start entrypoint of the target PE, initially,
            // the module is not loaded in the memory, thus a page-fault will happen and
            // the page-fault handler will bring the module content to the memory and after
            // that, the start entrypoint of PE is called again
            // It's not possible for us to handle everything here without checking for the
            // possible page-fault, it is because the first instruction is not available to be
            // read from the memory, thus, it shows a wrong instruction and the user might not
            // use the instrumentation step-in from the start up of the entrypoint.
            // Because if the user uses the instrumentation step-in command then it should go
            // the page-fault handler routine in the kernel and it's not what the user expects
            // we inject a #PF here and let the Windows handle the page-fault. Meanwhile, we
            // set the hardware debug breakpoint again at the start of the entrypoint, so, the
            // next time that the instruction is about to be fetched, a vm-exit happens as a
            // result of intercepting #DBs
            // In some cases, there is no need to inject #PF to the guest. One example is when
            // the target page is already available in the memory like the same process is also
            // open in the debuggee. In these cases, we handle the break directly without injecting
            // any page-fault
            //
 
            if (!CheckAccessValidityAndSafety(ProcessDebuggingDetail->EntrypointOfMainModule, sizeof(CHAR)))
            {
                // LogInfo("Injecting #PF for entrypoint at : %llx", ProcessDebuggingDetail->EntrypointOfMainModule);
 
                //
                // We're waiting for this pointer to be called again after handling page-fault
                //
                g_IsWaitingForReturnAndRunFromPageFault = TRUE;
 
                //
                // Create page-fault error code (user, fetch #PF)
                //
                PageFaultErrorCode.AsUInt = 0x14;
 
                //
                // Inject the page-fault
                //
                VmFuncEventInjectPageFaultWithCr2(DbgState->CoreId,
                                                  ProcessDebuggingDetail->EntrypointOfMainModule,
                                                  PageFaultErrorCode.AsUInt);
 
                //
                // Also, set the RFLAGS.TF to intercept the process (thread) again after inject #PF
                //
                VmFuncSetRflagTrapFlag(TRUE);
 
                //
                // Indicate that we should set the trap flag to the FALSE next time on
                // the same process/thread
                //
                if (!BreakpointRestoreTheTrapFlagOnceTriggered(HANDLE_TO_UINT32(PsGetCurrentProcessId()), HANDLE_TO_UINT32(PsGetCurrentThreadId())))
                {
                    LogWarning("Warning, it is currently not possible to add the current process/thread to the list of processes "
                               "where the trap flag should be masked. Please ensure that you manually unset the trap flag");
                }
            }
            else
            {
                //
                // Address is valid, probably the module is previously loaded
                // or another process with same image is currently running
                // Thus, there is no need to inject #PF, we'll handle it in debugger
                //
                AttachingReachedToValidLoadedModule(DbgState, ProcessDebuggingDetail);
            }
        }
        else if (g_IsWaitingForReturnAndRunFromPageFault)
        {
            //
            // not waiting for a break after the page-fault anymore
            //
            g_IsWaitingForReturnAndRunFromPageFault = FALSE;
 
            //
            // We reached here as a result of setting the trap flag after
            // injecting a page-fault
            //
            AttachingReachedToValidLoadedModule(DbgState, ProcessDebuggingDetail);
        }
    }
}

AttachingInitialize()

BOOLEAN AttachingInitialize

(

)

Initialize the attaching mechanism.

as we use the functionalities for these functions, we initialize them from the debugger at start up of debugger (not initialization of user-debugger)

Returns

BOOLEAN

{
    UNICODE_STRING FunctionName;
 
    //
    // Find address of PsGetProcessPeb
    //
    if (g_PsGetProcessPeb == NULL)
    {
        RtlInitUnicodeString(&FunctionName, L"PsGetProcessPeb");
        g_PsGetProcessPeb = (PsGetProcessPeb)MmGetSystemRoutineAddress(&FunctionName);
 
        if (g_PsGetProcessPeb == NULL)
        {
            LogError("Err, cannot resolve PsGetProcessPeb");
 
            //
            // Won't fail the entire debugger for not finding this
            //
            // return FALSE;
        }
    }
 
    //
    // Find address of PsGetProcessWow64Process
    //
    if (g_PsGetProcessWow64Process == NULL)
    {
        RtlInitUnicodeString(&FunctionName, L"PsGetProcessWow64Process");
        g_PsGetProcessWow64Process = (PsGetProcessWow64Process)MmGetSystemRoutineAddress(&FunctionName);
 
        if (g_PsGetProcessWow64Process == NULL)
        {
            LogError("Err, cannot resolve PsGetProcessPeb");
 
            //
            // Won't fail the entire debugger for not finding this
            //
            // return FALSE;
        }
    }
 
    //
    // Find address of ZwQueryInformationProcess
    //
    if (g_ZwQueryInformationProcess == NULL)
    {
        UNICODE_STRING RoutineName;
 
        RtlInitUnicodeString(&RoutineName, L"ZwQueryInformationProcess");
 
        g_ZwQueryInformationProcess = (ZwQueryInformationProcess)MmGetSystemRoutineAddress(&RoutineName);
 
        if (g_ZwQueryInformationProcess == NULL)
        {
            LogError("Err, cannot resolve ZwQueryInformationProcess");
 
            //
            // Won't fail the entire debugger for not finding this
            //
            // return FALSE;
        }
    }
 
    return TRUE;
}

AttachingQueryDetailsOfActiveDebuggingThreadsAndProcesses()

BOOLEAN AttachingQueryDetailsOfActiveDebuggingThreadsAndProcesses	(	PVOID	BufferToStoreDetails,
		UINT32	BufferSize )

Query details of active debugging threads.

Parameters

BufferToStoreDetails
BufferSize

Returns

BOOLEAN

{
    UINT32 CountOfProcessesAndThreadsToStore;
 
    CountOfProcessesAndThreadsToStore = BufferSize / SIZEOF_USERMODE_DEBUGGING_THREAD_OR_PROCESS_STATE_DETAILS;
 
    if (CountOfProcessesAndThreadsToStore == 0)
    {
        //
        // No active thread or process
        //
        return FALSE;
    }
 
    // LogInfo("Count of active process and threads : %x", CountOfProcessesAndThreadsToStore);
 
    //
    // Get the results
    //
    ThreadHolderQueryDetailsOfActiveDebuggingThreadsAndProcesses(BufferToStoreDetails, CountOfProcessesAndThreadsToStore);
 
    return TRUE;
}

AttachingReachedToValidLoadedModule()

BOOLEAN AttachingReachedToValidLoadedModule	(	PROCESSOR_DEBUGGING_STATE *	DbgState,
		PUSERMODE_DEBUGGING_PROCESS_DETAILS	ProcessDebuggingDetail )

Handle cases where we reached to the valid loaded module The main module should be loaded once we reach to this function.

Parameters

DbgState	The state of the debugger on the current core
ProcessDebuggingDetail

Returns

BOOLEAN

{
    DEBUGGEE_BP_PACKET BpRequest = {0};
 
    //
    // Double check to make sure the main module is loaded
    //
    if (!CheckAccessValidityAndSafety(ProcessDebuggingDetail->EntrypointOfMainModule, sizeof(CHAR)))
    {
        LogError("Err, the main module is not loaded or the main entrypoint is not valid");
        return FALSE;
    }
 
    //
    // Setting a breakpoint to the main entrypoint of the module
    //
    BpRequest.Address = ProcessDebuggingDetail->EntrypointOfMainModule;
    BpRequest.Core    = DEBUGGEE_BP_APPLY_TO_ALL_CORES;
    BpRequest.Pid     = DEBUGGEE_BP_APPLY_TO_ALL_PROCESSES;
    BpRequest.Tid     = DEBUGGEE_BP_APPLY_TO_ALL_THREADS;
 
    //
    // Remove the breakpoint after hit
    //
    BpRequest.RemoveAfterHit = TRUE;
 
    //
    // Check if the process needs to check for callbacks for the very first instruction
    //
    if (ProcessDebuggingDetail->CheckCallBackForInterceptingFirstInstruction)
    {
        //
        // This breakpoint should check for callbacks
        //
        BpRequest.CheckForCallbacks = TRUE;
    }
 
    //
    // Register the breakpoint
    // Note that, even though it's a user-mode breakpoint, we are currently
    // in the memory layout of the target process, thus, no switching memory
    // layout is needed
    //
    if (!BreakpointAddNew(&BpRequest, FALSE))
    {
        LogError("Err, unable to set breakpoint on the entrypoint module");
        return FALSE;
    }
 
    //
    // Finish the starting point of the thread
    //
    AttachingSetStartingPhaseOfProcessDebuggingDetailsByToken(FALSE, ProcessDebuggingDetail->Token);
 
    //
    // Check if we're connect to the kHyperDbg or uHyperDbg
    //
    if (g_KernelDebuggerState)
    {
        //
        // Handling state through the kernel-mode debugger
        //
        KdHandleBreakpointAndDebugBreakpoints(DbgState,
                                              DEBUGGEE_PAUSING_REASON_DEBUGGEE_STARTING_MODULE_LOADED,
                                              NULL);
    }
    else if (g_UserDebuggerState)
    {
        //
        // Handling state through the user-mode debugger
        //
        UdHandleInstantBreak(DbgState,
                             DEBUGGEE_PAUSING_REASON_DEBUGGEE_STARTING_MODULE_LOADED,
                             ProcessDebuggingDetail);
    }
    else
    {
        LogError("Err, no debugger is attached to handle the entrypoint interception");
        return FALSE;
    }
 
    //
    // Handled successfully
    //
    return TRUE;
}

AttachingRemoveAndFreeAllProcessDebuggingDetails()

VOID AttachingRemoveAndFreeAllProcessDebuggingDetails

(

)

Remove and deallocate all thread debuggig details.

Returns

VOID

{
    LIST_FOR_EACH_LINK(g_ProcessDebuggingDetailsListHead, USERMODE_DEBUGGING_PROCESS_DETAILS, AttachedProcessList, ProcessDebuggingDetails)
    {
        //
        // Free the thread holding structure(s)
        //
        ThreadHolderFreeHoldingStructures(ProcessDebuggingDetails);
 
        //
        // Remove thread debugging detail from the list active threads
        //
        RemoveEntryList(&ProcessDebuggingDetails->AttachedProcessList);
 
        //
        // Unallocate the pool
        //
        PlatformMemFreePool(ProcessDebuggingDetails);
    }
}

AttachingTargetProcess()

VOID AttachingTargetProcess

(

PDEBUGGER_ATTACH_DETACH_USER_MODE_PROCESS

Request

)

Dispatch and perform attaching tasks.

this function should not be called in vmx-root

Parameters

AttachRequest

Returns

VOID

{
    //
    // As we're here, we need to initialize the user-mode debugger
    //
    if (!UdInitializeUserDebugger())
    {
        Request->Result = DEBUGGER_ERROR_DEBUGGER_NOT_INITIALIZED;
        return;
    }
 
    switch (Request->Action)
    {
    case DEBUGGER_ATTACH_DETACH_USER_MODE_PROCESS_ACTION_ATTACH:
 
        AttachingPerformAttachToProcess(Request, Request->IsStartingNewProcess);
 
        break;
 
    case DEBUGGER_ATTACH_DETACH_USER_MODE_PROCESS_ACTION_DETACH:
 
        AttachingPerformDetach(Request);
 
        break;
 
    case DEBUGGER_ATTACH_DETACH_USER_MODE_PROCESS_ACTION_REMOVE_HOOKS:
 
        AttachingRemoveHooks(Request);
 
        break;
 
    case DEBUGGER_ATTACH_DETACH_USER_MODE_PROCESS_ACTION_KILL_PROCESS:
 
        AttachingKillProcess(Request);
 
        break;
 
    case DEBUGGER_ATTACH_DETACH_USER_MODE_PROCESS_ACTION_CONTINUE_PROCESS:
 
        AttachingContinueProcess(Request);
 
        break;
 
    case DEBUGGER_ATTACH_DETACH_USER_MODE_PROCESS_ACTION_PAUSE_PROCESS:
 
        AttachingPauseProcess(Request);
 
        break;
 
    case DEBUGGER_ATTACH_DETACH_USER_MODE_PROCESS_ACTION_SWITCH_BY_PROCESS_OR_THREAD:
 
        AttachingSwitchProcess(Request);
 
        break;
 
    case DEBUGGER_ATTACH_DETACH_USER_MODE_PROCESS_ACTION_QUERY_COUNT_OF_ACTIVE_DEBUGGING_THREADS:
 
        AttachingQueryCountOfActiveDebuggingThreadsAndProcesses(Request);
 
        break;
 
    default:
 
        Request->Result = DEBUGGER_ERROR_INVALID_ACTION_TYPE;
 
        break;
    }
}