HyperDbg Debugger

https://doxygen.hyperdbg.org/
Admin
HyperDbg is an open-source, hypervisor-assisted Windows debugger for kernel and user-mode debugging...
Tokens:3,689,512
Snippets:22,258
Trust Score:5.7
Update:1 year ago
Show doc for...
Tokens:
Raw
### Path and Test Setup Functions (C++)

Source: https://doxygen.hyperdbg.org/globals_func_s

Functions for setting up installation paths and test names. 'SetupPathForFileName' is for managing file paths, while 'SetupTestName' is for naming test cases.

```cpp
SetupPathForFileName();

```

```cpp
SetupTestName();

```

--------------------------------

### Display Help Message Syntax

Source: https://doxygen.hyperdbg.org/help_8cpp

This snippet demonstrates how to display the syntax and examples for the '.help' command. It utilizes the 'ShowMessages' function to output formatted text to the console, guiding users on how to use the help command effectively.

```C++
#include "pch.h"

VOID CommandHelpHelp ()
{
    ShowMessages(".help : shows help and example(s) of a specific command.\n\n");
    ShowMessages("syntax : \t.help [Command (string)]\n");
    ShowMessages("\n");
    ShowMessages("\te.g : .help !monitor\n");
}
```

--------------------------------

### ManageDriver API

Source: https://doxygen.hyperdbg.org/install_8cpp

Manages the installation, removal, starting, and stopping of system drivers.

```APIDOC
## ManageDriver()

### Description
Manages the installation, removal, starting, and stopping of system drivers.

### Method
Not specified (likely a function call within a library or application).

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **DriverName** (LPCTSTR) - Required - The name of the driver.
- **ServiceName** (LPCTSTR) - Required - The name of the service associated with the driver.
- **Function** (UINT16) - Required - The function to perform. Possible values include DRIVER_FUNC_INSTALL, DRIVER_FUNC_STOP, DRIVER_FUNC_REMOVE.

### Request Example
(Code example not directly applicable for a function call, but illustrates usage)
```c
ManageDriver("MyDriver", "MyService", DRIVER_FUNC_INSTALL);
```

### Response
#### Success Response (BOOLEAN)
- **TRUE**: Operation successful.
- **FALSE**: Operation failed.

#### Response Example
```
TRUE
```
```

--------------------------------

### Display Help for 'lm' Command in C++

Source: https://doxygen.hyperdbg.org/lm_8cpp

Displays detailed help information for the 'lm' command. This function prints usage syntax, examples, and descriptions of parameters like 'Name', 'pid', and 'Filter'. It is used to guide users on how to effectively utilize the 'lm' command for listing user/kernel modules.

```cpp
VOID CommandLmHelp() {
    ShowMessages("lm : lists user/kernel modules' base address, size, name and path.\n\n");

    ShowMessages("syntax : 	lm [m Name (string)] [pid ProcessId (hex)] [Filter (string)]\n");

    ShowMessages("\n");
    ShowMessages("	e.g : lm\n");
    ShowMessages("	e.g : lm km\n");
    ShowMessages("	e.g : lm um\n");
    ShowMessages("	e.g : lm m nt\n");
    ShowMessages("	e.g : lm km m ntos\n");
    ShowMessages("	e.g : lm um m kernel32\n");
    ShowMessages("	e.g : lm um m kernel32 pid 1240\n");
}
```

--------------------------------

### Setup HyperDbg Script Engine Test Environment - Python

Source: https://doxygen.hyperdbg.org/namespacetest-environment

This Python function, `main`, orchestrates the setup of the HyperDbg script engine test environment. It defines source and multiple destination directories, creates necessary directories, removes existing ones if they exist, and utilizes the `copy_dir` function to copy test case files. It also includes print statements for user feedback.

```python
def main():

    # 
    # Create script engine test files
    # 
    print("Creating script engine test environment...")

    from_dir = "..\\hyperdbg\\script-engine\\modules\\script-engine-test\\script-test-cases"
    to_dir1 = "..\\hyperdbg\\hyperdbg-cli\\script-test-cases"

    if os.path.exists(to_dir1) and os.path.isdir(to_dir1):
        shutil.rmtree(to_dir1)
    
    os.mkdir(to_dir1)
    
    copy_dir(from_dir, to_dir1)
    
    #
    # copy to build directories
    #
    to_dir2 = "..\\hyperdbg\\build\\bin\\debug"
    to_dir3 = "..\\hyperdbg\\build\\bin\\release"
    
    if os.path.exists(to_dir2) :
        to_dir2 = to_dir2 + "\\script-test-cases"
    
    if os.path.exists(to_dir2) and os.path.isdir(to_dir2):
        shutil.rmtree(to_dir2)
    
    os.mkdir(to_dir2)
    copy_dir(from_dir, to_dir2) 
    
    if os.path.exists(to_dir3) :
        to_dir3 = to_dir3 + "\\script-test-cases"
    
    if os.path.exists(to_dir3) and os.path.isdir(to_dir3):
        shutil.rmtree(to_dir3)
    
    os.mkdir(to_dir3)
    copy_dir(from_dir, to_dir3)
    
    
    
    if os.path.exists(to_dir2) :
        to_dir2 = to_dir2 + "\\script-test-cases"
    
    
    print("Testing environment is made successfully")
    
    
main
```

--------------------------------

### HyperDbg load Command Help

Source: https://doxygen.hyperdbg.org/help_8h

Provides help for the 'load' command in HyperDbg, used to install drivers and load modules. It specifies the syntax for loading a module by its name and provides an example.

```text
ShowMessages("load : installs the drivers and load the modules.\n\n");

ShowMessages("syntax : \tload [ModuleName (string)]\n");

ShowMessages("\n");
ShowMessages("\t\te.g : load vmm\n");

```

--------------------------------

### Start Process (C)

