.attach (attach to a process)

Description of the '.attach' command in HyperDbg.

Command

.attach

Syntax

.attach [pid ProcessId (hex)]

Description

Attaches to a running program and pauses the target process. HyperDbg tries to intercept the threads running in user mode (not kernel mode) when you attach to the target process.

It means that you should keep interacting with the target process to get threads. When you run the first command to the target thread, intercepting threads will be ignored, and HyperDbg won't intercept new threads.

The user-mode debugger is still in the beta version and not stable. We decided to exclude it from this release and release it in future versions. If you want to test the user-mode debugger in VMI Mode, you should build HyperDbg with special instructions. Please follow the instruction here.

In contrast with the kernel debugger, the user debugger is still very basic and needs a lot of tests and improvements. We highly recommend not to run the user debugger in your bare metal system. Instead, run it on a supported virtual machine to won't end up with a Blue Screen of Death (BSOD) in your primary device. Please keep reporting the issues to improve the user debugger.

This command won't use any Windows API for intercepting and pausing threads, and everything is done at the hypervisor level.

Parameters

[pid ProcessId (hex)]

The target process id.

Examples

Imagine we want to attach to a running program with process id equal to 12c0.

HyperDbg> .attach pid 12c0

IOCTL

This function works by calling DeviceIoControl with IOCTL = IOCTL_DEBUGGER_ATTACH_DETACH_USER_MODE_PROCESS. You have to send it in the following structure.

typedef struct _DEBUGGER_ATTACH_DETACH_USER_MODE_PROCESS
{
    BOOLEAN                                              IsStartingNewProcess;
    UINT32                                               ProcessId;
    UINT32                                               ThreadId;
    BOOLEAN                                              Is32Bit;
    BOOLEAN                                              IsPaused; // used in switching to threads
    DEBUGGER_ATTACH_DETACH_USER_MODE_PROCESS_ACTION_TYPE Action;
    UINT32                                               CountOfActiveDebuggingThreadsAndProcesses; // used in showing the list of active threads/processes
    UINT64                                               Token;
    UINT64                                               Result;

} DEBUGGER_ATTACH_DETACH_USER_MODE_PROCESS, *PDEBUGGER_ATTACH_DETACH_USER_MODE_PROCESS;

First, you should fill the ProcessId set the IsStartingNewProcess to FALSE and Action to DEBUGGER_ATTACH_DETACH_USER_MODE_PROCESS_ACTION_ATTACH in the above structure, when the IOCTL returns from the kernel, other parts are filled with appropriate data from the process.

After getting the results from the kernel and if the Result is equal to DEBUGGER_OPERATION_WAS_SUCCESSFULL the pausing phase of the process is started.

The Action can be from the following enum:

typedef enum _DEBUGGER_ATTACH_DETACH_USER_MODE_PROCESS_ACTION_TYPE
{
    DEBUGGER_ATTACH_DETACH_USER_MODE_PROCESS_ACTION_ATTACH,
    DEBUGGER_ATTACH_DETACH_USER_MODE_PROCESS_ACTION_DETACH,
    DEBUGGER_ATTACH_DETACH_USER_MODE_PROCESS_ACTION_REMOVE_HOOKS,
    DEBUGGER_ATTACH_DETACH_USER_MODE_PROCESS_ACTION_KILL_PROCESS,
    DEBUGGER_ATTACH_DETACH_USER_MODE_PROCESS_ACTION_PAUSE_PROCESS,
    DEBUGGER_ATTACH_DETACH_USER_MODE_PROCESS_ACTION_SWITCH_BY_PROCESS_OR_THREAD,
    DEBUGGER_ATTACH_DETACH_USER_MODE_PROCESS_ACTION_QUERY_COUNT_OF_ACTIVE_DEBUGGING_THREADS,

} DEBUGGER_ATTACH_DETACH_USER_MODE_PROCESS_ACTION_TYPE;

Remarks

This command is logically designed to be used in VMI Mode. You can use the '.process' and the '.thread' commands in Debugger Mode.

Requirements

None

Related

.start (start a new process)

.restart (restart the process)

.detach (detach from the process)

.switch (show the list and switch between active debugging threads)

.kill (terminate the process)