HyperDbg Documentation
CommunityDownloadResearchTutorialhwdbg
  • HyperDbg
  • Getting Started
    • Quick Start
    • FAQ
    • Build & Install
    • Attach to HyperDbg
      • Attach to a remote machine
      • Attach to local machine
      • Start a new process
      • Attach to a running process
  • Using HyperDbg
    • Prerequisites
      • Operation Modes
      • How to create a condition?
      • How to create an action?
      • Signatures
    • User-mode Debugging
      • Principles
      • Examples
        • basics
        • events
          • Getting Results of a System-call
    • Kernel-mode Debugging
      • Principles
      • Examples
        • beginning
          • Connecting To HyperDbg
          • Configuring Symbol Server/Path
        • basics
          • Setting Breakpoints & Stepping Instructions
          • Displaying & Editing & Searching Memory
          • Showing & Modifying Registers and Flags
          • Switching to a Specific Process or Thread
          • Mapping Data & Create Structures, and Enums From Symbols
        • events
          • Managing Events
          • Hooking Any Function
          • Intercepting All SYSCALLs
          • Monitoring Accesses To Structures
          • Triggering Special Instructions
          • Identifying System Behavior
        • Scripting Language Examples
    • Software Development Kit (SDK)
      • Events
        • Conditions
        • Actions
      • IOCTL
        • Event Registration
  • Commands
    • Debugging Commands
      • ? (evaluate and execute expressions and scripts in debuggee)
      • ~ (display and change the current operating core)
      • a (assemble virtual address)
      • load (load the kernel modules)
      • unload (unload the kernel modules)
      • status (show the debuggee status)
      • events (show and modify active/disabled events)
      • p (step-over)
      • t (step-in)
      • i (instrumentation step-in)
      • gu (step-out or go up)
      • r (read or modify registers)
      • bp (set breakpoint)
      • bl (list breakpoints)
      • be (enable breakpoints)
      • bd (disable breakpoints)
      • bc (clear and remove breakpoints)
      • g (continue debuggee or processing kernel packets)
      • x (examine symbols and find functions and variables address)
      • db, dc, dd, dq (read virtual memory)
      • eb, ed, eq (edit virtual memory)
      • sb, sd, sq (search virtual memory)
      • u, u64, u2, u32 (disassemble virtual address)
      • k, kd, kq (display stack backtrace)
      • dt (display and map virtual memory to structures)
      • struct (make structures, enums, data types from symbols)
      • sleep (wait for specific time in the .script command)
      • pause (break to the debugger and pause processing kernel packets)
      • print (evaluate and print expression in debuggee)
      • lm (view loaded modules)
      • cpu (check cpu supported technologies)
      • rdmsr (read model-specific register)
      • wrmsr (write model-specific register)
      • flush (remove pending kernel buffers and messages)
      • prealloc (reserve pre-allocated pools)
      • preactivate (pre-activate special functionalities)
      • output (create output source for event forwarding)
      • test (test functionalities)
      • settings (configures different options and preferences)
      • exit (exit from the debugger)
    • Meta Commands
      • .help (show the help of commands)
      • .debug (prepare and connect to debugger)
      • .connect (connect to a session)
      • .disconnect (disconnect from a session)
      • .listen (listen on a port and wait for the debugger to connect)
      • .status (show the debugger status)
      • .start (start a new process)
      • .restart (restart the process)
      • .attach (attach to a process)
      • .detach (detach from the process)
      • .switch (show the list and switch between active debugging processes)
      • .kill (terminate the process)
      • .process, .process2 (show the current process and switch to another process)
      • .thread, .thread2 (show the current thread and switch to another thread)
      • .pagein (bring the page into the RAM)
      • .dump (save the virtual memory into a file)
      • .formats (show number formats)
      • .script (run batch script commands)
      • .sympath (set the symbol server)
      • .sym (load pdb symbols)
      • .pe (parse PE file)
      • .logopen (open log file)
      • .logclose (close log file)
      • .cls (clear the screen)
    • Extension Commands
      • !a (assemble physical address)
      • !pte (display page-level address and entries)
      • !db, !dc, !dd, !dq (read physical memory)
      • !eb, !ed, !eq (edit physical memory)
      • !sb, !sd, !sq (search physical memory)
      • !u, !u64, !u2, !u32 (disassemble physical address)
      • !dt (display and map physical memory to structures)
      • !track (track and map function calls and returns to the symbols)
      • !epthook (hidden hook with EPT - stealth breakpoints)
      • !epthook2 (hidden hook with EPT - detours)
      • !monitor (monitor read/write/execute to a range of memory)
      • !syscall, !syscall2 (hook system-calls)
      • !sysret, !sysret2 (hook SYSRET instruction execution)
      • !mode (detect kernel-to-user and user-to-kernel transitions)
      • !cpuid (hook CPUID instruction execution)
      • !msrread (hook RDMSR instruction execution)
      • !msrwrite (hook WRMSR instruction execution)
      • !tsc (hook RDTSC/RDTSCP instruction execution)
      • !pmc (hook RDPMC instruction execution)
      • !vmcall (hook hypercalls)
      • !exception (hook first 32 entries of IDT)
      • !interrupt (hook external device interrupts)
      • !dr (hook access to debug registers)
      • !ioin (hook IN instruction execution)
      • !ioout (hook OUT instruction execution)
      • !hide (enable transparent-mode)
      • !unhide (disable transparent-mode)
      • !measure (measuring and providing details for transparent-mode)
      • !va2pa (convert a virtual address to physical address)
      • !pa2va (convert physical address to virtual address)
      • !dump (save the physical memory into a file)
      • !pcitree (show PCI/PCIe device tree)
      • !pcicam (dump the PCI/PCIe configuration space)
      • !idt (show Interrupt Descriptor Table entries)
      • !apic (dump local APIC entries in XAPIC and X2APIC modes)
      • !ioapic (dump I/O APIC)
    • Scripting Language
      • Assumptions & Evaluations
      • Variables & Assignments
      • Casting & Type-awareness
      • Conditionals & Loops
      • Constants & Functions
      • Debugger Script (DS)
      • Examples
        • view system state (registers, memory, variables)
        • change system state (registers, memory, variables)
        • trace function calls
        • pause the debugger conditionally
        • conditional breakpoints and events
        • patch the normal sequence of execution
        • access to a shared variable from different cores
        • count occurrences of events
      • Functions
        • debugger
          • pause
        • events
          • event_enable
          • event_disable
          • event_clear
          • event_sc
          • event_inject
          • event_inject_error_code
          • flush
        • exports
          • print
          • printf
        • interlocked
          • interlocked_compare_exchange
          • interlocked_decrement
          • interlocked_exchange
          • interlocked_exchange_add
          • interlocked_increment
        • memory
          • check_address
          • eb, ed, eq
          • eb_pa, ed_pa, eq_pa
          • memcpy
          • memcpy_pa
          • memcmp
          • virtual_to_physical
          • physical_to_virtual
        • diassembler
          • disassemble_len
          • disassemble_len32
        • spinlocks
          • spinlock_lock
          • spinlock_lock_custom_wait
          • spinlock_unlock
        • strings
          • strlen
          • wcslen
          • strcmp
          • strncmp
          • wcscmp
          • wcsncmp
    • Commands Map
  • Tips & Tricks
    • Considerations
      • Basic concepts in Intel VT-x
      • VMX root-mode vs VMX non-root mode
      • The "unsafe" behavior
      • Script engine in VMX non-root mode
      • Difference between process and thread switching commands
      • Accessing Invalid Address
      • Transparent Mode
    • Nested-Virtualization Environments
      • Supported Virtual Machines
      • Run HyperDbg on VMware
      • Run HyperDbg on Hyper-V
      • Supporting VMware/Hyper-V
      • VMware backdoor I/O ports
    • Misc
      • Event forwarding
      • Event short-circuiting
      • Event calling stage
      • Instant events
      • Message overflow
      • Customize build
        • Increase Communication Buffer Size
        • Number of EPT Hooks in One Page
        • Change Script Engine Limitations
      • Enable and disable events in Debugger Mode
      • Switch to New Process Layout
  • Contribution
    • Style Guide
      • Coding style
      • Command style
      • Doxygen style
    • Logo & Artworks
  • Design
    • Features
      • VMM (Module)
        • Control over NMIs
        • VMX root-mode compatible message tracing
        • Design of !epthook
        • Design of !epthook2
        • Design of !monitor
        • Design of !syscall & !sysret
        • Design of !exception & !interrupt
    • Debugger Internals
      • Events
      • Conditions
      • Actions
      • Kernel Debugger
        • Design Perspective
        • Connection
  • Links
    • Twitter
    • Telegram
    • Discord
    • Matrix
    • Mastodon
    • YouTube
    • hwdbg (Chip Debugger)
    • Doxygen
    • Contribution
Powered by GitBook
On this page
  • Command
  • Syntax
  • Description
  • Parameters
  • Examples
  • IOCTL
  • Remarks
  • Requirements
  • Related
Edit on GitHub
  1. Commands
  2. Meta Commands

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

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

Previous.kill (terminate the process)Next.thread, .thread2 (show the current thread and switch to another thread)

Last updated 3 months ago

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 . You can use the '' and the '' commands in . However, you can use it to view the list of the processes in both and .

Important: the implementation of these commands is different. Please visit 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 '' command.

Parameters

[list]

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

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

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

Related

It shows the list of processes (see ).

If the Result is DEBUGEER_OPERATION_WAS_SUCCESSFULL, the operation was successful, and you should use the '' 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.

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

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

It also means that if you press the '' 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 .

Debugger Mode
.attach
.detach
VMI Mode
VMI Mode
Debugger Mode
this article
g
Remarks
g
.sym
here
g
here
.thread, .thread2 (show the current thread and switch to another thread)
Switching to a Specific Process or Thread
Difference between process and thread switching commands