Source: https://doxygen.hyperdbg.org/_hyper_dbg_lib_imports_8h_source

Starts a new process. It takes the path to the executable as an argument. This is a simplified version of starting a process without command-line arguments.

```c
IMPORT_EXPORT_LIBHYPERDBG BOOLEAN hyperdbg_u_start_process(const WCHAR *path)
```

--------------------------------

### Start Process with Arguments using C

Source: https://doxygen.hyperdbg.org/_hyper_dbg_lib_imports_8h

Starts a new process with specified arguments. It requires the path to the executable and a string containing the arguments. Returns true on success.

```c
BOOLEAN hyperdbg_u_start_process_with_args(const WCHAR * _path_, const WCHAR * _arguments_)
{
 return UdAttachToProcess(NULL, _path_, _arguments_, FALSE);
}
```

--------------------------------

### Start Process (C)

Source: https://doxygen.hyperdbg.org/export_8cpp

Launches a new process. Supports starting a process with specified arguments.

```c
#include "pch.h"

BOOLEAN hyperdbg_u_start_process (const WCHAR *path)
{
  // Function implementation details would go here.
  return FALSE; // Placeholder
}

BOOLEAN hyperdbg_u_start_process_with_args (const WCHAR *path, const WCHAR *arguments)
{
  // Function implementation details would go here.
  return FALSE; // Placeholder
}
```

--------------------------------

### Start Process

Source: https://doxygen.hyperdbg.org/_hyper_dbg_lib_imports_8h

Starts a new process. Can optionally include command-line arguments.

```APIDOC
## hyperdbg_u_start_process

### Description
Start a new process.

### Method
BOOLEAN (No HTTP method applicable, this is a library function)

### Endpoint
N/A

### Parameters
#### Path Parameters
N/A

#### Query Parameters
N/A

#### Request Body
- **path** (const WCHAR *) - The path to the executable file for the new process.
```

```APIDOC
## hyperdbg_u_start_process_with_args

### Description
Start a new process with specified command-line arguments.

### Method
BOOLEAN (No HTTP method applicable, this is a library function)

### Endpoint
N/A

### Parameters
#### Path Parameters
N/A

#### Query Parameters
N/A

#### Request Body
- **path** (const WCHAR *) - The path to the executable file for the new process.
- **arguments** (const WCHAR *) - The command-line arguments for the new process.
```

--------------------------------

### Display CommandStart Help in C++

Source: https://doxygen.hyperdbg.org/start_8cpp

Provides help information for the '.start' command. It displays the syntax for running a user-mode process and provides an example of its usage, including specifying the path to the executable.

```cpp
ShowMessages(".start : runs a user-mode process.\n\n");
ShowMessages("syntax : \t.start [path Path (string)] [Parameters (string)]\n");
ShowMessages("\n");
ShowMessages("\te.g : .start path c:\\reverse eng\\my_file.exe\n");
```

--------------------------------

### StartDriver Function in C

Source: https://doxygen.hyperdbg.org/install_8cpp

Starts a driver service. It takes the SCM handle and the driver name as input. Returns TRUE if the start request is successful, FALSE otherwise. This function is used by ManageDriver after installing a driver.

```c
BOOLEAN StartDriver(SC_HANDLE SchSCManager, LPCTSTR DriverName) {
    // Implementation details for starting the driver service would be here.
    // This function is called by ManageDriver.
    // Example: StartService(SchService, ...);
    return TRUE; // Placeholder
}
```

--------------------------------

### Core HyperDbg Project Setup (C/C++)

Source: https://doxygen.hyperdbg.org/include_2_s_d_k_2_examples_2hyperdbg__app_2header_2pch_8h_source

This snippet shows the essential preprocessor directives and include statements for setting up a HyperDbg user-mode reversing module. It includes environment headers, Windows SDK headers (with WIN32_LEAN_AND_MEAN defined), and HyperDbg SDK headers.

```c++
#pragma once

//
// Environment headers
//
#include "platform/user/header/Environment.h"

//
// Windows SDK headers
//
#define WIN32_LEAN_AND_MEAN

//
// Scope definitions
//
#define HYPERDBG_USER_MODE_REVERSING_MODULE

#include <Windows.h>

#include <iostream>
#include <stdio.h>
#include <string>

//
// HyperDbg SDK headers
//
#include "SDK/HyperDbgSdk.h"
#include "SDK/Imports/User/HyperDbgLibImports.h"
```

--------------------------------

### Get Output Sources Initialized Status

Source: https://doxygen.hyperdbg.org/kernel-listening_8cpp

Indicates whether the debugger has started using output sources.

```APIDOC
## Get g_OutputSourcesInitialized

### Description
Shows whether the debugger started using output sources or not.

### Method
Not Applicable (Global Variable Access)

### Endpoint
Not Applicable (Global Variable Access)

### Parameters
None

### Request Example
```c
// Example usage (conceptual)
BOOLEAN outputSourcesInit = g_OutputSourcesInitialized;
```

### Response
#### Success Response (200)
- **g_OutputSourcesInitialized** (BOOLEAN) - TRUE if output sources are initialized, FALSE otherwise.

#### Response Example
```json
{
  "status": "success",
  "outputSourcesInitialized": true
}
```
```

--------------------------------

### Initialize Hypervisor

Source: https://doxygen.hyperdbg.org/_hv_8h

Initializes the hypervisor, likely setting up essential structures and callbacks. It takes a pointer to VMM_CALLBACKS.

```C
BOOLEAN HvInitVmm (VMM_CALLBACKS *VmmCallbacks)
```

--------------------------------

### Get Maximum Instruction Length (C)

Source: https://doxygen.hyperdbg.org/_address_check_8c

Returns the maximum possible length of an instruction that can be read starting from the provided memory address.

```c
#include "pch.h"

UINT32 CheckAddressMaximumInstructionLength (PVOID Address)
```

