forwarding.h File Reference

Headers for event source forwarding. More...

Go to the source code of this file.

Classes
struct	_DEBUGGER_EVENT_FORWARDING
	structures hold the detail of event forwarding More...

Macros
#define	MAXIMUM_CHARACTERS_FOR_EVENT_FORWARDING_NAME   50
	maximum characters for event forwarding source names

Typedefs
typedef void(*	hyperdbg_event_forwarding_t) (const char *, unsigned int)
	maximum characters for event forwarding source names
typedef enum _DEBUGGER_EVENT_FORWARDING_TYPE	DEBUGGER_EVENT_FORWARDING_TYPE
	event forwarding type
typedef enum _DEBUGGER_EVENT_FORWARDING_STATE	DEBUGGER_EVENT_FORWARDING_STATE
	event forwarding states
typedef enum _DEBUGGER_OUTPUT_SOURCE_STATUS	DEBUGGER_OUTPUT_SOURCE_STATUS
	output source status
typedef struct _DEBUGGER_EVENT_FORWARDING	DEBUGGER_EVENT_FORWARDING
	structures hold the detail of event forwarding
typedef struct _DEBUGGER_EVENT_FORWARDING *	PDEBUGGER_EVENT_FORWARDING

Enumerations
enum	_DEBUGGER_EVENT_FORWARDING_TYPE { EVENT_FORWARDING_NAMEDPIPE , EVENT_FORWARDING_FILE , EVENT_FORWARDING_TCP , EVENT_FORWARDING_MODULE }
	event forwarding type More...
enum	_DEBUGGER_EVENT_FORWARDING_STATE { EVENT_FORWARDING_STATE_NOT_OPENED , EVENT_FORWARDING_STATE_OPENED , EVENT_FORWARDING_CLOSED }
	event forwarding states More...
enum	_DEBUGGER_OUTPUT_SOURCE_STATUS {   DEBUGGER_OUTPUT_SOURCE_STATUS_SUCCESSFULLY_OPENED , DEBUGGER_OUTPUT_SOURCE_STATUS_SUCCESSFULLY_CLOSED , DEBUGGER_OUTPUT_SOURCE_STATUS_ALREADY_OPENED , DEBUGGER_OUTPUT_SOURCE_STATUS_ALREADY_CLOSED ,   DEBUGGER_OUTPUT_SOURCE_STATUS_UNKNOWN_ERROR }
	output source status More...

Functions
UINT64	ForwardingGetNewOutputSourceTag ()
	Get the output source tag and increase the global variable for tag.
DEBUGGER_OUTPUT_SOURCE_STATUS	ForwardingOpenOutputSource (PDEBUGGER_EVENT_FORWARDING SourceDescriptor)
	Opens the output source.
DEBUGGER_OUTPUT_SOURCE_STATUS	ForwardingCloseOutputSource (PDEBUGGER_EVENT_FORWARDING SourceDescriptor)
	Closes the output source.
BOOLEAN	ForwardingCheckAndPerformEventForwarding (UINT32 OperationCode, CHAR *Message, UINT32 MessageLength)
	Check and send the event result to the corresponding sources.
BOOLEAN	ForwardingWriteToFile (HANDLE FileHandle, CHAR *Message, UINT32 MessageLength)
	Write the output results to the file.
BOOLEAN	ForwardingSendToNamedPipe (HANDLE NamedPipeHandle, CHAR *Message, UINT32 MessageLength)
	Send the output results to the namedpipe.
BOOLEAN	ForwardingSendToTcpSocket (SOCKET TcpSocket, CHAR *Message, UINT32 MessageLength)
	Send the output results to the tcp socket.
VOID *	ForwardingCreateOutputSource (DEBUGGER_EVENT_FORWARDING_TYPE SourceType, const string &Description, SOCKET *Socket, HMODULE *Module)
	Create a new source (create handle from the source)

Detailed Description

Headers for event source forwarding.

Author

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

Version

0.1

Date

2020-11-16

Copyright

This project is released under the GNU Public License v3.

Macro Definition Documentation

MAXIMUM_CHARACTERS_FOR_EVENT_FORWARDING_NAME

#define MAXIMUM_CHARACTERS_FOR_EVENT_FORWARDING_NAME   50

maximum characters for event forwarding source names

Typedef Documentation

DEBUGGER_EVENT_FORWARDING

typedef struct _DEBUGGER_EVENT_FORWARDING DEBUGGER_EVENT_FORWARDING

structures hold the detail of event forwarding

