forwarding.cpp File Reference

Event source forwarding. More...

#include "pch.h"

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.
VOID *	ForwardingCreateOutputSource (DEBUGGER_EVENT_FORWARDING_TYPE SourceType, const string &Description, SOCKET *Socket, HMODULE *Module)
	Create a new source (create handle from the source)
BOOLEAN	ForwardingPerformEventForwarding (PDEBUGGER_GENERAL_EVENT_DETAIL EventDetail, CHAR *Message, UINT32 MessageLength)
	Send the event result to the corresponding sources.
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.

Variables
UINT64	g_OutputSourceTag
	This variable holds the trace and generate numbers for unique tag of the output resources.
LIST_ENTRY	g_OutputSources
	Holds a list of output sources created by output command.
LIST_ENTRY	g_EventTrace
	Holds a list of events in kernel and the state of events and the commands to show the state of each command (disabled/enabled)

Detailed Description

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.

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;
}

ForwardingPerformEventForwarding()

BOOLEAN ForwardingPerformEventForwarding	(	PDEBUGGER_GENERAL_EVENT_DETAIL	EventDetail,
		CHAR *	Message,
		UINT32	MessageLength )

Send the event result to the corresponding sources.

Parameters

EventDetail	Description saved about the event in the user-mode
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

{
    BOOLEAN     Result   = FALSE;
    PLIST_ENTRY TempList = 0;
 
    for (size_t i = 0; i < DebuggerOutputSourceMaximumRemoteSourceForSingleEvent; i++)
    {
        //
        // Check whether we reached to the end of the events
        //
        if (EventDetail->OutputSourceTags[i] == NULL)
        {
            return Result;
        }
 
        //
        // If we reach here then the output tag is not null
        // means that we should find the event tag from list
        // of tags
        //
        TempList = &g_OutputSources;
 
        while (&g_OutputSources != TempList->Flink)
        {
            TempList = TempList->Flink;
 
            PDEBUGGER_EVENT_FORWARDING CurrentOutputSourceDetails = CONTAINING_RECORD(
                TempList,
                DEBUGGER_EVENT_FORWARDING,
                OutputSourcesList);
 
            if (EventDetail->OutputSourceTags[i] ==
                CurrentOutputSourceDetails->OutputUniqueTag)
            {
                //
                // Indicate that we found a tag that matches this item
                // Now, we should check whether the output is opened or
                // not closed
                //
                if (CurrentOutputSourceDetails->State ==
                    EVENT_FORWARDING_STATE_OPENED)
                {
                    switch (CurrentOutputSourceDetails->Type)
                    {
                    case EVENT_FORWARDING_NAMEDPIPE:
                        Result = ForwardingSendToNamedPipe(
                            CurrentOutputSourceDetails->Handle,
                            Message,
                            MessageLength);
                        break;
                    case EVENT_FORWARDING_FILE:
                        Result = ForwardingWriteToFile(CurrentOutputSourceDetails->Handle,
                                                       Message,
                                                       MessageLength);
                        break;
                    case EVENT_FORWARDING_TCP:
                        Result = ForwardingSendToTcpSocket(
                            CurrentOutputSourceDetails->Socket,
                            Message,
                            MessageLength);
                        break;
                    case EVENT_FORWARDING_MODULE:
                        ((hyperdbg_event_forwarding_t)CurrentOutputSourceDetails->Handle)(
                            Message,
                            MessageLength);
                        Result = TRUE;
                        break;
                    default:
                        break;
                    }
                }
 
                //
                // No need to search through the list anymore
                //
                break;
            }
        }
    }
 
    return FALSE;
}

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;
}

Variable Documentation

g_EventTrace

LIST_ENTRY g_EventTrace

extern

Holds a list of events in kernel and the state of events and the commands to show the state of each command (disabled/enabled)

this list is not have any relation with the things that HyperDbg holds for each event in the kernel

{0};

g_OutputSources

LIST_ENTRY g_OutputSources

extern

Holds a list of output sources created by output command.

user-mode events and output sources are two separate things in HyperDbg

{0};

g_OutputSourceTag

UINT64 g_OutputSourceTag

extern

This variable holds the trace and generate numbers for unique tag of the output resources.