--------------------------------

### Direct VMCALL Setup for EPT Hooks

Source: https://doxygen.hyperdbg.org/_hooks_8h_source

A function that uses a direct VMCALL to set up an EPT hook. This is a specialized method for hook installation.

```c
BOOLEAN EptHookFromVmxRoot(PVOID TargetAddress);
```

--------------------------------

### Initialize Hypervisor (C)

Source: https://doxygen.hyperdbg.org/_hv_8h

Initializes the hypervisor by saving callbacks, performing compatibility checks, allocating guest state, and initializing VMX. It relies on functions like CompatibilityCheckPerformChecks, GlobalGuestStateAllocateZeroedMemory, and VmxInitialize.

```c
BOOLEAN HvInitVmm(VMM_CALLBACKS* _VmmCallbacks_) {
    ULONG ProcessorsCount;
    BOOLEAN Result = FALSE;

    RtlCopyMemory(&g_Callbacks, _VmmCallbacks_, sizeof(VMM_CALLBACKS));
    CompatibilityCheckPerformChecks();
    Result = GlobalGuestStateAllocateZeroedMemory();

    if (!Result) {
        return FALSE;
    }

    ProcessorsCount = KeQueryActiveProcessorCount(0);

    for (UINT32 i = 0; i < ProcessorsCount; i++) {
        g_GuestState[i].CoreId = i;
    }

    MemoryMapperInitialize();
    g_TransparentMode = FALSE;
    g_WaitingForInterruptWindowToInjectPageFault = FALSE;

    return VmxInitialize();
}
```

--------------------------------

### Get Symbol Buffer Head Wrapper (C++)

Source: https://doxygen.hyperdbg.org/libhyperdbg_2header_2script-engine_8h_source

Retrieves the 'head' or starting element of a symbol buffer. Useful for accessing the first entry in a symbol list.

```cpp
UINT64 ScriptEngineWrapperGetHead(PVOID SymbolBuffer)
```

--------------------------------

### Start Command Handler and Help - C++

Source: https://doxygen.hyperdbg.org/start_8cpp

Provides the C++ implementation for the '.start' command handler and its help function. It utilizes standard string vectors and commands for its operation. Dependencies include 'pch.h'.

```cpp
#include "pch.h"

VOID CommandStartHelp ()
|
| help of the .start command

VOID CommandStart (vector< string > SplitCommand, string Command)
|
| .start command handler

```

--------------------------------

### HyperDbg .start command help

Source: https://doxygen.hyperdbg.org/help_8h

Provides help for the '.start' command, used to execute a user-mode process. It takes the process path and optional parameters as input.

```C
VOID CommandStartHelp(VOID)
{
    ShowMessages(".start : runs a user-mode process.\n\n");

    ShowMessages("syntax : \t.start [path Path (string)] [Parameters (string)]\n");

    ShowMessages("\n");
    ShowMessages("\te.g : .start path c:\\reverse eng\\my_file.exe\n");
}
```

--------------------------------

### Get Event ID (Kernel Mode)

Source: https://doxygen.hyperdbg.org/_pseudo_registers_8c

Retrieves the event ID, which is derived from the Tag member of the ACTION_BUFFER structure minus a starting seed value. This is implemented for kernel-mode operations.

```c
#ifdef SCRIPT_ENGINE_KERNEL_MODE
return (ActionBuffer->Tag - DebuggerEventTagStartSeed);
#endif // SCRIPT_ENGINE_KERNEL_MODE
```

--------------------------------

### C++ Help Function: CommandStartHelp

Source: https://doxygen.hyperdbg.org/interpreter_8cpp

Provides help for the '.start' command. This function has no parameters.

```cpp
VOID CommandStartHelp()
```

--------------------------------

### Implement CommandStart in C++

Source: https://doxygen.hyperdbg.org/start_8cpp

Handles the '.start' command to launch a user-mode process. It parses the command line, extracts the executable path and arguments, and optionally attaches to the process. This function checks for debugger activation and handles incorrect command usage.

```cpp
#if ActivateUserModeDebugger == FALSE

if (!g_IsSerialConnectedToRemoteDebugger)
{
ShowMessages("the user-mode debugger in VMI Mode 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. But starting processes is fully supported "
"in the Debugger Mode.\n"
"(it's not recommended to use it in VMI Mode yet!)\n");
return;
}

#endif // !ActivateUserModeDebugger

if (SplitCommand.size() <= 2)
{
ShowMessages("incorrect use of the '.start'\n\n");
CommandStartHelp();
return;
}

if (!SplitCommand.at(1).compare("path"))
{
Trim(Command);
Command.erase(0, SplitCommand.at(0).size());
Command.erase(0, 4 + 1);
Trim(Command);
SplitPathAndArgs(PathAndArgs, Command);
StringToWString(g_StartCommandPath, PathAndArgs.at(0));

if (PathAndArgs.size() != 1)
{
for (auto item : PathAndArgs)
{
Arguments += item + " ";
}
Arguments.pop_back();
StringToWString(g_StartCommandPathAndArguments, Arguments);
}
}
else
{
ShowMessages("err, couldn't resolve error at '%s'\n\n",
SplitCommand.at(1).c_str());
CommandStartHelp();
return;
}

if (Arguments.empty())
{
UdAttachToProcess(NULL,
g_StartCommandPath.c_str(),
NULL,
FALSE);
}
else
{
UdAttachToProcess(NULL,
g_StartCommandPath.c_str(),
(WCHAR *)g_StartCommandPathAndArguments.c_str(),
FALSE);
}
}
```

--------------------------------

### Manage VMM Driver with HyperDbg

Source: https://doxygen.hyperdbg.org/globals_h

Functions for installing, starting, stopping, and uninstalling the VMM driver for HyperDbg. These operations are crucial for setting up and tearing down the debugging environment. They interact with the core HyperDbg library.

