libhyperdbg.h File Reference

headers for libhyperdbg More...

Go to the source code of this file.

Functions
INT	HyperDbgCreateHandleFromVmmModule ()
	Create handle from VMM module.
INT	HyperDbgUnloadVmm ()
	Unload VMM driver.
INT	HyperDbgInstallVmmDriver ()
	Install VMM driver.
INT	HyperDbgUninstallVmmDriver ()
	Remove the VMM driver.
INT	HyperDbgLoadVmmModule ()
	load vmm module
INT	HyperDbgStopVmmDriver ()
	Stop VMM driver.
INT	HyperDbgInterpreter (CHAR *Command)
	Interpret commands.
INT	ScriptReadFileAndExecuteCommandline (INT argc, CHAR *argv[])
	Parsing the command line options for scripts.
VOID	HyperDbgShowSignature ()
	Show signature of HyperDbg.
VOID	SetTextMessageCallback (PVOID Handler)
	Set the function callback that will be called if any message needs to be shown.
PVOID	SetTextMessageCallbackUsingSharedBuffer (PVOID Handler)
	Set the function callback that will be called if any message needs to be shown.
VOID	UnsetTextMessageCallback ()
	Unset the function callback that will be called if any message needs to be shown.

Detailed Description

headers for libhyperdbg

Author

Sina Karvandi (sina@.nosp@m.hype.nosp@m.rdbg..nosp@m.org)

Version

1.0

Date

2024-06-24

Copyright

This project is released under the GNU Public License v3.

Function Documentation

HyperDbgCreateHandleFromVmmModule()

INT HyperDbgCreateHandleFromVmmModule

(

)

Create handle from VMM module.

Returns

INT return zero if it was successful or non-zero if there was error

lpSecurityAttirbutes

lpTemplateFile

{
    DWORD ErrorNum;
    DWORD ThreadId;
 
    if (g_DeviceHandle)
    {
        ShowMessages("handle of the driver found, if you use 'load' before, please "
                     "unload it using 'unload'\n");
        return 1;
    }
 
    //
    // Make sure that this variable is false, because it might be set to
    // true as the result of a previous load
    //
    g_IsVmxOffProcessStart = FALSE;
 
    //
    // Init entering vmx
    //
    g_DeviceHandle = CreateFileA(
        "\\\\.\\HyperDbgDebuggerDevice",
        GENERIC_READ | GENERIC_WRITE,
        FILE_SHARE_READ | FILE_SHARE_WRITE,
        NULL, 
        OPEN_EXISTING,
        FILE_ATTRIBUTE_NORMAL | FILE_FLAG_OVERLAPPED,
        NULL); 
 
    if (g_DeviceHandle == INVALID_HANDLE_VALUE)
    {
        ErrorNum = GetLastError();
        if (ErrorNum == ERROR_ACCESS_DENIED)
        {
            ShowMessages("err, access denied\nare you sure you have administrator "
                         "rights?\n");
        }
        else if (ErrorNum == ERROR_GEN_FAILURE)
        {
            ShowMessages("err, a device attached to the system is not functioning\n"
                         "vmx feature might be disabled from BIOS or VBS/HVCI is active\n");
        }
        else
        {
            ShowMessages("err, CreateFile failed (%x)\n", ErrorNum);
        }
 
        g_DeviceHandle = NULL;
        return 1;
    }
 
    //
    // Initialize the list of events
    //
    InitializeListHead(&g_EventTrace);
 
#if !UseDbgPrintInsteadOfUsermodeMessageTracking
    HANDLE Thread = CreateThread(NULL, 0, IrpBasedBufferThread, NULL, 0, &ThreadId);
 
    // if (Thread)
    // {
    // ShowMessages("thread Created successfully\n");
    // }
 
#endif
 
    return 0;
}

HyperDbgInstallVmmDriver()

INT HyperDbgInstallVmmDriver

(

)

Install VMM driver.

Returns

INT return zero if it was successful or non-zero if there was error

