remote-connection.cpp File Reference

handle remote connections command More...

#include "pch.h"

Functions
VOID	RemoteConnectionListen (PCSTR Port)
	Listen of a port and wait for a client connection.
DWORD WINAPI	RemoteConnectionThreadListeningToDebuggee (LPVOID lpParam)
	A thread that listens for server (debuggee) messages and show it by using ShowMessages wrapper.
VOID	RemoteConnectionConnect (PCSTR Ip, PCSTR Port)
	Connect to a remote debuggee (guest) as a client (host).
INT	RemoteConnectionSendCommand (const CHAR *sendbuf, INT len)
	send the command as a client (debugger, host) to the server (debuggee, guest)
INT	RemoteConnectionSendResultsToHost (const CHAR *sendbuf, INT len)
	Send the results of executing a command from deubggee (server, guest) to the debugger (client, host).
INT	RemoteConnectionCloseTheConnectionWithDebuggee ()
	Close the connect from client side to the debuggee.

Variables
BYTE	g_EndOfBufferCheckTcp [TCP_END_OF_BUFFER_CHARS_COUNT]
	the buffer that we set at the end of buffers for tcp connection
BOOLEAN	g_IsConnectedToHyperDbgLocally
	Shows whether the user is allowed to use 'load' command to load modules locally in VMI (virtual machine introspection) mode.
BOOLEAN	g_IsConnectedToRemoteDebuggee
	Shows whether the current debugger is the host and connected to a remote debuggee (guest).
BOOLEAN	g_IsConnectedToRemoteDebugger
	Shows whether the current system is a guest (debuggee) and a remote debugger is connected to this system.
BOOLEAN	g_BreakPrintingOutput
	Shows whether the pause command or CTRL+C or CTRL+Break is executed or not.
BOOLEAN	g_IsEndOfMessageReceived
	variable to keep track if the end of the message received (for showing signature)
SOCKET	g_SeverSocket
	The socket object of guest debuggee (not debugger) it is because in HyperDbg, debugger is client and debuggee is a server.
SOCKET	g_ServerListenSocket
	Server in debuggee needs an extra socket.
SOCKET	g_ClientConnectSocket
	The socket object of host debugger (not debuggee) it is because in HyperDbg, debuggee is server and debugger is a client.
HANDLE	g_RemoteDebuggeeListeningThread
	In debugger (not debuggee), we save the ip of server debuggee in this variable to use it later e.g, in signature.
HANDLE	g_EndOfMessageReceivedEvent
	Handle to if the end of the message received (for showing signature).

Detailed Description

handle remote connections command

Author

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

Version

0.1

Date

2020-08-21

Copyright

This project is released under the GNU Public License v3.

Function Documentation

RemoteConnectionCloseTheConnectionWithDebuggee()

INT RemoteConnectionCloseTheConnectionWithDebuggee

(

)

Close the connect from client side to the debuggee.

Returns

INT returning 0 means that there was no error in executing the function and 1 shows there was an error

{
    CommunicationClientShutdownConnection(g_ClientConnectSocket);
    CommunicationClientCleanup(g_ClientConnectSocket);
 
    return 0;
}

RemoteConnectionConnect()

VOID RemoteConnectionConnect	(	PCSTR	Ip,
		PCSTR	Port )

Connect to a remote debuggee (guest) as a client (host).

this routine is supposed to be called by .connect command

Parameters

Ip
Port

Returns

VOID