```cpp
HyperDbgInstallVmmDriver()
HyperDbgLoadVmmModule()
HyperDbgStopDriver()
HyperDbgStopVmmDriver()
HyperDbgUninstallDriver()
HyperDbgUninstallVmmDriver()
HyperDbgUnloadVmm()
```

--------------------------------

### DriverEntry

Source: https://doxygen.hyperdbg.org/include_2_s_d_k_2_examples_2hyperdbg__driver_2header_2driver_2_driver_8h

Initializes the driver and sets up device and I/O handling.

```APIDOC
## POST /DriverEntry

### Description
Loads and unloads the driver, setting up the device for interaction with user-mode.

### Method
POST

### Endpoint
/DriverEntry

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **DriverObject** (PDRIVER_OBJECT) - Required - Represents the driver object.
- **RegistryPath** (PUNICODE_STRING) - Required - The registry path for the driver.

### Request Example
```json
{
  "DriverObject": "<driver_object_address>",
  "RegistryPath": "<registry_path>"
}
```

### Response
#### Success Response (200)
- **Ntstatus** (NTSTATUS) - Indicates the success or failure of the operation.

#### Response Example
```json
{
  "Ntstatus": "STATUS_SUCCESS"
}
```
```

--------------------------------

### Get help for struct command in HyperDbg

Source: https://doxygen.hyperdbg.org/dt-struct_8cpp

This function provides help information for the 'struct' command in HyperDbg. It likely displays usage instructions, available options, and examples for displaying structure data.

```cpp
#include "pch.h"

VOID | CommandStructHelp ()
| help of the struct command   
```

--------------------------------

### Get help for dt command in HyperDbg

Source: https://doxygen.hyperdbg.org/dt-struct_8cpp

This function provides help information for the 'dt' command in HyperDbg. It likely displays usage instructions, available options, and examples for displaying type information.

```cpp
#include "pch.h"

VOID | CommandDtHelp ()
| help of the dt command   
```

--------------------------------

### Starting a Target Process with Arguments (C++)

Source: https://doxygen.hyperdbg.org/commands_8h

Demonstrates the logic within CommandRev for handling the '.start path' command. This snippet shows how to parse the target executable path and its arguments, trim the command string, split the path from arguments, and convert them to wide strings for process attachment. It includes checks for the correct number of arguments and handles cases with or without command-line arguments.

```cpp
// ... inside CommandRev function ...

if (!SplitCommand.at(1).compare("path")) {
    // Trim the command
    Trim(Command);

    // Remove '!rev' from it
    Command.erase(0, SplitCommand.at(0).size());

    // Remove path + space
    Command.erase(0, 4 + 1);

    // Trim it again
    Trim(Command);

    // Split Path and args
    SplitPathAndArgs(PathAndArgs, Command);

    // Convert path to wstring
    StringToWString(g_StartCommandPath, PathAndArgs.at(0));

    if (PathAndArgs.size() != 1) {
        // There are arguments to this command
        for (auto item : PathAndArgs) {
            Arguments += item + " ";
        }
        // Remove the latest space
        Arguments.pop_back();
        // Convert arguments to wstring
        StringToWString(g_StartCommandPathAndArguments, Arguments);
    }
}

// ... rest of the function ...

if (Arguments.empty()) {
    UdAttachToProcess(NULL,
        g_StartCommandPath.c_str(),
        NULL,
        TRUE);
} else {
    UdAttachToProcess(NULL,
        g_StartCommandPath.c_str(),
        (WCHAR *)g_StartCommandPathAndArguments.c_str(),
        TRUE);
}

```

--------------------------------

### Initialize Hypervisor (C)

Source: https://doxygen.hyperdbg.org/_export_8c

Initializes the hypervisor with provided callback functions. It's a crucial first step for hypervisor operations. Returns a boolean indicating success.

```C
BOOLEAN VmFuncInitVmm(VMM_CALLBACKS * _VmmCallbacks_)
{
 return HvInitVmm(VmmCallbacks);
}
```

--------------------------------

### HyperDbg !syscall Command Syntax and Examples

Source: https://doxygen.hyperdbg.org/syscall-sysret_8cpp

Provides a comprehensive guide to the !syscall command in HyperDbg. It explains how to monitor and hook syscall instructions by accessing memory and checking instructions, or by emulating #UDs. The description includes command syntax with various parameters like SyscallNumber, ProcessId, CoreId, IsImmediate, EnableShortCircuiting, CallingStage, PreAllocatedBuffer, Script, Condition, Code, and OutputName, along with illustrative examples.

```plaintext
syntax : 	!syscall [SyscallNumber (hex)] [pid ProcessId (hex)] [core CoreId (hex)] [imm IsImmediate (yesno)] [sc EnableShortCircuiting (onoff)] [stage CallingStage (prepostall)] [buffer PreAllocatedBuffer (hex)] [script { Script (string) }] [asm condition { Condition (assembly/hex) }] [asm code { Code (assembly/hex) }] [output {OutputName (string)}]

	e.g : !syscall
	e.g : !syscall2
	e.g : !syscall 0x55
	e.g : !syscall2 0x55
	e.g : !syscall 0x55 pid 400
	e.g : !syscall 0x55 core 2 pid 400
	e.g : !syscall2 0x55 core 2 pid 400
	e.g : !syscall script { printf("system-call num: %%llx, at process id: %%x\
", @rax, $pid); }
	e.g : !syscall asm code { nop; nop; nop }
```

--------------------------------

### ExecTrapInitialize()

Source: https://doxygen.hyperdbg.org/_exec_trap_8h

Initializes the reversing machine by performing compatibility checks, allocating page tables for mode-based execution control, and setting up hooks.

```APIDOC
## ExecTrapInitialize()

### Description
Initializes the reversing machine based on service request. This involves checking processor compatibility for Mode-Based Execution Controls (MBEC), allocating EPT page tables for user and kernel mode, and initializing mode-based hooks.

### Method
BOOLEAN

### Endpoint
N/A (This is a function call, not a network endpoint)

### Parameters
None

### Request Example
```c
// No specific request body for this function call
ExecTrapInitialize();
```

### Response
#### Success Response (TRUE)
- **Success**: Returns TRUE if the initialization is successful.

#### Response Example
```json
{
  "Success": true
}
```

#### Failure Response (FALSE)
- **Failure**: Returns FALSE if the reversing machine is already initialized, the processor does not support MBEC, or if any of the initialization steps fail.

#### Response Example
```json
{
  "Success": false
}
```
```

--------------------------------

### C Macro: _LIST_FOR_NEXT for linked list traversal

Source: https://doxygen.hyperdbg.org/_meta_macros_8h

Defines a macro to get the next element in a linked list traversal. It takes the starting point, list head, type, member name, and a variable name. It relies on _NEXT_ENTRY and UNIQUE_NAME.

```c
#define _LIST_FOR_NEXT(_start, _head, _type, _member, _var) \
for (_type * _var = _NEXT_ENTRY(_start, _member, _type), *UNIQUE_NAME(_n) = _NEXT_ENTRY(_var, _member, _type); \
&_var->_member != &_head; \
_var = UNIQUE_NAME(_n), UNIQUE_NAME(_n) = _NEXT_ENTRY(_var, _member, _type))
```

--------------------------------

### CheckAddressMaximumInstructionLength: Get Max Instruction Size

Source: https://doxygen.hyperdbg.org/_address_check_8c

Calculates the maximum instruction length that can be safely read starting from a given address. It considers page boundaries and uses a helper function to check memory access validity. The function depends on MAXIMUM_INSTR_SIZE and PAGE_SIZE constants.

```c
UINT32 CheckAddressMaximumInstructionLength  | ( | PVOID | _Address_| ) |   
{
UINT64 SizeOfSafeBufferToRead = 0;

//
// Compute the amount of buffer we can read without problem
//
SizeOfSafeBufferToRead = (UINT64)Address & 0xfff;
SizeOfSafeBufferToRead += MAXIMUM_INSTR_SIZE;

if (SizeOfSafeBufferToRead >= PAGE_SIZE)
{
SizeOfSafeBufferToRead = SizeOfSafeBufferToRead - PAGE_SIZE;

//
// When we reached here, we're sure the instruction is on the boundary of a
// page table, so we have the maximum instruction length to read, but just
// to make sure that the instruction is not continued into two pages, we'll
// check the validity of the next page
//
if (CheckAccessValidityAndSafety((UINT64)Address + PAGE_SIZE, sizeof(CHAR)))
{
//
// Address is safe to be read from the next page, so we just extend it
// to the MAXIMUM_INSTR_SIZE
//
SizeOfSafeBufferToRead = MAXIMUM_INSTR_SIZE;
}
else
{
SizeOfSafeBufferToRead = MAXIMUM_INSTR_SIZE - SizeOfSafeBufferToRead;
}
}
else
{
SizeOfSafeBufferToRead = MAXIMUM_INSTR_SIZE;
}

return (UINT32)SizeOfSafeBufferToRead;
}
```

--------------------------------

### Handle .start command

Source: https://doxygen.hyperdbg.org/commands_8h_source

Handles the '.start' command for starting or resuming execution. It accepts a vector of strings for the split command and the command string.

```cpp
VOID CommandStart(vector< string > SplitCommand, string Command)
.start command handler
**Definition** start.cpp:45
```

--------------------------------

### Display Settings Command Help

Source: https://doxygen.hyperdbg.org/settings_8cpp

Displays helpful information and usage examples for the 'settings' command. This function outlines the different ways the command can be used, including querying, setting values, and toggling options.

```cpp
VOID CommandSettingsHelp  | ( | __| )
{
ShowMessages(
"settings : queries, sets, or changes a value for a special settings option.\n\n");

ShowMessages("syntax : \tsettings [OptionName (string)]\n");
ShowMessages("syntax : \tsettings [OptionName (string)] [Value (hex)]\n");
ShowMessages("syntax : \tsettings [OptionName (string)] [Value (string)]\n");
ShowMessages("syntax : \tsettings [OptionName (string)] [on|off]\n");

ShowMessages("\n");
ShowMessages("\t\t e.g : settings autounpause\n");
ShowMessages("\t\t e.g : settings autounpause on\n");
ShowMessages("\t\t e.g : settings autounpause off\n");
ShowMessages("\t\t e.g : settings addressconversion on\n");
ShowMessages("\t\t e.g : settings addressconversion off\n");
ShowMessages("\t\t e.g : settings autoflush on\n");
ShowMessages("\t\t e.g : settings autoflush off\n");
ShowMessages("\t\t e.g : settings syntax intel\n");
ShowMessages("\t\t e.g : settings syntax att\n");
ShowMessages("\t\t e.g : settings syntax masm\n");
}
```

--------------------------------

### Show Settings Command Syntax (settings)

Source: https://doxygen.hyperdbg.org/help_8h

Details the 'settings' command, used for querying, setting, or changing debugger settings. It shows syntax for different operations like getting a setting's value, setting a value (hex or string), or toggling options (on/off), with various usage examples.