{
    //
    // The driver is not started yet so let us the install driver
    // First setup full path to driver name
    //
 
    //
    // If the user has not specified a custom driver location, then we
    // need to find the driver in the same directory as the executable
    //
    if (!g_UseCustomDriverLocation)
    {
        if (!SetupPathForFileName(KERNEL_DEBUGGER_DRIVER_NAME_AND_EXTENSION, g_DriverLocation, sizeof(g_DriverLocation), TRUE))
        {
            return 1;
        }
 
        //
        // Use default driver name
        //
        strcpy_s(g_DriverName, KERNEL_DEBUGGER_DRIVER_NAME);
    }
 
    if (!ManageDriver(g_DriverName, g_DriverLocation, DRIVER_FUNC_INSTALL))
    {
        ShowMessages("unable to install VMM driver\n");
 
        //
        // Error - remove driver
        //
        ManageDriver(g_DriverName, g_DriverLocation, DRIVER_FUNC_REMOVE);
 
        return 1;
    }
 
    return 0;
}

HyperDbgInterpreter()

INT HyperDbgInterpreter

(

CHAR *

Command

)

Interpret commands.

Parameters

Command

The text of command

Returns

INT returns return zero if it was successful or non-zero if there was error

{
    BOOLEAN               HelpCommand       = FALSE;
    UINT64                CommandAttributes = NULL;
    CommandType::iterator Iterator;
 
    //
    // Check if it's the first command and whether the mapping of command is
    // initialized or not
    //
    if (!g_IsCommandListInitialized)
    {
        //
        // Initialize the debugger
        //
        InitializeDebugger();
 
        g_IsCommandListInitialized = TRUE;
    }
 
    //
    // Save the command into log open file
    //
    if (g_LogOpened && !g_ExecutingScript)
    {
        LogopenSaveToFile(Command);
        LogopenSaveToFile("\n");
    }
 
    //
    // Remove the comments
    //
    InterpreterRemoveComments(Command);
 
    //
    // Convert to string
    //
    string CommandString(Command);
 
    // for test
    // CommandParser parser;
    // auto          tokens1 = parser.parse(CommandString);
 
    //
    // Convert to lower case
    //
    transform(CommandString.begin(), CommandString.end(), CommandString.begin(), [](unsigned char c) { return std::tolower(c); });
 
    vector<string> SplitCommand {Split(CommandString, ' ')};
 
    //
    // Check if user entered an empty input
    //
    if (SplitCommand.empty())
    {
        ShowMessages("\n");
        return 0;
    }
 
    string FirstCommand = SplitCommand.front();
 
    //
    // Read the command's attributes
    //
    CommandAttributes = GetCommandAttributes(FirstCommand);
 
    //
    // Check if the command needs to be continued by pressing enter
    //
    if (CommandAttributes & DEBUGGER_COMMAND_ATTRIBUTE_REPEAT_ON_ENTER)
    {
        g_ShouldPreviousCommandBeContinued = TRUE;
    }
    else
    {
        g_ShouldPreviousCommandBeContinued = FALSE;
    }
 
    //
    // Check and send remote command and also we check whether this
    // is a command that should be handled in this command or we can
    // send it to the remote computer, it is because in a remote connection
    // still some of the commands should be handled in the local HyperDbg
    //
    if (g_IsConnectedToRemoteDebuggee &&
        !(CommandAttributes & DEBUGGER_COMMAND_ATTRIBUTE_LOCAL_COMMAND_IN_REMOTE_CONNECTION))
    {
        //
        // Check it here because generally, we use this variable in host
        // for showing the correct signature but we won't try to block
        // other commands, the only thing is events which is blocked
        // by the remote computer itself
        //
        if (g_BreakPrintingOutput)
        {
            g_BreakPrintingOutput = FALSE;
        }
 
        //
        // It's a connection over network (VMI-Mode)
        //
        RemoteConnectionSendCommand(Command, (UINT32)strlen(Command) + 1);
 
        ShowMessages("\n");
 
        //
        // Indicate that we sent the command to the target system
        //
        return 2;
    }
    else if (g_IsSerialConnectedToRemoteDebuggee &&
             !(CommandAttributes &
               DEBUGGER_COMMAND_ATTRIBUTE_LOCAL_COMMAND_IN_DEBUGGER_MODE))
    {
        //
        // It's a connection over serial (Debugger-Mode)
        //
 
        if (CommandAttributes & DEBUGGER_COMMAND_ATTRIBUTE_WONT_STOP_DEBUGGER_AGAIN)
        {
            KdSendUserInputPacketToDebuggee(Command, (UINT32)strlen(Command) + 1, TRUE);
 
            //
            // Set the debuggee to show that it's running
            //
            KdSetStatusAndWaitForPause();
        }
        else
        {
            //
            // Disable the breakpoints and events while executing the command in the remote computer
            //
            KdSendTestQueryPacketToDebuggee(TEST_BREAKPOINT_TURN_OFF_BPS_AND_EVENTS_FOR_COMMANDS_IN_REMOTE_COMPUTER);
            KdSendUserInputPacketToDebuggee(Command, (UINT32)strlen(Command) + 1, FALSE);
            KdSendTestQueryPacketToDebuggee(TEST_BREAKPOINT_TURN_ON_BPS_AND_EVENTS_FOR_COMMANDS_IN_REMOTE_COMPUTER);
        }
 
        //
        // Indicate that we sent the command to the target system
        //
        return 2;
    }
 
    //
    // Detect whether it's a .help command or not
    //
    if (!FirstCommand.compare(".help") || !FirstCommand.compare("help") ||
        !FirstCommand.compare(".hh"))
    {
        if (SplitCommand.size() == 2)
        {
            //
            // Show that it's a help command
            //
            HelpCommand  = TRUE;
            FirstCommand = SplitCommand.at(1);
        }
        else
        {
            ShowMessages("incorrect use of the '%s'\n", FirstCommand.c_str());
            CommandHelpHelp();
            return 0;
        }
    }
 
    //
    // Start parsing commands
    //
    Iterator = g_CommandsList.find(FirstCommand);
 
    if (Iterator == g_CommandsList.end())
    {
        //
        //  Command doesn't exist
        //
        string         CaseSensitiveCommandString(Command);
        vector<string> CaseSensitiveSplitCommand {Split(CaseSensitiveCommandString, ' ')};
 
        if (!HelpCommand)
        {
            ShowMessages("err, couldn't resolve command at '%s'\n", CaseSensitiveSplitCommand.front().c_str());
        }
        else
        {
            ShowMessages("err, couldn't find the help for the command at '%s'\n",
                         CaseSensitiveSplitCommand.at(1).c_str());
        }
    }
    else
    {
        if (HelpCommand)
        {
            Iterator->second.CommandHelpFunction();
        }
        else
        {
            //
            // Check if command is case-sensitive or not
            //
            if ((Iterator->second.CommandAttrib &
                 DEBUGGER_COMMAND_ATTRIBUTE_LOCAL_CASE_SENSITIVE))
            {
                string CaseSensitiveCommandString(Command);
                Iterator->second.CommandFunction(SplitCommand, CaseSensitiveCommandString);
            }
            else
            {
                Iterator->second.CommandFunction(SplitCommand, CommandString);
            }
        }
    }
 
    //
    // Save the command into log open file
    //
    if (g_LogOpened && !g_ExecutingScript)
    {
        LogopenSaveToFile("\n");
    }
 
    return 0;
}

HyperDbgLoadVmmModule()

INT HyperDbgLoadVmmModule

(

)

load vmm module

Returns

int return zero if it was successful or non-zero if there

{
    BOOL   Status;
    HANDLE hToken;
    char   CpuId[13] = {0};
 
    //
    // Enable Debug privilege
    //
    Status = OpenProcessToken(GetCurrentProcess(), TOKEN_ADJUST_PRIVILEGES, &hToken);
    if (!Status)
    {
        ShowMessages("err, OpenProcessToken failed (%x)\n", GetLastError());
        return 1;
    }
 
    Status = SetPrivilege(hToken, SE_DEBUG_NAME, TRUE);
    if (!Status)
    {
        CloseHandle(hToken);
        return 1;
    }
 
    //
    // Read the vendor string
    //
    CpuReadVendorString(CpuId);
 
    ShowMessages("current processor vendor is : %s\n", CpuId);
 
    if (strcmp(CpuId, "GenuineIntel") == 0)
    {
        ShowMessages("virtualization technology is vt-x\n");
    }
    else
    {
        ShowMessages("this program is not designed to run in a non-VT-x "
                     "environment !\n");
        return 1;
    }
 
    if (VmxSupportDetection())
    {
        ShowMessages("vmx operation is supported by your processor\n");
    }
    else
    {
        ShowMessages("vmx operation is not supported by your processor\n");
        return 1;
    }
 
    //
    // Create event to show if the hypervisor is loaded or not
    //
    g_IsDriverLoadedSuccessfully = CreateEvent(NULL, FALSE, FALSE, NULL);
 
    if (HyperDbgCreateHandleFromVmmModule() == 1)
    {
        //
        // No need to handle anymore
        //
        CloseHandle(g_IsDriverLoadedSuccessfully);
        return 1;
    }
 
    //
    // Vmm module (Hypervisor) is loaded
    //
 
    //
    // We wait for the first message from the kernel debugger to continue
    //
    WaitForSingleObject(
        g_IsDriverLoadedSuccessfully,
        INFINITE);
 
    //
    // No need to handle anymore
    //
    CloseHandle(g_IsDriverLoadedSuccessfully);
 
    //
    // If we reach here so the module are loaded
    //
    g_IsDebuggerModulesLoaded = TRUE;
 
    ShowMessages("vmm module is running...\n");
 
    return 0;
}

