.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.

Requirements

None
Copy link
Edit on GitHub
On this page
Command
Syntax
Description
Parameters
Examples
IOCTL
Remarks
Requirements
Related