```assembly
VOID CommandSettingsHelp  | ( | __| ) |
ShowMessages(
"settings : queries, sets, or changes a value for a special settings option.\n\n");
ShowMessages("syntax : \tsettings [OptionName (string)]\n");
ShowMessages("syntax : \tsettings [OptionName (string)] [Value (hex)]\n");
ShowMessages("syntax : \tsettings [OptionName (string)] [Value (string)]\n");
ShowMessages("syntax : \tsettings [OptionName (string)] [on|off]\n");
ShowMessages("\n");
ShowMessages("\t\te.g : settings autounpause\n");
ShowMessages("\t\te.g : settings autounpause on\n");
ShowMessages("\t\te.g : settings autounpause off\n");
ShowMessages("\t\te.g : settings addressconversion on\n");
ShowMessages("\t\te.g : settings addressconversion off\n");
ShowMessages("\t\te.g : settings autoflush on\n");
ShowMessages("\t\te.g : settings autoflush off\n");
ShowMessages("\t\te.g : settings syntax intel\n");
ShowMessages("\t\te.g : settings syntax att\n");
ShowMessages("\t\te.g : settings syntax masm\n");
```

--------------------------------

### VMX Virtualization Setup

Source: https://doxygen.hyperdbg.org/_vmx_8h

Functions for setting up and performing virtualization.

```APIDOC
## POST /api/vmx/virtualizespecificcore

### Description
Allocates VMX regions for all logical cores (Vmxon region and Vmcs region).

### Method
POST

### Endpoint
/api/vmx/virtualizespecificcore

### Response
#### Success Response (200)
- **ReturnValue** (BOOLEAN) - True if allocation was successful, false otherwise.

#### Response Example
```json
{
  "ReturnValue": true
}
```
```

```APIDOC
## POST /api/vmx/fixcrbits

### Description
Fixes values for CR0 and CR4 bits.

### Method
POST

### Endpoint
/api/vmx/fixcrbits

### Response
#### Success Response (200)
- **ReturnValue** (VOID) - This operation does not return a value.

#### Response Example
```json
{}
```
```

```APIDOC
## POST /api/vmx/loadvmcs

### Description
Loads the VMCS (Virtual Machine Control Structure).

### Method
POST

### Endpoint
/api/vmx/loadvmcs

### Parameters
#### Request Body
- **VCpu** (VIRTUAL_MACHINE_STATE*) - Required - Pointer to the VCPU state.

### Response
#### Success Response (200)
- **ReturnValue** (BOOLEAN) - True if loading was successful, false otherwise.

#### Response Example
```json
{
  "ReturnValue": true
}
```
```

```APIDOC
## POST /api/vmx/clearvmcss

### Description
Clears the VMCS state.

### Method
POST

### Endpoint
/api/vmx/clearvmcss

### Parameters
#### Request Body
- **VCpu** (VIRTUAL_MACHINE_STATE*) - Required - Pointer to the VCPU state.

### Response
#### Success Response (200)
- **ReturnValue** (BOOLEAN) - True if clearing was successful, false otherwise.

#### Response Example
```json
{
  "ReturnValue": true
}
```
```

```APIDOC
## GET /api/vmx/isonvmxroot

### Description
Checks deterministically whether the caller is in VMX root mode.

### Method
GET

### Endpoint
/api/vmx/isonvmxroot

### Response
#### Success Response (200)
- **ReturnValue** (BOOLEAN) - True if in VMX root mode, false otherwise.

#### Response Example
```json
{
  "ReturnValue": true
}
```
```

```APIDOC
## POST /api/vmx/virtualizecurrentsystem

### Description
Initializes VMX operation for the current system.

### Method
POST

### Endpoint
/api/vmx/virtualizecurrentsystem

### Parameters
#### Request Body
- **GuestStack** (PVOID) - Required - Pointer to the guest stack.

### Response
#### Success Response (200)
- **ReturnValue** (BOOLEAN) - True if virtualization was successful, false otherwise.

#### Response Example
```json
{
  "ReturnValue": true
}
```
```

```APIDOC
## POST /api/vmx/setupvmcs

### Description
Sets up the VMCS for VMX operation.

### Method
POST

### Endpoint
/api/vmx/setupvmcs

### Parameters
#### Request Body
- **VCpu** (VIRTUAL_MACHINE_STATE*) - Required - Pointer to the VCPU state.
- **GuestStack** (PVOID) - Required - Pointer to the guest stack.

### Response
#### Success Response (200)
- **ReturnValue** (BOOLEAN) - True if setup was successful, false otherwise.

#### Response Example
```json
{
  "ReturnValue": true
}
```
```

--------------------------------

### Start Command Path and Arguments

Source: https://doxygen.hyperdbg.org/libhyperdbg_2header_2globals_8h

Stores the path and arguments used with the '.start' command. This allows for launching processes with specific configurations.

```c
std::wstring g_StartCommandPath = L""
```

```c
std::wstring g_StartCommandPathAndArguments = L""
```

--------------------------------

### Show Memory Search Syntax (!s*)

Source: https://doxygen.hyperdbg.org/help_8h

Details the '!s*' family of commands ('sb', 'sd', 'sq') for searching contiguous memory based on byte patterns. It specifies syntax for search start address, length, byte pattern, and optional process ID, with examples for different data types (byte, double-word, quad-word).

```assembly
VOID CommandSearchMemoryHelp  | ( | __| ) |
ShowMessages("sb !sb sd !sd sq !sq : searches a contiguous memory for a "
"special byte pattern\n");
ShowMessages("sb Byte and ASCII characters\n");
ShowMessages("sd Double-word values (4 bytes)\n");
ShowMessages("sq Quad-word values (8 bytes). \n");
ShowMessages("\n If you want to search in physical (address) memory then add '!' "
"at the start of the command\n");
ShowMessages("syntax : \tsb [StartAddress (hex)] [l Length (hex)] [BytePattern (hex)] [pid ProcessId (hex)]\n");
ShowMessages("syntax : \tsd [StartAddress (hex)] [l Length (hex)] [BytePattern (hex)] [pid ProcessId (hex)]\n");
ShowMessages("syntax : \tsq [StartAddress (hex)] [l Length (hex)] [BytePattern (hex)] [pid ProcessId (hex)]\n");
ShowMessages("\n");
ShowMessages("\t\te.g : sb nt!ExAllocatePoolWithTag 90 85 95 l ffff \n");
ShowMessages("\t\te.g : sb nt!ExAllocatePoolWithTag+5 90 85 95 l ffff \n");
ShowMessages("\t\te.g : sb @rcx+5 90 85 95 l ffff \n");
ShowMessages("\t\te.g : sb fffff8077356f010 90 85 95 l ffff \n");
ShowMessages("\t\te.g : sd fffff8077356f010 90423580 l ffff pid 1c0 \n");
ShowMessages("\t\te.g : !sq 100000 9090909090909090 l ffff\n");
ShowMessages("\t\te.g : !sq @rdx+r12 9090909090909090 l ffff\n");
ShowMessages("\t\te.g : !sq 100000 9090909090909090 9090909090909090 "
"9090909090909090 l ffffff\n");
```

