Use target remote for remote connections

.github/workflows/tests.yml

@@ -21,7 +21,7 @@ jobs:
       matrix:
         runner: [ubuntu-24.04, ubuntu-22.04]
 
-    name: "Run Unit tests on ${{ matrix.runner }}"
+    name: "Tests/${{ matrix.runner }}"
     runs-on: ${{ matrix.runner }}
     defaults:
       run:

.gitignore

@@ -14,3 +14,4 @@ debug.log
 htmlcov
 .benchmarks
 site/
+untracked/

docs/commands/gef-remote.md

@@ -1,15 +1,8 @@
 ## Command `gef-remote`
 
-[`target remote`](https://sourceware.org/gdb/onlinedocs/gdb/Remote-Debugging.html#Remote-Debugging)
-is the traditional GDB way of debugging process or system remotely. However this command by itself
-does a limited job (80's bandwith FTW) to collect more information about the target, making the
-process of debugging more cumbersome. GEF greatly improves that state with the `gef-remote` command.
-
-📝 **Note**: If using GEF, `gef-remote` **must** be your way or debugging remote processes, never
-`target remote`. Maintainers will provide minimal support or help if you decide to use the
-traditional `target remote` command. For many reasons, you **should not** use `target remote` alone
-with GEF. It is still important to note that the default `target remote` command has been
-overwritten by a minimal copy `gef-remote`, in order to make most tools relying on this command work.
+📝 **IMPORTANT NOTE**: `gef-remote` is deprecated since 2024.09 in favor of `target remote`. The
+command will be removed in a future release. Do not rely on it.
+
 
 `gef-remote` can function in 2 ways:
 

ruff.toml

@@ -0,0 +1,2 @@
+[lint.per-file-ignores]
+"gef.py" = ["E701"]

tests/api/gef_memory.py

@@ -12,6 +12,7 @@
     ARCH,
     debug_target,
     gdbserver_session,
+    get_random_port,
     qemuuser_session,
     GDBSERVER_DEFAULT_HOST,
 )
@@ -121,48 +122,35 @@ def test_func_parse_maps_local_procfs(self):
     @pytest.mark.slow
     def test_func_parse_maps_remote_gdbserver(self):
         gef, gdb = self._gef, self._gdb
-        # When in a gef-remote session `parse_gdb_info_proc_maps` should work to
+        # When in a remote session `parse_gdb_info_proc_maps` should work to
         # query the memory maps
-        while True:
-            port = random.randint(1025, 65535)
-            if port != self._port:
-                break
+        port = get_random_port()
 
         with pytest.raises(Exception):
-            gdb.execute(f"gef-remote {GDBSERVER_DEFAULT_HOST} {port}")
+            gdb.execute(f"target remote :{port}")
 
         with gdbserver_session(port=port) as _:
-            gdb.execute(f"gef-remote {GDBSERVER_DEFAULT_HOST} {port}")
+            gdb.execute(f"target remote :{port}")
             sections = gef.memory.maps
             assert len(sections) > 0
 
     @pytest.mark.skipif(ARCH not in ("x86_64",), reason=f"Skipped for {ARCH}")
     def test_func_parse_maps_remote_qemu(self):
         gdb, gef = self._gdb, self._gef
-        # When in a gef-remote qemu-user session `parse_gdb_info_proc_maps`
-        # should work to query the memory maps
-        while True:
-            port = random.randint(1025, 65535)
-            if port != self._port:
-                break
+        port = get_random_port()
 
         with qemuuser_session(port=port) as _:
-            cmd = f"gef-remote --qemu-user --qemu-binary {self._target} {GDBSERVER_DEFAULT_HOST} {port}"
+            cmd = f"target remote :{port}"
             gdb.execute(cmd)
             sections = gef.memory.maps
             assert len(sections) > 0
 
     def test_func_parse_maps_realpath(self):
         gef, gdb = self._gef, self._gdb
-        # When in a gef-remote session `parse_gdb_info_proc_maps` should work to
-        # query the memory maps
-        while True:
-            port = random.randint(1025, 65535)
-            if port != self._port:
-                break
+        port = get_random_port()
 
         with gdbserver_session(port=port) as _:
-            gdb.execute(f"gef-remote {GDBSERVER_DEFAULT_HOST} {port}")
+            gdb.execute(f"target remote :{port}")
             gdb.execute("b main")
             gdb.execute("continue")
             sections = gef.memory.maps

tests/api/gef_remote.py

@@ -0,0 +1,108 @@
+"""
+`target remote/extended-remote` test module.
+"""
+
+
+from tests.base import RemoteGefUnitTestGeneric
+from tests.utils import debug_target, gdbserver_session, gdbserver_multi_session, get_random_port, qemuuser_session
+
+
+class GefRemoteApi(RemoteGefUnitTestGeneric):
+
+    def setUp(self) -> None:
+        self._target = debug_target("default")
+        return super().setUp()
+
+    def test_gef_remote_test_gdbserver(self):
+        """Test `gdbserver file`"""
+        _gdb = self._gdb
+        _gef = self._gef
+        _root = self._conn.root
+        port = get_random_port()
+
+        with gdbserver_session(port=port):
+            assert not _root.eval("is_target_remote()")
+            assert not _root.eval("is_target_remote_or_extended()")
+            assert not _root.eval("is_running_in_gdbserver()")
+            assert not _root.eval("is_running_in_rr()")
+            assert not _root.eval("is_running_in_qemu()")
+
+            _gdb.execute(f"target remote :{port}")
+
+            assert _root.eval("is_target_remote()")
+            assert _root.eval("is_target_remote_or_extended()")
+            assert _root.eval("is_running_in_gdbserver()")
+            assert _root.eval("is_running_in_gdbserver()")
+
+            assert not _root.eval("is_target_extended_remote()")
+            assert not _root.eval("is_running_in_qemu()")
+            assert not _root.eval("is_running_in_qemu_system()")
+            assert not _root.eval("is_running_in_qemu_user()")
+            assert not _root.eval("is_running_in_rr()")
+
+            assert hasattr(_gef.session, "remote")
+            assert "GDBSERVER" in str(_gef.session.remote)
+            assert "GDBSERVER_MULTI" not in str(_gef.session.remote)
+
+    def test_gef_remote_test_gdbserver_multi(self):
+        """Test `gdbserver --multi file`"""
+        _gdb = self._gdb
+        _gef = self._gef
+        _root = self._conn.root
+        port = get_random_port()
+
+        with gdbserver_multi_session(port=port):
+            assert not _root.eval("is_target_remote()")
+            assert not _root.eval("is_target_remote_or_extended()")
+            assert not _root.eval("is_running_in_gdbserver()")
+            assert not _root.eval("is_running_in_rr()")
+            assert not _root.eval("is_running_in_qemu()")
+
+            _gdb.execute(f"target extended-remote :{port}")
+            _gdb.execute(f"set remote exec-file {self._target}")
+            _gdb.execute(f"file {self._target}")
+            _gdb.execute(f"start {self._target}")
+
+            assert _root.eval("is_target_remote_or_extended()")
+            assert _root.eval("is_target_extended_remote()")
+            assert _root.eval("is_running_in_gdbserver()")
+            assert not _root.eval("is_target_remote()")
+
+            assert not _root.eval("is_running_in_qemu()")
+            assert not _root.eval("is_running_in_qemu_system()")
+            assert not _root.eval("is_running_in_qemu_user()")
+            assert not _root.eval("is_running_in_rr()")
+
+            assert hasattr(_gef.session, "remote")
+            assert "GDBSERVER_MULTI" in str(_gef.session.remote)
+
+    def test_gef_remote_test_qemuuser(self):
+        """Test `qemu-user -g`"""
+        _gdb = self._gdb
+        _gef = self._gef
+        _root = self._conn.root
+        port = get_random_port()
+
+        with qemuuser_session(port=port):
+            assert not _root.eval("is_target_remote()")
+            assert not _root.eval("is_target_remote_or_extended()")
+            assert not _root.eval("is_running_in_gdbserver()")
+
+            _gdb.execute(f"target remote :{port}")
+
+            assert _root.eval("is_target_remote()")
+            assert _root.eval("is_target_remote_or_extended()")
+            assert _root.eval("is_running_in_qemu()")
+            assert _root.eval("is_running_in_qemu_user()")
+
+            assert not _root.eval("is_target_extended_remote()")
+            assert not _root.eval("is_running_in_qemu_system()")
+            assert not _root.eval("is_running_in_gdbserver()")
+            assert not _root.eval("is_running_in_rr()")
+
+            assert hasattr(_gef.session, "remote")
+            assert "QEMU_USER" in str(_gef.session.remote)
+
+    # TODO add tests for
+    #  - [ ] qemu-system
+    #  - [ ] rr

tests/api/gef_session.py

@@ -14,6 +14,7 @@
     ARCH,
     debug_target,
     gdbserver_session,
+    get_random_port,
     qemuuser_session,
     GDBSERVER_DEFAULT_HOST,
 )
@@ -63,12 +64,11 @@ def test_root_dir_local(self):
     def test_root_dir_remote(self):
         gdb = self._gdb
         gdb.execute("start")
-
         expected = os.stat("/")
-        host = GDBSERVER_DEFAULT_HOST
-        port = random.randint(1025, 65535)
+        port = get_random_port()
+
         with gdbserver_session(port=port):
-            gdb.execute(f"gef-remote {host} {port}")
+            gdb.execute(f"target remote :{port}")
             result = self._conn.root.eval("os.stat(gef.session.root)")
             assert (expected.st_dev == result.st_dev) and (
                 expected.st_ino == result.st_ino
@@ -77,11 +77,8 @@ def test_root_dir_remote(self):
     @pytest.mark.skipif(ARCH not in ("x86_64",), reason=f"Skipped for {ARCH}")
     def test_root_dir_qemu(self):
         gdb, gef = self._gdb, self._gef
+        port = get_random_port()
 
-        host = GDBSERVER_DEFAULT_HOST
-        port = random.randint(1025, 65535)
         with qemuuser_session(port=port):
-            gdb.execute(
-                f"gef-remote --qemu-user --qemu-binary {self._target} {host} {port}"
-            )
+            gdb.execute(f"target remote :{port}")
             assert re.search(r"\/proc\/[0-9]+/root", str(gef.session.root))

tests/base.py

@@ -1,16 +1,14 @@
 import os
 import pathlib
-import random
 import re
 import subprocess
-import tempfile
 import time
-from typing import Tuple
+
 import unittest
 
 import rpyc
 
-from .utils import debug_target
+from .utils import debug_target, get_random_port, which
 
 COVERAGE_DIR = os.getenv("COVERAGE_DIR", "")
 GEF_PATH = pathlib.Path(os.getenv("GEF_PATH", "gef.py")).absolute()
@@ -19,6 +17,8 @@
 RPYC_PORT = 18812
 RPYC_SPAWN_TIME = 1.0
 RPYC_MAX_REMOTE_CONNECTION_ATTEMPTS = 5
+GDB_BINARY_PATH = which("gdb-multiarch")
+RPYC_CONNECT_FAILURE_DELAY = 0.2
 
 
 class RemoteGefUnitTestGeneric(unittest.TestCase):
@@ -28,6 +28,7 @@ class RemoteGefUnitTestGeneric(unittest.TestCase):
     """
 
     def setUp(self) -> None:
+        self._gdb_path = GDB_BINARY_PATH
         attempt = RPYC_MAX_REMOTE_CONNECTION_ATTEMPTS
         while True:
             try:
@@ -41,7 +42,7 @@ def setUp(self) -> None:
                 attempt -= 1
                 if attempt == 0:
                     raise
-                time.sleep(0.2)
+                time.sleep(RPYC_CONNECT_FAILURE_DELAY)
                 continue
 
         self._gdb = self._conn.root.gdb
@@ -58,7 +59,7 @@ def __setup(self):
         #
         # Select a random tcp port for rpyc
         #
-        self._port = random.randint(1025, 65535)
+        self._port = get_random_port()
         self._commands = ""
 
         if COVERAGE_DIR:
@@ -71,25 +72,20 @@ def __setup(self):
 pi cov.start()
 """
 
-        self._commands += f"""
-source {GEF_PATH}
-gef config gef.debug True
-gef config gef.propagate_debug_exception True
-gef config gef.disable_color True
-source {RPYC_GEF_PATH}
-pi start_rpyc_service({self._port})
-"""
-
-        self._initfile = tempfile.NamedTemporaryFile(mode="w", delete=False)
-        self._initfile.write(self._commands)
-        self._initfile.flush()
+        # self._initfile = tempfile.NamedTemporaryFile(mode="w", delete=False)
+        # self._initfile.write(self._commands)
+        # self._initfile.flush()
         self._command = [
-            "gdb",
-            "-q",
-            "-nx",
-            "-ex",
-            f"source {self._initfile.name}",
+            # fmt: off
+            self._gdb_path, "-q", "-nx",
+            "-ex", f"source {GEF_PATH}",
+            "-ex", "gef config gef.debug True",
+            "-ex", "gef config gef.propagate_debug_exception True",
+            "-ex", "gef config gef.disable_color True",
+            "-ex", f"source {RPYC_GEF_PATH}",
+            "-ex", f"pi start_rpyc_service({self._port})",
             "--",
+            # fmt: off
             str(self._target.absolute()),  # type: ignore pylint: disable=E1101
         ]
         self._process = subprocess.Popen(self._command)
@@ -109,7 +105,9 @@ def tearDown(self) -> None:
         return super().tearDown()
 
     @property
-    def gdb_version(self) -> Tuple[int, int]:
-        res = [int(d) for d in re.search(r"(\d+)\D(\d+)", self._gdb.VERSION).groups()]
-        assert len(res) >= 2
-        return tuple(res)
+    def gdb_version(self) -> tuple[int, int]:
+        res = re.search(r"(\d+)\D(\d+)", self._gdb.VERSION)
+        assert res
+        groups = [int(d) for d in res.groups()]
+        assert len(groups) == 2
+        return groups[0], groups[1]