DEBUGGER_EVENT_FORWARDING_STATE

typedef enum _DEBUGGER_EVENT_FORWARDING_STATE DEBUGGER_EVENT_FORWARDING_STATE

event forwarding states

DEBUGGER_EVENT_FORWARDING_TYPE

typedef enum _DEBUGGER_EVENT_FORWARDING_TYPE DEBUGGER_EVENT_FORWARDING_TYPE

event forwarding type

DEBUGGER_OUTPUT_SOURCE_STATUS

typedef enum _DEBUGGER_OUTPUT_SOURCE_STATUS DEBUGGER_OUTPUT_SOURCE_STATUS

output source status

this enum is used as the result returned from the functions that work with opening and closing sources

hyperdbg_event_forwarding_t

typedef void(* hyperdbg_event_forwarding_t) (const char *, unsigned int)

maximum characters for event forwarding source names

PDEBUGGER_EVENT_FORWARDING

typedef struct _DEBUGGER_EVENT_FORWARDING * PDEBUGGER_EVENT_FORWARDING

Enumeration Type Documentation

_DEBUGGER_EVENT_FORWARDING_STATE

enum _DEBUGGER_EVENT_FORWARDING_STATE

event forwarding states

Enumerator
EVENT_FORWARDING_STATE_NOT_OPENED
EVENT_FORWARDING_STATE_OPENED
EVENT_FORWARDING_CLOSED

{
    EVENT_FORWARDING_STATE_NOT_OPENED,
    EVENT_FORWARDING_STATE_OPENED,
    EVENT_FORWARDING_CLOSED,
 
} DEBUGGER_EVENT_FORWARDING_STATE;

_DEBUGGER_EVENT_FORWARDING_TYPE

enum _DEBUGGER_EVENT_FORWARDING_TYPE

event forwarding type

Enumerator
EVENT_FORWARDING_NAMEDPIPE
EVENT_FORWARDING_FILE
EVENT_FORWARDING_TCP
EVENT_FORWARDING_MODULE

{
    EVENT_FORWARDING_NAMEDPIPE,
    EVENT_FORWARDING_FILE,
    EVENT_FORWARDING_TCP,
    EVENT_FORWARDING_MODULE,
 
} DEBUGGER_EVENT_FORWARDING_TYPE;

_DEBUGGER_OUTPUT_SOURCE_STATUS

enum _DEBUGGER_OUTPUT_SOURCE_STATUS

output source status

this enum is used as the result returned from the functions that work with opening and closing sources

Enumerator
DEBUGGER_OUTPUT_SOURCE_STATUS_SUCCESSFULLY_OPENED
DEBUGGER_OUTPUT_SOURCE_STATUS_SUCCESSFULLY_CLOSED
DEBUGGER_OUTPUT_SOURCE_STATUS_ALREADY_OPENED
DEBUGGER_OUTPUT_SOURCE_STATUS_ALREADY_CLOSED
DEBUGGER_OUTPUT_SOURCE_STATUS_UNKNOWN_ERROR

{
    DEBUGGER_OUTPUT_SOURCE_STATUS_SUCCESSFULLY_OPENED,
    DEBUGGER_OUTPUT_SOURCE_STATUS_SUCCESSFULLY_CLOSED,
    DEBUGGER_OUTPUT_SOURCE_STATUS_ALREADY_OPENED,
    DEBUGGER_OUTPUT_SOURCE_STATUS_ALREADY_CLOSED,
    DEBUGGER_OUTPUT_SOURCE_STATUS_UNKNOWN_ERROR,
 
} DEBUGGER_OUTPUT_SOURCE_STATUS;

Function Documentation

ForwardingCheckAndPerformEventForwarding()

BOOLEAN ForwardingCheckAndPerformEventForwarding	(	UINT32	OperationCode,
		CHAR *	Message,
		UINT32	MessageLength )

Check and send the event result to the corresponding sources.

Parameters

OperationCode	The target operation code or tag
MessageLength	Length of the message

This function will not check whether the event has an output source or not, the caller if this function should make sure that the following event has valid output sources or not

Returns

BOOLEAN whether sending results was successful or not