{
    DWORD  ThreadId;
    CHAR   Recv[3]  = {0};
    UINT32 BuffRecv = 0;
 
    //
    // Check if the debugger or debuggee is already active
    //
    if (IsConnectedToAnyInstanceOfDebuggerOrDebuggee())
    {
        return;
    }
 
    //
    // Connect to server
    //
    if (CommunicationClientConnectToServer(Ip, Port, &g_ClientConnectSocket) == 1)
    {
        //
        // There was an error
        //
 
        //
        // Indicate that debugger is not connected
        //
        g_IsConnectedToHyperDbgLocally = FALSE;
 
        //
        // Indicate that it's not a remote  debuggee
        //
        g_IsConnectedToRemoteDebuggee = FALSE;
 
        //
        // Shutdown connection
        //
        CommunicationClientShutdownConnection(g_ClientConnectSocket);
 
        //
        // Cleanup
        //
        CommunicationClientCleanup(g_ClientConnectSocket);
    }
    else
    {
        //
        // Connection was successful
        //
 
        //
        // Check to see whether the version of debugger and debuggee matches together or not
        //
        if (CommunicationClientSendMessage(g_ClientConnectSocket, (const CHAR *)BuildSignature, sizeof(BuildSignature)) != 0)
        {
            //
            // Failed
            //
            ShowMessages("err, failed to communicate with debuggee\n");
            return;
        }
 
        //
        // Receive the handshake results
        //
        if (CommunicationClientReceiveMessage(g_ClientConnectSocket, Recv, sizeof(Recv), &BuffRecv) != 0)
        {
            //
            // Failed, break
            //
            ShowMessages("err, failed to receive message from debuggee\n");
            return;
        }
 
        //
        // Check if the handshake was successful or not
        //
        if (strcmp((const CHAR *)"OK", Recv) != 0)
        {
            //
            // Build version not matched
            //
            ShowMessages(ASSERT_MESSAGE_BUILD_SIGNATURE_DOESNT_MATCH);
            return;
        }
 
        //
        // Indicate that local debugger is not connected
        //
        g_IsConnectedToHyperDbgLocally = FALSE;
 
        //
        // Indicate that it's a remote debuggee
        //
        g_IsConnectedToRemoteDebuggee = TRUE;
 
        //
        // Create an event to show signature when the messages finished
        //
        if (g_EndOfMessageReceivedEvent == NULL)
        {
            g_EndOfMessageReceivedEvent = CreateEvent(NULL, FALSE, FALSE, NULL);
        }
 
        //
        // Now, we should create a thread, which always listens to
        // the remote debuggee for new messages
        // Listen for upcoming messages
        //
        g_RemoteDebuggeeListeningThread = CreateThread(
            NULL,
            0,
            RemoteConnectionThreadListeningToDebuggee,
            NULL,
            0,
            &ThreadId);
 
        ShowMessages("connected to %s:%s\n", Ip, Port);
    }
}

RemoteConnectionListen()

VOID RemoteConnectionListen

(

PCSTR

Port

)

Listen of a port and wait for a client connection.

this routine is supposed to be called by .listen command

Parameters

Port

Returns

VOID