HyperDbgShowSignature()

VOID HyperDbgShowSignature

(

)

Show signature of HyperDbg.

Returns

VOID

{
    if (g_IsConnectedToRemoteDebuggee)
    {
        //
        // Remote debugging over tcp (vmi-mode)
        //
        ShowMessages("[%s:%s] HyperDbg> ", g_ServerIp.c_str(), g_ServerPort.c_str());
    }
    else if (g_ActiveProcessDebuggingState.IsActive)
    {
        //
        // Debugging a special process
        //
        ShowMessages("%x:%x u%sHyperDbg> ",
                     g_ActiveProcessDebuggingState.ProcessId,
                     g_ActiveProcessDebuggingState.ThreadId,
                     g_ActiveProcessDebuggingState.Is32Bit ? "86" : "64");
    }
    else if (g_IsSerialConnectedToRemoteDebuggee)
    {
        //
        // Remote debugging over serial (debugger-mode)
        //
        ShowMessages("%x: kHyperDbg> ", g_CurrentRemoteCore);
    }
    else
    {
        //
        // Anything other than above scenarios including local debugging
        // in vmi-mode
        //
        ShowMessages("HyperDbg> ");
    }
}

HyperDbgStopVmmDriver()

INT HyperDbgStopVmmDriver

(

)

Stop VMM driver.

Returns

INT return zero if it was successful or non-zero if there was error

{
    return HyperDbgStopDriver(g_DriverName);
}

HyperDbgUninstallVmmDriver()

INT HyperDbgUninstallVmmDriver

(

)

Remove the VMM driver.

Returns

INT return zero if it was successful or non-zero if there was error

{
    return HyperDbgUninstallDriver(g_DriverName);
}

HyperDbgUnloadVmm()

INT HyperDbgUnloadVmm

(

)

Unload VMM driver.

Returns

INT return zero if it was successful or non-zero if there was error

