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
  • Download & Install
  • Build & Compile
  • Starting with HyperDbg
  • Choosing Environment
  • Running HyperDbg
  • Check for VMX support
  • Disable Driver Signature Enforcement
  • Disable VBS, HVCI, and Device Guard
  • Run & Test
  • Next Step
Edit on GitHub
  1. Getting Started

Build & Install

This document helps you to build and install HyperDbg

PreviousFAQNextAttach to HyperDbg

Last updated 4 months ago

Download & Install

In order to use HyperDbg, you have two options. You can download the , or manually download the source code and compile the binaries from the source code.

If you download compiled binary files, you can skip the Build & Compile section and move to the next section, otherwise, to build HyperDbg, you need to install the following software.

Visual Studio Community, Enterprise, or Professional 2022 or later.

  • You can download it at: []

Windows Software Development Kit (Windows SDK)

  • You can download it at: []

Windows Driver Kit (WDK)

  • You can download it at: []

HyperDbg is currently compiled with the latest version of SDK and WDK. If you encounter any problems compiling with previous versions of SDK, or WDK, you have to update it before compiling HyperDbg.

Build & Compile

First, clone the project using git or download precompiled binaries from .

git clone --recursive https://github.com/HyperDbg/HyperDbg.git

Open the visual studio and build the solution.

After building, you need to disable driver signature enforcement. It is because the current versions of HyperDbg are not digitally signed.

For this purpose, you can Disable Driver Signature Enforcement.

Starting with HyperDbg

The rest of this article focuses on the process of installing and setting up HyperDbg. If you prefer a visual guide, you can watch a corresponding video instead of reading through this section.

Choosing Environment

HyperDbg works best with VMware Workstation Player/Pro.

Running HyperDbg

Running HyperDbg has multiple stages. First, you should make sure to enable Intel VT-x from the BIOS. Next, you have to disable Driver Signature Enforcement (DSE) and turn off Virtualization Based Security (VBS). Then you can run HyperDbg.

If you want to use HyperDbg on your own computer (host), for example for local kernel debugging, you need to disable Driver Signature Enforcement (DSE) on your local machine. Disabling DSE allows you to use HyperDbg (load drivers) on your own computer.

But if you want to debug a different computer (a Guest Virtual Machine), you don't need to disable it on your own computer (host). Instead, you only need to make the necessary changes on the guest machine itself.

In short:

  • Disable Driver Signature Enforcement on your own computer (host) if you want to run HyperDbg on it for local kernel debugging.

  • When debugging a remote guest machine, make the required changes on the guest machine, without disabling Driver Signature Enforcement (DSE) on your own host computer.

Remember, when attaching to a guest virtual machine, HyperDbg does not load any drivers or hypervisors on your host machine. Instead, it functions as a simple application that connects to the guest machine through the serial port and allows you to control it. In other words, HyperDbg acts as a simple bridge between your host machine and the target guest machine. It establishes a connection through the serial port without making any modifications or loading additional software on your host machine. Instead, the drivers and hypervisor will be loaded on the target guest machine.

On the rest of this page, you'll read a detailed explanation of performing the above stages.

Check for VMX support

This check should be done in the HOST machine.

If you've ever run HyperDbg and encountered the below error, it means that VT-x is disabled from your BIOS.

Enabling VT-x from BIOS is vendor-specific. Usually, if you press [F2], or [Delete], or [ESC] during the boot time, you'll enter the BIOS, and there should be an option to Support Virtualization or something like that. You should enable it from BIOS, and after that, you're good to go.

Disable Driver Signature Enforcement

The next step is disabling Driver Signature Enforcement (DSE).

HyperDbg's driver is NOT digitally signed.

If you use other options, please keep in mind that you should be cautious as PatchGuard will start and detect some of the modifications that might be problematic.

Disabling DSE can be done in three ways (you have to choose one of them):

  • Attaching WinDbg at the boot time (Recommended)

  • Temporarily Disable DSE

Disable DSE by Attaching WinDbg

To debug a target Virtual Machine (VM), you need to perform actions on both the guest and the host. In other words, WinDbg is running on the host machine, and you're using it to connect and debug the guest machine. This allows you to analyze and troubleshoot issues within the target VM by using WinDbg (like regular kernel mode debugging by using WinDbg) and when WinDbg attaches to the target VM, it disables both the Driver Signature Enforcement (DSE) and if it's connected from the very first start of the Windows boot, it disables PatchGuard initialization.

HyperDbg won't import (or need) anything from WinDbg. We only need it to disable DSE and PatchGuard.

When you load the HyperDbg's driver, you can close the WinDbg, and everything is handled in HyperDbg, and no need for WinDbg anymore. We want WinDbg to avoid starting PatchGuard and let us load our unsigned driver.

If your computer has the secure boot enabled, you'll see the following error.

That's it all. We're good to go to the next section.