{
    CHAR recvbuf[COMMUNICATION_BUFFER_SIZE] = {0};
 
    //
    // Check if the debugger or debuggee is already active
    //
    if (IsConnectedToAnyInstanceOfDebuggerOrDebuggee())
    {
        return;
    }
 
    //
    // Start server and wait for client
    //
    CommunicationServerCreateServerAndWaitForClient(Port, &g_SeverSocket, &g_ServerListenSocket);
 
    //
    // Check the version of debuggee and debugger
    //
    if (CommunicationServerReceiveMessage(g_SeverSocket, recvbuf, COMMUNICATION_BUFFER_SIZE) != 0)
    {
        //
        // Failed
        //
        ShowMessages("err, unable to handshake with the remote debugger\n");
 
        //
        // Close the connection
        //
        CommunicationServerShutdownAndCleanupConnection(g_SeverSocket, g_ServerListenSocket);
 
        return;
    }
 
    //
    // Check whether the signature of debuggee and debugger match or not
    //
    if (strcmp((const CHAR *)BuildSignature, recvbuf) != 0)
    {
        //
        // Build version not matched
        //
        ShowMessages(ASSERT_MESSAGE_BUILD_SIGNATURE_DOESNT_MATCH);
 
        //
        // Send unsuccessful handshake (version match) message
        //
        if (CommunicationServerSendMessage(g_SeverSocket, "NO", 3) != 0)
        {
            //
            // Failed
            //
            ShowMessages("err, unable to handshake with the remote debugger\n");
        }
 
        //
        // Close the connection
        //
        CommunicationServerShutdownAndCleanupConnection(g_SeverSocket, g_ServerListenSocket);
 
        return;
    }
    else
    {
        //
        // Send successful handshake (version match) message
        //
        if (CommunicationServerSendMessage(g_SeverSocket, "OK", 3) != 0)
        {
            //
            // Failed
            //
            ShowMessages("err, unable to handshake with the remote debugger\n");
 
            //
            // Close the connection
            //
            CommunicationServerShutdownAndCleanupConnection(g_SeverSocket, g_ServerListenSocket);
 
            return;
        }
    }
 
    //
    // Indicate that it's a remote debugger
    //
    g_IsConnectedToRemoteDebugger = TRUE;
 
    //
    // And also, make it a local debugger
    //
    g_IsConnectedToHyperDbgLocally = TRUE;
 
    //
    // Zero the buffer for next command
    //
    RtlZeroMemory(recvbuf, COMMUNICATION_BUFFER_SIZE);
 
    while (true)
    {
        //
        // Receive message (this loop works as a command executer,
        // we don't send the results to the remote machine by using
        // this tools
        //
        if (CommunicationServerReceiveMessage(g_SeverSocket, recvbuf, COMMUNICATION_BUFFER_SIZE) != 0)
        {
            //
            // Failed, break
            //
            break;
        }
 
        //
        // Execute the command
        //
        INT CommandExecutionResult = HyperDbgInterpreter(recvbuf);
 
        //
        // Send end of buffer
        //
        RemoteConnectionSendResultsToHost((const CHAR *)g_EndOfBufferCheckTcp, sizeof(g_EndOfBufferCheckTcp));
 
        //
        // if the debugger encounters an exit state then the return will be 1
        //
        if (CommandExecutionResult == 1)
        {
            //
            // Exit from the debugger
            //
            exit(0);
        }
 
        //
        // Zero the buffer for next command
        //
        RtlZeroMemory(recvbuf, COMMUNICATION_BUFFER_SIZE);
    }
 
    //
    // Indicate that debugger is not connected
    //
    g_IsConnectedToHyperDbgLocally = FALSE;
 
    //
    // Indicate that it's note a remote debugger
    //
    g_IsConnectedToRemoteDebugger = FALSE;
 
    //
    // Indicate that we're not in remote debugger anymore
    //
    ShowMessages("closing the connection...\n");
 
    //
    // Close the connection
    //
    CommunicationServerShutdownAndCleanupConnection(g_SeverSocket,
                                                    g_ServerListenSocket);
}

RemoteConnectionSendCommand()

INT RemoteConnectionSendCommand	(	const CHAR *	sendbuf,
		INT	len )

send the command as a client (debugger, host) to the server (debuggee, guest)

Parameters

sendbuf	address of message buffer
len	length of buffer

Returns

INT returning 0 means that there was no error in executing the function and 1 shows there was an error

{
    //
    // Send Message
    //
    if (CommunicationClientSendMessage(g_ClientConnectSocket, sendbuf, len) != 0)
    {
        //
        // Failed
        //
        return 1;
    }
 
    //
    // We wait for the debuggee to send the message
    //
    WaitForSingleObject(
        g_EndOfMessageReceivedEvent,
        INFINITE);
 
    //
    // Successful
    //
    return 0;
}

RemoteConnectionSendResultsToHost()

INT RemoteConnectionSendResultsToHost	(	const CHAR *	sendbuf,
		INT	len )

Send the results of executing a command from deubggee (server, guest) to the debugger (client, host).

Parameters

sendbuf	buffer address
len	length of buffer

Returns

INT returning 0 means that there was no error in executing the function and 1 shows there was an error

{
    //
    // Send the message
    //
    if (CommunicationServerSendMessage(g_SeverSocket, sendbuf, len) != 0)
    {
        //
        // Failed
        //
        return 1;
    }
 
    return 0;
}

RemoteConnectionThreadListeningToDebuggee()

DWORD WINAPI RemoteConnectionThreadListeningToDebuggee

(

LPVOID

lpParam

)

A thread that listens for server (debuggee) messages and show it by using ShowMessages wrapper.

Parameters

lpParam

Returns

DWORD

