.thread, .thread2 (show the current thread and switch to another thread)
Description of '.thread, .thread2' commands in HyperDbg.

Command

.thread
.thread2

Syntax

.thread
.thread [list] [process Eprocess (hex)]
.thread [tid ThreadId (hex)]
.thread [thread Ethread (hex)]
.thread2 [tid ThreadId (hex)]
.thread2 [thread Ethread (hex)]

Description

Shows or changes the current thread. 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 threads 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 '.thread' command and when you should use the alternative '.thread2' command.
If you want to change the thread to a new thread, after using the '.thread' or the '.thread2' commands, you should use the 'g' command.

Parameters

[list]
It shows the list of threads.
[process Eprocess (hex)] (optional)
If you specify the list as the first argument, you can optionally specify the target process that you want to see its threads, otherwise, the threads for the current process are shown.
[tid ThreadId (hex)]
The thread id of the thread that you want to switch to it.
[thread Ethread (hex)]
The _ETHREAD of the thread that you want to switch to it.
If you don't specify any parameters to the '.thread' or the '.thread2' commands, it shows the threads of the current process.

Examples

Use the following command to see the currently executing thread (and other information like thread and process object addresses and the image name).
1
3: kHyperDbg> .thread
2
thread id: e80 (pid: 40c)
3
thread (_ETHREAD): ffff948c`ba35a080
4
process (_EPROCESS): ffff948c`c1594340
5
process name (16-Byte): hyperdbg-cli.e
Copied!
If you want to switch to a thread with a thread id equal to 23f8, use the below command. After that, use the 'g' command, and when the debuggee breaks again, you can see that the thread is changed to your requested thread.
1
2: kHyperDbg> .thread tid 23f8
2
press 'g' to continue the debuggee, if the tid or the thread object address is valid then the debuggee will be automatically paused when it attached to the target thread
3
4
2: kHyperDbg> g
5
debuggee is running...
6
switched to the specified thread
7
fffff801`63265c52 0F B6 87 84 01 00 00 movzx eax, byte ptr ds:[rdi+0x184]
8
9
3: kHyperDbg> .thread
10
thread id: 23f8 (pid: 1b6c)
11
thread (_ETHREAD): ffff948c`c1957080
12
process (_EPROCESS): ffff948c`c0a0d080
13
process name (16-Byte): test.exe
Copied!
If you want to switch to a thread by using its thread object address (nt!_ETHREAD), use the following command.
1
2: kHyperDbg> .thread thread ffff948c`c1957080
2
press 'g' to continue the debuggee, if the tid or the thread object address is valid then the debuggee will be automatically paused when it attached to the target thread
3
4
2: kHyperDbg> g
5
debuggee is running...
6
switched to the specified thread
7
00007ff6`e8df2450 90 nop
Copied!
If you want to see a list of threads in the current process.
1
2: kHyperDbg> .thread list
2
PROCESS ffff948cc1594340 IMAGE hyperdbg-cli.e
3
THREAD ffff948cba186080 (40c.20c8)
4
THREAD ffff948cbfc7b080 (40c.1794)
5
THREAD ffff948cba35a080 (40c.e80)
Copied!
If you want to view a list of threads of a special process, use its process object (nt!_EPROCESS) address. You can get a list of process objects list using the '.process' command.
1
2: kHyperDbg> .thread list process ffff948cc1590340
2
PROCESS ffff948cc1590340 IMAGE MicrosoftEdgeU
3
THREAD ffff948cbf8f2080 (e08.1918)
4
THREAD ffff948cc056c080 (e08.c88)
5
THREAD ffff948cbfedf040 (e08.628)
6
THREAD ffff948cbf3ad080 (e08.18c0)
7
THREAD ffff948cc09ed080 (e08.1b00)
8
THREAD ffff948cc14ea080 (e08.888)
Copied!

IOCTL

This commands works over serial by sending the serial packets to the remote computer.
First of all, you should fill the DEBUGGEE_DETAILS_AND_SWITCH_THREAD_PACKET structure.
Set the ThreadId or Thread to your target thread (if you want to change the current thread), set the ActionType to DEBUGGEE_DETAILS_AND_SWITCH_THREAD_PERFORM_SWITCH and leave the Result.
This is the enum for action type.
1
typedef enum _DEBUGGEE_DETAILS_AND_SWITCH_THREAD_TYPE
2
{
3
4
DEBUGGEE_DETAILS_AND_SWITCH_THREAD_PERFORM_SWITCH,
5
DEBUGGEE_DETAILS_AND_SWITCH_THREAD_GET_THREAD_DETAILS,
6
DEBUGGEE_DETAILS_AND_SWITCH_THREAD_GET_THREAD_LIST,
7
8
} DEBUGGEE_DETAILS_AND_SWITCH_THREAD_TYPE;
Copied!
If you want to get the current thread id and _ETHREAD, then set the ActionType to DEBUGGEE_DETAILS_AND_SWITCH_THREAD_GET_THREAD_DETAILS and leave the ThreadId and Thread.
If you want to see the list of threads, you should set the ActionType to DEBUGGEE_DETAILS_AND_SWITCH_THREAD_GET_THREAD_LIST and also fill the below structure with offsets derived from the PDB file in addition to the target process that you want to see its threads.
If you set Process to NULL, it shows the current process's threads.
1
typedef struct _DEBUGGEE_THREAD_LIST_NEEDED_DETAILS
2
{
3
UINT32 ThreadListHeadOffset; // nt!_EPROCESS.ThreadListHead
4
UINT32 ThreadListEntryOffset; // nt!_ETHREAD.ThreadListEntry
5
UINT32 CidOffset; // nt!_ETHREAD.Cid
6
UINT64 PsActiveProcessHead; // nt!PsActiveProcessHead
7
ULONG ActiveProcessLinksOffset; // nt!_EPROCESS.ActiveProcessLinks
8
UINT64 Process;
9
10
} DEBUGGEE_THREAD_LIST_NEEDED_DETAILS, *PDEBUGGEE_THREAD_LIST_NEEDED_DETAILS;cccc
Copied!
When you set CheckByClockInterrupt to TRUE, the semantics for the '.thread' is used and if you set it to FALSE then the '.thread2''s semantic is used for the thread switch request.
1
typedef struct _DEBUGGEE_DETAILS_AND_SWITCH_THREAD_PACKET
2
{
3
DEBUGGEE_DETAILS_AND_SWITCH_THREAD_TYPE ActionType;
4
UINT32 ThreadId;
5
UINT32 ProcessId;
6
UINT64 Thread;
7
UINT64 Process;
8
BOOLEAN CheckByClockInterrupt;
9
UCHAR ProcessName[16];
10
DEBUGGEE_THREAD_LIST_NEEDED_DETAILS ThreadListSymDetails;
11
UINT32 Result;
12
13
} DEBUGGEE_DETAILS_AND_SWITCH_THREAD_PACKET, *PDEBUGGEE_DETAILS_AND_SWITCH_THREAD_PACKET;
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_THREAD 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_THREAD
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 thread. Otherwise, the returned result is an error, and the current thread is not changed. If you want the current thread, then if the Result is DEBUGEER_OPERATION_WAS_SUCCESSFULL, then the current thread id is stored at ThreadId and the thread object address is stored at Thread.
The following function is responsible for changing the core in the debugger.
1
BOOLEAN
2
KdSendSwitchThreadPacketToDebuggee(DEBUGGEE_DETAILS_AND_SWITCH_THREAD_TYPE ActionType,
3
UINT32 NewTid,
4
UINT64 NewThread,
5
BOOLEAN CheckByClockInterrupt,
6
PDEBUGGEE_THREAD_LIST_NEEDED_DETAILS SymDetailsForThreadList);
Copied!

Remarks

If you want to see a list of threads, you need to load the public symbol file (PDB) for the ntoskrnl.exe using the '.sym' command.
The difference between these commands (.thread and .thread2) is explained here.
If you've entered an invalid address as _ETHREAD or an invalid thread id, HyperDbg keeps checking for the target address or TID, and whenever the debugger is paused again, it won't check for the thread anymore.
It also means that if you press the 'g' command and an event or a breakpoint is triggered before switching to the new thread, switching will be ignored, and you need to re-switch to the target thread and use the '.thread' or '.thread2' commands again.
Some threads might never trigger even if their thread id or ETHREAD is valid. It is because in these cases, Windows halts or suspends those processes (and, of course, its threads) 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.

Requirements

None