Module Mapping Caveats

Beware! Many of the conveniences in Ghidra assume that the target is running from the same file system as Ghidra, which will not be the case when the target is remote. Be sure your current project is populated only with programs imported from the target’s file system. Additionally, if prompted to import something new, be sure to redirect to the remote file system, because the dialog will default to the path on the local file system.

Variation in Configuration

There are a number of configurations for remote debugging with many moving parts. Some of those parts are contributed by Ghidra’s Debugger, some are not. Depending on your particular target and platform, there may be several options available to you. Consider a remote Linux target in user space. While this list is not exhaustive, some options are:

• Use gdbserver over SSH
• Use Trace RMI over SSH
• Use gdbserver and connect to it manually
• Connect Trace RMI manually

Generally, for each of these options it boils down to which components will be colocated with the target and which will be colocated with Ghidra.

Using gdbserver over SSH

In this configuration, Ghidra and GDB will be located in the user’s local environment, while gdbserver and the specimen will be located in the target environment. We will connect the local gdb to the remote gdbserver by forwarding stdio over SSH.

1. First, prepare the target, which for demonstration purposes has the IP address 10.0.0.1. Generally, this just means booting it up and ensuring it has gdbserver installed. NOTE: You do not need to run gdbserver or the target binary. The launcher will do that for you.

2. From the launch menu, select gdb + gdbserver via ssh.

   

3. Read the wall of text, at least the first time, and verify the remote system is prepared.

4. Fill out the options appropriately. Notably, correct the location of the target image to point at its location on the target system. Enter “user@10.0.0.1” for the [User@]Host option, substituting your username for the remote system.

5. Click Launch.

At this point, most things will work the same as they would for a local target.

Using Trace RMI over SSH

In this configuration, Ghidra will be located in the user’ls local environment, while gdb and the specimen will be located in the target environment. Notice that we are not using gdbserver. We will connect the local Ghidra to the remote gdb by forwarding Trace RMI over SSH. See the help (press F1 on the gdb via ssh menu item for advantages and disadvantages of using this vs. gdbserver.)

1. First, prepare the target. This is more involved than using gdbserver, since you will need to ensure gdb and the Trace RMI plugin for it are installed. The packages, which should be included with Ghidra, are ghidratrace and ghidragdb, but you may need to build them first. If you installed gdb and python3 from your distribution’s repositories, installation of the Python packages should be straightfoward. Search the Ghidra installation for files ending in .whl. If the ghidratrace and ghidragdb packages are there, you can skip this build step and just transfer them to the target. On the local system:

   python3 -m pip install build # unless you already have it
   cd /path/to/ghidra/Ghidra/Debug/Debugger-rmi-trace/pypkg
   python3 -m build

   This will output .tar.gz and .whl files under pypkg/dist. Do the same for Debugger-agent-gdb/pypkg. Transfer the resulting .whl files to the target, then on the target system:

   python3 -m pip install /path/to/ghidratrace-[version].whl /path/to/ghidragdb-[version].whl

   If you are offline, the dependencies are included in the pypkg/dist directory for each module. Transfer and install them, too. You may try python -m pip install --no-index -f /path/to/packages ghidragdb, if all the packages and dependencies are in the one directory. Chances are, GDB embeds the same Python, so they become importable from GDB. Test using gdb on the target system:

   python import ghidragdb

   No news is good news! You can quit GDB, since that was just for verifying the installation.

2. From the launch menu, select gdb via ssh.

   

3. Fill out the options appropriately. Notably, correct the location of the target image to point at its location on the target system. Enter “user@10.0.0.1” for the [User@]Host option, substituting your username for the remote system.

4. Click Launch.

At this point, most things will work the same as they would for a local target.

python3 -m pip install build
cd /path/to/ghidra/Ghidra/Debug/Debugger-rmi-trace/pypkg
python3 -m build

ldd $(which gdb)

(gdb) python-interactive
>>> import sys
>>> sys.version

Using gdbserver manually

The configuration and result here are similar using gdbserver over SSH, but will be performed manually.

1. First, prepare the target. This time, you will need to start gdbserver on the remote system manually. For demonstration, we will listen on 10.0.0.1 port 12345:

   gdbserver 10.0.0.1:12345 termmines

2. From the launch menu, select remote gdb.

3. Fill out the options appropriately. Notably, enter “10.0.0.1” for the Host option, and “12345” for the Port option.

4. Click Launch.

At this point, most things will work the same as they would for a local target.

Connecting Trace RMI manually

The configuration and result here are similar to using Trace RMI over SSH, but will be performed manually.

1. First, prepare the target. Follow the same installation steps as above for Trace RMI over SSH, if you have not already.

2. In Ghidra’s Connections window, click Accept a single inbound TCP connection in the local toolbar.

   

3. Set Host/Address to “10.0.0.1”, so that we can connect to it over the network. NOTE: You may leave the port as “0” or pick a specific port, assuming you have permission to use it.

4. Click Listen, and then take note of the acceptor’s port number in the Connections window, e.g., “12345.”

5. Now, on the remote system, start gdb and type:

   python import ghidragdb
   file termmines
   # set args, if you'd like
   ghidra trace connect 10.0.0.1:12345
   ghidra trace start
   ghidra trace sync-enable
   starti

At this point, most things will work the same as they would for a local target. You may notice Ghidra has not given you a new terminal. Just use the one you already have on the remote target.

A notable advantage of this configuration is that you can enter whatever gdb commands you want to start your target. Here we demonstrated the simplest case of a “native” target. It is also possible to use this procedure to connect Ghidra into a running gdb session.

Rube Goldberg Configurations

While you should always prefer the simpler configuration, it is possible to combine components to meet a variety of needs. For example, to debug a native Android target from Windows, you could run Ghidra on Windows, connect it to GDB via SSH to a Linux virtual machine, e.g., WSL2, and then connect that to gdbserver running in an Android emulator.

Exercise: Debug your Friend’s termmines

If you are in a classroom setting, pair up. Otherwise, play both roles, preferably using separate machines for Ghidra and the target. Using one of the above procedures, debug termmines. One of you should prepare the target environment. The other should connect to it and launch the specimen. Then trade roles, choose a different procedure, and do it again.