debugger.h File Reference

General debugger functions. More...

Go to the source code of this file.

Classes
struct	_DEBUGGER_SYNCRONIZATION_EVENTS_STATE
	In debugger holds the state of events. More...

Macros
#define	DEBUGGER_MAXIMUM_SYNCRONIZATION_KERNEL_DEBUGGER_OBJECTS   0x40
	maximum number of event handles in kernel-debugger
#define	DEBUGGER_SYNCRONIZATION_OBJECT_KERNEL_DEBUGGER_IS_DEBUGGER_RUNNING   0x0
	An event to show whether the debugger is running or not in kernel-debugger.
#define	DEBUGGER_SYNCRONIZATION_OBJECT_KERNEL_DEBUGGER_STARTED_PACKET_RECEIVED   0x1
#define	DEBUGGER_SYNCRONIZATION_OBJECT_KERNEL_DEBUGGER_PAUSED_DEBUGGEE_DETAILS   0x2
#define	DEBUGGER_SYNCRONIZATION_OBJECT_KERNEL_DEBUGGER_CORE_SWITCHING_RESULT   0x3
#define	DEBUGGER_SYNCRONIZATION_OBJECT_KERNEL_DEBUGGER_PROCESS_SWITCHING_RESULT   0x4
#define	DEBUGGER_SYNCRONIZATION_OBJECT_KERNEL_DEBUGGER_THREAD_SWITCHING_RESULT   0x5
#define	DEBUGGER_SYNCRONIZATION_OBJECT_KERNEL_DEBUGGER_SCRIPT_RUNNING_RESULT   0x6
#define	DEBUGGER_SYNCRONIZATION_OBJECT_KERNEL_DEBUGGER_SCRIPT_FORMATS_RESULT   0x7
#define	DEBUGGER_SYNCRONIZATION_OBJECT_KERNEL_DEBUGGER_DEBUGGEE_FINISHED_COMMAND_EXECUTION   0x8
#define	DEBUGGER_SYNCRONIZATION_OBJECT_KERNEL_DEBUGGER_FLUSH_RESULT   0x9
#define	DEBUGGER_SYNCRONIZATION_OBJECT_KERNEL_DEBUGGER_REGISTER_EVENT   0xa
#define	DEBUGGER_SYNCRONIZATION_OBJECT_KERNEL_DEBUGGER_ADD_ACTION_TO_EVENT   0xb
#define	DEBUGGER_SYNCRONIZATION_OBJECT_KERNEL_DEBUGGER_MODIFY_AND_QUERY_EVENT   0xc
#define	DEBUGGER_SYNCRONIZATION_OBJECT_KERNEL_DEBUGGER_READ_REGISTERS   0xd
#define	DEBUGGER_SYNCRONIZATION_OBJECT_KERNEL_DEBUGGER_BP   0xe
#define	DEBUGGER_SYNCRONIZATION_OBJECT_KERNEL_DEBUGGER_LIST_OR_MODIFY_BREAKPOINTS   0xf
#define	DEBUGGER_SYNCRONIZATION_OBJECT_KERNEL_DEBUGGER_READ_MEMORY   0x10
#define	DEBUGGER_SYNCRONIZATION_OBJECT_KERNEL_DEBUGGER_EDIT_MEMORY   0x11
#define	DEBUGGER_SYNCRONIZATION_OBJECT_KERNEL_DEBUGGER_SYMBOL_RELOAD   0x12
#define	DEBUGGER_SYNCRONIZATION_OBJECT_KERNEL_DEBUGGER_TEST_QUERY   0x13
#define	DEBUGGER_SYNCRONIZATION_OBJECT_KERNEL_DEBUGGER_CALLSTACK_RESULT   0x14
#define	DEBUGGER_SYNCRONIZATION_OBJECT_KERNEL_DEBUGGER_SEARCH_QUERY_RESULT   0x15
#define	DEBUGGER_SYNCRONIZATION_OBJECT_KERNEL_DEBUGGER_VA2PA_AND_PA2VA_RESULT   0x16
#define	DEBUGGER_SYNCRONIZATION_OBJECT_KERNEL_DEBUGGER_PTE_RESULT   0x17
#define	DEBUGGER_SYNCRONIZATION_OBJECT_KERNEL_DEBUGGER_SHORT_CIRCUITING_EVENT_STATE   0x18
#define	DEBUGGER_SYNCRONIZATION_OBJECT_KERNEL_DEBUGGER_PAGE_IN_STATE   0x19
#define	DEBUGGER_SYNCRONIZATION_OBJECT_KERNEL_DEBUGGER_WRITE_REGISTER   0x1a
#define	DEBUGGER_MAXIMUM_SYNCRONIZATION_USER_DEBUGGER_OBJECTS   0x40
	Maximum number of event handles in user-debugger.
#define	DEBUGGER_SYNCRONIZATION_OBJECT_USER_DEBUGGER_IS_DEBUGGER_RUNNING   0x30
	An event to show whether the debugger is running or not in user-debugger.

Typedefs
typedef enum _DEBUGGER_EVENT_PARSING_ERROR_CAUSE	DEBUGGER_EVENT_PARSING_ERROR_CAUSE
	Reason for error in parsing commands.
typedef enum _DEBUGGER_EVENT_PARSING_ERROR_CAUSE *	PDEBUGGER_EVENT_PARSING_ERROR_CAUSE
typedef struct _DEBUGGER_SYNCRONIZATION_EVENTS_STATE	DEBUGGER_SYNCRONIZATION_EVENTS_STATE
	In debugger holds the state of events.
typedef struct _DEBUGGER_SYNCRONIZATION_EVENTS_STATE *	PDEBUGGER_SYNCRONIZATION_EVENTS_STATE

Enumerations
enum	_DEBUGGER_EVENT_PARSING_ERROR_CAUSE {   DEBUGGER_EVENT_PARSING_ERROR_CAUSE_SUCCESSFUL_NO_ERROR = 0 , DEBUGGER_EVENT_PARSING_ERROR_CAUSE_SCRIPT_SYNTAX_ERROR = 1 , DEBUGGER_EVENT_PARSING_ERROR_CAUSE_NO_INPUT = 2 , DEBUGGER_EVENT_PARSING_ERROR_CAUSE_MAXIMUM_INPUT_REACHED = 3 ,   DEBUGGER_EVENT_PARSING_ERROR_CAUSE_OUTPUT_NAME_NOT_FOUND = 4 , DEBUGGER_EVENT_PARSING_ERROR_CAUSE_OUTPUT_SOURCE_ALREADY_CLOSED = 5 , DEBUGGER_EVENT_PARSING_ERROR_CAUSE_ALLOCATION_ERROR = 6 , DEBUGGER_EVENT_PARSING_ERROR_CAUSE_FORMAT_ERROR = 7 ,   DEBUGGER_EVENT_PARSING_ERROR_CAUSE_ATTEMPT_TO_BREAK_ON_VMI_MODE = 8 , DEBUGGER_EVENT_PARSING_ERROR_CAUSE_IMMEDIATE_MESSAGING_IN_EVENT_FORWARDING_MODE = 9 , DEBUGGER_EVENT_PARSING_ERROR_CAUSE_USING_SHORT_CIRCUITING_IN_POST_EVENTS = 10 }
	Reason for error in parsing commands. More...

Functions
VOID	InterpreterRemoveComments (char *CommandText)
	Remove batch comments.
BOOLEAN	ShowErrorMessage (UINT32 Error)
	shows the error message
BOOLEAN	IsConnectedToAnyInstanceOfDebuggerOrDebuggee ()
	Shows whether the debugger is connected to a debugger or debuggee connected to a debugger.
BOOLEAN	IsTagExist (UINT64 Tag)
	Check whether the tag exists or not, if the tag is DEBUGGER_MODIFY_EVENTS_APPLY_TO_ALL_TAG then if we find just one event, it also means that the tag is found.
UINT64	DebuggerGetNtoskrnlBase ()
	Get ntoskrnl.exe base in the kernel.
UINT64	DebuggerGetKernelBase ()
	Get the base address of the kernel module.
BOOLEAN	DebuggerPauseDebuggee ()
	pauses the debuggee
BOOLEAN	InterpretConditionsAndCodes (vector< string > *SplitCommand, vector< string > *SplitCommandCaseSensitive, BOOLEAN IsConditionBuffer, PUINT64 BufferAddress, PUINT32 BufferLength)
	Interpret conditions (if an event has condition) and custom code.
VOID	FreeEventsAndActionsMemory (PDEBUGGER_GENERAL_EVENT_DETAIL Event, PDEBUGGER_GENERAL_ACTION ActionBreakToDebugger, PDEBUGGER_GENERAL_ACTION ActionCustomCode, PDEBUGGER_GENERAL_ACTION ActionScript)
	Deallocate buffers relating to events and actions.
BOOLEAN	SendEventToKernel (PDEBUGGER_GENERAL_EVENT_DETAIL Event, UINT32 EventBufferLength)
	Register the event to the kernel.
BOOLEAN	RegisterActionToEvent (PDEBUGGER_GENERAL_EVENT_DETAIL Event, PDEBUGGER_GENERAL_ACTION ActionBreakToDebugger, UINT32 ActionBreakToDebuggerLength, PDEBUGGER_GENERAL_ACTION ActionCustomCode, UINT32 ActionCustomCodeLength, PDEBUGGER_GENERAL_ACTION ActionScript, UINT32 ActionScriptLength)
	Register the action to the event.
BOOLEAN	InterpretGeneralEventAndActionsFields (vector< string > *SplitCommand, vector< string > *SplitCommandCaseSensitive, VMM_EVENT_TYPE_ENUM EventType, PDEBUGGER_GENERAL_EVENT_DETAIL *EventDetailsToFill, PUINT32 EventBufferLength, PDEBUGGER_GENERAL_ACTION *ActionDetailsToFillBreakToDebugger, PUINT32 ActionBufferLengthBreakToDebugger, PDEBUGGER_GENERAL_ACTION *ActionDetailsToFillCustomCode, PUINT32 ActionBufferLengthCustomCode, PDEBUGGER_GENERAL_ACTION *ActionDetailsToFillScript, PUINT32 ActionBufferLengthScript, PDEBUGGER_EVENT_PARSING_ERROR_CAUSE ReasonForErrorInParsing)
	Interpret general event fields.
BOOLEAN	CallstackReturnAddressToCallingAddress (UCHAR *ReturnAddress, PUINT32 IndexOfCallFromReturnAddress)
	Walkthrough the stack.
VOID	CallstackShowFrames (PDEBUGGER_SINGLE_CALLSTACK_FRAME CallstackFrames, UINT32 FrameCount, DEBUGGER_CALLSTACK_DISPLAY_METHOD DisplayMethod, BOOLEAN Is32Bit)
	Show stack frames.
UINT64	GetNewDebuggerEventTag ()
	Get the New Debugger Event Tag object and increase the global variable for tag.
DWORD WINAPI	ListeningSerialPauseDebuggeeThread (PVOID Param)
	Check if the remote debugger needs to pause the system.
DWORD WINAPI	ListeningSerialPauseDebuggerThread (PVOID Param)
	Check if the remote debuggee needs to pause the system.
VOID	LogopenSaveToFile (const char *Text)
	Append text to the file object.
BOOL	BreakController (DWORD CtrlType)
	handle CTRL+C and CTRL+Break events
VOID	CommandEventsShowEvents ()
	print every active and disabled events
BOOLEAN	CommandEventsModifyAndQueryEvents (UINT64 Tag, DEBUGGER_MODIFY_EVENTS_TYPE TypeOfAction)
	modify a special event (enable/disable/clear) and send the request directly to the kernel
VOID	CommandEventsHandleModifiedEvent (UINT64 Tag, PDEBUGGER_MODIFY_EVENTS ModifyEventRequest)
	Handle events after modification.
VOID	CommandEventsClearAllEventsAndResetTags ()
	Clears all the events and resets the tag.
VOID	CommandFlushRequestFlush ()
	flush command handler
UINT64	GetCommandAttributes (const string &FirstCommand)
	Get Command Attributes.
VOID	DetachFromProcess ()
	perform detach from process
VOID	CommandPauseRequest ()
	request to pause
VOID	CommandGRequest ()
	Request to unpause.
VOID	CommandBpRequest (UINT64 Address, UINT32 Pid, UINT32 Tid, UINT32 CoreNumer)
	request breakpoint
VOID	CommandTrackHandleReceivedInstructions (unsigned char *BufferToDisassemble, UINT32 BuffLength, BOOLEAN Isx86_64, UINT64 RipAddress)
	Handle received 'call' or 'ret'.
VOID	CommandTrackHandleReceivedCallInstructions (const char *NameOfFunctionFromSymbols, UINT64 ComputedAbsoluteAddress)
	Handle received 'call'.
VOID	CommandTrackHandleReceivedRetInstructions (UINT64 CurrentRip)
	Handle received 'ret'.
BOOLEAN	HyperDbgWriteMemory (PVOID DestinationAddress, DEBUGGER_EDIT_MEMORY_TYPE MemoryType, UINT32 ProcessId, PVOID SourceAddress, UINT32 NumberOfBytes)
	API function for writing the memory content.
BOOLEAN	HyperDbgReadAllRegisters (GUEST_REGS *GuestRegisters, GUEST_EXTRA_REGISTERS *ExtraRegisters)
	Read all registers.
BOOLEAN	HyperDbgReadTargetRegister (REGS_ENUM RegisterId, UINT64 *TargetRegister)
	Read target register.
BOOLEAN	HyperDbgWriteTargetRegister (REGS_ENUM RegisterId, UINT64 Value)
	Write target register.
BOOLEAN	HyperDbgRegisterShowAll ()
	handler of r show all registers
BOOLEAN	HyperDbgRegisterShowTargetRegister (REGS_ENUM RegisterId)
	handler of r show the target register
BOOLEAN	HyperDbgDebugRemoteDeviceUsingComPort (const CHAR *PortName, DWORD Baudrate)
	Connect to a remote serial device (Debugger)
BOOLEAN	HyperDbgDebugRemoteDeviceUsingNamedPipe (const CHAR *NamedPipe)
	Connect to a remote named pipe (Debugger)
BOOLEAN	HyperDbgDebugCurrentDeviceUsingComPort (const CHAR *PortName, DWORD Baudrate)
	Connect to a remote serial device (Debuggee)

Detailed Description

General debugger functions.

Author

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

Version

0.1

Date

2020-05-27

Copyright

This project is released under the GNU Public License v3.

Macro Definition Documentation

DEBUGGER_MAXIMUM_SYNCRONIZATION_KERNEL_DEBUGGER_OBJECTS

#define DEBUGGER_MAXIMUM_SYNCRONIZATION_KERNEL_DEBUGGER_OBJECTS   0x40

maximum number of event handles in kernel-debugger

DEBUGGER_MAXIMUM_SYNCRONIZATION_USER_DEBUGGER_OBJECTS

#define DEBUGGER_MAXIMUM_SYNCRONIZATION_USER_DEBUGGER_OBJECTS   0x40

Maximum number of event handles in user-debugger.

DEBUGGER_SYNCRONIZATION_OBJECT_KERNEL_DEBUGGER_ADD_ACTION_TO_EVENT

#define DEBUGGER_SYNCRONIZATION_OBJECT_KERNEL_DEBUGGER_ADD_ACTION_TO_EVENT   0xb

DEBUGGER_SYNCRONIZATION_OBJECT_KERNEL_DEBUGGER_BP

#define DEBUGGER_SYNCRONIZATION_OBJECT_KERNEL_DEBUGGER_BP   0xe

DEBUGGER_SYNCRONIZATION_OBJECT_KERNEL_DEBUGGER_CALLSTACK_RESULT

#define DEBUGGER_SYNCRONIZATION_OBJECT_KERNEL_DEBUGGER_CALLSTACK_RESULT   0x14

DEBUGGER_SYNCRONIZATION_OBJECT_KERNEL_DEBUGGER_CORE_SWITCHING_RESULT

#define DEBUGGER_SYNCRONIZATION_OBJECT_KERNEL_DEBUGGER_CORE_SWITCHING_RESULT   0x3

DEBUGGER_SYNCRONIZATION_OBJECT_KERNEL_DEBUGGER_DEBUGGEE_FINISHED_COMMAND_EXECUTION

#define DEBUGGER_SYNCRONIZATION_OBJECT_KERNEL_DEBUGGER_DEBUGGEE_FINISHED_COMMAND_EXECUTION   0x8

DEBUGGER_SYNCRONIZATION_OBJECT_KERNEL_DEBUGGER_EDIT_MEMORY

#define DEBUGGER_SYNCRONIZATION_OBJECT_KERNEL_DEBUGGER_EDIT_MEMORY   0x11

DEBUGGER_SYNCRONIZATION_OBJECT_KERNEL_DEBUGGER_FLUSH_RESULT

#define DEBUGGER_SYNCRONIZATION_OBJECT_KERNEL_DEBUGGER_FLUSH_RESULT   0x9

DEBUGGER_SYNCRONIZATION_OBJECT_KERNEL_DEBUGGER_IS_DEBUGGER_RUNNING

#define DEBUGGER_SYNCRONIZATION_OBJECT_KERNEL_DEBUGGER_IS_DEBUGGER_RUNNING   0x0

An event to show whether the debugger is running or not in kernel-debugger.

DEBUGGER_SYNCRONIZATION_OBJECT_KERNEL_DEBUGGER_LIST_OR_MODIFY_BREAKPOINTS

#define DEBUGGER_SYNCRONIZATION_OBJECT_KERNEL_DEBUGGER_LIST_OR_MODIFY_BREAKPOINTS   0xf

DEBUGGER_SYNCRONIZATION_OBJECT_KERNEL_DEBUGGER_MODIFY_AND_QUERY_EVENT

#define DEBUGGER_SYNCRONIZATION_OBJECT_KERNEL_DEBUGGER_MODIFY_AND_QUERY_EVENT   0xc

DEBUGGER_SYNCRONIZATION_OBJECT_KERNEL_DEBUGGER_PAGE_IN_STATE

#define DEBUGGER_SYNCRONIZATION_OBJECT_KERNEL_DEBUGGER_PAGE_IN_STATE   0x19

DEBUGGER_SYNCRONIZATION_OBJECT_KERNEL_DEBUGGER_PAUSED_DEBUGGEE_DETAILS

#define DEBUGGER_SYNCRONIZATION_OBJECT_KERNEL_DEBUGGER_PAUSED_DEBUGGEE_DETAILS   0x2

DEBUGGER_SYNCRONIZATION_OBJECT_KERNEL_DEBUGGER_PROCESS_SWITCHING_RESULT

#define DEBUGGER_SYNCRONIZATION_OBJECT_KERNEL_DEBUGGER_PROCESS_SWITCHING_RESULT   0x4

DEBUGGER_SYNCRONIZATION_OBJECT_KERNEL_DEBUGGER_PTE_RESULT

#define DEBUGGER_SYNCRONIZATION_OBJECT_KERNEL_DEBUGGER_PTE_RESULT   0x17

DEBUGGER_SYNCRONIZATION_OBJECT_KERNEL_DEBUGGER_READ_MEMORY

#define DEBUGGER_SYNCRONIZATION_OBJECT_KERNEL_DEBUGGER_READ_MEMORY   0x10

DEBUGGER_SYNCRONIZATION_OBJECT_KERNEL_DEBUGGER_READ_REGISTERS

#define DEBUGGER_SYNCRONIZATION_OBJECT_KERNEL_DEBUGGER_READ_REGISTERS   0xd