{
    CHAR   RecvBuf[COMMUNICATION_BUFFER_SIZE + TCP_END_OF_BUFFER_CHARS_COUNT] = {0};
    UINT32 BuffLenReceived                                                    = 0;
 
    while (g_IsConnectedToRemoteDebuggee)
    {
        //
        // Receive message
        //
        if (CommunicationClientReceiveMessage(g_ClientConnectSocket, RecvBuf, COMMUNICATION_BUFFER_SIZE, &BuffLenReceived) != 0)
        {
            //
            // Failed, break
            //
            break;
        }
 
        //
        // Check if it's end of the buffer
        //
        for (SIZE_T i = 0; i < BuffLenReceived; i++)
        {
            if (RecvBuf[i] == g_EndOfBufferCheckTcp[0] &&
                RecvBuf[i + 1] == g_EndOfBufferCheckTcp[1] &&
                RecvBuf[i + 2] == g_EndOfBufferCheckTcp[2] &&
                RecvBuf[i + 3] == g_EndOfBufferCheckTcp[3])
            {
                g_IsEndOfMessageReceived = TRUE;
 
                //
                // Cut the last string using \x00 \x00
                //
                RecvBuf[i]     = '\x00';
                RecvBuf[i + 1] = '\x00';
                break;
            }
        }
 
        //
        // This is just because we want to show a correct signature
        //
        if (!g_BreakPrintingOutput)
        {
            //
            // Show message from remote debuggee
            //
            ShowMessages("%s", RecvBuf);
        }
 
        //
        // Show the signature
        //
        if (g_IsEndOfMessageReceived)
        {
            //
            // it's not end of message anymore
            //
            g_IsEndOfMessageReceived = FALSE;
 
            //
            // Trigger the event
            //
            SetEvent(g_EndOfMessageReceivedEvent);
        }
 
        //
        // Clear the buffer
        //
        RtlZeroMemory(RecvBuf, COMMUNICATION_BUFFER_SIZE);
    }
 
    //
    // The connection was aborted
    // Uinitialize every connections
    //
 
    //
    // Indicate that debugger is not connected
    //
    g_IsConnectedToHyperDbgLocally = FALSE;
 
    //
    // Indicate that it's a remote debuggee
    //
    g_IsConnectedToRemoteDebuggee = FALSE;
 
    //
    // Show the signature
    //
    HyperDbgShowSignature();
 
    return 0;
}

Variable Documentation

g_BreakPrintingOutput

BOOLEAN g_BreakPrintingOutput

extern

Shows whether the pause command or CTRL+C or CTRL+Break is executed or not.

g_ClientConnectSocket

SOCKET g_ClientConnectSocket

extern

The socket object of host debugger (not debuggee) it is because in HyperDbg, debuggee is server and debugger is a client.

{0};

g_EndOfBufferCheckTcp

BYTE g_EndOfBufferCheckTcp[TCP_END_OF_BUFFER_CHARS_COUNT]

extern

the buffer that we set at the end of buffers for tcp connection

                                                          {
    TCP_END_OF_BUFFER_CHAR_1,
    TCP_END_OF_BUFFER_CHAR_2,
    TCP_END_OF_BUFFER_CHAR_3,
    TCP_END_OF_BUFFER_CHAR_4};

g_EndOfMessageReceivedEvent

HANDLE g_EndOfMessageReceivedEvent

extern

Handle to if the end of the message received (for showing signature).

g_IsConnectedToHyperDbgLocally

BOOLEAN g_IsConnectedToHyperDbgLocally

extern

Shows whether the user is allowed to use 'load' command to load modules locally in VMI (virtual machine introspection) mode.

g_IsConnectedToRemoteDebuggee

BOOLEAN g_IsConnectedToRemoteDebuggee

extern

Shows whether the current debugger is the host and connected to a remote debuggee (guest).

g_IsConnectedToRemoteDebugger

BOOLEAN g_IsConnectedToRemoteDebugger

extern

Shows whether the current system is a guest (debuggee) and a remote debugger is connected to this system.

g_IsEndOfMessageReceived

BOOLEAN g_IsEndOfMessageReceived

extern

variable to keep track if the end of the message received (for showing signature)

g_RemoteDebuggeeListeningThread

HANDLE g_RemoteDebuggeeListeningThread

extern

In debugger (not debuggee), we save the ip of server debuggee in this variable to use it later e.g, in signature.

g_ServerListenSocket

SOCKET g_ServerListenSocket

extern

Server in debuggee needs an extra socket.

{0};

g_SeverSocket

SOCKET g_SeverSocket

extern

The socket object of guest debuggee (not debugger) it is because in HyperDbg, debugger is client and debuggee is a server.

{0};