{
    PLIST_ENTRY TempList;
    BOOLEAN     OutputSourceFound = FALSE;
 
    //
    // We should check whether the following flag matches
    // with an output or not, also this is not where we want to
    // check output resources
    //
    TempList = &g_EventTrace;
    while (&g_EventTrace != TempList->Blink)
    {
        TempList = TempList->Blink;
 
        PDEBUGGER_GENERAL_EVENT_DETAIL EventDetail = CONTAINING_RECORD(
            TempList,
            DEBUGGER_GENERAL_EVENT_DETAIL,
            CommandsEventList);
 
        if (EventDetail->HasCustomOutput && (UINT32)EventDetail->Tag == OperationCode)
        {
            //
            // Output source found
            //
            OutputSourceFound = TRUE;
 
            //
            // Send the event to output sources
            // Minus one (-1) is because we want to
            // remove the null character at end of the message
            //
            if (!ForwardingPerformEventForwarding(
                    EventDetail,
                    Message,
                    MessageLength))
            {
                ShowMessages("err, there was an error transferring the "
                             "message to the remote sources\n");
            }
 
            break;
        }
    }
 
    return OutputSourceFound;
}

ForwardingCloseOutputSource()

DEBUGGER_OUTPUT_SOURCE_STATUS ForwardingCloseOutputSource

(

PDEBUGGER_EVENT_FORWARDING

SourceDescriptor

)

Closes the output source.

Parameters

SourceDescriptor

Descriptor of the source

Returns

DEBUGGER_OUTPUT_SOURCE_STATUS return status of the closing function

{
    //
    // Check if already closed
    //
    if (SourceDescriptor->State == EVENT_FORWARDING_CLOSED)
    {
        return DEBUGGER_OUTPUT_SOURCE_STATUS_ALREADY_CLOSED;
    }
 
    //
    // Check if not opened
    //
    if (SourceDescriptor->State == EVENT_FORWARDING_STATE_NOT_OPENED ||
        SourceDescriptor->State != EVENT_FORWARDING_STATE_OPENED)
    {
        //
        // Not opennd ? or state other than opened ?
        //
        return DEBUGGER_OUTPUT_SOURCE_STATUS_UNKNOWN_ERROR;
    }
 
    //
    // Set the state
    //
    SourceDescriptor->State = EVENT_FORWARDING_CLOSED;
 
    //
    // Now, it's time to close the source based on its type
    //
    if (SourceDescriptor->Type == EVENT_FORWARDING_FILE)
    {
        //
        // Close the handle
        //
        CloseHandle(SourceDescriptor->Handle);
 
        //
        // Return the status
        //
        return DEBUGGER_OUTPUT_SOURCE_STATUS_SUCCESSFULLY_CLOSED;
    }
    else if (SourceDescriptor->Type == EVENT_FORWARDING_TCP)
    {
        //
        // Shutdown connection
        //
        CommunicationClientShutdownConnection(SourceDescriptor->Socket);
 
        //
        // Cleanup
        //
        CommunicationClientCleanup(SourceDescriptor->Socket);
 
        //
        // Return the status
        //
        return DEBUGGER_OUTPUT_SOURCE_STATUS_SUCCESSFULLY_CLOSED;
    }
    else if (SourceDescriptor->Type == EVENT_FORWARDING_NAMEDPIPE)
    {
        //
        // Close the file
        //
        NamedPipeClientClosePipe(SourceDescriptor->Handle);
 
        //
        // Return the status
        //
        return DEBUGGER_OUTPUT_SOURCE_STATUS_SUCCESSFULLY_CLOSED;
    }
    else if (SourceDescriptor->Type == EVENT_FORWARDING_MODULE)
    {
        //
        // Free the library
        //
        FreeLibrary(SourceDescriptor->Module);
 
        //
        // Return the status
        //
        return DEBUGGER_OUTPUT_SOURCE_STATUS_SUCCESSFULLY_CLOSED;
    }
 
    return DEBUGGER_OUTPUT_SOURCE_STATUS_UNKNOWN_ERROR;
}

ForwardingCreateOutputSource()

VOID * ForwardingCreateOutputSource	(	DEBUGGER_EVENT_FORWARDING_TYPE	SourceType,
		const string &	Description,
		SOCKET *	Socket,
		HMODULE *	Module )

Create a new source (create handle from the source)

Parameters

SourceType	Type of the source
Description	Description of the source
Socket	Socket object in the case of TCP connection
Module	Module object in the case of loading modules

If the target connection is a tcp connection then there is no handle and instead there is a socket, this way we pass a valid value for handle (TRUE) which is not a valid handle but it indicates that the operation was successful and the caller can use the pointer that it passed as the socket. On anything other than tcp sockets, the socket pointer in not modified; thus, it's not value

Returns

HANDLE returns handle of the source