DEBUGGER_SYNCRONIZATION_OBJECT_KERNEL_DEBUGGER_REGISTER_EVENT

#define DEBUGGER_SYNCRONIZATION_OBJECT_KERNEL_DEBUGGER_REGISTER_EVENT   0xa

DEBUGGER_SYNCRONIZATION_OBJECT_KERNEL_DEBUGGER_SCRIPT_FORMATS_RESULT

#define DEBUGGER_SYNCRONIZATION_OBJECT_KERNEL_DEBUGGER_SCRIPT_FORMATS_RESULT   0x7

DEBUGGER_SYNCRONIZATION_OBJECT_KERNEL_DEBUGGER_SCRIPT_RUNNING_RESULT

#define DEBUGGER_SYNCRONIZATION_OBJECT_KERNEL_DEBUGGER_SCRIPT_RUNNING_RESULT   0x6

DEBUGGER_SYNCRONIZATION_OBJECT_KERNEL_DEBUGGER_SEARCH_QUERY_RESULT

#define DEBUGGER_SYNCRONIZATION_OBJECT_KERNEL_DEBUGGER_SEARCH_QUERY_RESULT   0x15

DEBUGGER_SYNCRONIZATION_OBJECT_KERNEL_DEBUGGER_SHORT_CIRCUITING_EVENT_STATE

#define DEBUGGER_SYNCRONIZATION_OBJECT_KERNEL_DEBUGGER_SHORT_CIRCUITING_EVENT_STATE   0x18

DEBUGGER_SYNCRONIZATION_OBJECT_KERNEL_DEBUGGER_STARTED_PACKET_RECEIVED

#define DEBUGGER_SYNCRONIZATION_OBJECT_KERNEL_DEBUGGER_STARTED_PACKET_RECEIVED   0x1

DEBUGGER_SYNCRONIZATION_OBJECT_KERNEL_DEBUGGER_SYMBOL_RELOAD

#define DEBUGGER_SYNCRONIZATION_OBJECT_KERNEL_DEBUGGER_SYMBOL_RELOAD   0x12

DEBUGGER_SYNCRONIZATION_OBJECT_KERNEL_DEBUGGER_TEST_QUERY

#define DEBUGGER_SYNCRONIZATION_OBJECT_KERNEL_DEBUGGER_TEST_QUERY   0x13

DEBUGGER_SYNCRONIZATION_OBJECT_KERNEL_DEBUGGER_THREAD_SWITCHING_RESULT

#define DEBUGGER_SYNCRONIZATION_OBJECT_KERNEL_DEBUGGER_THREAD_SWITCHING_RESULT   0x5

DEBUGGER_SYNCRONIZATION_OBJECT_KERNEL_DEBUGGER_VA2PA_AND_PA2VA_RESULT

#define DEBUGGER_SYNCRONIZATION_OBJECT_KERNEL_DEBUGGER_VA2PA_AND_PA2VA_RESULT   0x16

DEBUGGER_SYNCRONIZATION_OBJECT_KERNEL_DEBUGGER_WRITE_REGISTER

#define DEBUGGER_SYNCRONIZATION_OBJECT_KERNEL_DEBUGGER_WRITE_REGISTER   0x1a

DEBUGGER_SYNCRONIZATION_OBJECT_USER_DEBUGGER_IS_DEBUGGER_RUNNING

#define DEBUGGER_SYNCRONIZATION_OBJECT_USER_DEBUGGER_IS_DEBUGGER_RUNNING   0x30

An event to show whether the debugger is running or not in user-debugger.

Typedef Documentation

DEBUGGER_EVENT_PARSING_ERROR_CAUSE

typedef enum _DEBUGGER_EVENT_PARSING_ERROR_CAUSE DEBUGGER_EVENT_PARSING_ERROR_CAUSE

Reason for error in parsing commands.

DEBUGGER_SYNCRONIZATION_EVENTS_STATE

typedef struct _DEBUGGER_SYNCRONIZATION_EVENTS_STATE DEBUGGER_SYNCRONIZATION_EVENTS_STATE

In debugger holds the state of events.

PDEBUGGER_EVENT_PARSING_ERROR_CAUSE

typedef enum _DEBUGGER_EVENT_PARSING_ERROR_CAUSE * PDEBUGGER_EVENT_PARSING_ERROR_CAUSE

PDEBUGGER_SYNCRONIZATION_EVENTS_STATE

typedef struct _DEBUGGER_SYNCRONIZATION_EVENTS_STATE * PDEBUGGER_SYNCRONIZATION_EVENTS_STATE

Enumeration Type Documentation

_DEBUGGER_EVENT_PARSING_ERROR_CAUSE

enum _DEBUGGER_EVENT_PARSING_ERROR_CAUSE

Reason for error in parsing commands.

Enumerator
DEBUGGER_EVENT_PARSING_ERROR_CAUSE_SUCCESSFUL_NO_ERROR
DEBUGGER_EVENT_PARSING_ERROR_CAUSE_SCRIPT_SYNTAX_ERROR
DEBUGGER_EVENT_PARSING_ERROR_CAUSE_NO_INPUT
DEBUGGER_EVENT_PARSING_ERROR_CAUSE_MAXIMUM_INPUT_REACHED
DEBUGGER_EVENT_PARSING_ERROR_CAUSE_OUTPUT_NAME_NOT_FOUND
DEBUGGER_EVENT_PARSING_ERROR_CAUSE_OUTPUT_SOURCE_ALREADY_CLOSED
DEBUGGER_EVENT_PARSING_ERROR_CAUSE_ALLOCATION_ERROR
DEBUGGER_EVENT_PARSING_ERROR_CAUSE_FORMAT_ERROR
DEBUGGER_EVENT_PARSING_ERROR_CAUSE_ATTEMPT_TO_BREAK_ON_VMI_MODE
DEBUGGER_EVENT_PARSING_ERROR_CAUSE_IMMEDIATE_MESSAGING_IN_EVENT_FORWARDING_MODE
DEBUGGER_EVENT_PARSING_ERROR_CAUSE_USING_SHORT_CIRCUITING_IN_POST_EVENTS

{
    DEBUGGER_EVENT_PARSING_ERROR_CAUSE_SUCCESSFUL_NO_ERROR                          = 0,
    DEBUGGER_EVENT_PARSING_ERROR_CAUSE_SCRIPT_SYNTAX_ERROR                          = 1,
    DEBUGGER_EVENT_PARSING_ERROR_CAUSE_NO_INPUT                                     = 2,
    DEBUGGER_EVENT_PARSING_ERROR_CAUSE_MAXIMUM_INPUT_REACHED                        = 3,
    DEBUGGER_EVENT_PARSING_ERROR_CAUSE_OUTPUT_NAME_NOT_FOUND                        = 4,
    DEBUGGER_EVENT_PARSING_ERROR_CAUSE_OUTPUT_SOURCE_ALREADY_CLOSED                 = 5,
    DEBUGGER_EVENT_PARSING_ERROR_CAUSE_ALLOCATION_ERROR                             = 6,
    DEBUGGER_EVENT_PARSING_ERROR_CAUSE_FORMAT_ERROR                                 = 7,
    DEBUGGER_EVENT_PARSING_ERROR_CAUSE_ATTEMPT_TO_BREAK_ON_VMI_MODE                 = 8,
    DEBUGGER_EVENT_PARSING_ERROR_CAUSE_IMMEDIATE_MESSAGING_IN_EVENT_FORWARDING_MODE = 9,
    DEBUGGER_EVENT_PARSING_ERROR_CAUSE_USING_SHORT_CIRCUITING_IN_POST_EVENTS        = 10,
 
} DEBUGGER_EVENT_PARSING_ERROR_CAUSE,

Function Documentation

BreakController()

BOOL BreakController

(

DWORD

CtrlType

)

handle CTRL+C and CTRL+Break events

Parameters

CtrlType

Returns

BOOL

{
    switch (CtrlType)
    {
        //
        // Handle the CTRL + C & CTRL + Break signal
        //
    case CTRL_BREAK_EVENT:
    case CTRL_C_EVENT:
 
        //
        // check if we should ignore the break requests or not
        //
        if (g_IgnorePauseRequests)
        {
            return TRUE;
        }
 
        //
        // Check for aborting symbol loading routines
        //
        if (g_IsExecutingSymbolLoadingRoutines)
        {
            //
            // Avoid to calling it again
            //
            g_IsExecutingSymbolLoadingRoutines = FALSE;
 
            //
            // Abort the execution
            //
            ScriptEngineSymbolAbortLoadingWrapper();
        }
 
        //
        // Check if the debuggee is running because of pausing or not
        //
        if (g_IsSerialConnectedToRemoteDebuggee)
        {
            if (g_IsInstrumentingInstructions)
            {
                g_IsInstrumentingInstructions = FALSE;
            }
            else
            {
                KdBreakControlCheckAndPauseDebugger();
            }
        }
        else if (!g_IsDebuggerModulesLoaded && !g_IsConnectedToRemoteDebuggee)
        {
            //
            // vmm module is not loaded here
            //
        }
        else
        {
            if (g_IsInstrumentingInstructions)
            {
                g_IsInstrumentingInstructions = FALSE;
            }
            else
            {
                //
                // Sleep because the other thread that shows must be stopped
                //
                g_BreakPrintingOutput = TRUE;
 
                //
                // Check if its a remote debuggee then we should send the 'pause' command
                //
                if (g_IsConnectedToRemoteDebuggee)
                {
                    RemoteConnectionSendCommand("pause", (UINT32)strlen("pause") + 1);
                }
 
                Sleep(300);
 
                //
                // It is because we didn't query the target debuggee auto-unpause variable
                //
                if (!g_IsConnectedToRemoteDebuggee)
                {
                    if (g_AutoUnpause)
                    {
                        ShowMessages(
                            "\npausing...\nauto-unpause mode is enabled, "
                            "debugger will automatically continue when you run a new "
                            "event command, if you want to change this behaviour then "
                            "run run 'settings autounpause off'\n\n");
                    }
                    else
                    {
                        ShowMessages(
                            "\npausing...\nauto-unpause mode is disabled, you "
                            "should run 'g' when you want to continue, otherwise run "
                            "'settings "
                            "autounpause on'\n\n");
                    }
 
                    //
                    // Show the signature of HyperDbg
                    //
                    HyperDbgShowSignature();
 
                    if (g_ActiveProcessDebuggingState.IsActive)
                    {
                        UdPauseProcess(g_ActiveProcessDebuggingState.ProcessDebuggingToken);
                    }
                }
            }
        }
 
        return TRUE;
 
        //
        // CTRL+CLOSE: confirm that the user wants to exit.
        //
    case CTRL_CLOSE_EVENT:
        return TRUE;
 
    case CTRL_LOGOFF_EVENT:
        return FALSE;
 
    case CTRL_SHUTDOWN_EVENT:
        return FALSE;
 
    default:
 
        //
        // Return TRUE if handled this message, further handler functions won't be
        // called.
        // Return FALSE to pass this message to further handlers until default
        // handler calls ExitProcess().
        //
        return FALSE;
    }
}

CallstackReturnAddressToCallingAddress()

BOOLEAN CallstackReturnAddressToCallingAddress	(	UCHAR *	ReturnAddress,
		PUINT32	IndexOfCallFromReturnAddress )

Walkthrough the stack.

This code is borrowed from here : https://github.com/electronicarts/EAThread/blob/master/source/x86/eathread_callstack_x86.cpp

Parameters

ReturnAddress
IndexOfCallFromReturnAddress

Returns

BOOLEAN

{
    //
    // While negative array indices can be considered non-idiomatic it
    // was felt that they are semantically appropriate as this code bases
    // its comparisons from the return address and that it would be cleaner
    // than using *(ReturnAddress - index).
    //
 
    //
    // Three op-codes are used for the call instruction, 9A, E8, and FF.
    // For a reference on the IA32 instruction format, see:
    // http://www.cs.princeton.edu/courses/archive/spr06/cos217/reading/ia32vol2.pdf
    //
 
    //
    // 9A cp - CALL ptr16:32 (7-byte)
    //
    if (ReturnAddress[-7] == 0x9A)
    {
        *IndexOfCallFromReturnAddress = 7;
        return TRUE;
    }
    // E8 cd - CALL rel32 (5-byte)
    else if (ReturnAddress[-5] == 0xE8)
    {
        *IndexOfCallFromReturnAddress = 5;
        return TRUE;
    }
    else
    {
        //
        // The third opcode to specify "call" instructions is FF.
        // Unfortunately this instruction also needs the succeeding ModR/M
        // byte to fully determine instruction length. The SIB value is
        // another byte used for extending the range of addressing modes
        // supported by the ModR/M byte. The values of this ModR/M byte
        // used in conjunction with the call instruction are as follows:
        //
        // 7-byte call:
        // FF [ModR/M] [SIB] [4-byte displacement]
        //    * ModR/M is either 0x94 or 0x9C
        //
        // 6-byte call:
        // FF [ModR/M] [4-byte displacement]
        //    * ModR/M can be:
        //      * 0x90 - 0x9F EXCLUDING 0x94 or 0x9C
        //      * 0x15 or 0x1D
        //
        // 4-byte call:
        // FF [ModR/M] [SIB] [1-byte displacement]
        //    * ModR/M is either 0x54 or 0x5C
        //
        // 3-byte call:
        // FF [ModR/M] [1-byte displacement]
        //    * ModR/M can be:
        //      * 0x50 - 0x5F EXCLUDING 0x54 or 0x5C
        // FF [ModR/M] [SIB]
        //    * ModR/M is either 0x14 or 0x1C
        //
        // 2-byte call:
        // FF [ModR/M]
        //    * ModR/M can be:
        //      * 0xD0 - 0xDF
        //      * 0x10 - 0x1F EXCEPT 0x14, 0x15, 0x1C, or 0x1D
        //
 
        //
        // The mask of F8 is used because we want to mask out the bottom
        // three bits (which are most often used for register selection)
        //
        const unsigned char RmMask = 0xF8;
 
        //
        // 7-byte format:
        //
        if (ReturnAddress[-7] == 0xFF &&
            (ReturnAddress[-6] == 0x94 || ReturnAddress[-6] == 0x9C))
        {
            *IndexOfCallFromReturnAddress = 7;
            return TRUE;
        }
 
        //
        // 6-byte format:
        // FF [ModR/M] [4-byte displacement]
        //
        else if (ReturnAddress[-6] == 0xFF &&
                 ((ReturnAddress[-5] & RmMask) == 0x90 || (ReturnAddress[-5] & RmMask) == 0x98) &&
                 (ReturnAddress[-5] != 0x94 && ReturnAddress[-5] != 0x9C))
        {
            *IndexOfCallFromReturnAddress = 6;
            return TRUE;
        }
 
        //
        // Alternate 6-byte format:
        //
        else if (ReturnAddress[-6] == 0xFF &&
                 (ReturnAddress[-5] == 0x15 || ReturnAddress[-5] == 0x1D))
        {
            *IndexOfCallFromReturnAddress = 6;
            return TRUE;
        }
 
        //
        // 4-byte format:
        // FF [ModR/M] [SIB] [1-byte displacement]
        //
        else if (ReturnAddress[-4] == 0xFF &&
                 (ReturnAddress[-3] == 0x54 || ReturnAddress[-3] == 0x5C))
        {
            *IndexOfCallFromReturnAddress = 4;
            return TRUE;
        }
 
        //
        // 3-byte format:
        // FF [ModR/M] [1-byte displacement]
        //
        else if (ReturnAddress[-3] == 0xFF &&
                 ((ReturnAddress[-2] & RmMask) == 0x50 || (ReturnAddress[-2] & RmMask) == 0x58) &&
                 (ReturnAddress[-2] != 0x54 && ReturnAddress[-2] != 0x5C))
        {
            *IndexOfCallFromReturnAddress = 3;
            return TRUE;
        }
 
        //
        // Alternate 3-byte format:
        // FF [ModR/M] [SIB]
        //
        else if (ReturnAddress[-3] == 0xFF &&
                 (ReturnAddress[-2] == 0x14 || ReturnAddress[-2] == 0x1C))
        {
            *IndexOfCallFromReturnAddress = 3;
            return TRUE;
        }
 
        //
        // 2-byte calling format:
        // FF [ModR/M]
        //
        else if (ReturnAddress[-2] == 0xFF &&
                 ((ReturnAddress[-1] & RmMask) == 0xD0 || (ReturnAddress[-1] & RmMask) == 0xD8))
        {
            *IndexOfCallFromReturnAddress = 2;
            return TRUE;
        }
 
        //
        // Alternate 2-byte calling format:
        // FF [ModR/M]
        //
        else if (ReturnAddress[-2] == 0xFF &&
                 ((ReturnAddress[-1] & RmMask) == 0x10 || (ReturnAddress[-1] & RmMask) == 0x18) &&
                 (ReturnAddress[-1] != 0x14 && ReturnAddress[-1] != 0x15 &&
                  ReturnAddress[-1] != 0x1C && ReturnAddress[-1] != 0x1D))
        {
            *IndexOfCallFromReturnAddress = 2;
            return TRUE;
        }
        else
        {
            return FALSE;
        }
    }
 
    return FALSE;
}

CallstackShowFrames()

VOID CallstackShowFrames	(	PDEBUGGER_SINGLE_CALLSTACK_FRAME	CallstackFrames,
		UINT32	FrameCount,
		DEBUGGER_CALLSTACK_DISPLAY_METHOD	DisplayMethod,
		BOOLEAN	Is32Bit )

Show stack frames.

Parameters

CallstackFrames
FrameCount
DisplayMethod
Is32Bit

Returns

VOID

{
    UINT32                                                 CallLength;
    UINT64                                                 TargetAddress;
    UINT64                                                 UsedBaseAddress;
    BOOLEAN                                                IsCall = FALSE;
    std::map<UINT64, LOCAL_FUNCTION_DESCRIPTION>::iterator Iterate;
 
    //
    // Print callstack frames
    //
    for (size_t i = 0; i < FrameCount; i++)
    {
        IsCall = FALSE;
 
        if (CallstackFrames[i].IsValidAddress)
        {
            //
            // Check if it's call or just a simple code address
            //
            if (CallstackFrames[i].IsExecutable && CallstackReturnAddressToCallingAddress(
                                                       (unsigned char *)&CallstackFrames[i].InstructionBytesOnRip[MAXIMUM_CALL_INSTR_SIZE],
                                                       &CallLength))
            {
                //
                // Computer the "call" instruction address
                //
                TargetAddress = CallstackFrames[i].Value - CallLength;
 
                IsCall = TRUE;
            }
            else
            {
                //
                // Check if we wanna show the stack params
                //
                if (DisplayMethod == DEBUGGER_CALLSTACK_DISPLAY_METHOD_WITHOUT_PARAMS)
                {
                    continue;
                }
 
                IsCall        = FALSE;
                TargetAddress = CallstackFrames[i].Value;
            }
 
            ShowMessages("[$+%03x] ", i * (Is32Bit ? sizeof(UINT32) : sizeof(UINT64)));
 
            if (IsCall)
            {
                if (Is32Bit)
                {
                    ShowMessages("  %08x    (from ", TargetAddress);
                }
                else
                {
                    ShowMessages("  %016llx    (from ", TargetAddress);
                }
            }
            else
            {
                if (Is32Bit)
                {
                    ShowMessages("     %08x (addr ", TargetAddress);
                }
                else
                {
                    ShowMessages("     %016llx (addr ", TargetAddress);
                }
            }
 
            //
            // Show the name of the function if available
            // Apply addressconversion of settings here
            //
            if (g_AddressConversion)
            {
                if (SymbolShowFunctionNameBasedOnAddress(TargetAddress, &UsedBaseAddress))
                {
                    ShowMessages(" ");
                }
            }
 
            if (Is32Bit)
            {
                ShowMessages("<%08x>)\n", TargetAddress);
            }
            else
            {
                ShowMessages("<%016llx>)\n", TargetAddress);
            }
        }
        else
        {
            //
            // Check if we wanna show the stack params
            //
            if (DisplayMethod == DEBUGGER_CALLSTACK_DISPLAY_METHOD_WITHOUT_PARAMS)
            {
                continue;
            }
 
            ShowMessages("[$+%03x] ", i * (Is32Bit ? sizeof(UINT32) : sizeof(UINT64)));
 
            if (Is32Bit)
            {
                ShowMessages("     %08x\n", CallstackFrames[i].Value);
            }
            else
            {
                ShowMessages("     %016llx\n", CallstackFrames[i].Value);
            }
        }
    }
}

