add SDK API to debug remote device or from debuggee in the debugger mode

HyperDbg · Jul 12, 2024 · c55dd4a · c55dd4a
1 parent 8f1f0f2
commit c55dd4a
Show file tree

Hide file tree

Showing 5 changed files with 182 additions and 21 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -13,6 +13,7 @@ New release of the HyperDbg Debugger.
 - Export SDK APIs for reading/writing into registers in the Debugger Mode
 - Export SDK API for writing memory in the VMI Mode and the Debugger Mode
 - Export SDK API for getting kernel base address
+- Export SDK API for connecting to the debugger and from debuggee in the Debugger Mode
 
 ### Changed
 - Fix clearing '!monitor' hooks on a different process or if the process is closed (#409) ([link](https://github.com/HyperDbg/HyperDbg/issues/409))

diff --git a/hyperdbg/include/SDK/Imports/User/HyperDbgLibImports.h b/hyperdbg/include/SDK/Imports/User/HyperDbgLibImports.h
@@ -78,6 +78,18 @@ hyperdbg_u_set_custom_driver_path(CHAR * driver_file_path, CHAR * driver_name);
 IMPORT_EXPORT_LIBHYPERDBG VOID
 hyperdbg_u_use_default_driver_path();
 
+//
+// Connect to the debugger in the Debugger Mode
+//
+BOOLEAN
+hyperdbg_u_connect_remote_debugger_using_com_port(const CHAR * port_name, DWORD baudrate);
+
+BOOLEAN
+hyperdbg_u_connect_remote_debugger_using_named_pipe(const CHAR * named_pipe);
+
+BOOLEAN
+hyperdbg_u_connect_current_debugger_using_com_port(const CHAR * port_name, DWORD baudrate);
+
 //
 // Miscalenous functions
 //

diff --git a/hyperdbg/libhyperdbg/code/debugger/commands/meta-commands/debug.cpp b/hyperdbg/libhyperdbg/code/debugger/commands/meta-commands/debug.cpp
@@ -50,6 +50,39 @@ CommandDebugHelp()
     ShowMessages("valid COM ports : COM1, COM2, COM3, COM4 \n");
 }
 
+/**
+ * @brief Check if COM port is valid or not
+ *
+ * @param ComPort
+ * @return BOOLEAN
+ */
+BOOLEAN
+CommandDebugCheckComPort(const CHAR * ComPort, UINT32 * Port)
+{
+    if (_stricmp(ComPort, "com1") == 0)
+    {
+        *Port = COM1_PORT;
+        return TRUE;
+    }
+    else if (_stricmp(ComPort, "com2") == 0)
+    {
+        *Port = COM2_PORT;
+        return TRUE;
+    }
+    else if (_stricmp(ComPort, "com3") == 0)
+    {
+        *Port = COM3_PORT;
+        return TRUE;
+    }
+    else if (_stricmp(ComPort, "com4") == 0)
+    {
+        *Port = COM4_PORT;
+        return TRUE;
+    }
+
+    return FALSE;
+}
+
 /**
  * @brief Check if baud rate is valid or not
  *
@@ -72,36 +105,98 @@ CommandDebugCheckBaudrate(DWORD Baudrate)
 }
 
 /**
- * @brief Check if COM port is valid or not
+ * @brief Connect to a remote serial device (Debugger)
+ *
+ * @param PortName
+ * @param Baudrate
  *
- * @param ComPort
  * @return BOOLEAN
  */
 BOOLEAN