{
    string IpPortDelimiter;
    string Ip;
    string Port;
 
    if (SourceType == EVENT_FORWARDING_FILE)
    {
        //
        // Create a new file
        //
        HANDLE FileHandle = CreateFileA(Description.c_str(), GENERIC_WRITE, 0, NULL, OPEN_ALWAYS, FILE_ATTRIBUTE_NORMAL, NULL);
 
        //
        // The handle might be INVALID_HANDLE_VALUE which will be
        // checked by the caller
        //
        return (void *)FileHandle;
    }
    else if (SourceType == EVENT_FORWARDING_MODULE)
    {
        HMODULE ModuleHandle = LoadLibraryA(Description.c_str());
 
        if (ModuleHandle == NULL)
        {
            ShowMessages("err, unable to load the module\n");
            return INVALID_HANDLE_VALUE;
        }
 
        hyperdbg_event_forwarding_t hyperdbg_event_forwarding = (hyperdbg_event_forwarding_t)GetProcAddress(ModuleHandle, "hyperdbg_event_forwarding");
 
        if (hyperdbg_event_forwarding == NULL)
        {
            ShowMessages("err, unable to find the 'hyperdbg_event_forwarding' function\n");
            return INVALID_HANDLE_VALUE;
        }
 
        //
        // Set the module handle
        //
        *Module = ModuleHandle;
 
        //
        // The handle is the location of the hyperdbg_event_forwarding function
        //
        return (void *)hyperdbg_event_forwarding;
    }
    else if (SourceType == EVENT_FORWARDING_NAMEDPIPE)
    {
        HANDLE PipeHandle = NamedPipeClientCreatePipe(Description.c_str());
 
        if (!PipeHandle)
        {
            //
            // Unable to create handle
            //
            return INVALID_HANDLE_VALUE;
        }
 
        return (void *)PipeHandle;
    }
    else if (SourceType == EVENT_FORWARDING_TCP)
    {
        //
        // Check if the port is included in the description string or not
        //
        if (Description.find(':') != std::string::npos)
        {
            //
            // Split the ip and port by : delimiter
            //
            IpPortDelimiter = ':';
            size_t find     = Description.find(IpPortDelimiter);
            Ip              = Description.substr(0, find);
            Port            = Description.substr(find + 1, find + Description.size());
 
            //
            // Connect to server, in this function 0 means there was no error
            // and 1 means there was an error
            //
            if (CommunicationClientConnectToServer(Ip.c_str(), Port.c_str(), Socket) == 0)
            {
                //
                // Send a fake handle just to avoid sending INVALID_HANDLE_VALUE
                // because this functionality doesn't work with handlers; however,
                // send 1 or TRUE is a valid handle
                //
                return (void *)TRUE;
            }
            else
            {
                //
                // There was an error in connecting to the server
                // so return an invalid handle
                //
                return INVALID_HANDLE_VALUE;
            }
        }
        else
        {
            //
            // Invalid address format
            //
            return INVALID_HANDLE_VALUE;
        }
    }
 
    //
    // By default, handle is invalid
    //
    return INVALID_HANDLE_VALUE;
}

ForwardingGetNewOutputSourceTag()

UINT64 ForwardingGetNewOutputSourceTag

(

)

Get the output source tag and increase the global variable for tag.

Returns

UINT64

{
    return g_OutputSourceTag++;
}

ForwardingOpenOutputSource()

DEBUGGER_OUTPUT_SOURCE_STATUS ForwardingOpenOutputSource

(

PDEBUGGER_EVENT_FORWARDING

SourceDescriptor

)

Opens the output source.

Parameters

SourceDescriptor

Descriptor of the source

Returns

DEBUGGER_OUTPUT_SOURCE_STATUS return status of the opening function