CommandBpRequest()

VOID CommandBpRequest	(	UINT64	Address,
		UINT32	Pid,
		UINT32	Tid,
		UINT32	CoreNumer )

request breakpoint

Parameters

Address	Address
Pid	Process Id
Tid	Thread Id
CoreNumer	Core Number

Returns

VOID

{
    DEBUGGEE_BP_PACKET BpPacket = {0};
 
    //
    // Set the details for the remote packet
    //
    BpPacket.Address = Address;
    BpPacket.Core    = CoreNumer;
    BpPacket.Pid     = Pid;
    BpPacket.Tid     = Tid;
 
    //
    // Send the bp packet
    //
    KdSendBpPacketToDebuggee(&BpPacket);
}

CommandEventsClearAllEventsAndResetTags()

VOID CommandEventsClearAllEventsAndResetTags

(

)

Clears all the events and resets the tag.

Returns

VOID

{
    //
    // Check if events are initialized
    //
    if (g_EventTraceInitialized)
    {
        CommandEventClearEvent(DEBUGGER_MODIFY_EVENTS_APPLY_TO_ALL_TAG);
 
        //
        // Indicate that it's not initialized
        //
        g_EventTraceInitialized = FALSE;
 
        //
        // Reset tag numbering mechanism
        //
        g_EventTag = DebuggerEventTagStartSeed;
    }
}

CommandEventsHandleModifiedEvent()

VOID CommandEventsHandleModifiedEvent	(	UINT64	Tag,
		PDEBUGGER_MODIFY_EVENTS	ModifyEventRequest )

Handle events after modification.

Parameters

Tag	the tag of the target event
ModifyEventRequest	Results

Returns

VOID

{
    if (ModifyEventRequest->KernelStatus == DEBUGGER_OPERATION_WAS_SUCCESSFUL)
    {
        //
        // Successful, nothing to show but we should also
        // do the same (change) the user-mode structures
        // that hold the event data
        //
        if (ModifyEventRequest->TypeOfAction == DEBUGGER_MODIFY_EVENTS_ENABLE)
        {
            if (!CommandEventEnableEvent(Tag))
            {
                ShowMessages("err, the event was successfully, "
                             "(enabled|disabled|cleared) but "
                             "can't apply it to the user-mode structures\n");
            }
        }
        else if (ModifyEventRequest->TypeOfAction == DEBUGGER_MODIFY_EVENTS_DISABLE)
        {
            if (!CommandEventDisableEvent(Tag))
            {
                ShowMessages("err, the event was successfully, "
                             "(enabled|disabled|cleared) but "
                             "can't apply it to the user-mode structures\n");
            }
            else
            {
                //
                // The action was applied successfully
                //
                if (g_BreakPrintingOutput)
                {
                    //
                    // It is because we didn't query the target debuggee auto-flush
                    // variable
                    //
                    if (!g_IsConnectedToRemoteDebuggee &&
                        !g_IsSerialConnectedToRemoteDebuggee &&
                        !g_IsSerialConnectedToRemoteDebugger)
                    {
                        if (!g_AutoFlush)
                        {
                            ShowMessages(
                                "auto-flush mode is disabled, if there is still "
                                "messages or buffers in the kernel, you continue to see "
                                "the messages when you run 'g' until the kernel "
                                "buffers are empty. you can run 'settings autoflush "
                                "on' and after disabling and clearing events, "
                                "kernel buffers will be flushed automatically\n");
                        }
                        else
                        {
                            //
                            // We should flush buffers here
                            //
                            CommandFlushRequestFlush();
                        }
                    }
                }
            }
        }
        else if (ModifyEventRequest->TypeOfAction == DEBUGGER_MODIFY_EVENTS_CLEAR)
        {
            if (!CommandEventClearEvent(Tag))
            {
                ShowMessages("err, the event was successfully, "
                             "(enabled|disabled|cleared) but "
                             "can't apply it to the user-mode structures\n");
            }
            else
            {
                //
                // If HyperDbg is operating at the Debugger Mode, we'll indicate that
                // the event will be cleared after continuing the debuggee
                //
                if (g_IsSerialConnectedToRemoteDebuggee)
                {
                    ShowMessages("%s successfully cleared, but please note in the Debugger Mode (current mode), HyperDbg "
                                 "cannot clear events instantly. Instead, it first disables the events, and when "
                                 "you continue the debuggee (e.g., by pressing the 'g' command), the event will be cleared. "
                                 "Reapplying the same event without first continuing the debuggee may result in undefined behavior\n",
                                 Tag == DEBUGGER_MODIFY_EVENTS_APPLY_TO_ALL_TAG ? "events are" : "the event is");
                }
 
                //
                // The action was applied successfully
                //
                if (g_BreakPrintingOutput)
                {
                    //
                    // It is because we didn't query the target debuggee auto-flush
                    // variable
                    //
                    if (!g_IsConnectedToRemoteDebuggee)
                    {
                        if (!g_AutoFlush)
                        {
                            ShowMessages(
                                "auto-flush mode is disabled, if there is still "
                                "messages or buffers in the kernel, you continue to see "
                                "the messages when you run 'g' until the kernel "
                                "buffers are empty. you can run 'settings autoflush "
                                "on' and after disabling and clearing events, "
                                "kernel buffers will be flushed automatically\n");
                        }
                        else
                        {
                            //
                            // We should flush buffers here
                            //
                            CommandFlushRequestFlush();
                        }
                    }
                }
            }
        }
        else if (ModifyEventRequest->TypeOfAction ==
                 DEBUGGER_MODIFY_EVENTS_QUERY_STATE)
        {
            //
            // Nothing to show
            //
        }
        else
        {
            ShowMessages(
                "err, the event was successfully, (enabled|disabled|cleared) but "
                "can't apply it to the user-mode structures\n");
        }
    }
    else
    {
        //
        // Interpret error
        //
        ShowErrorMessage((UINT32)ModifyEventRequest->KernelStatus);
        return;
    }
}

CommandEventsModifyAndQueryEvents()

BOOLEAN CommandEventsModifyAndQueryEvents	(	UINT64	Tag,
		DEBUGGER_MODIFY_EVENTS_TYPE	TypeOfAction )

modify a special event (enable/disable/clear) and send the request directly to the kernel

if you pass DEBUGGER_MODIFY_EVENTS_APPLY_TO_ALL_TAG as the tag then it will be applied to all the active/disabled events in the kernel

Parameters

Tag	the tag of the target event
TypeOfAction	whether its a enable/disable/clear

Returns

BOOLEAN Shows whether the event is enabled or disabled

{
    BOOLEAN                Status;
    ULONG                  ReturnedLength;
    DEBUGGER_MODIFY_EVENTS ModifyEventRequest = {0};
 
    //
    // Check if there is no event, then we shouldn't apply the
    // enable, disable, or clear commands, this command also
    // checks for DEBUGGER_MODIFY_EVENTS_APPLY_TO_ALL_TAG to
    // see if at least one tag exists or not; however, it's not
    // necessary as the kernel will check for the validity of
    // tag too, but let's not send it to kernel as we can prevent
    // invalid requests from user-mode too
    //
    if (!IsTagExist(Tag))
    {
        if (Tag == DEBUGGER_MODIFY_EVENTS_APPLY_TO_ALL_TAG)
        {
            ShowMessages("there is no event\n");
        }
        else
        {
            ShowMessages("err, tag id is invalid\n");
        }
        return FALSE;
    }
 
    if (g_IsSerialConnectedToRemoteDebuggee)
    {
        //
        // Remote debuggee Debugger Mode
        //
        KdSendEventQueryAndModifyPacketToDebuggee(Tag, TypeOfAction, NULL);
    }
    else
    {
        //
        // Local debugging VMI-Mode
        //
 
        //
        // Check if debugger is loaded or not
        //
        AssertShowMessageReturnStmt(g_DeviceHandle, ASSERT_MESSAGE_DRIVER_NOT_LOADED, AssertReturnFalse);
 
        //
        // Fill the structure to send it to the kernel
        //
        ModifyEventRequest.Tag          = Tag;
        ModifyEventRequest.TypeOfAction = TypeOfAction;
 
        //
        // Send the request to the kernel
        //
        Status =
            DeviceIoControl(g_DeviceHandle,                // Handle to device
                            IOCTL_DEBUGGER_MODIFY_EVENTS,  // IO Control Code (IOCTL)
                            &ModifyEventRequest,           // Input Buffer to driver.
                            SIZEOF_DEBUGGER_MODIFY_EVENTS, // Input buffer length
                            &ModifyEventRequest,           // Output Buffer from driver.
                            SIZEOF_DEBUGGER_MODIFY_EVENTS, // Length of output
                                                           // buffer in bytes.
                            &ReturnedLength,               // Bytes placed in buffer.
                            NULL                           // synchronous call
            );
 
        if (!Status)
        {
            ShowMessages("ioctl failed with code 0x%x\n", GetLastError());
            return FALSE;
        }
 
        //
        // Perform further actions
        //
        CommandEventsHandleModifiedEvent(Tag, &ModifyEventRequest);
 
        if (TypeOfAction == DEBUGGER_MODIFY_EVENTS_QUERY_STATE)
        {
            return ModifyEventRequest.IsEnabled;
        }
    }
 
    //
    // in all the cases except query state it shows whether the operation was
    // successful or not
    //
    return TRUE;
}

CommandEventsShowEvents()

VOID CommandEventsShowEvents

(

)

print every active and disabled events

this function will not show cleared events

Returns

VOID

{
    //
    // It's an events without any argument so we have to show
    // all the currently active events
    //
    PLIST_ENTRY TempList         = 0;
    BOOLEAN     IsThereAnyEvents = FALSE;
 
    TempList = &g_EventTrace;
    while (&g_EventTrace != TempList->Blink)
    {
        TempList = TempList->Blink;
 
        PDEBUGGER_GENERAL_EVENT_DETAIL CommandDetail = CONTAINING_RECORD(TempList, DEBUGGER_GENERAL_EVENT_DETAIL, CommandsEventList);
        string                         CommandMessage((char *)CommandDetail->CommandStringBuffer);
 
        //
        // Do not show the \n(s)
        //
        ReplaceAll(CommandMessage, "\n", " ");
 
        //
        // Only show portion of message
        //
        if (CommandMessage.length() > 70)
        {
            CommandMessage = CommandMessage.substr(0, 70);
            CommandMessage += "...";
        }
 
        ShowMessages("%x\t(%s)\t    %s\n",
                     CommandDetail->Tag - DebuggerEventTagStartSeed,
                     // CommandDetail->IsEnabled ? "enabled" : "disabled",
                     CommandEventQueryEventState(CommandDetail->Tag)
                         ? "enabled"
                         : "disabled", /* Query is live now */
                     CommandMessage.c_str());
 
        if (!IsThereAnyEvents)
        {
            IsThereAnyEvents = TRUE;
        }
    }
 
    if (!IsThereAnyEvents)
    {
        ShowMessages("no active/disabled events \n");
    }
}

CommandFlushRequestFlush()

VOID CommandFlushRequestFlush

(

)

flush command handler

Returns

VOID

{
    BOOL                           Status;
    ULONG                          ReturnedLength;
    DEBUGGER_FLUSH_LOGGING_BUFFERS FlushRequest = {0};
 
    if (g_IsSerialConnectedToRemoteDebuggee)
    {
        //
        // It's a debug-mode
        //
        KdSendFlushPacketToDebuggee();
    }
    else
    {
        //
        // It's a vmi-mode
        //
        AssertShowMessageReturnStmt(g_DeviceHandle, ASSERT_MESSAGE_DRIVER_NOT_LOADED, AssertReturn);
 
        //
        // By the way, we don't need to send an input buffer
        // to the kernel, but let's keep it like this, if we
        // want to pass some other arguments to the kernel in
        // the future
        //
        Status = DeviceIoControl(
            g_DeviceHandle,                        // Handle to device
            IOCTL_DEBUGGER_FLUSH_LOGGING_BUFFERS,  // IO Control Code (IOCTL)
            &FlushRequest,                         // Input Buffer to driver.
            SIZEOF_DEBUGGER_FLUSH_LOGGING_BUFFERS, // Input buffer length
            &FlushRequest,                         // Output Buffer from driver.
            SIZEOF_DEBUGGER_FLUSH_LOGGING_BUFFERS, // Length of output buffer in
                                                   // bytes.
            &ReturnedLength,                       // Bytes placed in buffer.
            NULL                                   // synchronous call
        );
 
        if (!Status)
        {
            ShowMessages("ioctl failed with code 0x%x\n", GetLastError());
            return;
        }
 
        if (FlushRequest.KernelStatus == DEBUGGER_OPERATION_WAS_SUCCESSFUL)
        {
            //
            // The amount of message that are deleted are the amount of
            // vmx-root messages and vmx non-root messages
            //
            ShowMessages(
                "flushing buffers was successful, total %d messages were cleared.\n",
                FlushRequest.CountOfMessagesThatSetAsReadFromVmxNonRoot +
                    FlushRequest.CountOfMessagesThatSetAsReadFromVmxRoot);
        }
        else
        {
            ShowMessages("flushing buffers was not successful :(\n");
        }
    }
}

CommandGRequest()

VOID CommandGRequest

(

)

Request to unpause.

Returns

VOID

{
    //
    // Check if the remote serial debuggee is paused or not
    //
    if (g_IsSerialConnectedToRemoteDebuggee)
    {
        KdBreakControlCheckAndContinueDebugger();
    }
    else
    {
        //
        // Set the g_BreakPrintingOutput to FALSE
        //
        g_BreakPrintingOutput = FALSE;
 
        //
        // If it's a remote debugger then we send the remote debuggee a 'g'
        // and if we're connect to user debugger then we send the packet
        // with current debugging thread token
        //
        if (g_IsConnectedToRemoteDebuggee)
        {
            RemoteConnectionSendCommand("g", (UINT32)strlen("g") + 1);
        }
        else if (g_ActiveProcessDebuggingState.IsActive)
        {
            if (g_ActiveProcessDebuggingState.IsPaused)
            {
                UdContinueDebuggee(g_ActiveProcessDebuggingState.ProcessDebuggingToken);
 
                //
                // Target process is running
                //
                g_ActiveProcessDebuggingState.IsPaused = FALSE;
            }
            else
            {
                ShowMessages("err, target process is already running\n");
            }
        }
    }
}

CommandPauseRequest()

VOID CommandPauseRequest

(

)

request to pause

Returns

VOID

{
    //
    // Set the g_BreakPrintingOutput to TRUE
    //
    g_BreakPrintingOutput = TRUE;
    ShowMessages("pausing...\n");
 
    //
    // If it's a remote debugger then we send the remote debuggee a 'g'
    //
    if (g_IsConnectedToRemoteDebuggee)
    {
        RemoteConnectionSendCommand("pause", (UINT32)strlen("pause") + 1);
    }
    else if (g_ActiveProcessDebuggingState.IsActive && UdPauseProcess(g_ActiveProcessDebuggingState.ProcessDebuggingToken))
    {
        ShowMessages("please keep interacting with the process until all the "
                     "threads are intercepted and halted; whenever you execute "
                     "the first command, the thread interception will be stopped\n");
    }
}

CommandTrackHandleReceivedCallInstructions()

VOID CommandTrackHandleReceivedCallInstructions	(	const char *	NameOfFunctionFromSymbols,
		UINT64	ComputedAbsoluteAddress )

Handle received 'call'.

Parameters

NameOfFunctionFromSymbols
ComputedAbsoluteAddress

Returns

VOID

CommandTrackHandleReceivedInstructions()

VOID CommandTrackHandleReceivedInstructions	(	unsigned char *	BufferToDisassemble,
		UINT32	BuffLength,
		BOOLEAN	Isx86_64,
		UINT64	RipAddress )

Handle received 'call' or 'ret'.

Parameters

BufferToDisassemble
BuffLength
Isx86_64
RipAddress

Returns

VOID