-CommandDebugCheckComPort(const string & ComPort, UINT32 * Port)
+HyperDbgDebugRemoteDeviceUsingComPort(const CHAR * PortName, DWORD Baudrate)
 {
-    if (!ComPort.compare("com1"))
+    UINT32 Port;
+
+    //
+    // Check if baudrate is valid or not
+    //
+    if (!CommandDebugCheckBaudrate(Baudrate))
     {
-        *Port = COM1_PORT;
-        return TRUE;
+        //
+        // Baud-rate is invalid
+        //
+        return FALSE;
     }
-    else if (!ComPort.compare("com2"))
+
+    //
+    // check if com port address is valid or not
+    //
+    if (!CommandDebugCheckComPort(PortName, &Port))
     {
-        *Port = COM2_PORT;
-        return TRUE;
+        //
+        // com port is invalid
+        //
+        return FALSE;
     }
-    else if (!ComPort.compare("com3"))
+
+    //
+    // Everything is okay, connect to the remote machine to send (debugger)
+    //
+    return KdPrepareAndConnectDebugPort(PortName, Baudrate, Port, FALSE, FALSE);
+}
+
+/**
+ * @brief Connect to a remote named pipe (Debugger)
+ *
+ * @param NamedPipe
+ *
+ * @return BOOLEAN
+ */
+BOOLEAN
+HyperDbgDebugRemoteDeviceUsingNamedPipe(const CHAR * NamedPipe)
+{
+    return KdPrepareAndConnectDebugPort(NamedPipe, NULL, NULL, FALSE, TRUE);
+}
+
+/**
+ * @brief Connect to a remote serial device (Debuggee)
+ *
+ * @param PortName
+ * @param Baudrate
+ *
+ * @return BOOLEAN
+ */
+BOOLEAN
+HyperDbgDebugCurrentDeviceUsingComPort(const CHAR * PortName, DWORD Baudrate)
+{
+    UINT32 Port;
+
+    //
+    // Check if baudrate is valid or not
+    //
+    if (!CommandDebugCheckBaudrate(Baudrate))
     {
-        *Port = COM3_PORT;
-        return TRUE;
+        //
+        // Baud-rate is invalid
+        //
+        return FALSE;
     }
-    else if (!ComPort.compare("com4"))
+
+    //
+    // check if com port address is valid or not
+    //
+    if (!CommandDebugCheckComPort(PortName, &Port))
     {
-        *Port = COM4_PORT;
-        return TRUE;
+        //
+        // com port is invalid
+        //
+        return FALSE;
     }
 
-    return FALSE;
+    //
+    // Everything is okay, connect to the remote machine to send (debuggee)
+    //
+    return KdPrepareAndConnectDebugPort(PortName, Baudrate, Port, TRUE, FALSE);
 }
 
 /**
@@ -193,7 +288,7 @@ CommandDebug(vector<string> SplitCommand, string Command)
             //
             // check if com port address is valid or not
             //
-            if (!CommandDebugCheckComPort(SplitCommand.at(4), &Port))
+            if (!CommandDebugCheckComPort(SplitCommand.at(4).c_str(), &Port))
             {
                 //
                 // com port is invalid
@@ -206,7 +301,7 @@ CommandDebug(vector<string> SplitCommand, string Command)
             //
             // Everything is okay, connect to the remote machine to send (debugger)
             //
-            KdPrepareAndConnectDebugPort(SplitCommand.at(4).c_str(), Baudrate, Port, FALSE, FALSE);
+            HyperDbgDebugRemoteDeviceUsingComPort(SplitCommand.at(4).c_str(), Baudrate);
         }
         else if (!SplitCommand.at(2).compare("namedpipe"))
         {
@@ -221,7 +316,7 @@ CommandDebug(vector<string> SplitCommand, string Command)
             //
             // Connect to a namedpipe (it's probably a Virtual Machine debugging)
             //
-            KdPrepareAndConnectDebugPort(Token.c_str(), NULL, NULL, FALSE, TRUE);
+            HyperDbgDebugRemoteDeviceUsingNamedPipe(Token.c_str());
         }
         else
         {
@@ -280,7 +375,7 @@ CommandDebug(vector<string> SplitCommand, string Command)
             //
             // check if com port address is valid or not
             //
-            if (!CommandDebugCheckComPort(SplitCommand.at(4), &Port))
+            if (!CommandDebugCheckComPort(SplitCommand.at(4).c_str(), &Port))
             {
                 //
                 // com port is invalid
@@ -293,7 +388,7 @@ CommandDebug(vector<string> SplitCommand, string Command)
             //
             // Everything is okay, prepare to send (debuggee)
             //
-            KdPrepareAndConnectDebugPort(SplitCommand.at(4).c_str(), Baudrate, Port, TRUE, FALSE);
+            HyperDbgDebugCurrentDeviceUsingComPort(SplitCommand.at(4).c_str(), Baudrate);
         }
         else
         {

diff --git a/hyperdbg/libhyperdbg/code/export/export.cpp b/hyperdbg/libhyperdbg/code/export/export.cpp
@@ -434,3 +434,47 @@ hyperdbg_u_get_kernel_base()
 {
     return DebuggerGetKernelBase();
 }
+
+/**
+ * @brief Connect to the remote debugger using COM port
+ *
+ * @param port_name The port name
+ * @param baudrate The baudrate
+ *
+ * @return BOOLEAN Returns true if it was successful
+ */
+BOOLEAN
+hyperdbg_u_connect_remote_debugger_using_com_port(const CHAR * port_name, DWORD baudrate)
+{
+    return HyperDbgDebugRemoteDeviceUsingComPort(port_name, baudrate);
+}
+
+/**
+ * @brief Connect to the remote debugger using named pipe
+ *
+ * @param named_pipe The named pipe
+ *
+ * @return BOOLEAN Returns true if it was successful
+ */
+BOOLEAN
+hyperdbg_u_connect_remote_debugger_using_named_pipe(const CHAR * named_pipe)
+{
+    return HyperDbgDebugRemoteDeviceUsingNamedPipe(named_pipe);
+}
+
+BOOLEAN
+HyperDbgDebugCurrentDeviceUsingComPort(const CHAR * PortName, DWORD Baudrate);
+
+/**
+ * @brief Connect to the current debugger using COM port
+ *
+ * @param port_name The port name
+ * @param baudrate The baudrate
+ *
+ * @return BOOLEAN Returns true if it was successful
+ */
+BOOLEAN
+hyperdbg_u_connect_current_debugger_using_com_port(const CHAR * port_name, DWORD baudrate)
+{
+    return HyperDbgDebugCurrentDeviceUsingComPort(port_name, baudrate);
+}
diff --git a/hyperdbg/libhyperdbg/header/debugger.h b/hyperdbg/libhyperdbg/header/debugger.h
@@ -276,3 +276,12 @@ HyperDbgRegisterShowAll();
 
 BOOLEAN
 HyperDbgRegisterShowTargetRegister(REGS_ENUM RegisterId);
+
+BOOLEAN
+HyperDbgDebugRemoteDeviceUsingComPort(const CHAR * PortName, DWORD Baudrate);
+
+BOOLEAN
+HyperDbgDebugRemoteDeviceUsingNamedPipe(const CHAR * NamedPipe);
+
+BOOLEAN
+HyperDbgDebugCurrentDeviceUsingComPort(const CHAR * PortName, DWORD Baudrate);