--------------------------------

### Helper Functions for VmxVirtualizeCurrentSystem

Source: https://doxygen.hyperdbg.org/_vmx_8c

This section details helper functions used by VmxVirtualizeCurrentSystem for VMX setup and management.

```APIDOC
## Helper Functions for VMX Virtualization

### IdtEmulationPrepareHostIdt()

#### Description
Prepares the Host IDT (Interrupt Descriptor Table).

#### Method
N/A

#### Endpoint
N/A

#### Parameters
- **VCpu** (VIRTUAL_MACHINE_STATE*) - In/Out - Pointer to the virtual machine state structure.

### SegmentPrepareHostGdt()

#### Description
Initializes the host GDT (Global Descriptor Table) and TSS (Task State Segment).

#### Method
N/A

#### Endpoint
N/A

#### Parameters
- **OsGdtBase** (SEGMENT_DESCRIPTOR_32*) - Base address of the OS GDT.
- **OsGdtLimit** (UINT16) - Limit of the OS GDT.
- **TrSelector** (UINT16) - TR (TSS segment selector).
- **HostStack** (UINT64) - Stack for the host.
- **AllocatedHostGdt** (SEGMENT_DESCRIPTOR_32*) - Pointer to the allocated host GDT.
- **AllocatedHostTss** (TASK_STATE_SEGMENT_64*) - Pointer to the allocated host TSS.

### VmxClearVmcsState()

#### Description
Clears the VMCS (Virtual Machine Control Structure) state using the `vmclear` instruction.

#### Method
N/A

#### Endpoint
N/A

#### Parameters
- **VCpu** (VIRTUAL_MACHINE_STATE*) - Pointer to the virtual machine state structure.

#### Returns
- `BOOLEAN` - `TRUE` if successful, `FALSE` otherwise.

### VmxLoadVmcs()

#### Description
Loads the VMCS state using the `vmptrld` instruction.

#### Method
N/A

#### Endpoint
N/A

#### Parameters
- **VCpu** (VIRTUAL_MACHINE_STATE*) - Pointer to the virtual machine state structure.

#### Returns
- `BOOLEAN` - `TRUE` if successful, `FALSE` otherwise.

### VmxSetupVmcs()

#### Description
Creates and configures a VMCS layout.

#### Method
N/A

#### Endpoint
N/A

#### Parameters
- **VCpu** (VIRTUAL_MACHINE_STATE*) - Pointer to the virtual machine state structure.
- **GuestStack** (PVOID) - Pointer to the guest stack.

#### Returns
- `BOOLEAN` - `TRUE` if successful, `FALSE` otherwise.
```

--------------------------------

### Install VMM Driver in HyperDbg

Source: https://doxygen.hyperdbg.org/_hyper_dbg_lib_imports_8h

Installs the VMM (Virtual Machine Monitor) driver. Returns 0 upon successful installation and 1 if the installation failed.

```C
#include <hyperdbg.h>

INT hyperdbg_u_install_vmm_driver(void)
{
    return HyperDbgInstallVmmDriver();
}
```

--------------------------------

### Process Kernel Module Symbol Resolution (C++)

Source: https://doxygen.hyperdbg.org/symbol_8cpp

This snippet iterates through loaded kernel modules, extracts their paths, resolves PDB details (GUID and Age), and stores this information. It handles the special case where module paths start with \\SystemRoot\\ by replacing it with the actual system root path. The function `ScriptEngineConvertFileToPdbFileAndGuidAndAgeDetailsWrapper` is crucial for PDB resolution.

```cpp
for (UINT32 i = 0; i < ModuleInfo->NumberOfModules; i++)
{
    UINT32 IndexInSymbolBuffer = ModulesCount + i;

    auto PathName = ModuleInfo->Modules[i].FullPathName + ModuleInfo->Modules[i].OffsetToFileName;

    RtlZeroMemory(ModuleSymbolPath, sizeof(ModuleSymbolPath));
    RtlZeroMemory(ModuleSymbolGuidAndAge, sizeof(ModuleSymbolGuidAndAge));

    string ModuleFullPath((const char *)ModuleInfo->Modules[i].FullPathName);

    if (ModuleFullPath.rfind("\\SystemRoot\", 0) == 0)
    {
        Replace(ModuleFullPath, "\\SystemRoot", SystemRootString);
    }

    if (ScriptEngineConvertFileToPdbFileAndGuidAndAgeDetailsWrapper(ModuleFullPath.c_str(),
        ModuleSymbolPath,
        ModuleSymbolGuidAndAge,
        FALSE))
    {
        IsSymbolPdbDetailAvailable = TRUE;
    }
    else
    {
        IsSymbolPdbDetailAvailable = FALSE;
    }

    ModuleSymDetailArray[IndexInSymbolBuffer].BaseAddress = (UINT64)ModuleInfo->Modules[i].ImageBase;
    memcpy(ModuleSymDetailArray[IndexInSymbolBuffer].FilePath, ModuleFullPath.c_str(), ModuleFullPath.size());

    if (IsSymbolPdbDetailAvailable)
    {
        ModuleSymDetailArray[IndexInSymbolBuffer].IsSymbolDetailsFound = TRUE;
        memcpy(ModuleSymDetailArray[IndexInSymbolBuffer].ModuleSymbolGuidAndAge, ModuleSymbolGuidAndAge, MAXIMUM_GUID_AND_AGE_SIZE);
        memcpy(ModuleSymDetailArray[IndexInSymbolBuffer].ModuleSymbolPath, ModuleSymbolPath, MAX_PATH);

        string ModuleSymbolPathString(ModuleSymbolPath);
        if (ModuleSymbolPathString.find(":\\\\") != std::string::npos)
            ModuleSymDetailArray[IndexInSymbolBuffer].IsLocalSymbolPath = TRUE;
        else
            ModuleSymDetailArray[IndexInSymbolBuffer].IsLocalSymbolPath = FALSE;
    }
    else
    {
        ModuleSymDetailArray[IndexInSymbolBuffer].IsSymbolDetailsFound = FALSE;
    }

    if (SendOverSerial)
    {
        KdSendSymbolDetailPacket(&ModuleSymDetailArray[IndexInSymbolBuffer], i, ModuleInfo->NumberOfModules + ModulesCount);
    }
}
```