{
 

CommandTrackHandleReceivedRetInstructions()

VOID CommandTrackHandleReceivedRetInstructions

(

UINT64

CurrentRip

)

Handle received 'ret'.

Parameters

CurrentRip

Returns

VOID

{
 

DebuggerGetKernelBase()

UINT64 DebuggerGetKernelBase

(

)

Get the base address of the kernel module.

Returns

UINT64

{
    UINT64 KernelBase = NULL;
 
    if (g_IsSerialConnectedToRemoteDebuggee)
    {
        KernelBase = g_KernelBaseAddress;
    }
    else
    {
        KernelBase          = DebuggerGetNtoskrnlBase();
        g_KernelBaseAddress = KernelBase;
    }
 
    return KernelBase;
}

DebuggerGetNtoskrnlBase()

UINT64 DebuggerGetNtoskrnlBase

(

)

Get ntoskrnl.exe base in the kernel.

Returns

UINT64 Base address of ntoskrnl.exe

{
    NTSTATUS             Status                  = STATUS_UNSUCCESSFUL;
    UINT64               NtoskrnlBase            = NULL;
    PRTL_PROCESS_MODULES Modules                 = NULL;
    ULONG                SysModuleInfoBufferSize = 0;
 
    //
    // Get required size of "RTL_PROCESS_MODULES" buffer
    //
    Status = NtQuerySystemInformation((SYSTEM_INFORMATION_CLASS)SystemModuleInformation, NULL, NULL, &SysModuleInfoBufferSize);
 
    Modules = (PRTL_PROCESS_MODULES)malloc(SysModuleInfoBufferSize);
 
    if (Modules == NULL)
    {
        return NULL64_ZERO;
    }
 
    NtQuerySystemInformation((SYSTEM_INFORMATION_CLASS)SystemModuleInformation, Modules, SysModuleInfoBufferSize, NULL);
 
    for (UINT32 i = 0; i < Modules->NumberOfModules; i++)
    {
        if (!strcmp((const char *)Modules->Modules[i].FullPathName + Modules->Modules[i].OffsetToFileName,
                    "ntoskrnl.exe"))
        {
            NtoskrnlBase = (UINT64)Modules->Modules[i].ImageBase;
            break;
        }
    }
 
    free(Modules);
 
    return NtoskrnlBase;
}

DebuggerPauseDebuggee()

BOOLEAN DebuggerPauseDebuggee

(

)

pauses the debuggee

Returns

BOOLEAN shows whether the pause was successful or not, if successful then when it returns true the debuggee is not paused anymore (continued)

{
    BOOLEAN                        StatusIoctl    = 0;
    ULONG                          ReturnedLength = 0;
    DEBUGGER_PAUSE_PACKET_RECEIVED PauseRequest   = {0};
 
    //
    // Send a pause IOCTL
    //
    StatusIoctl = DeviceIoControl(g_DeviceHandle,                        // Handle to device
                                  IOCTL_PAUSE_PACKET_RECEIVED,           // IO Control Code (IOCTL)
                                  &PauseRequest,                         // Input Buffer to driver.
                                  SIZEOF_DEBUGGER_PAUSE_PACKET_RECEIVED, // Input buffer
                                                                         // length
                                  &PauseRequest,                         // Output Buffer from driver.
                                  SIZEOF_DEBUGGER_PAUSE_PACKET_RECEIVED, // Length of output
                                                                         // buffer in bytes.
                                  &ReturnedLength,                       // Bytes placed in buffer.
                                  NULL                                   // synchronous call
    );
 
    if (!StatusIoctl)
    {
        ShowMessages("ioctl failed with code 0x%x\n", GetLastError());
        return FALSE;
    }
 
    if (PauseRequest.Result == DEBUGGER_OPERATION_WAS_SUCCESSFUL)
    {
        //
        // Nothing to show, the request was successfully processed
        //
        return TRUE;
    }
    else
    {
        ShowErrorMessage(PauseRequest.Result);
        return FALSE;
    }
    return FALSE;
}

DetachFromProcess()

VOID DetachFromProcess

(

)

perform detach from process

Returns

VOID

{
    DEBUGGER_ATTACH_DETACH_USER_MODE_PROCESS DetachRequest = {0};
 
    //
    // Check if debugger is loaded or not
    //
    AssertShowMessageReturnStmt(g_DeviceHandle, ASSERT_MESSAGE_DRIVER_NOT_LOADED, AssertReturn);
 
    //
    // Check if we attached to a process or not
    //
    if (!g_ActiveProcessDebuggingState.IsActive)
    {
        ShowMessages("you're not attached to any thread\n");
        return;
    }
 
    //
    // Perform the detaching of the target process
    //
    UdDetachProcess(g_ActiveProcessDebuggingState.ProcessId, g_ActiveProcessDebuggingState.ProcessDebuggingToken);
}

FreeEventsAndActionsMemory()

VOID FreeEventsAndActionsMemory	(	PDEBUGGER_GENERAL_EVENT_DETAIL	Event,
		PDEBUGGER_GENERAL_ACTION	ActionBreakToDebugger,
		PDEBUGGER_GENERAL_ACTION	ActionCustomCode,
		PDEBUGGER_GENERAL_ACTION	ActionScript )

Deallocate buffers relating to events and actions.

Parameters

return VOID

{
    if (Event != NULL)
    {
        if (Event->CommandStringBuffer != NULL)
        {
            free(Event->CommandStringBuffer);
        }
 
        free(Event);
    }
 
    if (ActionBreakToDebugger != NULL)
    {
        free(ActionBreakToDebugger);
    }
    if (ActionCustomCode != NULL)
    {
        free(ActionCustomCode);
    }
    if (ActionScript != NULL)
    {
        free(ActionScript);
    }
}

GetCommandAttributes()

UINT64 GetCommandAttributes

(

const string &

FirstCommand

)

Get Command Attributes.

Parameters

FirstCommand

just the first word of command (without other parameters)

Returns

BOOLEAN Mask of the command's attributes

{
    CommandType::iterator Iterator;
 
    //
    // Some commands should not be passed to the remote system
    // and instead should be handled in the current debugger
    //
 
    Iterator = g_CommandsList.find(FirstCommand);
 
    if (Iterator == g_CommandsList.end())
    {
        //
        // Command doesn't exist, if it's not exists then it's better to handle
        // it locally, instead of sending it to the remote computer
        //
        return DEBUGGER_COMMAND_ATTRIBUTE_ABSOLUTE_LOCAL;
    }
    else
    {
        return Iterator->second.CommandAttrib;
    }
 
    return NULL;
}

GetNewDebuggerEventTag()

UINT64 GetNewDebuggerEventTag

(

)

Get the New Debugger Event Tag object and increase the global variable for tag.

Returns

UINT64

{
    return g_EventTag++;
}

HyperDbgDebugCurrentDeviceUsingComPort()

BOOLEAN HyperDbgDebugCurrentDeviceUsingComPort	(	const CHAR *	PortName,
		DWORD	Baudrate )

Connect to a remote serial device (Debuggee)

Parameters

PortName
Baudrate

Returns

BOOLEAN

{
    UINT32 Port;
 
    //
    // Check if baudrate is valid or not
    //
    if (!CommandDebugCheckBaudrate(Baudrate))
    {
        //
        // Baud-rate is invalid
        //
        return FALSE;
    }
 
    //
    // check if com port address is valid or not
    //
    if (!CommandDebugCheckComPort(PortName, &Port))
    {
        //
        // com port is invalid
        //
        return FALSE;
    }
 
    //
    // Everything is okay, connect to the remote machine to send (debuggee)
    //
    return KdPrepareAndConnectDebugPort(PortName, Baudrate, Port, TRUE, FALSE);
}

HyperDbgDebugRemoteDeviceUsingComPort()

BOOLEAN HyperDbgDebugRemoteDeviceUsingComPort	(	const CHAR *	PortName,
		DWORD	Baudrate )

Connect to a remote serial device (Debugger)

Parameters

PortName
Baudrate

Returns

BOOLEAN

{
    UINT32 Port;
 
    //
    // Check if baudrate is valid or not
    //
    if (!CommandDebugCheckBaudrate(Baudrate))
    {
        //
        // Baud-rate is invalid
        //
        return FALSE;
    }
 
    //
    // check if com port address is valid or not
    //
    if (!CommandDebugCheckComPort(PortName, &Port))
    {
        //
        // com port is invalid
        //
        return FALSE;
    }
 
    //
    // Everything is okay, connect to the remote machine to send (debugger)
    //
    return KdPrepareAndConnectDebugPort(PortName, Baudrate, Port, FALSE, FALSE);
}

HyperDbgDebugRemoteDeviceUsingNamedPipe()

BOOLEAN HyperDbgDebugRemoteDeviceUsingNamedPipe

(

const CHAR *

NamedPipe

)

Connect to a remote named pipe (Debugger)

Parameters

NamedPipe

Returns

BOOLEAN

{
    return KdPrepareAndConnectDebugPort(NamedPipe, NULL, NULL, FALSE, TRUE);
}

HyperDbgReadAllRegisters()

BOOLEAN HyperDbgReadAllRegisters	(	GUEST_REGS *	GuestRegisters,
		GUEST_EXTRA_REGISTERS *	ExtraRegisters )

Read all registers.

Parameters

GuestRegisters	The guest registers
ExtraRegisters	The extra registers

Returns

BOOLEAN Returns true if it was successful

{
    PGUEST_REGS                          Regs;
    PGUEST_EXTRA_REGISTERS               ExtraRegs;
    DEBUGGEE_REGISTER_READ_DESCRIPTION * RegState       = NULL;
    UINT32                               SizeOfRegState = 0;
 
    //
    // Calculate the size of the register state
    //
    SizeOfRegState = sizeof(DEBUGGEE_REGISTER_READ_DESCRIPTION) + sizeof(GUEST_REGS) + sizeof(GUEST_EXTRA_REGISTERS);
 
    //
    // Allocate memory for the register state
    //
    RegState = (DEBUGGEE_REGISTER_READ_DESCRIPTION *)malloc(SizeOfRegState);
 
    //
    // Check if the memory allocation was successful
    //
    if (RegState == NULL)
    {
        return FALSE;
    }
 
    //
    // Set the register ID to show all registers
    //
    RegState->RegisterId = DEBUGGEE_SHOW_ALL_REGISTERS;
 
    if (!KdSendReadRegisterPacketToDebuggee(RegState, SizeOfRegState))
    {
        free(RegState);
        return FALSE;
    }
 
    if (RegState->KernelStatus == DEBUGGER_OPERATION_WAS_SUCCESSFUL)
    {
        //
        // Copy the registers and extra registers to the output
        //
        Regs      = (GUEST_REGS *)(((CHAR *)RegState) + sizeof(DEBUGGEE_REGISTER_READ_DESCRIPTION));
        ExtraRegs = (GUEST_EXTRA_REGISTERS *)(((CHAR *)RegState) + sizeof(DEBUGGEE_REGISTER_READ_DESCRIPTION) + sizeof(GUEST_REGS));
 
        if (GuestRegisters != NULL)
        {
            memcpy(GuestRegisters, Regs, sizeof(GUEST_REGS));
        }
 
        if (ExtraRegisters != NULL)
        {
            memcpy(ExtraRegisters, ExtraRegs, sizeof(GUEST_EXTRA_REGISTERS));
        }
    }
    else
    {
        ShowErrorMessage(RegState->KernelStatus);
        free(RegState);
        return FALSE;
    }
 
    free(RegState);
    return TRUE;
}

HyperDbgReadTargetRegister()

BOOLEAN HyperDbgReadTargetRegister	(	REGS_ENUM	RegisterId,
		UINT64 *	TargetRegister )

Read target register.

Parameters

RegisterId	The register ID
TargetRegister	The value of the target register

Returns

BOOLEAN Returns true if it was successful

{
    DEBUGGEE_REGISTER_READ_DESCRIPTION RegState = {0};
 
    //
    // Set the register ID
    //
    RegState.RegisterId = (UINT32)RegisterId;
 
    if (!KdSendReadRegisterPacketToDebuggee(&RegState, sizeof(DEBUGGEE_REGISTER_READ_DESCRIPTION)))
    {
        return FALSE;
    }
 
    if (RegState.KernelStatus == DEBUGGER_OPERATION_WAS_SUCCESSFUL)
    {
        if (TargetRegister != NULL)
        {
            *TargetRegister = RegState.Value;
        }
    }
    else
    {
        ShowErrorMessage(RegState.KernelStatus);
        return FALSE;
    }
 
    return TRUE;
}

HyperDbgRegisterShowAll()

BOOLEAN HyperDbgRegisterShowAll

(

)

handler of r show all registers

Returns

BOOLEAN

{
    GUEST_REGS            Regs      = {0};
    GUEST_EXTRA_REGISTERS ExtraRegs = {0};
    RFLAGS                Rflags    = {0};
 
    if (!HyperDbgReadAllRegisters(&Regs, &ExtraRegs))
    {
        return FALSE;
    }
 
    //
    // Show the result of reading registers like rax=0000000000018b01
    //
    Rflags.AsUInt = ExtraRegs.RFLAGS;
 
    ShowMessages(
        "RAX=%016llx RBX=%016llx RCX=%016llx\n"
        "RDX=%016llx RSI=% 016llx RDI=%016llx\n"
        "RIP=%016llx RSP=%016llx RBP=%016llx\n"
        "R8 =%016llx R9 =%016llx R10=%016llx\n"
        "R11=%016llx R12=%016llx R13=%016llx\n"
        "R14=%016llx R15=%016llx IOPL=%02x\n"
        "%s  %s  %s  %s\n%s  %s  %s  %s\n"
        "CS %04x SS %04x DS %04x ES %04x FS %04x GS %04x\n"
        "RFLAGS=%016llx\n",
        Regs.rax,
        Regs.rbx,
        Regs.rcx,
        Regs.rdx,
        Regs.rsi,
        Regs.rdi,
        ExtraRegs.RIP,
        Regs.rsp,
        Regs.rbp,
        Regs.r8,
        Regs.r9,
        Regs.r10,
        Regs.r11,
        Regs.r12,
        Regs.r13,
        Regs.r14,
        Regs.r15,
        Rflags.IoPrivilegeLevel,
        Rflags.OverflowFlag ? "OF 1" : "OF 0",
        Rflags.DirectionFlag ? "DF 1" : "DF 0",
        Rflags.InterruptEnableFlag ? "IF 1" : "IF 0",
        Rflags.SignFlag ? "SF  1" : "SF  0",
        Rflags.ZeroFlag ? "ZF 1" : "ZF 0",
        Rflags.ParityFlag ? "PF 1" : "PF 0",
        Rflags.CarryFlag ? "CF 1" : "CF 0",
        Rflags.AuxiliaryCarryFlag ? "AXF 1" : "AXF 0",
        ExtraRegs.CS,
        ExtraRegs.SS,
        ExtraRegs.DS,
        ExtraRegs.ES,
        ExtraRegs.FS,
        ExtraRegs.GS,
        ExtraRegs.RFLAGS);
 
    return TRUE;
}

HyperDbgRegisterShowTargetRegister()

BOOLEAN HyperDbgRegisterShowTargetRegister

(

REGS_ENUM

RegisterId

)

handler of r show the target register

Parameters

RegisterId

The register ID

Returns

BOOLEAN Returns true if it was successful

{
    UINT64 TargetRegister = 0;
 
    //
    // Read target register
    //
    if (!HyperDbgReadTargetRegister(RegisterId, &TargetRegister))
    {
        return FALSE;
    }
 
    ShowMessages("%s=%016llx\n",
                 RegistersNames[RegisterId],
                 TargetRegister);
 
    return TRUE;
}

HyperDbgWriteMemory()

BOOLEAN HyperDbgWriteMemory	(	PVOID	DestinationAddress,
		DEBUGGER_EDIT_MEMORY_TYPE	MemoryType,
		UINT32	ProcessId,
		PVOID	SourceAddress,
		UINT32	NumberOfBytes )

API function for writing the memory content.

Parameters

AddressToEdit
MemoryType
ProcessId
SourceAddress
NumberOfBytes

Returns

BOOLEAN

{
    UINT32                         RequiredBytes = 0;
    DEBUGGER_EDIT_MEMORY_BYTE_SIZE ByteSize;
    UINT64 *                       TargetBuffer;
    UINT32                         FinalSize    = 0;
    BOOLEAN                        Result       = FALSE;
    BYTE *                         BufferToEdit = (BYTE *)SourceAddress;
 
    //
    // Set the byte size to byte granularity
    //
    ByteSize = EDIT_BYTE;
 
    //
    // Calculate the count of 64 chunks
    //
    RequiredBytes = NumberOfBytes * sizeof(UINT64);
 
    //
    // Allocate structure + buffer
    //
    TargetBuffer = (UINT64 *)malloc(RequiredBytes);
 
    if (!TargetBuffer)
    {
        return FALSE;
    }
 
    //
    // Zero the buffer
    //
    ZeroMemory(TargetBuffer, FinalSize);
 
    //
    // Copy requested memory in 64bit chunks
    //
    for (size_t i = 0; i < NumberOfBytes; i++)
    {
        TargetBuffer[i] = BufferToEdit[i];
    }
 
    //
    // Perform the write operation
    //
    Result = WriteMemoryContent((UINT64)DestinationAddress,
                                MemoryType,
                                ByteSize,
                                ProcessId,
                                NumberOfBytes,
                                TargetBuffer);
 
    //
    // Free the malloc buffer
    //
    free(TargetBuffer);
 
    return Result;
}

HyperDbgWriteTargetRegister()

BOOLEAN HyperDbgWriteTargetRegister	(	REGS_ENUM	RegisterId,
		UINT64	Value )

Write target register.

Parameters

RegisterId	The register ID
Value	The value of the target register

Returns

BOOLEAN Returns true if it was successful

{
    DEBUGGEE_REGISTER_WRITE_DESCRIPTION RegState = {0};
 
    //
    // Set the register ID
    //
    RegState.RegisterId = (UINT32)RegisterId;
    RegState.Value      = Value;
 
    if (!KdSendWriteRegisterPacketToDebuggee(&RegState))
    {
        return FALSE;
    }
 
    if (RegState.KernelStatus == DEBUGGER_OPERATION_WAS_SUCCESSFUL)
    {
        return TRUE;
    }
    else
    {
        ShowErrorMessage(RegState.KernelStatus);
        return FALSE;
    }
}

InterpretConditionsAndCodes()

BOOLEAN InterpretConditionsAndCodes	(	vector< string > *	SplitCommand,
		vector< string > *	SplitCommandCaseSensitive,
		BOOLEAN	IsConditionBuffer,
		PUINT64	BufferAddress,
		PUINT32	BufferLength )

Interpret conditions (if an event has condition) and custom code.

If this function returns true then it means that there is a condition or code buffer in this command split and the details are returned in the input structure

Parameters

SplitCommand	the initialized command that are split by space
SplitCommandCaseSensitive	the initialized command that are split by space case sensitive
IsConditionBuffer	is it a condition buffer or a custom code buffer
BufferAddress	the address that the allocated buffer will be saved on it
BufferLength	the length of the buffer

Returns

BOOLEAN shows whether the interpret was successful (true) or not successful (false)

{
    BOOLEAN        IsAsm         = FALSE;
    BOOLEAN        IsTextVisited = FALSE;
    BOOLEAN        IsInState     = FALSE;
    BOOLEAN        IsEnded       = FALSE;
    string         Temp;
    string         TempStr;
    string         AppendedFinalBuffer;
    vector<string> SaveBuffer;
    vector<CHAR>   ParsedBytes;
    vector<int>    IndexesToRemove;
    UCHAR *        FinalBuffer;
    UINT32         AssembledByteCount;
    int            NewIndexToRemove = 0;
    int            Index            = 0;
 
    for (auto Section : *SplitCommand)
    {
        Index++;
 
        if (IsInState)
        {
            //
            // Check if the buffer is ended or not
            //
            if (!Section.compare("}"))
            {
                //
                // Save to remove this string from the command
                //
                IndexesToRemove.push_back(Index);
                IsEnded = TRUE;
                break;
            }
 
            //
            // Check if the condition is end or not
            //
            if (HasEnding(Section, "}"))
            {
                //
                // Save to remove this string from the command
                //
                IndexesToRemove.push_back(Index);
 
                //
                // remove the last character and append it to the ConditionBuffer
                //
                SaveBuffer.emplace_back(Section.begin(), Section.begin() + Section.size() - 1);
 
                IsEnded = TRUE;
                break;
            }
 
            //
            // Save to remove this string from the command
            //
            IndexesToRemove.push_back(Index);
 
            //
            // Add the codes into condition bi
            //
            SaveBuffer.push_back(Section);
 
            //
            // We want to stay in this condition
            //
            continue;
        }
 
        if (IsTextVisited && !Section.compare("{"))
        {
            //
            // Save to remove this string from the command
            //
            IndexesToRemove.push_back(Index);
 
            IsInState = TRUE;
            continue;
        }
 
        if (IsTextVisited && Section.rfind('{', 0) == 0)
        {
            //
            // Section starts with {
            //
 
            //
            // Check if it ends with }
            //
            if (HasEnding(Section, "}"))
            {
                //
                // Save to remove this string from the command
                //
                IndexesToRemove.push_back(Index);
 
                TempStr = Section.erase(0, 1);
                SaveBuffer.emplace_back(TempStr.begin(), TempStr.begin() + TempStr.size() - 1);
 
                IsEnded = TRUE;
                break;
            }
 
            //
            // Save to remove this string from the command
            //
            IndexesToRemove.push_back(Index);
 
            SaveBuffer.push_back(Section.erase(0, 1));
 
            IsInState = TRUE;
            continue;
        }
 
        if (!Section.compare("asm"))
        {
            if (IsTextVisited)
            {
                ShowMessages("wrong use of \"asm\"\n"); // asm must not be after condition or code
            }
            else
            {
                IndexesToRemove.push_back(Index);
 
                IsAsm = TRUE;
                continue;
            }
        }
 
        if (IsConditionBuffer)
        {
            if (!Section.compare("condition"))
            {
                //
                // Save to remove this string from the command
                //
                IndexesToRemove.push_back(Index);
 
                IsTextVisited = TRUE;
                continue;
            }
        }
        else
        {
            //
            // It's code
            //
            if (!Section.compare("code"))
            {
                //
                // Save to remove this string from the command
                //
                IndexesToRemove.push_back(Index);
 
                IsTextVisited = TRUE;
                continue;
            }
        }
 
        if (IsConditionBuffer)
        {
            if (!Section.compare("condition{"))
            {
                //
                // Save to remove this string from the command
                //
                IndexesToRemove.push_back(Index);
 
                IsTextVisited = TRUE;
                IsInState     = TRUE;
                continue;
            }
        }
        else
        {
            //
            // It's code
            //
            if (!Section.compare("code{"))
            {
                //
                // Save to remove this string from the command
                //
                IndexesToRemove.push_back(Index);
 
                IsTextVisited = TRUE;
                IsInState     = TRUE;
                continue;
            }
        }
 
        if (IsConditionBuffer)
        {
            if (Section.rfind("condition{", 0) == 0)
            {
                //
                // Save to remove this string from the command
                //
                IndexesToRemove.push_back(Index);
 
                IsTextVisited = TRUE;
                IsInState     = TRUE;
 
                if (!HasEnding(Section, "}"))
                {
                    //
                    // Section starts with condition{
                    //
                    SaveBuffer.push_back(Section.erase(0, 10));
                    continue;
                }
                else
                {
                    //
                    // remove the last character and first character append it to the
                    // ConditionBuffer
                    //
                    TempStr = Section.erase(0, 10);
                    SaveBuffer.emplace_back(TempStr.begin(), TempStr.begin() + TempStr.size() - 1);
 
                    IsEnded = TRUE;
                    break;
                }
            }
        }
        else
        {
            //
            // It's a code
            //
            if (Section.rfind("code{", 0) == 0)
            {
                //
                // Save to remove this string from the command
                //
                IndexesToRemove.push_back(Index);
 
                IsTextVisited = TRUE;
                IsInState     = TRUE;
 
                if (!HasEnding(Section, "}"))
                {
                    //
                    // Section starts with code{
                    //
                    SaveBuffer.push_back(Section.erase(0, 5));
                    continue;
                }
                else
                {
                    //
                    // remove the last character and first character append it to the
                    // ConditionBuffer
                    //
                    TempStr = Section.erase(0, 5);
                    SaveBuffer.emplace_back(TempStr.begin(), TempStr.begin() + TempStr.size() - 1);
 
                    IsEnded = TRUE;
                    break;
                }
            }
        }
    }
 
    //
    // Now we have everything in condition buffer
    // Check to see if it is empty or not
    //
    if (SaveBuffer.size() == 0)
    {
        //
        // Nothing in condition buffer, return zero
        //
        return FALSE;
    }
 
    //
    // Check if we see '}' at the end
    //
    if (!IsEnded)
    {
        //
        // Nothing in condition buffer, return zero
        //
        return FALSE;
    }
 
    //
    // Check if asm code was provided instead of hex
    //
    if (IsAsm)
    {
        //
        // Append " " between two std::strings
        //
        auto ApndSemCln = [](std::string a, std::string b) {
            return std::move(a) + ' ' + std::move(b);
        };
 
        //
        // Concatenate each assembly line
        //
        std::string AsmCode = std::accumulate(std::next(SaveBuffer.begin()), SaveBuffer.end(), SaveBuffer[0], ApndSemCln);
 
        AssembleData AssembleData;
        AssembleData.AsmRaw = AsmCode; // by now, it should only have one element
        AssembleData.ParseAssemblyData();
 
        //
        // Append a 'ret' at the end of asm code
        //
        AssembleData.AsmFixed += "; ret";
 
        if (AssembleData.Assemble(0)) // we just want the hex bytes, so NULL instead of Start_Address
        {
            ShowMessages("err, assemble error code: '%u'\n\n", AssembleData.KsErr);
            return FALSE;
        }
        else
        {
            //
            // Get the BytesCount; for readability.
            //
            AssembledByteCount = (UINT32)AssembleData.BytesCount;
 
            //
            // * FinalBuffer *
            //
            FinalBuffer = (unsigned char *)malloc(AssembledByteCount);
 
            if (FinalBuffer == NULL)
            {
                return FALSE;
            }
 
            memcpy(FinalBuffer, AssembleData.EncodedBytes, AssembledByteCount);
 
            //
            // Set the buffer and length
            //
            *BufferAddress = (UINT64)FinalBuffer;
            *BufferLength  = AssembledByteCount;
        }
    }
    else
    {
        //
        // Append a 'ret' at the end of the buffer
        //
        SaveBuffer.push_back("c3");
 
        //
        // If we reach here then there is sth in condition buffer
        //
        for (auto Section : SaveBuffer)
        {
            //
            // Check if the section is started with '0x'
            //
            if (Section.rfind("0x", 0) == 0 || Section.rfind("0X", 0) == 0 || Section.rfind("\\x", 0) == 0 || Section.rfind("\\X", 0) == 0)
            {
                Temp = Section.erase(0, 2);
            }
            else if (Section.rfind('x', 0) == 0 || Section.rfind('X', 0) == 0)
            {
                Temp = Section.erase(0, 1);
            }
            else
            {
                Temp = std::move(Section);
            }
 
            //
            // replace \x s
            //
            ReplaceAll(Temp, "\\x", "");
 
            //
            // check if the buffer is aligned to 2
            //
            if (Temp.size() % 2 != 0)
            {
                //
                // Add a zero to the start of the buffer
                //
                Temp.insert(0, 1, '0');
            }
 
            if (!IsHexNotation(Temp))
            {
                ShowMessages("please enter condition code in a hex notation\n");
                return FALSE;
            }
            AppendedFinalBuffer.append(Temp);
        }
 
        //
        // Convert it to vectored bytes
        //
        ParsedBytes = HexToBytes(AppendedFinalBuffer);
 
        //
        // Convert to a contigues buffer
        //
        FinalBuffer = (unsigned char *)malloc(ParsedBytes.size());
 
        if (FinalBuffer == NULL)
        {
            return FALSE;
        }
 
        std::copy(ParsedBytes.begin(), ParsedBytes.end(), FinalBuffer);
 
        //
        // Set the buffer and length
        //
        *BufferAddress = (UINT64)FinalBuffer;
        *BufferLength  = (UINT32)ParsedBytes.size();
    }
 
    //
    // Removing the code or condition indexes from the command
    //
    NewIndexToRemove = 0;
    for (auto IndexToRemove : IndexesToRemove)
    {
        NewIndexToRemove++;
 
        SplitCommand->erase(SplitCommand->begin() + (IndexToRemove - NewIndexToRemove));
        SplitCommandCaseSensitive->erase(SplitCommandCaseSensitive->begin() + (IndexToRemove - NewIndexToRemove));
    }
 
    return TRUE;
}

InterpreterRemoveComments()

VOID InterpreterRemoveComments

(

char *

CommandText

)

Remove batch comments.

Returns

VOID

{
    BOOLEAN IsComment       = FALSE;
    BOOLEAN IsOnString      = FALSE;
    UINT32  LengthOfCommand = (UINT32)strlen(CommandText);
 
    for (size_t i = 0; i < LengthOfCommand; i++)
    {
        if (IsComment)
        {
            if (CommandText[i] == '\n')
            {
                IsComment = FALSE;
            }
            else
            {
                if (CommandText[i] != '\0')
                {
                    memmove((void *)&CommandText[i], (const void *)&CommandText[i + 1], strlen(CommandText) - i);
                    i--;
                }
            }
        }
        else if (CommandText[i] == '#' && !IsOnString)
        {
            //
            // Comment detected
            //
            IsComment = TRUE;
            i--;
        }
        else if (CommandText[i] == '"')
        {
            if (i != 0 && CommandText[i - 1] == '\\')
            {
                //
                // It's an escape character for : \"
                //
            }
            else if (IsOnString)
            {
                IsOnString = FALSE;
            }
            else
            {
                IsOnString = TRUE;
            }
        }
    }
}

InterpretGeneralEventAndActionsFields()

BOOLEAN InterpretGeneralEventAndActionsFields	(	vector< string > *	SplitCommand,
		vector< string > *	SplitCommandCaseSensitive,
		VMM_EVENT_TYPE_ENUM	EventType,
		PDEBUGGER_GENERAL_EVENT_DETAIL *	EventDetailsToFill,
		PUINT32	EventBufferLength,
		PDEBUGGER_GENERAL_ACTION *	ActionDetailsToFillBreakToDebugger,
		PUINT32	ActionBufferLengthBreakToDebugger,
		PDEBUGGER_GENERAL_ACTION *	ActionDetailsToFillCustomCode,
		PUINT32	ActionBufferLengthCustomCode,
		PDEBUGGER_GENERAL_ACTION *	ActionDetailsToFillScript,
		PUINT32	ActionBufferLengthScript,
		PDEBUGGER_EVENT_PARSING_ERROR_CAUSE	ReasonForErrorInParsing )

Interpret general event fields.

Parameters

SplitCommand	the commands that was split by space
SplitCommandCaseSensitive	the commands that was split by space case sensitive
EventType	type of event
EventDetailsToFill	a pointer address that will be filled by event detail buffer
EventBufferLength	a pointer the receives the buffer length of the event
ActionDetailsToFill	a pointer address that will be filled by action detail buffer
ActionBufferLength	a pointer the receives the buffer length of the action
ReasonForErrorInParsing	reason that interpretation failed, null if the returns true

Returns

BOOLEAN If this function returns true then it means that there was no error in parsing the general event details

{
    BOOLEAN                               Result                         = FALSE;
    PDEBUGGER_GENERAL_EVENT_DETAIL        TempEvent                      = NULL;
    PDEBUGGER_GENERAL_ACTION              TempActionBreak                = NULL;
    PDEBUGGER_GENERAL_ACTION              TempActionScript               = NULL;
    PDEBUGGER_GENERAL_ACTION              TempActionCustomCode           = NULL;
    VMM_CALLBACK_EVENT_CALLING_STAGE_TYPE CallingStage                   = VMM_CALLBACK_CALLING_STAGE_PRE_EVENT_EMULATION; // by default 'pre' event
    UINT32                                LengthOfCustomCodeActionBuffer = 0;
    UINT32                                LengthOfScriptActionBuffer     = 0;
    UINT32                                LengthOfBreakActionBuffer      = 0;
    UINT64                                ConditionBufferAddress;
    UINT32                                ConditionBufferLength = 0;
    vector<string>                        ListOfOutputSources;
    UINT64                                CodeBufferAddress;
    UINT32                                CodeBufferLength = 0;
    UINT64                                ScriptBufferAddress;
    UINT64                                ScriptCodeBuffer     = 0;
    BOOLEAN                               HasScriptSyntaxError = 0;
    UINT32                                ScriptBufferLength   = 0;
    UINT32                                ScriptBufferPointer  = 0;
    UINT32                                LengthOfEventBuffer  = 0;
    string                                CommandString;
    BOOLEAN                               IsAShortCircuitingEventByDefault = FALSE;
    BOOLEAN                               HasConditionBuffer               = FALSE;
    BOOLEAN                               HasOutputPath                    = FALSE;
    BOOLEAN                               HasCodeBuffer                    = FALSE;
    BOOLEAN                               HasScript                        = FALSE;
    BOOLEAN                               IsNextCommandPid                 = FALSE;
    BOOLEAN                               IsNextCommandCoreId              = FALSE;
    BOOLEAN                               IsNextCommandBufferSize          = FALSE;
    BOOLEAN                               IsNextCommandImmediateMessaging  = FALSE;
    BOOLEAN                               IsNextCommandExecutionStage      = FALSE;
    BOOLEAN                               IsNextCommandSc                  = FALSE;
    BOOLEAN                               ImmediateMessagePassing          = UseImmediateMessagingByDefaultOnEvents;
    UINT32                                CoreId;
    UINT32                                ProcessId;
    UINT32                                IndexOfValidSourceTags;
    UINT32                                RequestBuffer = 0;
    PLIST_ENTRY                           TempList;
    BOOLEAN                               OutputSourceFound;
    vector<int>                           IndexesToRemove;
    vector<UINT64>                        ListOfValidSourceTags;
    int                                   NewIndexToRemove = 0;
    int                                   Index            = 0;
 
    //
    // Create a command string to show in the history
    //
    for (auto Section : *SplitCommandCaseSensitive)
    {
        CommandString.append(Section);
        CommandString.append(" ");
    }
 
    //
    // Compute the size of buffer + 1 null for the end of buffer
    //
    UINT64 BufferOfCommandStringLength = CommandString.size() + 1;
 
    //
    // Allocate Buffer and zero for command to the buffer
    //
    PVOID BufferOfCommandString = malloc(BufferOfCommandStringLength);
 
    RtlZeroMemory(BufferOfCommandString, BufferOfCommandStringLength);
 
    //
    // Copy the string to the buffer
    //
    memcpy(BufferOfCommandString, CommandString.c_str(), CommandString.size());
 
    //
    // Check if there is a condition buffer in the command
    //
    if (!InterpretConditionsAndCodes(SplitCommand, SplitCommandCaseSensitive, TRUE, &ConditionBufferAddress, &ConditionBufferLength))
    {
        //
        // Indicate condition is not available
        //
        HasConditionBuffer = FALSE;
 
        //
        // ShowMessages("\nNo condition!\n");
        //
    }
    else
    {
        //
        // Indicate condition is available
        //
        HasConditionBuffer = TRUE;
 
        /*
    ShowMessages(
        "\n========================= Condition =========================\n");
 
    ShowMessages(
        "\nUINT64  DebuggerCheckForCondition(PGUEST_REGS Regs_RCX, PVOID "
        "Context_RDX)\n{\n");
 
    //
    // Disassemble the buffer
    //
    HyperDbgDisassembler64((unsigned char *)ConditionBufferAddress, 0x0,
                           ConditionBufferLength);
 
    ShowMessages("}\n\n");
 
    ShowMessages(
        "=============================================================\n");
      */
    }
 
    //
    // Check if there is a code buffer in the command
    //
    if (!InterpretConditionsAndCodes(SplitCommand, SplitCommandCaseSensitive, FALSE, &CodeBufferAddress, &CodeBufferLength))
    {
        //
        // Indicate code is not available
        //
        HasCodeBuffer = FALSE;
        //
        // ShowMessages("\nNo custom code!\n");
        //
    }
    else
    {
        //
        // Indicate code is available
        //
        HasCodeBuffer = TRUE;
 
        /*
    ShowMessages(
        "\n=========================    Code    =========================\n");
    ShowMessages("\nPVOID DebuggerRunCustomCodeFunc(PVOID "
                 "PreAllocatedBufferAddress_RCX, "
                 "PGUEST_REGS Regs_RDX, PVOID Context_R8)\n{\n");
 
    //
    // Disassemble the buffer
    //
    HyperDbgDisassembler64((unsigned char *)CodeBufferAddress, 0x0,
                           CodeBufferLength);
 
    ShowMessages("}\n\n");
 
    ShowMessages(
        "=============================================================\n");
        */
    }
 
    //
    // Check if there is a Script block in the command
    //
    if (!InterpretScript(SplitCommand,
                         SplitCommandCaseSensitive,
                         &HasScriptSyntaxError,
                         &ScriptBufferAddress,
                         &ScriptBufferLength,
                         &ScriptBufferPointer,
                         &ScriptCodeBuffer))
    {
        //
        // Indicate code is not available
        //
        HasScript = FALSE;
        //
        // ShowMessages("\nNo script!\n");
        //
    }
    else
    {
        //
        // Check if there is a syntax error
        //
        if (HasScriptSyntaxError)
        {
            free(BufferOfCommandString);
 
            *ReasonForErrorInParsing = DEBUGGER_EVENT_PARSING_ERROR_CAUSE_SCRIPT_SYNTAX_ERROR;
            return FALSE;
        }
 
        //
        // Indicate code is available
        //
        HasScript = TRUE;
    }
 
    //
    // Check if there is a output path in the command
    //
    if (!InterpretOutput(SplitCommand, SplitCommandCaseSensitive, ListOfOutputSources))
    {
        //
        // Indicate output is not available
        //
        HasOutputPath = FALSE;
 
        //
        // ShowMessages("\nNo condition!\n");
        //
    }
    else
    {
        //
        // Check for empty input
        //
        if (ListOfOutputSources.size() == 0)
        {
            //
            // No input !
            //
            free(BufferOfCommandString);
 
            ShowMessages("err, no input found\n");
            *ReasonForErrorInParsing = DEBUGGER_EVENT_PARSING_ERROR_CAUSE_NO_INPUT;
            return FALSE;
        }
 
        //
        // Check whether the size exceed maximum size or not
        //
        if (ListOfOutputSources.size() > DebuggerOutputSourceMaximumRemoteSourceForSingleEvent)
        {
            free(BufferOfCommandString);
 
            ShowMessages(
                "err, based on this build of HyperDbg, the maximum input sources for "
                "a single event is 0x%x sources but you entered 0x%x sources\n",
                DebuggerOutputSourceMaximumRemoteSourceForSingleEvent,
                ListOfOutputSources.size());
            *ReasonForErrorInParsing = DEBUGGER_EVENT_PARSING_ERROR_CAUSE_MAXIMUM_INPUT_REACHED;
            return FALSE;
        }
 
        //
        // Check whether the output source initialized or not
        //
        if (!g_OutputSourcesInitialized)
        {
            free(BufferOfCommandString);
 
            ShowMessages("err, the name you entered, not found. Did you use "
                         "'output' command to create it?\n");
            *ReasonForErrorInParsing = DEBUGGER_EVENT_PARSING_ERROR_CAUSE_OUTPUT_NAME_NOT_FOUND;
            return FALSE;
        }
 
        //
        // Convert output sources to the corresponding tags
        //
        for (auto item : ListOfOutputSources)
        {
            TempList          = 0;
            OutputSourceFound = FALSE;
 
            //
            // Now we should find the corresponding object in the list
            // of output sources and save its tags
            //
            TempList = &g_OutputSources;
 
            while (&g_OutputSources != TempList->Flink)
            {
                TempList = TempList->Flink;
 
                PDEBUGGER_EVENT_FORWARDING CurrentOutputSourceDetails = CONTAINING_RECORD(TempList, DEBUGGER_EVENT_FORWARDING, OutputSourcesList);
 
                if (strcmp(CurrentOutputSourceDetails->Name,
                           RemoveSpaces(item).c_str()) == 0)
                {
                    //
                    // Check to see the source state, whether it is closed or not
                    //
                    if (CurrentOutputSourceDetails->State == EVENT_FORWARDING_CLOSED)
                    {
                        free(BufferOfCommandString);
 
                        ShowMessages("err, output source already closed\n");
                        *ReasonForErrorInParsing = DEBUGGER_EVENT_PARSING_ERROR_CAUSE_OUTPUT_SOURCE_ALREADY_CLOSED;
                        return FALSE;
                    }
 
                    //
                    // Check to see the source state, whether it is opened or not
                    //
                    if (CurrentOutputSourceDetails->State == EVENT_FORWARDING_STATE_NOT_OPENED)
                    {
                        //
                        // Just show a message
                        //
                        ShowMessages("some of the output(s) are not opened, it's not an error, but please ensure "
                                     "to open the output using the 'output' command to forward the results to the "
                                     "target resource\n");
                    }
 
                    //
                    // Indicate that we found this item
                    //
                    OutputSourceFound = TRUE;
 
                    //
                    // Save the tag into a list which will be used later
                    //
                    ListOfValidSourceTags.push_back(
                        CurrentOutputSourceDetails->OutputUniqueTag);
 
                    //
                    // No need to search through the list anymore
                    //
                    break;
                }
            }
 
            if (!OutputSourceFound)
            {
                free(BufferOfCommandString);
 
                ShowMessages("err, the name you entered, not found. Did you use "
                             "'output' command to create it?\n");
                *ReasonForErrorInParsing = DEBUGGER_EVENT_PARSING_ERROR_CAUSE_OUTPUT_NAME_NOT_FOUND;
                return FALSE;
            }
        }
        //
        // Indicate output is available
        //
        HasOutputPath = TRUE;
    }
 
    //
    // Create action and event based on previously parsed buffers
    // (DEBUGGER_GENERAL_ACTION)
    //
    // Allocate the buffer (with ConditionBufferLength and CodeBufferLength)
    //
 
    /*
 
  Layout of Buffer :
 
   ________________________________
  |                                |
  |  DEBUGGER_GENERAL_EVENT_DETAIL |
  |                                |
  |________________________________|
  |                                |
  |       Condition Buffer         |
  |                                |
  |________________________________|
 
   */
 
    /*
   ________________________________
  |                                |
  |     DEBUGGER_GENERAL_ACTION    |
  |                                |
  |________________________________|
  |                                |
  |     Condition Custom Code      |
  |       or Script Buffer         |
  |________________________________|
 
  */
 
    LengthOfEventBuffer = sizeof(DEBUGGER_GENERAL_EVENT_DETAIL) + ConditionBufferLength;
 
    TempEvent = (PDEBUGGER_GENERAL_EVENT_DETAIL)malloc(LengthOfEventBuffer);
    RtlZeroMemory(TempEvent, LengthOfEventBuffer);
 
    //
    // Check if buffer is available
    //
    if (TempEvent == NULL)
    {
        ShowMessages("err, allocation error\n");
        *ReasonForErrorInParsing = DEBUGGER_EVENT_PARSING_ERROR_CAUSE_ALLOCATION_ERROR;
        goto ReturnWithError;
    }
 
    //
    // Event is enabled by default when created
    //
    TempEvent->IsEnabled = TRUE;
 
    //
    // Get a new tag for it
    //
    TempEvent->Tag = GetNewDebuggerEventTag();
 
    //
    // Set the core Id and Process Id to all cores and all
    // processes, next time we check whether the user needs
    // a special core or a special process then we change it
    //
    TempEvent->CoreId = DEBUGGER_EVENT_APPLY_TO_ALL_CORES;
 
    if (g_ActiveProcessDebuggingState.IsActive)
    {
        ShowMessages("notice: as you're debugging a user-mode application, "
                     "this event will only trigger on your current debugging process "
                     "(pid:%x). If you want the event from the entire system, "
                     "add 'pid all' to the event\n",
                     g_ActiveProcessDebuggingState.ProcessId);
 
        TempEvent->ProcessId = g_ActiveProcessDebuggingState.ProcessId;
    }
    else
    {
        TempEvent->ProcessId = DEBUGGER_EVENT_APPLY_TO_ALL_PROCESSES;
    }
 
    //
    // Set the event type
    //
    TempEvent->EventType = EventType;
 
    //
    // Get the current time
    //
    TempEvent->CreationTime = time(0);
 
    //
    // Set buffer string command
    //
    TempEvent->CommandStringBuffer = BufferOfCommandString;
 
    //
    // Fill the buffer of condition for event
    //
    if (HasConditionBuffer)
    {
        memcpy((PVOID)((UINT64)TempEvent + sizeof(DEBUGGER_GENERAL_EVENT_DETAIL)),
               (PVOID)ConditionBufferAddress,
               ConditionBufferLength);
 
        //
        // Set the size of the buffer for event condition
        //
        TempEvent->ConditionBufferSize = ConditionBufferLength;
    }
 
    //
    // Fill the buffer of custom code for action
    //
    if (HasCodeBuffer)
    {
        //
        // Allocate the Action (THIS ACTION BUFFER WILL BE FREED WHEN WE SENT IT TO
        // THE KERNEL AND RETURNED FROM THE KERNEL AS WE DON'T NEED IT ANYMORE)
        //
        LengthOfCustomCodeActionBuffer = sizeof(DEBUGGER_GENERAL_ACTION) + CodeBufferLength;
 
        TempActionCustomCode = (PDEBUGGER_GENERAL_ACTION)malloc(LengthOfCustomCodeActionBuffer);
 
        RtlZeroMemory(TempActionCustomCode, LengthOfCustomCodeActionBuffer);
 
        memcpy(
            (PVOID)((UINT64)TempActionCustomCode + sizeof(DEBUGGER_GENERAL_ACTION)),
            (PVOID)CodeBufferAddress,
            CodeBufferLength);
        //
        // Set the action Tag
        //
        TempActionCustomCode->EventTag = TempEvent->Tag;
 
        //
        // Set the action type
        //
        TempActionCustomCode->ActionType = RUN_CUSTOM_CODE;
 
        //
        // Set the action buffer size
        //
        TempActionCustomCode->CustomCodeBufferSize = CodeBufferLength;
 
        //
        // Increase the count of actions
        //
        TempEvent->CountOfActions = TempEvent->CountOfActions + 1;
    }
 
    //
    // Fill the buffer of script for action
    //
    if (HasScript)
    {
        //
        // Allocate the Action (THIS ACTION BUFFER WILL BE FREED WHEN WE SENT IT TO
        // THE KERNEL AND RETURNED FROM THE KERNEL AS WE DON'T NEED IT ANYMORE)
        //
        LengthOfScriptActionBuffer = sizeof(DEBUGGER_GENERAL_ACTION) + ScriptBufferLength;
        TempActionScript           = (PDEBUGGER_GENERAL_ACTION)malloc(LengthOfScriptActionBuffer);
 
        RtlZeroMemory(TempActionScript, LengthOfScriptActionBuffer);
 
        memcpy((PVOID)((UINT64)TempActionScript + sizeof(DEBUGGER_GENERAL_ACTION)),
               (PVOID)ScriptBufferAddress,
               ScriptBufferLength);
        //
        // Set the action Tag
        //
        TempActionScript->EventTag = TempEvent->Tag;
 
        //
        // Set the action type
        //
        TempActionScript->ActionType = RUN_SCRIPT;
 
        //
        // Set the action buffer size and pointer
        //
        TempActionScript->ScriptBufferSize    = ScriptBufferLength;
        TempActionScript->ScriptBufferPointer = ScriptBufferPointer;
 
        //
        // Increase the count of actions
        //
        TempEvent->CountOfActions = TempEvent->CountOfActions + 1;
 
        //
        // Free the buffer of script related functions
        //
        ScriptEngineWrapperRemoveSymbolBuffer((PVOID)ScriptCodeBuffer);
    }
 
    //
    // If this action didn't contain a buffer for custom code and
    // a buffer for script then it's a break to debugger
    //
    if (!HasCodeBuffer && !HasScript)
    {
        //
        // Allocate the Action (THIS ACTION BUFFER WILL BE FREED WHEN WE SENT IT TO
        // THE KERNEL AND RETURNED FROM THE KERNEL AS WE DON'T NEED IT ANYMORE)
        //
        LengthOfBreakActionBuffer = sizeof(DEBUGGER_GENERAL_ACTION);
 
        TempActionBreak = (PDEBUGGER_GENERAL_ACTION)malloc(LengthOfBreakActionBuffer);
 
        RtlZeroMemory(TempActionBreak, LengthOfBreakActionBuffer);
 
        //
        // Set the action Tag
        //
        TempActionBreak->EventTag = TempEvent->Tag;
 
        //
        // Set the action type
        //
        TempActionBreak->ActionType = BREAK_TO_DEBUGGER;
 
        //
        // Increase the count of actions
        //
        TempEvent->CountOfActions = TempEvent->CountOfActions + 1;
    }
 
    //
    // Interpret rest of the command
    //
    for (auto Section : *SplitCommand)
    {
        Index++;
        if (IsNextCommandBufferSize)
        {
            if (!ConvertStringToUInt32(Section, &RequestBuffer))
            {
                ShowMessages("err, buffer size is invalid\n");
                *ReasonForErrorInParsing = DEBUGGER_EVENT_PARSING_ERROR_CAUSE_FORMAT_ERROR;
                goto ReturnWithError;
            }
            else
            {
                //
                // Set the specific requested buffer size
                //
                if (TempActionBreak != NULL)
                {
                    TempActionBreak->PreAllocatedBuffer = RequestBuffer;
                }
                if (TempActionScript != NULL)
                {
                    TempActionScript->PreAllocatedBuffer = RequestBuffer;
                }
                if (TempActionCustomCode != NULL)
                {
                    TempActionCustomCode->PreAllocatedBuffer = RequestBuffer;
                }
            }
            IsNextCommandBufferSize = FALSE;
 
            //
            // Add index to remove it from the command
            //
            IndexesToRemove.push_back(Index);
 
            continue;
        }
 
        if (IsNextCommandImmediateMessaging)
        {
            if (!Section.compare("yes"))
            {
                ImmediateMessagePassing = TRUE;
            }
            else if (!Section.compare("no"))
            {
                ImmediateMessagePassing = FALSE;
            }
            else
            {
                //
                // err, not token recognized error
                //
 
                ShowMessages("err, immediate messaging token is invalid\n");
                *ReasonForErrorInParsing = DEBUGGER_EVENT_PARSING_ERROR_CAUSE_FORMAT_ERROR;
                goto ReturnWithError;
            }
 
            IsNextCommandImmediateMessaging = FALSE;
 
            //
            // Add index to remove it from the command
            //
            IndexesToRemove.push_back(Index);
 
            continue;
        }
 
        if (IsNextCommandExecutionStage)
        {
            if (!Section.compare("pre"))
            {
                CallingStage = VMM_CALLBACK_CALLING_STAGE_PRE_EVENT_EMULATION;
            }
            else if (!Section.compare("post"))
            {
                CallingStage = VMM_CALLBACK_CALLING_STAGE_POST_EVENT_EMULATION;
            }
            else if (!Section.compare("all"))
            {
                CallingStage = VMM_CALLBACK_CALLING_STAGE_ALL_EVENT_EMULATION;
            }
            else
            {
                //
                // err, not token recognized error
                //
 
                ShowMessages("err, the specified execution mode is invalid; you can either choose 'pre' or 'post'\n");
                *ReasonForErrorInParsing = DEBUGGER_EVENT_PARSING_ERROR_CAUSE_FORMAT_ERROR;
                goto ReturnWithError;
            }
 
            IsNextCommandExecutionStage = FALSE;
 
            //
            // Add index to remove it from the command
            //
            IndexesToRemove.push_back(Index);
 
            continue;
        }
 
        if (IsNextCommandSc)
        {
            if (!Section.compare("on"))
            {
                IsAShortCircuitingEventByDefault = TRUE;
            }
            else if (!Section.compare("off"))
            {
                IsAShortCircuitingEventByDefault = FALSE;
            }
            else
            {
                //
                // err, not token recognized error
                //
 
                ShowMessages("err, the specified short-circuiting state is invalid; you can either choose 'on' or 'off'\n");
                *ReasonForErrorInParsing = DEBUGGER_EVENT_PARSING_ERROR_CAUSE_FORMAT_ERROR;
                goto ReturnWithError;
            }
 
            IsNextCommandSc = FALSE;
 
            //
            // Add index to remove it from the command
            //
            IndexesToRemove.push_back(Index);
 
            continue;
        }
 
        if (IsNextCommandPid)
        {
            if (!Section.compare("all"))
            {
                TempEvent->ProcessId = DEBUGGER_EVENT_APPLY_TO_ALL_PROCESSES;
            }
            else if (!ConvertStringToUInt32(Section, &ProcessId))
            {
                ShowMessages("err, pid is invalid\n");
                *ReasonForErrorInParsing = DEBUGGER_EVENT_PARSING_ERROR_CAUSE_FORMAT_ERROR;
 
                goto ReturnWithError;
            }
            else
            {
                //
                // Set the specific process id
                //
                TempEvent->ProcessId = ProcessId;
            }
 
            IsNextCommandPid = FALSE;
 
            //
            // Add index to remove it from the command
            //
            IndexesToRemove.push_back(Index);
 
            continue;
        }
 
        if (IsNextCommandCoreId)
        {
            if (!ConvertStringToUInt32(Section, &CoreId))
            {
                ShowMessages("err, core id is invalid\n");
                *ReasonForErrorInParsing = DEBUGGER_EVENT_PARSING_ERROR_CAUSE_FORMAT_ERROR;
                goto ReturnWithError;
            }
            else
            {
                //
                // Set the specific core id
                //
                TempEvent->CoreId = CoreId;
            }
            IsNextCommandCoreId = FALSE;
 
            //
            // Add index to remove it from the command
            //
            IndexesToRemove.push_back(Index);
 
            continue;
        }
 
        if (!Section.compare("pid"))
        {
            IsNextCommandPid = TRUE;
 
            //
            // Add index to remove it from the command
            //
            IndexesToRemove.push_back(Index);
 
            continue;
        }
        if (!Section.compare("core"))
        {
            IsNextCommandCoreId = TRUE;
 
            //
            // Add index to remove it from the command
            //
            IndexesToRemove.push_back(Index);
 
            continue;
        }
 
        if (!Section.compare("imm"))
        {
            //
            // the next command is immediate messaging indicator
            //
            IsNextCommandImmediateMessaging = TRUE;
 
            //
            // Add index to remove it from the command
            //
            IndexesToRemove.push_back(Index);
 
            continue;
        }
 
        if (!Section.compare("stage"))
        {
            //
            // the next command is execution mode (pre- and post-events)
            //
            IsNextCommandExecutionStage = TRUE;
 
            //
            // Add index to remove it from the command
            //
            IndexesToRemove.push_back(Index);
 
            continue;
        }
 
        if (!Section.compare("sc"))
        {
            //
            // the next command is the default short-circuiting state
            //
            IsNextCommandSc = TRUE;
 
            //
            // Add index to remove it from the command
            //
            IndexesToRemove.push_back(Index);
 
            continue;
        }
 
        if (!Section.compare("buffer"))
        {
            IsNextCommandBufferSize = TRUE;
 
            //
            // Add index to remove it from the command
            //
            IndexesToRemove.push_back(Index);
 
            continue;
        }
    }
 
    //
    // Additional validation
    //
    if (IsNextCommandCoreId)
    {
        ShowMessages("err, please specify a value for 'core'\n");
 
        *ReasonForErrorInParsing = DEBUGGER_EVENT_PARSING_ERROR_CAUSE_FORMAT_ERROR;
 
        goto ReturnWithError;
    }
 
    if (IsNextCommandPid)
    {
        ShowMessages("err, please specify a value for 'pid'\n");
 
        *ReasonForErrorInParsing = DEBUGGER_EVENT_PARSING_ERROR_CAUSE_FORMAT_ERROR;
 
        goto ReturnWithError;
    }
 
    if (IsNextCommandBufferSize)
    {
        ShowMessages("err, please specify a value for 'buffer'\n");
 
        *ReasonForErrorInParsing = DEBUGGER_EVENT_PARSING_ERROR_CAUSE_FORMAT_ERROR;
 
        goto ReturnWithError;
    }
 
    if (IsNextCommandImmediateMessaging)
    {
        ShowMessages("err, please specify a value for 'imm'\n");
 
        *ReasonForErrorInParsing = DEBUGGER_EVENT_PARSING_ERROR_CAUSE_FORMAT_ERROR;
 
        goto ReturnWithError;
    }
 
    if (IsNextCommandExecutionStage)
    {
        ShowMessages("err, please specify a value for 'stage'\n");
 
        *ReasonForErrorInParsing = DEBUGGER_EVENT_PARSING_ERROR_CAUSE_FORMAT_ERROR;
 
        goto ReturnWithError;
    }
 
    if (IsNextCommandSc)
    {
        ShowMessages("err, please specify a value for 'sc'\n");
 
        *ReasonForErrorInParsing = DEBUGGER_EVENT_PARSING_ERROR_CAUSE_FORMAT_ERROR;
 
        goto ReturnWithError;
    }
 
    //
    // Check to make sure that short-circuiting is not used in post-events
    //
    if ((CallingStage == VMM_CALLBACK_CALLING_STAGE_POST_EVENT_EMULATION ||
         CallingStage == VMM_CALLBACK_CALLING_STAGE_ALL_EVENT_EMULATION) &&
        IsAShortCircuitingEventByDefault)
    {
        ShowMessages(
            "err, using the short-circuiting mechanism with 'post' or 'all' stage events "
            "doesn't make sense; it's not supported!\n");
 
        *ReasonForErrorInParsing = DEBUGGER_EVENT_PARSING_ERROR_CAUSE_USING_SHORT_CIRCUITING_IN_POST_EVENTS;
 
        goto ReturnWithError;
    }
 
    //
    // It's not possible to break to debugger in VMI-mode
    //
    if (!g_IsSerialConnectedToRemoteDebuggee && TempActionBreak != NULL)
    {
        ShowMessages(
            "err, the script or assembly code is either not found or invalid. "
            "As a result, the default action is to break. "
            "However, breaking to the debugger is not possible in the VMI Mode. "
            "To achieve full control of the system, you can switch to the Debugger Mode. "
            "In the VMI Mode, you can still use scripts and run custom code for local debugging."
            "For more information, please check: https://docs.hyperdbg.org/using-hyperdbg/prerequisites/operation-modes\n");
 
        *ReasonForErrorInParsing = DEBUGGER_EVENT_PARSING_ERROR_CAUSE_ATTEMPT_TO_BREAK_ON_VMI_MODE;
 
        goto ReturnWithError;
    }
 
    //
    // We do not support non-immediate message passing if the user
    // specified a special output
    //
    if (!ImmediateMessagePassing && HasOutputPath)
    {
        ShowMessages("err, non-immediate message passing is not supported in "
                     "'output-forwarding mode'\n");
 
        *ReasonForErrorInParsing = DEBUGGER_EVENT_PARSING_ERROR_CAUSE_IMMEDIATE_MESSAGING_IN_EVENT_FORWARDING_MODE;
 
        goto ReturnWithError;
    }
 
    //
    // Set the specific requested immediate message passing
    //
    if (TempActionBreak != NULL)
    {
        TempActionBreak->ImmediateMessagePassing = ImmediateMessagePassing;
    }
    if (TempActionScript != NULL)
    {
        TempActionScript->ImmediateMessagePassing = ImmediateMessagePassing;
    }
    if (TempActionCustomCode != NULL)
    {
        TempActionCustomCode->ImmediateMessagePassing = ImmediateMessagePassing;
    }
 
    //
    // Set the tags into the event list
    //
    IndexOfValidSourceTags = 0;
    for (auto item : ListOfValidSourceTags)
    {
        TempEvent->OutputSourceTags[IndexOfValidSourceTags] = item;
 
        //
        // Increase index
        //
        IndexOfValidSourceTags++;
    }
 
    //
    // If it has output then we should indicate it in event's object
    //
    if (HasOutputPath)
    {
        TempEvent->HasCustomOutput = TRUE;
    }
 
    //
    // Set the specific requested short-circuiting state
    //
    if (IsAShortCircuitingEventByDefault)
    {
        TempEvent->EnableShortCircuiting = TRUE;
    }
 
    //
    // Set the specific event mode (calling stage)
    //
    TempEvent->EventStage = CallingStage;
 
    //
    // Fill the address and length of event before release
    //
    *EventDetailsToFill = TempEvent;
    *EventBufferLength  = LengthOfEventBuffer;
 
    //
    // Fill the address and length of action before release
    //
    if (TempActionBreak != NULL)
    {
        *ActionDetailsToFillBreakToDebugger = TempActionBreak;
        *ActionBufferLengthBreakToDebugger  = LengthOfBreakActionBuffer;
    }
    if (TempActionScript != NULL)
    {
        *ActionDetailsToFillScript = TempActionScript;
        *ActionBufferLengthScript  = LengthOfScriptActionBuffer;
    }
    if (TempActionCustomCode != NULL)
    {
        *ActionDetailsToFillCustomCode = TempActionCustomCode;
        *ActionBufferLengthCustomCode  = LengthOfCustomCodeActionBuffer;
    }
 
    //
    // Remove the command that we interpreted above from the command
    //
    for (auto IndexToRemove : IndexesToRemove)
    {
        NewIndexToRemove++;
        SplitCommand->erase(SplitCommand->begin() + (IndexToRemove - NewIndexToRemove));
        SplitCommandCaseSensitive->erase(SplitCommandCaseSensitive->begin() + (IndexToRemove - NewIndexToRemove));
    }
 
    //
    // Check if list is initialized or not
    //
    if (!g_EventTraceInitialized)
    {
        InitializeListHead(&g_EventTrace);
        g_EventTraceInitialized = TRUE;
    }
 
    //
    // Add the event to the trace list
    // UPDATE : if we add it here, then if the event was not
    // successful then still the event shows this event, so
    // we have to add it lated
    //
    // InsertHeadList(&g_EventTrace, &(TempEvent->CommandsEventList));
 
    //
    // Everything is ok, let's return TRUE
    //
    *ReasonForErrorInParsing = DEBUGGER_EVENT_PARSING_ERROR_CAUSE_SUCCESSFUL_NO_ERROR;
    return TRUE;
 
ReturnWithError:
 
    if (BufferOfCommandString)
    {
        free(BufferOfCommandString);
    }
 
    if (TempEvent)
    {
        free(TempEvent);
    }
 
    if (TempActionBreak != NULL)
    {
        free(TempActionBreak);
    }
    if (TempActionScript != NULL)
    {
        free(TempActionScript);
    }
    if (TempActionCustomCode != NULL)
    {
        free(TempActionCustomCode);
    }
 
    return FALSE;
}

IsConnectedToAnyInstanceOfDebuggerOrDebuggee()

BOOLEAN IsConnectedToAnyInstanceOfDebuggerOrDebuggee

(

)

Shows whether the debugger is connected to a debugger or debuggee connected to a debugger.

we use this function to avoid connecting to a remote machine when debuggee or debugger is already connected to an instance

Returns

BOOLEAN

{
    if (g_DeviceHandle)
    {
        ShowMessages("err, the current system is already connected to the local "
                     "debugging, use '.disconnect' to disconnect\n");
        return TRUE;
    }
    else if (g_IsConnectedToRemoteDebuggee)
    {
        ShowMessages("err, the current system is already connected to remote "
                     "machine (debuggee), use '.disconnect' to disconnect from the "
                     "remote machine\n");
        return TRUE;
    }
    else if (g_IsConnectedToRemoteDebugger)
    {
        ShowMessages("err, the current system is already connected to remote "
                     "machine (debugger), use '.disconnect' to disconnect from the "
                     "remote machine from debugger\n");
        return TRUE;
    }
    else if (g_IsSerialConnectedToRemoteDebuggee)
    {
        ShowMessages(
            "err, the current system is already connected to remote "
            "machine (debuggee), use '.debug close' to disconnect from the "
            "remote machine\n");
        return TRUE;
    }
    else if (g_IsSerialConnectedToRemoteDebugger)
    {
        ShowMessages(
            "err, the current system is already connected to remote "
            "machine (debugger), use '.debug close' to disconnect from the "
            "remote machine from debugger\n");
        return TRUE;
    }
 
    return FALSE;
}

IsTagExist()

BOOLEAN IsTagExist

(

UINT64

Tag

)

Check whether the tag exists or not, if the tag is DEBUGGER_MODIFY_EVENTS_APPLY_TO_ALL_TAG then if we find just one event, it also means that the tag is found.

Parameters

Tag

Returns

BOOLEAN

{
    PLIST_ENTRY                    TempList      = 0;
    PDEBUGGER_GENERAL_EVENT_DETAIL CommandDetail = {0};
 
    if (!g_EventTraceInitialized)
    {
        return FALSE;
    }
 
    TempList = &g_EventTrace;
    while (&g_EventTrace != TempList->Blink)
    {
        TempList = TempList->Blink;
 
        CommandDetail = CONTAINING_RECORD(TempList, DEBUGGER_GENERAL_EVENT_DETAIL, CommandsEventList);
 
        if (CommandDetail->Tag == Tag || Tag == DEBUGGER_MODIFY_EVENTS_APPLY_TO_ALL_TAG)
        {
            return TRUE;
        }
    }
 
    //
    // Not found
    //
    return FALSE;
}

ListeningSerialPauseDebuggeeThread()

DWORD WINAPI ListeningSerialPauseDebuggeeThread

(

PVOID

Param

)

Check if the remote debugger needs to pause the system.

Parameters

SerialHandle

Returns

BOOLEAN

{
    //
    // Create a listening thead in debuggee
    //
    ListeningSerialPortInDebuggee();
 
    return 0;
}

ListeningSerialPauseDebuggerThread()

DWORD WINAPI ListeningSerialPauseDebuggerThread

(

PVOID

Param

)

Check if the remote debuggee needs to pause the system.

Parameters

Param

Returns

BOOLEAN

{
    //
    // Create a listening thead in debugger
    //
    ListeningSerialPortInDebugger();
 
    return 0;
}

LogopenSaveToFile()

VOID LogopenSaveToFile

(

const char *

Text

)

Append text to the file object.

Parameters

Text

Returns

VOID

{
    g_LogOpenFile << Text;
}

RegisterActionToEvent()

BOOLEAN RegisterActionToEvent	(	PDEBUGGER_GENERAL_EVENT_DETAIL	Event,
		PDEBUGGER_GENERAL_ACTION	ActionBreakToDebugger,
		UINT32	ActionBreakToDebuggerLength,
		PDEBUGGER_GENERAL_ACTION	ActionCustomCode,
		UINT32	ActionCustomCodeLength,
		PDEBUGGER_GENERAL_ACTION	ActionScript,
		UINT32	ActionScriptLength )

Register the action to the event.

Parameters

Event	the event instance buffer
ActionBreakToDebugger	the action of breaking into the debugger
ActionBreakToDebuggerLength	the action of breaking into the debugger (length)
ActionCustomCode	the action of custom code
ActionCustomCodeLength	the action of custom code (length)
ActionScript	the action of script buffer
ActionScriptLength	the action of script buffer (length)

Returns

BOOLEAN BOOLEAN if the request was successful then true if the request was not successful then false

{
    BOOL                              Status;
    ULONG                             ReturnedLength;
    DEBUGGER_EVENT_AND_ACTION_RESULT  ReturnedBuffer = {0};
    PDEBUGGER_EVENT_AND_ACTION_RESULT TempAddingResult;
 
    if (g_IsSerialConnectedToRemoteDebuggee)
    {
        //
        // It's action(s) in debugger mode
        //
 
        //
        // Send Break to debugger packet to debuggee
        //
        if (ActionBreakToDebugger != NULL)
        {
            //
            // Send the add action to event from here
            //
            TempAddingResult = KdSendAddActionToEventPacketToDebuggee(
                ActionBreakToDebugger,
                ActionBreakToDebuggerLength);
 
            //
            // Move the buffer to local buffer
            //
            memcpy(&ReturnedBuffer, TempAddingResult, sizeof(DEBUGGER_EVENT_AND_ACTION_RESULT));
        }
 
        //
        // Send custom code packet to debuggee
        //
        if (ActionCustomCode != NULL)
        {
            //
            // Send the add action to event from here
            //
            TempAddingResult = KdSendAddActionToEventPacketToDebuggee(
                ActionCustomCode,
                ActionCustomCodeLength);
 
            //
            // Move the buffer to local buffer
            //
            memcpy(&ReturnedBuffer, TempAddingResult, sizeof(DEBUGGER_EVENT_AND_ACTION_RESULT));
        }
 
        //
        // Send custom code packet to debuggee
        //
        if (ActionScript != NULL)
        {
            //
            // Send the add action to event from here
            //
            TempAddingResult = KdSendAddActionToEventPacketToDebuggee(
                ActionScript,
                ActionScriptLength);
 
            //
            // Move the buffer to local buffer
            //
            memcpy(&ReturnedBuffer, TempAddingResult, sizeof(DEBUGGER_EVENT_AND_ACTION_RESULT));
        }
    }
    else
    {
        //
        // It's either a local debugger to in vmi-mode remote conntection
        //
 
        AssertShowMessageReturnStmt(g_DeviceHandle, ASSERT_MESSAGE_DRIVER_NOT_LOADED, AssertReturnFalse);
 
        //
        // Send IOCTLs
        //
 
        //
        // Send Break to debugger ioctl
        //
        if (ActionBreakToDebugger != NULL)
        {
            Status = DeviceIoControl(
                g_DeviceHandle,                           // Handle to device
                IOCTL_DEBUGGER_ADD_ACTION_TO_EVENT,       // IO Control Code (IOCTL)
                ActionBreakToDebugger,                    // Input Buffer to driver.
                ActionBreakToDebuggerLength,              // Input buffer length
                &ReturnedBuffer,                          // Output Buffer from driver.
                sizeof(DEBUGGER_EVENT_AND_ACTION_RESULT), // Length
                                                          // of
                                                          // output
                                                          // buffer
                                                          // in
                                                          // bytes.
                &ReturnedLength,                          // Bytes placed in buffer.
                NULL                                      // synchronous call
            );
 
            if (!Status)
            {
                ShowMessages("ioctl failed with code 0x%x\n", GetLastError());
                return FALSE;
            }
        }
 
        //
        // Send custom code ioctl
        //
        if (ActionCustomCode != NULL)
        {
            Status = DeviceIoControl(
                g_DeviceHandle,                           // Handle to device
                IOCTL_DEBUGGER_ADD_ACTION_TO_EVENT,       // IO Control Code (IOCTL)
                ActionCustomCode,                         // Input Buffer to driver.
                ActionCustomCodeLength,                   // Input buffer length
                &ReturnedBuffer,                          // Output Buffer from driver.
                sizeof(DEBUGGER_EVENT_AND_ACTION_RESULT), // Length
                                                          // of
                                                          // output
                                                          // buffer
                                                          // in
                                                          // bytes.
                &ReturnedLength,                          // Bytes placed in buffer.
                NULL                                      // synchronous call
            );
 
            if (!Status)
            {
                ShowMessages("ioctl failed with code 0x%x\n", GetLastError());
                return FALSE;
            }
        }
 
        //
        // Send custom code ioctl
        //
        if (ActionScript != NULL)
        {
            Status = DeviceIoControl(
                g_DeviceHandle,                           // Handle to device
                IOCTL_DEBUGGER_ADD_ACTION_TO_EVENT,       // IO Control Code (IOCTL)
                ActionScript,                             // Input Buffer to driver.
                ActionScriptLength,                       // Input buffer length
                &ReturnedBuffer,                          // Output Buffer from driver.
                sizeof(DEBUGGER_EVENT_AND_ACTION_RESULT), // Length
                                                          // of
                                                          // output
                                                          // buffer
                                                          // in
                                                          // bytes.
                &ReturnedLength,                          // Bytes placed in buffer.
                NULL                                      // synchronous call
            );
 
            if (!Status)
            {
                ShowMessages("ioctl failed with code 0x%x\n", GetLastError());
                return FALSE;
            }
        }
    }
 
    //
    // As we're not needing any of action buffer, we'll free all of the
    // here in the case of a successful registration of action, however
    // event detail is needed for the 'event' command's list
    //
    FreeEventsAndActionsMemory(NULL, ActionBreakToDebugger, ActionCustomCode, ActionScript);
 
    //
    // Now, we'll register the command as returned buffer shows that
    // this event was successful and now we can add it to the list of
    // events
    //
    InsertHeadList(&g_EventTrace, &(Event->CommandsEventList));
 
    return TRUE;
}

SendEventToKernel()

BOOLEAN SendEventToKernel	(	PDEBUGGER_GENERAL_EVENT_DETAIL	Event,
		UINT32	EventBufferLength )

Register the event to the kernel.

Parameters

Event	the event structure to send
EventBufferLength	the buffer length of event

Returns

BOOLEAN if the request was successful then true if the request was not successful then false

{
    BOOL                              Status;
    ULONG                             ReturnedLength;
    DEBUGGER_EVENT_AND_ACTION_RESULT  ReturnedBuffer = {0};
    PDEBUGGER_EVENT_AND_ACTION_RESULT TempRegResult;
 
    if (g_IsSerialConnectedToRemoteDebuggee)
    {
        //
        // It's a debugger, we should send the events buffer directly
        // from here
        //
 
        //
        // Send the buffer from here
        //
        TempRegResult = KdSendRegisterEventPacketToDebuggee(Event, EventBufferLength);
 
        //
        // Move the buffer to local buffer
        //
        memcpy(&ReturnedBuffer, TempRegResult, sizeof(DEBUGGER_EVENT_AND_ACTION_RESULT));
    }
    else
    {
        //
        // It's either a debuggee or a local debugging instance
        //
 
        AssertShowMessageReturnStmt(g_DeviceHandle, ASSERT_MESSAGE_DRIVER_NOT_LOADED, AssertReturnFalse);
 
        //
        // Send IOCTL
        //
 
        Status = DeviceIoControl(g_DeviceHandle,                           // Handle to device
                                 IOCTL_DEBUGGER_REGISTER_EVENT,            // IO Control Code (IOCTL)
                                 Event,                                    // Input Buffer to driver.
                                 EventBufferLength,                        // Input buffer length
                                 &ReturnedBuffer,                          // Output Buffer from driver.
                                 sizeof(DEBUGGER_EVENT_AND_ACTION_RESULT), // Length
                                                                           // of
                                                                           // output
                                                                           // buffer
                                                                           // in
                                                                           // bytes.
                                 &ReturnedLength,                          // Bytes placed in buffer.
                                 NULL                                      // synchronous call
        );
 
        if (!Status)
        {
            ShowMessages("ioctl failed with code 0x%x\n", GetLastError());
            return FALSE;
        }
    }
 
    if (ReturnedBuffer.IsSuccessful && ReturnedBuffer.Error == 0)
    {
        //
        // Check for auto-unpause mode
        //
        if (!g_IsSerialConnectedToRemoteDebuggee && !g_IsSerialConnectedToRemoteDebugger && g_BreakPrintingOutput && g_AutoUnpause)
        {
            //
            // Allow debugger to show its contents
            //
 
            //
            // Set the g_BreakPrintingOutput to FALSE
            //
            g_BreakPrintingOutput = FALSE;
 
            //
            // If it's a remote debugger then we send the remote debuggee a 'g'
            //
            if (g_IsConnectedToRemoteDebuggee)
            {
                RemoteConnectionSendCommand("g", (UINT32)strlen("g") + 1);
            }
 
            ShowMessages("\n");
        }
    }
    else
    {
        //
        // Show the error
        //
        if (ReturnedBuffer.Error != 0)
        {
            ShowErrorMessage(ReturnedBuffer.Error);
        }
 
        return FALSE;
    }
 
    return TRUE;
}

ShowErrorMessage()

BOOLEAN ShowErrorMessage

(

UINT32

Error

)

shows the error message

Parameters

Error

Returns

BOOLEAN

{
    switch (Error)
    {
    case DEBUGGER_ERROR_TAG_NOT_EXISTS:
        ShowMessages("err, tag not found (%x)\n",
                     Error);
        break;
 
    case DEBUGGER_ERROR_INVALID_ACTION_TYPE:
        ShowMessages("err, invalid action type (%x)\n",
                     Error);
        break;
 
    case DEBUGGER_ERROR_ACTION_BUFFER_SIZE_IS_ZERO:
        ShowMessages("err, action buffer size is zero (%x)\n",
                     Error);
        break;
 
    case DEBUGGER_ERROR_EVENT_TYPE_IS_INVALID:
        ShowMessages("err, the event type is invalid (%x)\n",
                     Error);
        break;
 
    case DEBUGGER_ERROR_UNABLE_TO_CREATE_EVENT:
        ShowMessages("err, unable to create event (%x)\n",
                     Error);
        break;
 
    case DEBUGGER_ERROR_INVALID_ADDRESS:
 
        ShowMessages("err, invalid address (%x)\n"
                     "address may be paged-out or unavailable on the page table due to 'demand paging'\n"
                     "please refer to https://docs.hyperdbg.org/tips-and-tricks/considerations/accessing-invalid-address for further information\n",
                     Error);
        break;
 
    case DEBUGGER_ERROR_INVALID_CORE_ID:
        ShowMessages("err, invalid core id (%x)\n",
                     Error);
        break;
 
    case DEBUGGER_ERROR_EXCEPTION_INDEX_EXCEED_FIRST_32_ENTRIES:
        ShowMessages("err, exception index exceed first 32 entries (%x)\n",
                     Error);
        break;
 
    case DEBUGGER_ERROR_INTERRUPT_INDEX_IS_NOT_VALID:
        ShowMessages("err, interrupt index is not valid (%x)\n",
                     Error);
        break;
 
    case DEBUGGER_ERROR_UNABLE_TO_HIDE_OR_UNHIDE_DEBUGGER:
        ShowMessages("err, unable to hide or unhide debugger (%x)\n",
                     Error);
        break;
 
    case DEBUGGER_ERROR_DEBUGGER_ALREADY_UHIDE:
        ShowMessages("err, debugger already unhide (%x)\n",
                     Error);
        break;
 
    case DEBUGGER_ERROR_EDIT_MEMORY_STATUS_INVALID_PARAMETER:
        ShowMessages("err, edit memory request has invalid parameters (%x)\n",
                     Error);
        break;
 
    case DEBUGGER_ERROR_EDIT_MEMORY_STATUS_INVALID_ADDRESS_BASED_ON_CURRENT_PROCESS:
        ShowMessages("err, edit memory request has invalid address based on "
                     "current process layout, the address might be valid but not "
                     "present in the ram (%x)\n"
                     "address may be paged-out or unavailable on the page table due to 'demand paging'\n"
                     "please refer to https://docs.hyperdbg.org/tips-and-tricks/considerations/accessing-invalid-address for further information\n",
                     Error);
        break;
 
    case DEBUGGER_ERROR_EDIT_MEMORY_STATUS_INVALID_ADDRESS_BASED_ON_OTHER_PROCESS:
        ShowMessages("err, edit memory request has invalid address based on other "
                     "process layout (%x)\n",
                     Error);
        break;
 
    case DEBUGGER_ERROR_MODIFY_EVENTS_INVALID_TAG:
        ShowMessages("err, modify event with invalid tag (%x)\n",
                     Error);
        break;
 
    case DEBUGGER_ERROR_MODIFY_EVENTS_INVALID_TYPE_OF_ACTION:
        ShowMessages("err, modify event with invalid type of action (%x)\n",
                     Error);
        break;
 
    case DEBUGGER_ERROR_STEPPING_INVALID_PARAMETER:
        ShowMessages("err, invalid parameter passed to stepping core. (%x)\n",
                     Error);
        break;
 
    case DEBUGGER_ERROR_STEPPINGS_EITHER_THREAD_NOT_FOUND_OR_DISABLED:
        ShowMessages(
            "err, the target thread not found or the thread is disabled (%x)\n",
            Error);
        break;
 
    case DEBUGGER_ERROR_PREPARING_DEBUGGEE_INVALID_BAUDRATE:
        ShowMessages("err, invalid baud rate (%x)\n",
                     Error);
        break;
 
    case DEBUGGER_ERROR_PREPARING_DEBUGGEE_INVALID_SERIAL_PORT:
        ShowMessages("err, invalid serial port (%x)\n",
                     Error);
        break;
 
    case DEBUGGER_ERROR_PREPARING_DEBUGGEE_INVALID_CORE_IN_REMOTE_DEBUGGE:
        ShowMessages("err, invalid core selected in switching cores (%x)\n",
                     Error);
        break;
 
    case DEBUGGER_ERROR_PREPARING_DEBUGGEE_UNABLE_TO_SWITCH_TO_NEW_PROCESS:
        ShowMessages("err, unable to switch to the new process (%x)\n",
                     Error);
        break;
 
    case DEBUGGER_ERROR_PREPARING_DEBUGGEE_TO_RUN_SCRIPT:
        ShowMessages("err, unable to run the script on remote debuggee (%x)\n",
                     Error);
        break;
 
    case DEBUGGER_ERROR_INVALID_REGISTER_NUMBER:
        ShowMessages("err, invalid register number (%x)\n",
                     Error);
        break;
 
    case DEBUGGER_ERROR_MAXIMUM_BREAKPOINT_WITHOUT_CONTINUE:
        ShowMessages("err, maximum number of breakpoints are used, you need to "
                     "send an ioctl to re-allocate new pre-allocated buffers or "
                     "configure HyperDbg to pre-allocated more buffers by "
                     "configuring MAXIMUM_BREAKPOINTS_WITHOUT_CONTINUE (%x)\n",
                     Error);
        break;
 
    case DEBUGGER_ERROR_BREAKPOINT_ALREADY_EXISTS_ON_THE_ADDRESS:
        ShowMessages("err, breakpoint already exists on target address, you can "
                     "use 'bl' command to view a list of breakpoints (%x)\n",
                     Error);
        break;
 
    case DEBUGGER_ERROR_BREAKPOINT_ID_NOT_FOUND:
        ShowMessages("err, breakpoint id is invalid (%x)\n",
                     Error);
        break;
 
    case DEBUGGER_ERROR_BREAKPOINT_ALREADY_DISABLED:
        ShowMessages("err, breakpoint already disabled (%x)\n",
                     Error);
        break;
 
    case DEBUGGER_ERROR_BREAKPOINT_ALREADY_ENABLED:
        ShowMessages("err, breakpoint already enabled (%x)\n",
                     Error);
        break;
 
    case DEBUGGER_ERROR_MEMORY_TYPE_INVALID:
        ShowMessages("err, the memory type is invalid (%x)\n",
                     Error);
        break;
 
    case DEBUGGER_ERROR_INVALID_PROCESS_ID:
        ShowMessages("err, the process id is invalid, make sure to enter the "
                     "process id in hex format, or if you want to use it in decimal "
                     "format, add '0n' prefix to the number (%x)\n",
                     Error);
        break;
 
    case DEBUGGER_ERROR_EVENT_IS_NOT_APPLIED:
        ShowMessages("err, the event is not applied (%x)\n",
                     Error);
        break;
 
    case DEBUGGER_ERROR_DETAILS_OR_SWITCH_PROCESS_INVALID_PARAMETER:
        ShowMessages("err, either the process id or the _EPROCESS is invalid or "
                     "cannot get the details based on the provided parameters (%x)\n",
                     Error);
        break;
 
    case DEBUGGER_ERROR_DETAILS_OR_SWITCH_THREAD_INVALID_PARAMETER:
        ShowMessages("err, either the thread id, _ETHREAD, or _EPROCESS is invalid or "
                     "cannot get the details based on the provided parameters (%x)\n",
                     Error);
        break;
 
    case DEBUGGER_ERROR_MAXIMUM_BREAKPOINT_FOR_A_SINGLE_PAGE_IS_HIT:
        ShowMessages("err, the maximum breakpoint for a single page is hit, "
                     "you cannot apply more breakpoints in this page (%x)\n",
                     Error);
        break;
 
    case DEBUGGER_ERROR_PRE_ALLOCATED_BUFFER_IS_EMPTY:
        ShowMessages("err, the pre-allocated buffer is empty, usually this buffer will be "
                     "filled at the next IOCTL when the debugger is continued (%x)\n"
                     "please visit the documentation for the 'prealloc' command or use "
                     "'.help prealloc' to to reserve more pre-allocated pools\n",
                     Error);
        break;
 
    case DEBUGGER_ERROR_EPT_COULD_NOT_SPLIT_THE_LARGE_PAGE_TO_4KB_PAGES:
        ShowMessages("err, could not convert 2MB large page to 4KB pages (%x)\n",
                     Error);
        break;
 
    case DEBUGGER_ERROR_EPT_FAILED_TO_GET_PML1_ENTRY_OF_TARGET_ADDRESS:
        ShowMessages("err, failed to get the PML1 entry of the target address (%x)\n",
                     Error);
        break;
 
    case DEBUGGER_ERROR_EPT_MULTIPLE_HOOKS_IN_A_SINGLE_PAGE:
        ShowMessages("err, the page modification is not applied, make sure that you don't "
                     "put multiple EPT Hooks or Monitors on a single page (%x)\n",
                     Error);
        break;
 
    case DEBUGGER_ERROR_COULD_NOT_BUILD_THE_EPT_HOOK:
        ShowMessages("err, could not build the EPT hook (%x)\n",
                     Error);
        break;
 
    case DEBUGGER_ERROR_COULD_NOT_FIND_ALLOCATION_TYPE:
        ShowMessages("err, could not find the allocation type (%x)\n",
                     Error);
        break;
 
    case DEBUGGER_ERROR_INVALID_TEST_QUERY_INDEX:
        ShowMessages("err, invalid index specified for test query command (%x)\n",
                     Error);
        break;
 
    case DEBUGGER_ERROR_UNABLE_TO_ATTACH_TO_TARGET_USER_MODE_PROCESS:
        ShowMessages("err, unable to attach to the target process (%x)\n",
                     Error);
        break;
 
    case DEBUGGER_ERROR_UNABLE_TO_REMOVE_HOOKS_ENTRYPOINT_NOT_REACHED:
        ShowMessages("err, unable to remove hooks as the entrypoint of user-mode "
                     "process is not reached yet (%x)\n",
                     Error);
        break;
 
    case DEBUGGER_ERROR_UNABLE_TO_REMOVE_HOOKS:
        ShowMessages("err, unable to remove hooks (%x)\n",
                     Error);
        break;
 
    case DEBUGGER_ERROR_FUNCTIONS_FOR_INITIALIZING_PEB_ADDRESSES_ARE_NOT_INITIALIZED:
        ShowMessages("err, the routines for getting the PEB is not correctly "
                     "initialized (%x)\n",
                     Error);
        break;
 
    case DEBUGGER_ERROR_UNABLE_TO_DETECT_32_BIT_OR_64_BIT_PROCESS:
        ShowMessages("err, unable to detect whether the process was 32-bit "
                     "or 64-bit (%x)\n",
                     Error);
        break;
 
    case DEBUGGER_ERROR_UNABLE_TO_KILL_THE_PROCESS:
        ShowMessages("err, unable to kill the process (%x)\n",
                     Error);
        break;
 
    case DEBUGGER_ERROR_INVALID_THREAD_DEBUGGING_TOKEN:
        ShowMessages("err, invalid thread debugging token (%x)\n",
                     Error);
        break;
 
    case DEBUGGER_ERROR_UNABLE_TO_PAUSE_THE_PROCESS_THREADS:
        ShowMessages("err, unable to pause the threads of the process (%x)\n",
                     Error);
        break;
 
    case DEBUGGER_ERROR_UNABLE_TO_ATTACH_TO_AN_ALREADY_ATTACHED_PROCESS:
        ShowMessages("err, the user debugger is already attached to this "
                     "process, please use the '.switch' command to switch "
                     "to this process (%x)\n",
                     Error);
        break;
 
    case DEBUGGER_ERROR_THE_USER_DEBUGGER_NOT_ATTACHED_TO_THE_PROCESS:
        ShowMessages("err, the user debugger is not already attached to "
                     "the process (%x)\n",
                     Error);
        break;
 
    case DEBUGGER_ERROR_UNABLE_TO_DETACH_AS_THERE_ARE_PAUSED_THREADS:
        ShowMessages("err, the user debugger is not able to detach from "
                     "this process as there are paused threads in the "
                     "target process, please make sure to remove all "
                     "the events and continue the target process, then "
                     "perform the detach again (%x)\n",
                     Error);
        break;
 
    case DEBUGGER_ERROR_UNABLE_TO_SWITCH_PROCESS_ID_OR_THREAD_ID_IS_INVALID:
        ShowMessages("err, unable to switch to the process id or thread id "
                     "as the target process id or thread id is not found in "
                     "the attached threads list, please view the list of "
                     "processes and threads by using the '.switch list' command (%x)\n",
                     Error);
        break;
 
    case DEBUGGER_ERROR_UNABLE_TO_SWITCH_THERE_IS_NO_THREAD_ON_THE_PROCESS:
        ShowMessages("err, unable to switch to the process as the process doesn't "
                     "contain an active intercepted thread (%x)\n",
                     Error);
        break;
 
    case DEBUGGER_ERROR_UNABLE_TO_GET_MODULES_OF_THE_PROCESS:
        ShowMessages("err, unable to get user-mode modules of the process (%x)\n",
                     Error);
        break;
 
    case DEBUGGER_ERROR_UNABLE_TO_GET_CALLSTACK:
        ShowMessages("err, unable to get the callstack (%x)\n",
                     Error);
        break;
 
    case DEBUGGER_ERROR_UNABLE_TO_QUERY_COUNT_OF_PROCESSES_OR_THREADS:
        ShowMessages("err, unable to query count of processes or threads (%x)\n",
                     Error);
        break;
 
    case DEBUGGER_ERROR_USING_SHORT_CIRCUITING_EVENT_WITH_POST_EVENT_MODE_IS_FORBIDDEDN:
        ShowMessages("err, using short-circuiting event with post events is not possible (%x)\n",
                     Error);
        break;
 
    case DEBUGGER_ERROR_UNKNOWN_TEST_QUERY_RECEIVED:
        ShowMessages("err, unknown test query is received to the debugger (%x)\n",
                     Error);
        break;
 
    case DEBUGGER_ERROR_READING_MEMORY_INVALID_PARAMETER:
        ShowMessages("err, invalid process or memory address (%x)\n",
                     Error);
        break;
 
    case DEBUGGER_ERROR_THE_TRAP_FLAG_LIST_IS_FULL:
        ShowMessages("err, unable to add the current thread/process to the list of trap flags. "
                     "Are you debugging multiple threads or stepping through different processes "
                     "simultaneously? (%x)\n",
                     Error);
        break;
 
    case DEBUGGER_ERROR_UNABLE_TO_KILL_THE_PROCESS_DOES_NOT_EXISTS:
        ShowMessages("err, process does not exists (already terminated?) (%x)\n",
                     Error);
        break;
 
    case DEBUGGER_ERROR_MODE_EXECUTION_IS_INVALID:
        ShowMessages("err, the specified execution mode is invalid (%x)\n",
                     Error);
        break;
 
    case DEBUGGER_ERROR_PROCESS_ID_CANNOT_BE_SPECIFIED_WHILE_APPLYING_EVENT_FROM_VMX_ROOT_MODE:
        ShowMessages("err, you cannot specify process id while the debugger is paused in the debugger mode. "
                     "You can use the '.process' or the '.thread' command to switch to the target process's "
                     "memory layout (%x)\n",
                     Error);
        break;
 
    case DEBUGGER_ERROR_INSTANT_EVENT_PREALLOCATED_BUFFER_IS_NOT_ENOUGH_FOR_EVENT_AND_CONDITIONALS:
        ShowMessages("err, the requested buffer for storing event and conditions is larger than the pre-allocated "
                     "buffer size (%x)\nfor more information on how to resolve this issue, "
                     "please visit: https://docs.hyperdbg.org/tips-and-tricks/misc/instant-events\n",
                     Error);
        break;
 
    case DEBUGGER_ERROR_INSTANT_EVENT_REGULAR_PREALLOCATED_BUFFER_NOT_FOUND:
        ShowMessages("err, not enough pre-allocated buffer exists for storing the event. You can use the 'prealloc' "
                     "command to fix this issue by pre-allocating more buffers (%x)\nfor more information "
                     "please visit: https://docs.hyperdbg.org/tips-and-tricks/misc/instant-events\n",
                     Error);
        break;
 
    case DEBUGGER_ERROR_INSTANT_EVENT_BIG_PREALLOCATED_BUFFER_NOT_FOUND:
        ShowMessages("err, the requested event is considered as a \"big instant event\" and right now, there is no "
                     "pre-allocated buffer for storing it. You can use the 'prealloc' command to fix this issue by "
                     "pre-allocating big instant event buffers (%x)\nfor more information "
                     "please visit: https://docs.hyperdbg.org/tips-and-tricks/misc/instant-events\n",
                     Error);
        break;
 
    case DEBUGGER_ERROR_UNABLE_TO_CREATE_ACTION_CANNOT_ALLOCATE_BUFFER:
        ShowMessages("err, unable to allocate buffer for the target action (%x)\n",
                     Error);
        break;
 
    case DEBUGGER_ERROR_INSTANT_EVENT_ACTION_REGULAR_PREALLOCATED_BUFFER_NOT_FOUND:
        ShowMessages("err, not enough pre-allocated buffer exists for storing the event's action. You can use the 'prealloc' "
                     "command to fix this issue by pre-allocating more buffers (%x)\nfor more information "
                     "please visit: https://docs.hyperdbg.org/tips-and-tricks/misc/instant-events\n",
                     Error);
        break;
 
    case DEBUGGER_ERROR_INSTANT_EVENT_ACTION_BIG_PREALLOCATED_BUFFER_NOT_FOUND:
        ShowMessages("err, the requested action is considered as a \"big instant event (action)\" and right now, there is no "
                     "pre-allocated buffer for storing it. You can use the 'prealloc' command to fix this issue by "
                     "pre-allocating big instant event's action buffers (%x)\nfor more information "
                     "please visit: https://docs.hyperdbg.org/tips-and-tricks/misc/instant-events\n",
                     Error);
        break;
 
    case DEBUGGER_ERROR_INSTANT_EVENT_PREALLOCATED_BUFFER_IS_NOT_ENOUGH_FOR_ACTION_BUFFER:
        ShowMessages("err, the requested buffer for storing action is larger than the pre-allocated "
                     "buffer size (%x)\nfor more information on how to resolve this issue, "
                     "please visit: https://docs.hyperdbg.org/tips-and-tricks/misc/instant-events\n",
                     Error);
        break;
 
    case DEBUGGER_ERROR_INSTANT_EVENT_REQUESTED_OPTIONAL_BUFFER_IS_BIGGER_THAN_DEBUGGERS_SEND_RECEIVE_STACK:
        ShowMessages("err, the requested optional buffer is bigger than the debuggers send/receive stack, "
                     "please select a smaller requested buffer for the target event (%x)\n",
                     Error);
        break;
 
    case DEBUGGER_ERROR_INSTANT_EVENT_REGULAR_REQUESTED_SAFE_BUFFER_NOT_FOUND:
        ShowMessages("err, by default HyperDbg won't allocate requested safe buffers for instant events in "
                     "the debugger mode. You can use the 'prealloc' command to allocate (regular) requested safe "
                     "buffers before running this command (%x)\nfor more information "
                     "please visit: https://docs.hyperdbg.org/tips-and-tricks/misc/instant-events\n",
                     Error);
        break;
 
    case DEBUGGER_ERROR_INSTANT_EVENT_BIG_REQUESTED_SAFE_BUFFER_NOT_FOUND:
        ShowMessages("err, the requested safe buffer is bigger than regular buffers. You can use the 'prealloc' "
                     "command to allocate (big) requested safe buffers before running this command (%x)\n"
                     "for more information "
                     "please visit: https://docs.hyperdbg.org/tips-and-tricks/misc/instant-events\n",
                     Error);
        break;
 
    case DEBUGGER_ERROR_INSTANT_EVENT_PREALLOCATED_BUFFER_IS_NOT_ENOUGH_FOR_REQUESTED_SAFE_BUFFER:
        ShowMessages("err, the requested buffer for storing safe buffers of the action is larger than the pre-allocated "
                     "buffer size (%x)\nfor more information on how to resolve this issue, "
                     "please visit: https://docs.hyperdbg.org/tips-and-tricks/misc/instant-events\n",
                     Error);
        break;
 
    case DEBUGGER_ERROR_UNABLE_TO_ALLOCATE_REQUESTED_SAFE_BUFFER:
        ShowMessages("err, unable to allocate buffer for the target requested safe buffer (%x)\n",
                     Error);
        break;
 
    case DEBUGGER_ERROR_COULD_NOT_FIND_PREACTIVATION_TYPE:
        ShowMessages("err, invalid type is specified for preactivation (%x)\n",
                     Error);
        break;
 
    case DEBUGGER_ERROR_THE_MODE_EXEC_TRAP_IS_NOT_INITIALIZED:
        ShowMessages("err, the '!mode' event command cannot be directly initialized in the Debugger Mode. "
                     "To avoid wasting system resources and performance issues we decided to use another "
                     "command to initialize it first then use it. You can use the 'preactivate mode' command "
                     "to preactivate this mechanism after that, you can use the '!mode' event (%x)\n",
                     Error);
        break;
 
    case DEBUGGER_ERROR_THE_TARGET_EVENT_IS_DISABLED_BUT_CANNOT_BE_CLEARED_PRIRITY_BUFFER_IS_FULL:
        ShowMessages("err, the event(s) that you've requested are disabled, yet HyperDbg cannot remove (clear) them in "
                     "the subsequent run due to the user-mode priority buffers being at full capacity. "
                     "This typically occurs when you attempt to clear numerous events without resuming the debuggee. "
                     "Since these unserviced events remain in the queue, HyperDbg is unable to clear them. "
                     "To address this issue, you can resume the debuggee, allowing all queued events to be cleared (usually 2 to 10 seconds). "
                     "Afterward, you can pause the debuggee again and request the removal of new events (%x)\n"
                     "for more information on how to resolve this issue "
                     "please visit: https://docs.hyperdbg.org/tips-and-tricks/misc/instant-events\n",
                     Error);
        break;
 
    case DEBUGGER_ERROR_NOT_ALL_CORES_ARE_LOCKED_FOR_APPLYING_INSTANT_EVENT:
        ShowMessages("err, the event cannot be applied since not all cores are locked! "
                     "If you are using the instant-event mechanism or switching between cores, this will likely halt the system. "
                     "This may be caused by a race condition, but continuing and halting the debugger might resolve it. "
                     "If the problem persists, please open an issue and provide steps to reproduce it (%x)\n",
                     Error);
        break;
 
    case DEBUGGER_ERROR_TARGET_SWITCHING_CORE_IS_NOT_LOCKED:
        ShowMessages("err, target core is not locked! "
                     "This may be caused by a race condition, continuing and halting the debugger might resolve it. "
                     "If the problem persists, please open an issue and provide steps to reproduce it (%x)\n",
                     Error);
        break;
 
    case DEBUGGER_ERROR_INVALID_PHYSICAL_ADDRESS:
        ShowMessages("err, invalid physical address (%x)\n",
                     Error);
        break;
 
    default:
        ShowMessages("err, error not found (%x)\n",
                     Error);
        return FALSE;
        break;
    }
 
    return TRUE;
}