{
    //
    // Check if already closed
    //
    if (SourceDescriptor->State == EVENT_FORWARDING_CLOSED)
    {
        return DEBUGGER_OUTPUT_SOURCE_STATUS_ALREADY_CLOSED;
    }
 
    //
    // check if already opened
    //
    if (SourceDescriptor->State == EVENT_FORWARDING_STATE_OPENED)
    {
        return DEBUGGER_OUTPUT_SOURCE_STATUS_ALREADY_OPENED;
    }
 
    //
    // Set the status to opened
    //
    SourceDescriptor->State = EVENT_FORWARDING_STATE_OPENED;
 
    //
    // Now, it's time to open the source based on its type
    //
    if (SourceDescriptor->Type == EVENT_FORWARDING_FILE)
    {
        //
        // Nothing special to do here, file is opened with CreateFile
        // and nothing should be called to open the handle
        //
        return DEBUGGER_OUTPUT_SOURCE_STATUS_SUCCESSFULLY_OPENED;
    }
    else if (SourceDescriptor->Type == EVENT_FORWARDING_NAMEDPIPE)
    {
        //
        // Nothing special to do here, namedpipe is opened with CreateFile
        // and nothing should be called to open the handle
        //
        return DEBUGGER_OUTPUT_SOURCE_STATUS_SUCCESSFULLY_OPENED;
    }
    else if (SourceDescriptor->Type == EVENT_FORWARDING_TCP)
    {
        //
        // Nothing special to do here, tcp socket is opened with
        // CommunicationClientConnectToServer and nothing should be
        // called to open the socket
        //
        return DEBUGGER_OUTPUT_SOURCE_STATUS_SUCCESSFULLY_OPENED;
    }
    else if (SourceDescriptor->Type == EVENT_FORWARDING_MODULE)
    {
        //
        // Nothing special to do here, function is found previously
        // and nothing should be called to open the module
        //
        return DEBUGGER_OUTPUT_SOURCE_STATUS_SUCCESSFULLY_OPENED;
    }
 
    return DEBUGGER_OUTPUT_SOURCE_STATUS_UNKNOWN_ERROR;
}

ForwardingSendToNamedPipe()

BOOLEAN ForwardingSendToNamedPipe	(	HANDLE	NamedPipeHandle,
		CHAR *	Message,
		UINT32	MessageLength )

Send the output results to the namedpipe.

Parameters

NamedPipeHandle	Handle of the target namedpipe
Message	The message that should be sent to namedpipe
MessageLength	Length of the message

This function will not check whether the event has an output source or not, the caller if this function should make sure that the following event has valid output sources or not

Returns

BOOLEAN whether the sending to the namedpipe was successful or not

{
    BOOLEAN SentMessageResult;
 
    SentMessageResult =
        NamedPipeClientSendMessage(NamedPipeHandle, Message, MessageLength);
 
    if (!SentMessageResult)
    {
        //
        // Sending error
        //
        return FALSE;
    }
 
    //
    // Successfully sent
    //
    return TRUE;
}

ForwardingSendToTcpSocket()

BOOLEAN ForwardingSendToTcpSocket	(	SOCKET	TcpSocket,
		CHAR *	Message,
		UINT32	MessageLength )

Send the output results to the tcp socket.

Parameters

TcpSocket	Socket object of the target tcp socket
Message	The message that should be sent to the tcp socket
MessageLength	Length of the message

This function will not check whether the event has an output source or not, the caller if this function should make sure that the following event has valid output sources or not

Returns

BOOLEAN whether the sending to the tcp socket was successful or not

{
    if (CommunicationClientSendMessage(TcpSocket, Message, MessageLength) != 0)
    {
        //
        // Failed to send
        //
        return FALSE;
    }
 
    //
    // Successfully sent
    //
    return TRUE;
}

ForwardingWriteToFile()

BOOLEAN ForwardingWriteToFile	(	HANDLE	FileHandle,
		CHAR *	Message,
		UINT32	MessageLength )

Write the output results to the file.

Parameters

FileHandle	Handle of the target file
Message	The message that should be written to file
MessageLength	Length of the message

This function will not check whether the event has an output source or not, the caller if this function should make sure that the following event has valid output sources or not

Returns

BOOLEAN whether the writing to the file was successful or not

{
    DWORD BytesWritten = 0;
    BOOL  ErrorFlag    = FALSE;
 
    ErrorFlag = WriteFile(FileHandle,    // open file handle
                          Message,       // start of data to write
                          MessageLength, // number of bytes to write
                          &BytesWritten, // number of bytes that were written
                          NULL);         // no overlapped structure
 
    return TRUE;
 
    if (ErrorFlag == FALSE)
    {
        //
        // Err, terminal failure: Unable to write to file
        //
 
        return FALSE;
    }
    else
    {
        if (BytesWritten != MessageLength)
        {
            //
            // This is an error because a synchronous write that results in
            // success (WriteFile returns TRUE) should write all data as
            // requested. This would not necessarily be the case for
            // asynchronous writes.
            //
 
            return FALSE;
        }
        else
        {
            //
            // Successfully wrote
            //
            return TRUE;
        }
    }
 
    //
    // by default we assume there was an error
    //
    return FALSE;
}