Build & Install
This document helps you to build and install HyperDbg
To build HyperDbg, you need to install the following software.
Visual Studio Community, Enterprise or Professional 2015 or later.
Windows Software Development Kit (Windows SDK)
Windows Driver Kit (WDK)
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 or Put Windows in Test Mode.
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.
Open the following file:
HyperDbg/hyperdbg/include/Configuration.hChange the following constant from FALSE to TRUE.
/**
* @brief Activates the user-mode debugger
*/
#define ActivateUserModeDebugger FALSE
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 and turn off Virtualization Based Security (VBS). Then you can run HyperDbg.
On the rest of this page, you'll read a detailed explanation about performing the above stages.
If you've ever run HyperDbg and encountered the below error, it means that VT-x is disabled from your BIOS.
Disabled VT-x From 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.
The next step is disabling Driver Signature Enforcement (DSE).
HyperDbg's driver is NOT digitally signed.
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 '!syscall' or the '!sysret', which are PatchGuard detectable, will be usable.
If you use other options, please keep in mind that you should be cautious as PatchGuard will start and detect some of the modifications and might be problematic.
- Attaching WinDbg at the boot time (Recommended)
- Temporarily Disable DSE
- Putting Windows in Test Mode
If you choose the first option, you can use kdnet.exe from Windows SDK, which is described here. After that, you'll get a key that can be used on a remote machine to debug this machine using WinDbg.
Kdnet.exe
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.
Kdnet.exe (secure boot)
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.
This is the simplest way to disable driver signature enforcement on Windows 10 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.
Bear in mind that this method only temporarily disables driver signature enforcement, and after a restart, you have to re-disable it again.
In test mode, you can install any drivers you want without experiencing any problems. Don’t forget to go to normal Windows 10 mode after you solve your problem:
- 1.Open an elevated command prompt window on your PC: right-click on the Windows Start icon and select Command prompt (Admin).
- 2.In cmd type:
bcdedit /set TESTSIGNING ON - 3.Close the cmd window and restart your computer.
- 4.Install your drivers.
The last step before running HyperDbg is disabling Virtualization Based Security (VBS).
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.
VBS running
If you see "Enabled but not running" or "Not enabled", you're good to go to the next step.
Enabled but not running
Not enabled
If the VBS is enabled, you can disable it by typing "Core isolation" on the start menu and turning off "Memory integrity".
Turn off core isolation
The above step is enough to disable the VBS. After that, you should restart your computer so that VBS will be disabled on the next start.
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.
Congratulations, you're ready to run HyperDbg. Open hyperdbg-cli.exe, and visit Quick Start to start using HyperDbg.
Last modified 1yr ago