--------------------------------

### Setup VMCS

Source: https://doxygen.hyperdbg.org/_vmx_8h_source

Configures and sets up the Virtual Machine Control Structure (VMCS) for a virtual CPU, including the guest stack pointer. This prepares the VMCS with initial values for VMX operation.

```c
390VmxSetupVmcs(_In_ VIRTUAL_MACHINE_STATE * VCpu, _In_ PVOID GuestStack);
```

--------------------------------

### Start Command Handler (C++)

Source: https://doxygen.hyperdbg.org/commands_8h

Handles the '.start' command to launch a new process. It parses the command line to extract the executable path and arguments, then initiates the process. It includes logic to handle user-mode debugger activation and provides help messages for incorrect usage.

```cpp
VOID CommandStart(vector<string> _SplitCommand, string _Command) {
    vector<string> PathAndArgs;
    string Arguments = "";

    // Disable user-mode debugger in this version
#if ActivateUserModeDebugger == FALSE
    if (!g_IsSerialConnectedToRemoteDebugger) {
        ShowMessages("the user-mode debugger in VMI Mode 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. But starting processes is fully supported "
                   "in the Debugger Mode.\n" 
                   "(it's not recommended to use it in VMI Mode yet!)\n");
        return;
    }
#endif // !ActivateUserModeDebugger

    if (_SplitCommand.size() <= 2) {
        ShowMessages("incorrect use of the '.start'\n\n");
        CommandStartHelp();
        return;
    }

    if (!_SplitCommand.at(1).compare("path")) {
        // *** It's a run of target PE file ***

        // Trim the command
        Trim(_Command);

        // Remove '.start' or 'start' from it
        _Command.erase(0, _SplitCommand.at(0).size());

        // Remove path + space
        _Command.erase(0, 4 + 1);

        // Trim it again
        Trim(_Command);

        // Split Path and args
        SplitPathAndArgs(PathAndArgs, _Command);

        // Convert path to wstring
        StringToWString(g_StartCommandPath, PathAndArgs.at(0));

        if (PathAndArgs.size() != 1) {
            // There are arguments to this command
            for (auto item : PathAndArgs) {
                // Append the arguments
                Arguments += item + " ";
            }
            // Remove the latest space
            Arguments.pop_back();

            // Convert arguments to wstring
            StringToWString(g_StartCommandPathAndArguments, Arguments);
        }
    } else {
        ShowMessages("err, couldn't resolve error at '%s'\n\n",
                   _SplitCommand.at(1).c_str());
        CommandStartHelp();
        return;
    }

    // Perform run of the target file
    if (Arguments.empty()) {
        UdAttachToProcess(NULL,
                           g_StartCommandPath.c_str(),
                           NULL,
                           FALSE);
    } else {
        UdAttachToProcess(NULL,
                           g_StartCommandPath.c_str(),
                           (WCHAR *)g_StartCommandPathAndArguments.c_str(),
                           FALSE);
    }
}
```

--------------------------------

### HyperDbg Output Command Help (C++)

Source: https://doxygen.hyperdbg.org/output_8cpp

Displays help information for the 'output' command, explaining its syntax for creating, opening, and closing output instances. It covers various output methods including files, named pipes, TCP, and modules, along with examples.

```C++
VOID CommandOutputHelp()
{
    ShowMessages("output : creates an output instance that can be used in event "
    "forwarding.\n\n");

    ShowMessages("syntax : 	output [create Name (string)] [file|namedpipe|tcp Address (string)]\n");
    ShowMessages("syntax : 	output [open|close Name (string)]\n");

    ShowMessages("\n");
    ShowMessages("		e.g : output create MyOutputName1 file c:\\rev\\output.txt\n");
    ShowMessages("		e.g : output create MyOutputName2 tcp 192.168.1.10:8080\n");
    ShowMessages("		e.g : output create MyOutputName3 namedpipe "
    "\\\\.\\Pipe\\HyperDbgOutput\n");
    ShowMessages("		e.g : output create MyOutputName1 module "
    "c:\\rev\\event_forwarding.dll\n");
    ShowMessages("		e.g : output open MyOutputName1\n");
    ShowMessages("		e.g : output close MyOutputName1\n");
}
```

--------------------------------

### Define Debugger Thread Debugging Tag Start Seed (C)

Source: https://doxygen.hyperdbg.org/_constants_8h

Defines the starting seed for user-mode thread detail tokens. It's crucial that this seed does not start with zero to avoid misinterpretation as an error.

```c
#define DebuggerThreadDebuggingTagStartSeed 0x1000000
```
Tokens:
Raw