.process, .process2 (show the current process and switch to another process)

Description of '.process, .process2' commands in HyperDbg.

Command

.process
.process2

Syntax

.process
.process [list]
.process [pid ProcessId (hex)]
.process [process Eprocess (hex)]
.process2 [pid ProcessId (hex)]
.process2 [process Eprocess (hex)]

Description

Shows or changes the current process. These commands are logically designed to be used in Debugger Mode. You can use the '.attach' and the '.detach' commands in VMI Mode. However, you can use it to view the list of the processes in both VMI Mode and Debugger Mode.

Important: the implementation of these commands is different. Please visit this article to be aware of the differences and to know when you should use the '.process' command and when you should use the alternative '.process2' command.

If you want to change the process to a new process, after using the '.process' or the '.process2' commands, you should use the 'g' command.

Parameters

[list]

It shows the list of processes (see Remarks).

[pid ProcessId (hex)]

The process Id to switch on its memory layout.

[process Eprocess (hex)]

The _EPROCESS of the process to switch on its memory layout.

If you don't specify any parameters to the '.process' or the '.process2' commands, it shows current process.

Examples

The following command shows the current process.

2: kHyperDbg> .process
process id: 1e98
process (_EPROCESS): ffff948c`c153b080
process name (16-Byte): hyperdbg-cli.e

The following command shows the list of active processes.

2: kHyperDbg> .process list
PROCESS ffff948cba05f040
        Process Id: 0004        DirBase (Kernel Cr3): 00000000001aa002  Image: System

PROCESS ffff948cba0eb080
        Process Id: 006c        DirBase (Kernel Cr3): 0000000000263002  Image: Registry

PROCESS ffff948cbcb67040
        Process Id: 0188        DirBase (Kernel Cr3): 0000000202a1e002  Image: smss.exe

PROCESS ffff948cba9a6140
        Process Id: 01f8        DirBase (Kernel Cr3): 000000020b3d4002  Image: csrss.exe

PROCESS ffff948cbd8020c0
        Process Id: 024c        DirBase (Kernel Cr3): 0000000000e66002  Image: wininit.exe

PROCESS ffff948cbd811140
        Process Id: 0254        DirBase (Kernel Cr3): 00000000056fd002  Image: csrss.exe

PROCESS ffff948cbd83c080
        Process Id: 029c        DirBase (Kernel Cr3): 000000020c4a7002  Image: winlogon.exe

PROCESS ffff948cbd894080
        Process Id: 02e0        DirBase (Kernel Cr3): 000000020ced2002  Image: services.exe

PROCESS ffff948cbd897080
        Process Id: 02e8        DirBase (Kernel Cr3): 0000000211512002  Image: lsass.exe

PROCESS ffff948cbd907240
        Process Id: 0374        DirBase (Kernel Cr3): 000000020e007002  Image: svchost.exe

PROCESS ffff948cbd90e140
        Process Id: 0390        DirBase (Kernel Cr3): 000000020e3f5002  Image: fontdrvhost.ex

PROCESS ffff948cbd910140
        Process Id: 0398        DirBase (Kernel Cr3): 000000020e0fb002  Image: fontdrvhost.ex

PROCESS ffff948cbd8ba2c0
        Process Id: 03e8        DirBase (Kernel Cr3): 000000020e98e002  Image: svchost.exe
        
  ...

The following commands change the current process to 0x1ddc.

2: kHyperDbg> .process pid 1ddc
press 'g' to continue the debuggee, if the pid or the process object address is valid then the debuggee will be automatically paused when it attached to the target process

2: kHyperDbg> g
debuggee is running...
switched to the specified process
00007ff6`e8df2449    90                                  nop

The following commands change the current process to a process with _EPROCESS equals to ffff948cc2349280.

1: kHyperDbg> .process2 process ffff948cc2349280
press 'g' to continue the debuggee, if the pid or the process object address is valid then the debuggee will be automatically paused when it attached to the target process