{
    BOOL Status;
 
    AssertShowMessageReturnStmt(g_DeviceHandle, ASSERT_MESSAGE_DRIVER_NOT_LOADED, AssertReturnOne);
 
    ShowMessages("start terminating...\n");
 
    //
    // Uninitialize the user debugger if it's initialized
    //
    UdUninitializeUserDebugger();
 
    //
    // Send IOCTL to mark complete all IRP Pending
    //
    Status = DeviceIoControl(g_DeviceHandle,      // Handle to device
                             IOCTL_TERMINATE_VMX, // IO Control Code (IOCTL)
                             NULL,                // Input Buffer to driver.
                             0,                   // Length of input buffer in bytes. (x 2 is bcuz
                                                  // as the driver is x64 and has 64 bit values)
                             NULL,                // Output Buffer from driver.
                             0,                   // Length of output buffer in bytes.
                             NULL,                // Bytes placed in buffer.
                             NULL                 // synchronous call
    );
 
    //
    // wait to make sure we don't use an invalid handle in another Ioctl
    //
    if (!Status)
    {
        ShowMessages("ioctl failed with code 0x%x\n", GetLastError());
        return 1;
    }
 
    //
    // Send IOCTL to mark complete all IRP Pending
    //
    Status = DeviceIoControl(
        g_DeviceHandle,                                      // Handle to device
        IOCTL_RETURN_IRP_PENDING_PACKETS_AND_DISALLOW_IOCTL, // IO
                                                             // Control
                                                             // code
        NULL,                                                // Input Buffer to driver.
        0,                                                   // Length of input buffer in bytes. (x 2 is bcuz as the
                                                             // driver is x64 and has 64 bit values)
        NULL,                                                // Output Buffer from driver.
        0,                                                   // Length of output buffer in bytes.
        NULL,                                                // Bytes placed in buffer.
        NULL                                                 // synchronous call
    );
 
    //
    // wait to make sure we don't use an invalid handle in another Ioctl
    //
    if (!Status)
    {
        ShowMessages("ioctl failed with code 0x%x\n", GetLastError());
        return 1;
    }
 
    //
    // Indicate that the finish process start or not
    //
    g_IsVmxOffProcessStart = TRUE;
 
    Sleep(1000); // Wait so next thread can return from IRP Pending
 
    //
    // Send IRP_MJ_CLOSE to driver to terminate Vmxs
    //
    if (!CloseHandle(g_DeviceHandle))
    {
        ShowMessages("err, closing handle 0x%x\n", GetLastError());
        return 1;
    };
 
    //
    // Null the handle to indicate that the driver's device is not ready
    // to use
    //
    g_DeviceHandle = NULL;
 
    //
    // Debugger module is not loaded anymore
    //
    g_IsDebuggerModulesLoaded = FALSE;
 
    //
    // Check if we found an already built symbol table
    //
    SymbolDeleteSymTable();
 
    ShowMessages("you're not on HyperDbg's hypervisor anymore!\n");
 
    return 0;
}

ScriptReadFileAndExecuteCommandline()

INT ScriptReadFileAndExecuteCommandline	(	INT	argc,
		CHAR *	argv[] )

Parsing the command line options for scripts.

Parameters

argc
argv

Returns

INT

{
    vector<string> Args;
 
    //
    // Convert it to the array
    //
    for (size_t i = 2; i < argc; i++)
    {
        std::string TempStr(argv[i]);
        Args.push_back(TempStr);
    }
 
    //
    // Check if the target path and args for script is not empty
    //
    if (!Args.empty())
    {
        HyperDbgScriptReadFileAndExecuteCommand(Args);
        printf("\n");
    }
    else
    {
        printf("err, invalid command line options passed to the HyperDbg!\n");
        return FALSE;
    }
 
    return TRUE;
}

SetTextMessageCallback()

VOID SetTextMessageCallback

(

PVOID

Handler

)

Set the function callback that will be called if any message needs to be shown.

Parameters

Handler

Function that handles the messages

Returns

VOID

{
    g_MessageHandler = Handler;
}

SetTextMessageCallbackUsingSharedBuffer()

PVOID SetTextMessageCallbackUsingSharedBuffer

(

PVOID

Handler

)

Set the function callback that will be called if any message needs to be shown.

Parameters

Handler

Function that handles the messages

Returns

PVOID

{
    g_MessageHandler             = Handler;
    g_MessageHandlerSharedBuffer = malloc(COMMUNICATION_BUFFER_SIZE + TCP_END_OF_BUFFER_CHARS_COUNT);
 
    if (!g_MessageHandlerSharedBuffer)
    {
        g_MessageHandler = NULL;
        return NULL;
    }
 
    RtlZeroMemory(g_MessageHandlerSharedBuffer, COMMUNICATION_BUFFER_SIZE + TCP_END_OF_BUFFER_CHARS_COUNT);
 
    return g_MessageHandlerSharedBuffer;
}

UnsetTextMessageCallback()

VOID UnsetTextMessageCallback

(

)

Unset the function callback that will be called if any message needs to be shown.

Returns

VOID

{
    g_MessageHandler = NULL;
    free(g_MessageHandlerSharedBuffer);
    g_MessageHandlerSharedBuffer = NULL;
}