Temporarily Disable DSE

If you couldn't disable the DSE and PatchGuard by using the first option, you can perform this option. The following actions should be done in the guest if you want to debug a Virtual Machine (VM).

This is the simplest way to disable driver signature enforcement on Windows 10, and 11 but bear in mind that this method will temporarily disable driver signature enforcement.

After you restart, your computer driver signature enforcement will automatically turn itself on.

To disable driver signature enforcement, do the following:

  1. Press and hold the Shift key on your keyboard and click the Restart button.

  2. Choose to Troubleshoot > Advanced options > Startup Settings and click the Restart button.

  3. When your computer restarts, you’ll see a list of options. Press F7 on your keyboard to select Disable driver signature enforcement.

  4. Your computer will now restart, and you’ll be able to install unsigned drivers.

Keep in mind that this method only temporarily disables driver signature enforcement, and after a restart, you have to re-disable it again, and also it won't disable the PatchGuard, so, some of the commands that are not PatchGuard compatible won't work when you use this method.

Using EfiGuard

Disable VBS, HVCI, and Device Guard

The last step before running HyperDbg is disabling Virtualization Based Security (VBS).

Please note that to utilize HyperDbg in a nested-virtualization setup like VMware Workstation, ensure that VBS, Hyper-V 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 and the target guest debuggee must have Hyper-V disabled.

HyperDbg and VBS are both hypervisors running on ring -1. These hypervisors are not compatible, and you should disable VBS (and its sub-components like HVCI, Device Guard, etc.).

To check whether VBS is running on your system, type System Information on the start menu and click on the System Information app. After that, check whether the VBS is running or not like the below picture.

If you see "Enabled but not running" or "Not enabled", you're good to go to the next step.

If the VBS is enabled, you can disable it by typing "Core isolation" on the start menu and turning off "Memory integrity".

After that, go to "Turn Windows features on or off", and disable "Virtual Machine Platform" and "Windows Hypervisor Platform".

The above steps is enough to disable the VBS. After that, you should restart your computer so that VBS will be disabled on the next start. Once the computer started, check the System Information app again to see whether Virtualization-based security is disabled or not.

Done! The rest of this section describes other methods for disabling VBS, you don't need to follow it if you successfully disabled VBS.

If the above method didn't work for you, open Local Group Policy Editor (gpedit.msc) and navigate to the following path:

Local Computer Policy\Computer Configuration\Administrative Templates\System\Device Guard

Click on Turn on Virtualization Based Security.

Then choose the 'Disabled' option and click 'OK'.

After that, you should restart your computer and recheck System Information to see if it's still running or not.

Run & Test

Congratulations, you're ready to run HyperDbg.

From now on, you can either,

Next Step

You can run HyperDbg on your physical machine in the (local debugging), but you can't pause or step through the instruction in this execution mode. If you want to thoroughly use HyperDbg as a debugger (not as a system-log generator), you should use it with a virtual machine in the .

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

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

Please note that HyperDbg is currently available only for processors.

In order to disable driver signature enforcement, we have plenty of options. However, we recommend the first option, which is attaching WinDbg at the boot time. It's because this way, PatchGuard will not start, and some of HyperDbg's commands like the '' or the '', which are PatchGuard detectable, will be usable. Alternatively, you can use to use bypass both PatchGuard and DSE without using WinDbg.

Using

If you choose this option, you can use kdnet.exe from Windows SDK, please read in order to understand how you can use kdnet. After that, performing the actions described , you'll get a key that can be used on a remote machine to debug this machine using WinDbg, so, run the KDNET in your guest machine and get the keys and use the keys in the host machine.

You can disable secure boot from the BIOS. Most of the time, you should change the secure boot option to "Other OSes" that are not Windows, alternatively you .

You can use to disable both Driver Signature Enforcement (DSE) and PatchGuard. This way, you don't need to use WinDbg.

For more information, please visit the main , or if you want to use it on VMware, you can visit or this .

There are also other options to disable VBS as described .

or visit to start using HyperDbg.

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.

latest compiled binaries
https://www.visualstudio.com/downloads
https://developer.microsoft.com/en-us/windows/downloads/windows-sdk/
https://developer.microsoft.com/en-us/windows/hardware/windows-driver-kit
here
VMI Mode
Debugger Mode
https://www.vmware.com/products/workstation-player/workstation-player-evaluation.html
discussion
Telegram
Discord
Matrix
Intel
!syscall
!sysret
EfiGuard
EfiGuard
this documentation
here
disable secure boot in VMware
EfiGuard
repo
here
demo
here
Attach to a remote machine
Attach to the local machine
Quick Start
OST2's website
YouTube
Starting with HyperDbg
Disabled VT-x From BIOS
Kdnet.exe
Kdnet.exe (secure boot)
VBS running
Enabled but not running
Not enabled
Turn off core isolation
Disabling Windows Features