1: kHyperDbg> g
debuggee is running...
switched to the specified process
fffff801`63a12b22    0F 22 DC                            mov cr3, rsp

IOCTL

This commands works over serial by sending the serial packets to the remote computer.

First of all, you should fill the following structure, set the ProcessId or Process to your target process (if you want to change the current process), set the ActionType to DEBUGGEE_DETAILS_AND_SWITCH_PROCESS_PERFORM_SWITCH and leave the Result.

This is the enum for action type.

typedef enum _DEBUGGEE_DETAILS_AND_SWITCH_PROCESS_TYPE
{

    DEBUGGEE_DETAILS_AND_SWITCH_PROCESS_PERFORM_SWITCH,
    DEBUGGEE_DETAILS_AND_SWITCH_PROCESS_GET_PROCESS_DETAILS,
    DEBUGGEE_DETAILS_AND_SWITCH_PROCESS_GET_PROCESS_LIST,

} DEBUGGEE_DETAILS_AND_SWITCH_PROCESS_TYPE;

If you want to get the current process id and _EPROCESS, then set the ActionType to DEBUGGEE_DETAILS_AND_SWITCH_PROCESS_GET_PROCESS_DETAILS and leave the ProcessId and Process.

If you want to see the list of processes, you should set the ActionType to DEBUGGEE_DETAILS_AND_SWITCH_PROCESS_GET_PROCESS_LISTand also fill the below structure with offsets derived from the PDB file in addition to the address of nt!PsActiveProcessHead.

typedef struct _DEBUGGEE_PROCESS_LIST_NEEDED_DETAILS
{
    UINT64 PsActiveProcessHead;      // nt!PsActiveProcessHead
    ULONG  ImageFileNameOffset;      // nt!_EPROCESS.ImageFileName
    ULONG  UniquePidOffset;          // nt!_EPROCESS.UniqueProcessId
    ULONG  ActiveProcessLinksOffset; // nt!_EPROCESS.ActiveProcessLinks

} DEBUGGEE_PROCESS_LIST_NEEDED_DETAILS, *PDEBUGGEE_PROCESS_LIST_NEEDED_DETAILS;

When you set IsSwitchByClkIntr to TRUE, the semantics for the '.process' is used and if you set it to FALSE then the '.process2''s semantic is used for the process switch request.

typedef struct _DEBUGGEE_DETAILS_AND_SWITCH_PROCESS_PACKET
{
    DEBUGGEE_DETAILS_AND_SWITCH_PROCESS_TYPE ActionType;
    UINT32                                   ProcessId;
    UINT64                                   Process;
    BOOLEAN                                  IsSwitchByClkIntr;
    UCHAR                                    ProcessName[16];
    DEBUGGEE_PROCESS_LIST_NEEDED_DETAILS     ProcessListSymDetails;
    UINT32                                   Result;

} DEBUGGEE_DETAILS_AND_SWITCH_PROCESS_PACKET, *PDEBUGGEE_DETAILS_AND_SWITCH_PROCESS_PACKET;

After that, send the above structure to the debuggee when debuggee is paused and waiting for new command on vmx-root mode.

You should send the above structure with DEBUGGER_REMOTE_PACKET_REQUESTED_ACTION_ON_VMX_ROOT_MODE_CHANGE_PROCESS as RequestedAction and DEBUGGER_REMOTE_PACKET_TYPE_DEBUGGER_TO_DEBUGGEE_EXECUTE_ON_VMX_ROOT as PacketType.

In return, the debuggee sends the above structure with the following type.

DEBUGGER_REMOTE_PACKET_REQUESTED_ACTION_DEBUGGEE_RESULT_OF_CHANGING_PROCESS

In the returned structure, the Result is filled by the kernel.

If the Result is DEBUGEER_OPERATION_WAS_SUCCESSFULL, the operation was successful, and you should use the 'g' command to move to the new process. Otherwise, the returned result is an error, and the current process is not changed. If you want the current process, then if the Result is DEBUGEER_OPERATION_WAS_SUCCESSFULL, then the current process id is stored at ProcessIdand the process object address is stored at Process.

The following function is responsible for changing the core in the debugger.

BOOLEAN
KdSendSwitchProcessPacketToDebuggee(DEBUGGEE_DETAILS_AND_SWITCH_PROCESS_TYPE ActionType,
                                    UINT32                                   NewPid,
                                    UINT64                                   NewProcess,
                                    BOOLEAN                                  SetChangeByClockInterrupt,
                                    PDEBUGGEE_PROCESS_LIST_NEEDED_DETAILS    SymDetailsForProcessList);

Remarks

If you want to see a list of processes, you need to load the public symbol file (PDB) for the ntoskrnl.exe using the '.sym' command.

The difference between these commands (.process and .process2) is explained here.

If you've entered an invalid address as _EPROCESS or an invalid process id, HyperDbg keeps checking for the target address or PID, and whenever the debugger is paused again, it won't check for the process anymore.

It also means that if you press the 'g' command and an event or a breakpoint is triggered before switching to the new process, switching will be ignored, and you need to re-switch to the target process and use the '.process' or '.process2' commands again.

Some processes might never trigger even if their process id or EPROCESS is valid. It is because in these cases, Windows halts or suspends those processes and never switches to them. In these cases, you can switch to the memory layout of the target process by changing cr3 to your target cr3. For more details, please visit here.

If you use the '.process2' command, HyperDbg guarantees that the target process won't get the chance to be executed while the switch is performed. However, make sure that your target process is not currently processing on any cores in the processor.