.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.
1
2: kHyperDbg> .process
2
process id: 1e98
3
process (_EPROCESS): ffff948c`c153b080
4
process name (16-Byte): hyperdbg-cli.e
Copied!
The following command shows the list of active processes.
1
2: kHyperDbg> .process list
2
PROCESS ffff948cba05f040
3
Process Id: 0004 DirBase (Kernel Cr3): 00000000001aa002 Image: System
4
5
PROCESS ffff948cba0eb080
6
Process Id: 006c DirBase (Kernel Cr3): 0000000000263002 Image: Registry
7
8
PROCESS ffff948cbcb67040
9
Process Id: 0188 DirBase (Kernel Cr3): 0000000202a1e002 Image: smss.exe
10
11
PROCESS ffff948cba9a6140
12
Process Id: 01f8 DirBase (Kernel Cr3): 000000020b3d4002 Image: csrss.exe
13
14
PROCESS ffff948cbd8020c0
15
Process Id: 024c DirBase (Kernel Cr3): 0000000000e66002 Image: wininit.exe
16
17
PROCESS ffff948cbd811140
18
Process Id: 0254 DirBase (Kernel Cr3): 00000000056fd002 Image: csrss.exe
19
20
PROCESS ffff948cbd83c080
21
Process Id: 029c DirBase (Kernel Cr3): 000000020c4a7002 Image: winlogon.exe
22
23
PROCESS ffff948cbd894080
24
Process Id: 02e0 DirBase (Kernel Cr3): 000000020ced2002 Image: services.exe
25
26
PROCESS ffff948cbd897080
27
Process Id: 02e8 DirBase (Kernel Cr3): 0000000211512002 Image: lsass.exe
28
29
PROCESS ffff948cbd907240
30
Process Id: 0374 DirBase (Kernel Cr3): 000000020e007002 Image: svchost.exe
31
32
PROCESS ffff948cbd90e140
33
Process Id: 0390 DirBase (Kernel Cr3): 000000020e3f5002 Image: fontdrvhost.ex
34
35
PROCESS ffff948cbd910140
36
Process Id: 0398 DirBase (Kernel Cr3): 000000020e0fb002 Image: fontdrvhost.ex
37
38
PROCESS ffff948cbd8ba2c0
39
Process Id: 03e8 DirBase (Kernel Cr3): 000000020e98e002 Image: svchost.exe
40
41
...
Copied!
The following commands change the current process to 0x1ddc.
1
2: kHyperDbg> .process pid 1ddc
2
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
3
4
2: kHyperDbg> g
5
debuggee is running...
6
switched to the specified process
7
00007ff6`e8df2449 90 nop
Copied!
The following commands change the current process to a process with _EPROCESS equals to ffff948cc2349280.
1
1: kHyperDbg> .process2 process ffff948cc2349280
2
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
3
4
1: kHyperDbg> g
5
debuggee is running...
6
switched to the specified process
7
fffff801`63a12b22 0F 22 DC mov cr3, rsp
Copied!

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.
1
typedef enum _DEBUGGEE_DETAILS_AND_SWITCH_PROCESS_TYPE
2
{
3
4
DEBUGGEE_DETAILS_AND_SWITCH_PROCESS_PERFORM_SWITCH,
5
DEBUGGEE_DETAILS_AND_SWITCH_PROCESS_GET_PROCESS_DETAILS,
6
DEBUGGEE_DETAILS_AND_SWITCH_PROCESS_GET_PROCESS_LIST,
7
8
} DEBUGGEE_DETAILS_AND_SWITCH_PROCESS_TYPE;
Copied!
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.
1
typedef struct _DEBUGGEE_PROCESS_LIST_NEEDED_DETAILS
2
{
3
UINT64 PsActiveProcessHead; // nt!PsActiveProcessHead
4
ULONG ImageFileNameOffset; // nt!_EPROCESS.ImageFileName
5
ULONG UniquePidOffset; // nt!_EPROCESS.UniqueProcessId
6
ULONG ActiveProcessLinksOffset; // nt!_EPROCESS.ActiveProcessLinks
7
8
} DEBUGGEE_PROCESS_LIST_NEEDED_DETAILS, *PDEBUGGEE_PROCESS_LIST_NEEDED_DETAILS;
Copied!
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.
1
typedef struct _DEBUGGEE_DETAILS_AND_SWITCH_PROCESS_PACKET
2
{
3
DEBUGGEE_DETAILS_AND_SWITCH_PROCESS_TYPE ActionType;
4
UINT32 ProcessId;
5
UINT64 Process;
6
BOOLEAN IsSwitchByClkIntr;
7
UCHAR ProcessName[16];
8
DEBUGGEE_PROCESS_LIST_NEEDED_DETAILS ProcessListSymDetails;
9
UINT32 Result;
10
11
} DEBUGGEE_DETAILS_AND_SWITCH_PROCESS_PACKET, *PDEBUGGEE_DETAILS_AND_SWITCH_PROCESS_PACKET;
12
Copied!
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.
1
DEBUGGER_REMOTE_PACKET_REQUESTED_ACTION_DEBUGGEE_RESULT_OF_CHANGING_PROCESS
Copied!
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.
1
BOOLEAN
2
KdSendSwitchProcessPacketToDebuggee(DEBUGGEE_DETAILS_AND_SWITCH_PROCESS_TYPE ActionType,
3
UINT32 NewPid,
4
UINT64 NewProcess,
5
BOOLEAN SetChangeByClockInterrupt,
6
PDEBUGGEE_PROCESS_LIST_NEEDED_DETAILS SymDetailsForProcessList);
Copied!

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