Implement GDB interaction

Author: ptr-yudai

ptrlib/debugger/unix/debug.py

@@ -3,7 +3,7 @@
 import getpass
 import re
 from logging import getLogger
-from typing import TYPE_CHECKING, List, Union
+from typing import TYPE_CHECKING, List, Union, overload
 if TYPE_CHECKING:
     from ptrlib.connection.unixproc import UnixProcess
 
@@ -45,17 +45,31 @@ def __init__(self, pid: int):
     @property
     @attached
     def gdb(self) -> UnixProcess:
+        """Debugger session
+        """
         return self._gdb
+        
+    @property
+    def debug(self) -> bool:
+        """Debug mode
+        """
+        return self._gdb.debug
 
+    @debug.setter
+    def debug(self, mode: bool):
+        self._gdb.debug = mode
+
     @property
     def pid(self) -> int:
+        """PID of the target process
+        """
         return self._pid
 
     def _attach_direct(self):
         self._gdb = unix_process()(["gdb", "-q", "-p", str(self._pid)])
         init_msg = self._gdb.recvuntil(self._gdb_prompt, lookahead=True)
         if GDB_PTRACE_ERROR in init_msg:
-            raise PermissionError
+            raise PermissionError(f"Cannot attach pid={self._pid}")
 
     def _attach_with_sudo(self):
         self._gdb = unix_process()([
@@ -70,17 +84,24 @@ def _attach_with_sudo(self):
             init_msg = self._gdb.recvuntil(self._gdb_prompt, lookahead=True)
 
         if GDB_PTRACE_ERROR in init_msg:
-            raise PermissionError
+            raise PermissionError(f"Cannot attach pid={self._pid}")
 
     @detached
     def attach(self) -> 'UnixProcessDebugger':
         """Attach to process with GDB.
+
+        Return:
+            UnixProcessDebugger: This debugger instance.
         """
+        # TODO: Check if target process has already been attached
+        # TODO: Check if we have root privilege
         try:
             self._attach_direct()
+            return self
         except PermissionError:
-            self._attach_with_sudo()
+            pass
 
+        self._attach_with_sudo()
         return self
 
     @attached
@@ -90,19 +111,55 @@ def detach(self):
         self._gdb.close()
         del self._gdb
 
+    @overload
+    def execute(self, command: str, resume: bool=False) -> str: ...
+    @overload
+    def execute(self, command: List[str], resume: bool=False) -> List[str]: ...
     @attached
-    def execute(self, command: str) -> str:
+    def execute(self,
+                command: Union[str, List[str]],
+                resume: bool=False) -> Union[str, List[str]]:
+        """Execute a GDB command.
+
+        Args:
+            command (str): A command to execute, or a list of commands.
+            resume (bool): If true, continue execution after all commands are done.
+
+        Returns:
+            str: Result of the command.
+
+        Examples:
+            ```
+            conn = sock.process.attach()
+            stdout = int(conn.execute("p/x &_IO_2_1_stdout_").split(' = ')[1], 16)
+            conn.execute("break puts", resume=True)
+            sock.sendline(b"Hello")
+            res = conn.execute([
+                f"set {{long}}{stdout} = 0xfbad1887",
+                f"x/4xg {stdout}"
+            ])
+            print(res[1])
+            ```
+        """
+        if isinstance(command, list):
+            result = [self.execute(c) for c in command]
+            if resume:
+                self.execute('continue')
+            return result
+
         self._gdb.after(self._gdb_prompt).sendline(command)
-        # TODO: self._gdb.before(self._gdb_prompt).lastline()
+        # TODO: self._gdb.before(self._gdb_prompt).lastline() to keep color sequence
         result = self._gdb.recvuntil(self._gdb_prompt, drop=True, lookahead=True)
         # Remove ANSI escape sequences aggressively
-        return CTRL_RE.sub(b'', ANSI_RE.sub(b'', result)).decode().strip()
+        result = CTRL_RE.sub(b'', ANSI_RE.sub(b'', result)).decode().strip()
+        if resume:
+            self._gdb.after(self._gdb_prompt).sendline("continue")
+        return result            
 
-    def batch_execute(self, commands: List[str]) -> List[str]:
-        return [self.execute(command) for command in commands]
-    
     @attached
     def interactive(self):
+        """Interact with GDB terminal
+        """
         self._gdb.interactive(prompt='')
         # Return a prompt for further use
         self._gdb.unget(b'(gdb) ')

ptrlib/debugger/unix/process.py

@@ -152,18 +152,25 @@ def vmmap(self) -> List[UnixMemoryRegion]:
         return maps
 
     def attach(self, pid: Optional[Union[int, Callable[['UnixProcessManager'], int]]]=None) -> UnixProcessDebugger:
-        """
+        """Attach to a process with given pid.
+
+        Args:
+            pid (int): Process ID or a function or lambda that returns a pid.
+
         Examples:
             ```
             sock = Process("/bin/cat")
             conn = sock.process.attach()
-            conn.execute(["break write", "continue"])
+            #conn.debug = True
 
-            sock.sendline(b"Hello!")
-            a = conn.execute("p/x $rsi")
-            conn.detach()
+            conn.execute("break write", resume=True)
+            sock.sendline(b"Hello, World!")
 
+            a, b = conn.execute(["p/x $rsi", "x/1s $rsi"])
+            print(a)  # $1 = 0x7d0f5d1de000
+            print(b)  # 0x7d0f5d1de000: "Hello, World!\\n"
 
+            conn.detach()
             ```
         """
         if pid is None: