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
  • Downloading VMware
  • Connect to Debuggee (Debugger Mode)
  • Physical Machine (Host)
  • VMware Workstation Player or Pro (Guest)
  • VMware Workstation (Two VMs)
  • Connect to Debuggee (VMI Mode)
  • Disable VBS, and Hyper-V on Host
  • Next Step
Edit on GitHub
  1. Getting Started
  2. Attach to HyperDbg

Attach to a remote machine

Remote debugging in VMI Mode and Debugger Mode

PreviousAttach to HyperDbgNextAttach to local machine

Last updated 12 months ago

If you have access to a remote physical machine or a nested virtualization environment like (VMware Workstation, VirtualBox, Hyper-V, etc.), you can operate in both and .

In VMI Mode, you can't break the kernel mode and step through the kernel instructions; still, you can step and break user-mode applications. This mode needs a network connection (TCP).

In Debugger Mode, you can break the kernel mode and step through the kernel instructions. It needs a serial (cable or virtual device) to connect to the target machine.

If you've attempted all the provided instructions without success, we encourage you to initiate a ''. Outline your issue comprehensively, and we'll be more than happy to assist you in getting started with HyperDbg :)

Downloading VMware

HyperDbg works best with VMware Workstation Player/Pro.

You can download VMware Workstation Player (Free Non-commercial License) at: []

After that, you should install your desired operating system (Windows 10, or 11) on your VMware as a guest. Once, you finished installing your virtual machine, you can continue the rest of this article.

Here is a quick video that describes how to set up HyperDbg with VMware Workstation Pro/Player.

Connect to Debuggee (Debugger Mode)

For connecting in debugger mode, first, you need to provide a serial device.

Physical Machine (Host)

In order to connect to a physical machine in debugger mode, you need a physical serial port. After that, connect your target machine (debuggee) to another machine.

Debuggee needs to support Intel VMX and Intel EPT; however, the debugger does not need to support any special CPU feature and can be run on any machine, including a machine with an AMD processor.

If you want to have a kernel debug connection, first, you should run the following command in a debugger (host). As you can see, you can change the com3to your COM port that is connected to the debuggee. You can see connected COM ports on the device manager.

HyperDbg> .debug remote serial 115200 com3

If you want to use a named pipe instead of a COM port, you can execute the following command in the debugger (Host).

HyperDbg> .debug remote namedpipe \\.\pipe\HyperDbgPipe

After you tell the debugger to listen on a COM port or a named pipe, now you can run the following command in the debuggee.

HyperDbg> .debug prepare serial 115200 com2

VMware Workstation Player or Pro (Guest)

In order to run HyperDbg on a VMware Workstation machine, first, turn off your guest machine then, you need to enable Nested Virtualization. Open your virtual machine and click on Edit virtual machine settings.

You can use both VMware Workstation pro as well as VMware Workstation Player (Free for non-commercial use).

After that, click on Virtualize Intel VT-x/EPT or AMD-V/RVI and Virtualize IOMMU (IO memory management unit).

Okay, let's continue to the next step. You should create a serial port here. Click on Add... then choose Serial Port and click on Finish.

Now, click on Use named pipe: and add a name for your named pipe.

Your name should start with \\.\pipe\ . For example, choose \\.\pipe\HyperDbgDebug.

Make sure to enable Yield CPU on poll.

Now it's time to create a kernel debug connection. First of all, run the following command on the host (debugger). You should change the named pipe address to whatever name you chose on the previous part.

HyperDbg> .debug remote namedpipe \\.\pipe\HyperDbgPipe

After you tell the debugger to listen on a COM port or a named pipe, now you can run the following command in the debuggee (guest).

HyperDbg> .debug prepare serial 115200 com2

Most of the time, if the serial port is the only serial device that you add to the virtual machine, then the name of the connected port is com2. However, you can see the exact name of the COM port on the guest's device manager.

Please note that HyperDbg differs from WinDbg as it requires installation in both the target virtual machine and the host. Unlike WinDbg, which only needs to be installed on the host.

To use HyperDbg, the debugger should be started and listening on the host before connecting to it from the guest. Therefore, it is important to execute the commands on the debugger (host) first, and then connect to it from the debuggee (guest).

Done! You successfully connected to the HyperDbg.

The rest of this section is for special cases like if you want to connect HyperDbg from two VMs (without running HyperDbg on the Host), possible errors that you might encounter during the setup, and solutions.

VMware Workstation (Two VMs)

To run HyperDbg on two different guest virtual machines (rather than running it on the host), you can use the following instructions.

Serial Port Configuration – Debugger

To configure the debugger VM, follow these steps:

  1. Enable the option 'Used named pipe' and assign a custom name to the named pipe, such as \.\pipe\HyperDbgDebug.

  2. Select 'This end is the server' and 'The other end is an application.'

  3. Ensure that 'Yield CPU on poll' is enabled.

Serial Port Configuration – Debuggee

To configure the debuggee VM, follow these steps:

  1. Enable the option 'Used named pipe' and use the same name you previously selected for the debugger (e.g., \.\pipe\HyperDbgDebug).

  2. Select 'This end is the client' and 'The other end is an application.'

  3. Ensure that 'Yield CPU on poll' is enabled.

Once you've done configuring the serial ports, the next step is attaching to HyperDbg. Follow the steps outlined in the next section to establish a connection between the two VMs.

Connecting from VMs

On the debugger side, open HyperDbg and run the following command to listen on the serial port (ensure to replace "COM2" with the specific COM port assigned to your connection, most of the time it is COM1, COM2, or COM3):

HyperDbg> .debug remote serial 115200 com2

On the debuggee side, run the following command.

HyperDbg> .debug prepare serial 115200 com2

Note that there is a possibility that the COM port assigned to the debuggee and the debugger could be different. For instance, the debugger may be configured to use COM2, while the debuggee could be using COM1. It is important to take note of this potential difference and ensure that you consider the correct COM port assignments for both the debugger and the debuggee.

Done! You can use HyperDbg and control your debuggee from the debugger.

Connect to Debuggee (VMI Mode)

If you want to run HyperDbg in VMI Mode, you can follow the below steps.

First, make sure you have access to the remote machine by pinging its IP address and checking firewall rules. After that, run the following command in debuggee (guest).

HyperDbg> listen
listening on 50000 ...

The default port for HyperDbg is 50000, but if you want to choose another port, then add an argument as the port to the listen (e.g. 45000).

HyperDbg> listen 45000
listening on 45000 ...

Now, go to your debugger (host) system and run the following command. Make sure to change the IP address and port.

HyperDbg> .connect 192.168.1.10 50000
connected to 192.168.1.10:50000

After that, you see a connected message with an IP address of the debugger (host) in debuggee (guest).

HyperDbg> listen
listening on 50000 ...
connected to : 127.0.0.1:52830

Disable VBS, and Hyper-V on Host

If you see the error "Virtualized Intel VT-x/EPT is not supported on this platform.", you can perform the following instructions to solve it.

bcdedit /set hypervisorlaunchtype off

Once you're done with using HyperDbg, if you want to re-enable Hyper-V, you can run the following command (as administrator) and restart your computer.

bcdedit /set hypervisorlaunchtype auto

Next Step

Please be aware that if you encounter an error indicating that 'nested virtualization is not supported' when attempting to launch the virtual machine at a later time, it could be due to the presence of VBS or Hyper-V running on the host system. It's important to note that VMware Workstation does not offer support for nested virtualization while Hyper-V is active. In order to address this, you must first disable Hyper-V, following the instructions provided .

If you see an error for driver signature enforcement, please visit .

First of all, use the instructions provided , to create a serial port on both the debugger VM and the debuggee VM.

You can see the state of the debugger by using the '' command.

Important note: To utilize HyperDbg in a nested-virtualization setup like VMware Workstation, ensure that Hyper-V it is disabled on both the host and the guest machine. Although VMware Workstation and Hyper-V have become compatible, as of the document's current version, VMware Workstation's nested-virtualization feature is not supported when Hyper-V is enabled. Therefore, even if you are running two virtual machines, the primary host must have Hyper-V disabled. For more instructions, please visit .

First, make sure the VBS, HVCI, or Hyper-V is disabled in the Host as described . If it didn't solve the problem, you can run the following command (as administrator) and restart your computer to disable hypervisor auto-launch.

The OpenSecurityTraining2's "Reversing with HyperDbg (Dbg3301)" tutorial series, available on (preferred) and is the recommended way to get started with and learn HyperDbg. It guides you through the initial steps of using HyperDbg, covering essential concepts, principles, and debugging functionalities, along with practical examples and numerous reverse engineering methods that are unique to HyperDbg.

here
here
above
.status
here
here
OST2's website
YouTube
VMI Mode
Debugger Mode
discussion
https://www.vmware.com/products/workstation-player/workstation-player-evaluation.html
Getting Started with HyperDbg
Editing VM Settings
Enabling Nested-Virtualization
Adding a serial device
Change serial device configuration