# Debugger: Launchers

The Debugger has an updated and simplified launcher system. A nice collection of basic launchers for our supported platforms are provided out of the box. For Linux, we provide a suite of GDB-based launchers. For macOS, we provide a suite of LLDB-based launchers (though, these work on Linux, too). For Windows, we provide a launcher based on the Windows Debugger (`dbgeng.dll` and `dbgmodel.dll`).

Each launcher automates the creation of a Trace RMI acceptor, executes the back-end shell script in a Terminal, then waits for the resulting target trace. In contrast to the previous system, the Terminal is the first and most basic interface presented. Even if just about everything else goes wrong, the terminal should still be faithfully operational:

The Terminal is fully integrated into Ghidra's UI and so can be docked or undocked just like the rest of Ghidra's windows. It provides fairly robust VT-100 emulation. Thus, the user experience from the Terminal is nearly identical to using the same debugger outside of Ghidra. This terminal-first approach also ensures that you interact with the target application's standard I/O. This was not possible in the previous system, as we re-implemented the CLI using the back end's `execute` method. The debugger's (and so also the target's) actual I/O streams were hidden away within a GDB/MI wrapper.

Each launcher script sets up a — usually Python — environment, launches the actual debugger, and provides a sequence of commands for it to load the Trace RMI plugin, connect back to Ghidra, launch the actual target process, and start the target trace. At this point, the plugin generally takes over, reacting to user and target events, accepting front-end requests, and generally keeping Ghidra and the back end synchronized.

The list of launchers can be accessed in either of two places: 1) In the Debugger → Configure and Launch ... menu or more conveniently from the Launch button in the main toolbar. This is the blue bug button near the top center. The Configure and Launch ... menu lists all available launchers. Selecting one will prompt for its options then launch. To re-launch quickly, use the Launch button. Clicking it will re-launch using the most recent launcher and configuration for the current program. If this is the first launch of the given program, the button will instead activate its drop-down menu. The drop-down is also accessible by clicking the down arrow next to the Launch button. The drop-down lists all launchers that have been previously configured for the current program. Clicking one will immediately launch the program without prompting. The Configure and Launch ... sub-menu of the drop-down functions exactly like in the Debugger menu.

The Terminal provides some fairly standard actions. Other keyboard control sequences, notably CTRL-C, are interpreted by the terminal, rather than Ghidra's action system, to achieve their expected behavior, e.g., interrupt.

### Copy

This is accessed using the toolbar button or the key sequence CTRL-SHIFT-C. As expected, it copies the current selection to the system clipboard.

### Paste

This is accessed using the toolbar button or the key sequence CTRL-SHIFT-V. As expected, it pastes the text contents of the system clipboard into the terminal, as if typed.

### Find

This is accessed using the local drop-down menu or the key sequence CTRL-SHIFT-F. It displays a dialog for searching the terminal's scrollback buffer.

### Find Next/Previous

These actions are accessed using the local drop-down menu or the key sequence CTRL-SHIFT-H or CTRL-SHIFT-G, respectively. They repeat the last search in the forward or backward direction.

### Select All

This is accessed using the local drop-down menu or the key sequence CTRL-SHIFT-A. It selects all text in the terminal, including its scrollback buffer. If all the text is already selected, then this selects nothing, so that pressing the keystroke twice is effectively "Select None."

### Terminate

This action is accessed using the local drop-down menu. It will terminate the Terminal's current session. Exactly what that means is determined by the Terminal's creator. In general, it means to destroy the full debugging session associated with the Terminal. That may cause related terminals, e.g., a secondary terminal for target I/O and associated target traces, to be terminated as well. NOTE: This action is not implied by closing the Terminal window. Closing the window with an active session merely hides it. It can be recalled using the Window → Terminals menu. If the session has already been terminated (indicated by an orange border) then closing the window will, in fact, destroy the Terminal.

## Stock GDB Launchers

The following launchers based on GDB (GNU Debugger) are included out of the box:

### GDB

This launcher is a Python plugin for GDB, and so is best suited for debugging Linux user-space targets as well as many embedded systems. Please note you may need to obtain a properly-configured build of GDB for your target. If you are working with an embedded system, it is probably safest to install the "multiarch" build of GDB from your package manager.

#### Setup

You must have GDB installed on the local system, and it must embed the Python 3 interpreter. If you have access to PyPI, setting up your Python 3 environment is done using Pip. Please note the version specifier for Protobuf.

-     python3 -m pip install psutil protobuf==3.20.3

If you are offline, or would like to use our provided packages, we still use Pip, but with a more complicated invocation:

-     cd /path/to/ghidra_
      version/Ghidra/Debug
      python3 -m pip install --no-index -f Debugger-rmi-trace/pypkg/dist -f Debugger-agent-gdb/pypkg/dist psutil protobuf

Beware that GDB may embed a different Python interpreter than your system's default. If you are still getting import errors, check the version that GDB embeds:

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

Note the version and ensure that you are invoking Pip with that version. Supposing `sys.version` indicates 3.10, you should invoke Pip using `python3.10 -m pip`.

#### Options

- Image: This is the path to the target binary image (ELF). Ghidra will try to fill this in based on information gathered when the current program was imported. If the file exists and is executable on the local machine, it will be filled in automatically. Otherwise, it is up to you to locate it. NOTE: If you have patched the current program database, these changes are not applied to the target. You can either 1) apply the same patches to the target once it is running, or 2) export a patched copy of your image and direct this launcher to run it.
- Arguments: These are the command-line arguments to pass into the target process. These are passed as is to GDB's "`set args ...`" command.
- `gdb` command: This is the command or path to GDB. We recommend version 13 or later. We require version 8 or later.
- Run command: This is the GDB command to actually launch the target. In most cases this should be "`starti,`" since this will assure you an initial break and a chance to enable your breakpoints.
- Inferior TTY: Depending on your target and/or personal preference, you may opt to separate the debugger's and the target's I/O. If you check this box, the launcher will use GDB's "`set inferior-tty ...`" command to direct the target's I/O to a second Terminal window.

Once running, you are presented with GDB's command-line interface in Ghidra's Terminal. This is the bona fide GDB command-line interface, so it has all the functionality you would expect. If you command GDB from this shell, the plugin will keep Ghidra in sync. The terminal can also be used to interact with the target application when it is running. The plugin provides an additional set of commands for managing the connection to Ghidra, as well as controlling trace synchronization. These are all in the "`ghidra`" command prefix. You can use tab completion to enumerate the available commands and GDB's "`help`" command to examine their documentation.

### GDB via SSH

This works the same as the GDB launcher, but runs `gdb` on a remote system via `ssh`. In contrast to the previous system, which used an SSH library for Java, this launcher uses the `ssh` command on the local system. Thus, it should have broader compatibility with remote systems, and it should use the same configuration files as you are accustomed to. That said, we developed it using OpenSSH, so your experience will be best if your copy understands the same command-line arguments.

#### Setup

You must install GDB and an SSH server onto the target host. Your local SSH client must support remote port forwarding (-R option) and terminal allocation (`-t` option), and the remote server must be configured to permit them.

You will need to manually install the required Python packages on the target host, comprising our plugin for GDB and its dependencies. Copy all of the Python packages from `Ghidra/Debug/Debugger-rmi-trace/pypkg/dist/` and `Ghidra/Debug/Debugger-agent-gdb/pypkg/dist/` to the remote system. It is easiest to put them all in one directory, e.g., `~/ghidra-pypgk/`. Then install them:

-     python3 -m pip install --no-index -f ~/ghidra-pypkg/ ghidragdb

Please see GDB Setup for notes about embedded Python interpreter versions.

#### Options

- Image: This is the path to the target binary image (ELF) on the remote system. Ghidra will try to fill this in based on information gathered when the current program was imported; however, it cannot examine the remote system. If the file exists and is executable on the local machine, it will be filled in automatically. Whether or not it is filled automatically, please ensure the location is correct with respect to the remote system. NOTE: If you have patched the current program database, these changes are not applied to the target. You can either 1) apply the same patches to the target once it is running, or 2) export a patched copy of your image, copy it to the target system, and direct this launcher to run it.
- Arguments: This works the same as in GDB.
- [User@]Host: This is the host name of the target system, optionally including a user name. This is passed as is to `ssh`, which may interpret it according to local configuration.
- Remote Trace RMI Port: An available TCP port on the target system, which will listen for GDB's Trace RMI connection and forward it back to Ghidra.
- Extra `ssh` arguments: These are extra arguments to pass to `ssh`. They are inserted immediately after the `ssh` command but before the host name. Beware that syntax errors may cause strange behavior, and that not all features may be compatible with this launcher.
- `gdb` command: This works the same as in GDB, but with respect to the remote file system.
- Run command: This works the same as in GDB.
- Note there is no option to create a second Terminal (TTY) for the target.

### GDB + `gdbserver` via SSH

This works similarly to the GDB via SSH launcher, but instead of tunneling the Trace RMI connection, tunnels the RSP (`gdbserver`) connection. There is actually a fairly elegant method of doing this straight from within `gdb`, which is exactly what this launcher does:

-     target remote | ssh user@host gdbserver - /path/to/image

This has some advantages compared to running `gdb` on the remote target:

1. GDB may not be available on the remote target.
2. There is no need to install our plugin for GDB on the target.

But, it also has some drawbacks:

1. `gdbserver` must be installed on the remote system, and the local `gdb` must be compatible with it.
2. It may be slightly more annoying to map modules from the remote system, because of the way GDB reports these modules.
3. The memory map may be absent. Though this is overcome by creating an entry for the entire address space, if the map is of interest to your analysis, it may not be available.

#### Setup

You must have GDB installed on the local system and a compatible version of `gdbserver` installed on the target system. You must have an SSH server installed on the target system. It may be worth testing your setup manually (outside of Ghidra) to ensure everything is configured correctly. On the local system, follow the steps given in GDB Setup. There are no additional Python requirements on the target system.

#### Options

- Image: This works the same as in GDB via SSH.
- Arguments: This works the same as in GDB.
- [User@]Host: This works the same as in GDB via SSH.
- Remote Trace RMI Port: An available TCP port on the target system, which will listen for GDB's Trace RMI connection and forward it back to Ghidra.
- Extra `ssh` arguments: This works the same as in GDB via SSH.
- `gdbserver` command: This is the command or path to `gdbserver` with respect to the remote file system.
- Extra `gdbserver` arguments: These are extra arguments to pass to `gdbserver`. They are inserted immediately after `gdbserver` but before the dash. Beware that syntax errors may cause strange behavior, and that not all features may be compatible with this launcher.
- `gdb` command: This works the same as in GDB, with respect to the local file system.
- Note there is no option to create a second Terminal (TTY) for the target.

### QEMU + GDB

This launcher orchestrates a QEMU user-mode target and connects to it using our Python plugin for GDB. Ghidra will inspect the current program and attempt to map its language to the appropriate QEMU command, but this may fail, or be subtly incorrect.

#### Setup

You must acquire a version of QEMU and GDB that support the target architecture. On many distributions of Linux, you can install `gdb-multiarch`. Follow the steps given in GDB Setup.

#### Options

- Image: This is the path to the target binary image (ELF). This works the same as in GDB, but is passed to QEMU. This will also provide the name to GDB using its "`file ...`" command.
- Arguments: These are the command-line arguments to pass into the target process. These are passed as is on QEMU's command line.
- QEMU command: The command or path to QEMU.
- QEMU Port: An available TCP port for QEMU to listen on for GDB.
- Extra `qemu` arguments: Extra arguments to pass to `qemu`. These are inserted immediately after the `qemu` command but before the target program and arguments. Beware that syntax errors may cause strange behavior, and that not all features may be compatible with this launcher.
- `gdb` command: This works the same as in GDB, but defaults to "gdb-multiarch."
- QEMU TTY: This works similarly as in GDB, but just runs QEMU in the second Terminal window.

### Wine + GDB

This launchers runs `wine` in a `gdb` session on Linux and directs it to a target Windows executable. There are other ways to rig a Windows target in GDB on Linux, but this is the method we have chosen. This may prevent GDB from processing the object file, because it is a PE file, and most copies of GDB for UNIX will support only ELF. Nevertheless, Ghidra should recognize the target and map it, giving you symbols and debug info in the front end, even if not in the GDB CLI.

#### Setup

In addition to the steps given in GDB Setup, you must install Wine on your system. Prepare for configuration by locating the actual `wine` executable. These are often in some library directory and named "`wine32`" or "`wine64`." To find them, either examine the file list of the installed package, or dissect the wrapper `wine` script, usually on your path:

-     less $(which wine)

The locations are usually given in variables at the top of the script, e.g., "`/usr/lib/wine/wine64`". One is for 64-bit Windows targets and another is for 32-bit Windows targets. Unlike native Windows, Wine does not (yet) implement WoW64 (Windows on Windows 64). Instead, the 32-bit target is loaded using a 32-bit copy of Wine, and so is serviced by Linux's 32-bit system calls. NOTE: Careful attention must be given to select the correct `wine` executable for the target program's architecture! Even though the `wine` executable is smart enough to correct this mistake, it results in calls to `exec`, which confuse this launcher. If GDB complains that it cannot place breakpoints because of memory access, it is probably because of this mistake.

The launcher loads some additional support packages in our plugin for GDB, e.g., to scan the memory map for PE files and amend the module list. Thus, Ghidra can display both Windows and Linux modules, and map them to its program databases accordingly, despite GDB's inability to process PE files. There are perhaps other configurations of GDB for Linux that can process ELFs as well as PEs loaded by Wine, but they do not seem to be readily available in any popular package repositories.

#### Options

- Image: This is the path to the target binary image (EXE). This works the same as in GDB, but is passed to Wine via GDB's "`set args ...`". This will also provide the name to GDB using its "`file ...`" command.
- Arguments: These are the command-line arguments to pass into the target process. These are included in "`set args ...`".
- Path to `wine` binary: The path to wine for your target architecture. See note above!
- `gdb` command: This works the same as in GDB.
- Inferior TTY: This works the same as in GDB.

### Remote GDB

This launcher can target any TCP-based GDB stub that is compatible with a local copy of `gdb`. Essentially, it just starts `gdb` and then enters

-     target remote [host]:[port]

into it. It is best to test this command outside of Ghidra to be sure everything is compatible before using this launcher. This launcher does not require an image, nor does it create your target. Thus, it can be used without a current program.

#### Setup

On your local system, follow the steps given in GDB Setup. Your version of GDB must be compatible with the stub (e.g., `gdbserver`) on the target system. There are no additional requirements on the target system.

NOTE: The target program image must match that imported in Ghidra, or else things may not map or synchronize correctly.

#### Options

- Target: The type of target. Either `remote` or `remote-extended`, depending on the capabilities of the stub.
- Host: The host name of the target stub.
- Port: The TCP port of the target stub.
- Architecture (optional): If the stub does not describe its architecture to GDB, you must set it before connecting. This is passed as is to "`set arch ...`" immediately before the "`target ...`" command. Enter "`set arch`" into a GDB session outside of Ghidra to see the list of available options in your configuration. You may want to use `gdb-multiarch`.
- `gdb` command: This works the same as in GDB, though you may want to use `gdb-multiarch`.

### Raw GDB

This is hardly a launcher at all. It simply starts `gdb`, gets it connected to Ghidra, and starts a trace. This allows you to create or connect to whatever target your copy of GDB supports. While perhaps the most flexible, it is also the least convenient. It requires no image, so it can be used without a current program. That also means it will make no effort to ensure your target maps to the current program, if you happen to have one. You may have to do it manually.

#### Setup

Follow the steps given in GDB Setup.

#### Options

- `gdb` command: This works the same as in GDB.
- Architecture: Because the trace is created before the target, you must specify the target's architecture. This is passed as is to "`set arch ...`" immediately before the "`target ...`" command. Enter "`set arch`" into a GDB session outside of Ghidra to see the list of available options in your configuration.

## Stock LLDB Launchers

The following launchers based on the LLDB Debugger are included out of the box:

### LLDB

This launcher is a Python plugin for LLDB, and so is well suited for debugging user-space targets on a variety of platforms. It is the de facto debugger for macOS. It can be obtained by installing Xcode from the App Store. Though it may require a bit more careful configuration, it can also be obtained from other repositories like `brew`.

#### Setup

You must have LLDB installed on the local system, and it must embed the Python 3 interpreter. If you have access to PyPI, setting up your Python 3 environment is done using Pip. Please note the version specifier for Protobuf.

-     python3 -m pip install psutil protobuf==3.20.3

If you are offline, or would like to use our provided packages, we still use Pip, but with a more complicated invocation:

-     cd /path/to/ghidra_
      version/Ghidra/Debug
      python3 -m pip install --no-index -f Debugger-rmi-trace/pypkg/dist -f Debugger-agent-lldb/pypkg/dist psutil protobuf

Beware that LLDB may embed a different Python interpreter than your system's default. If you are still getting import errors, check the version that LLDB embeds:

-     (bash)$ lldb
      (lldb) script
      >>> import sys
      >>> sys.version

Note the version and ensure that you are invoking Pip with that version. Supposing `sys.version` indicates 3.10, you should invoke Pip using `python3.10 -m pip`.

#### Options

- Image: This is the path to the target binary image (executable). Ghidra will try to fill this in based on information gathered when the current program was imported. If the file exists and is executable on the local machine, it will be filled in automatically. Otherwise, it is up to you to locate it. NOTE: If you have patched the current program database, these changes are not applied to the target. You can either 1) apply the same patches to the target once it is running, or 2) export a patched copy of your image and direct this launcher to run it.
- Arguments: These are the command-line arguments to pass into the target. These are passed as is to LLDB's "`settings set target.run-args ...`" command.
- `lldb` command: This is the command or path to LLDB. We recommend version 15 or later.
- Run command: This is the LLDB command to actually launch the target. In most cases this should include "`--stop-at-entry`", since this will assure you an initial break and a chance to enable your breakpoints.
- Target TTY: Depending on your target and/or personal preference, you may opt to separate the debugger's and the target's I/O. If you check this box, the launcher will use LLDB's "`setting set target.output-path ...`" command (and similar for the input) to direct the target's I/O to a second Terminal window.

Once running, you are presented with LLDB's command-line interface in Ghidra's Terminal. This is the bona fide LLDB command-line interface, so it has all the functionality you would expect. If you command LLDB from this shell, the plugin will keep Ghidra in sync. The terminal can be used to interact with the target application when it is running. The plugin provides an additional set of commands for managing the connection to Ghidra, as well as controlling trace synchronization. These are all in the "`ghidra`" category. You can use tab completion to enumerate the available commands and LLDB's "`help`" command to examine their documentation.

### Remote LLDB

This launcher can target any TCP-based GDB stub that is compatible with a local copy of `lldb`. Essentially, it just starts `lldb` and then enters

-     gdb-remote [host]:[port]

into it. It is best to test this command outside of Ghidra to be sure everything is compatible before using this launcher. This launcher does not require an image, nor does it create your target. Thus, it can be used without a current program.

#### Setup

On your local system, follow the steps given in LLDB Setup. Your version of LLDB must be compatible with the stub (e.g., `gdbserver`) on the target system. There are no additional requirements on the target system.

NOTE: The target program image must match that imported in Ghidra, or else things may not map or synchronize correctly.

#### Options

- Host: The host name of the target stub.
- Port: The TCP port of the target stub.
- Architecture (optional): If the stub does not describe its architecture to GDB, you must set it before connecting. This is passed as is to "`setting set target.default-arch ...`" immediately before the "`gdb-remote ...`" command.
- `lldb` command: This works the same as in LLDB.

## Stock Windows Debugger (WinDbg) Launchers

The following launchers based on Microsoft's `dbgeng.dll` are included out of the box:

### dbgeng

This launcher is actually a Python implementation of a console debugger based on `dbgeng.dll`. This DLL represents the Microsoft Windows Debugger engine, and so is best suited for debugging Windows user-space targets. Windows kernel targets are not yet supported. This DLL also backs WinDbg and several other debuggers on Windows. By default, the launcher will search for this DLL in an installation of the Windows Debugging Kits version 10. If it does not find it there, it will probably crash with a message in the Terminal.

Please note on some system configurations, one of the debugger's dependencies `dbghelp.dll` may get loaded from the system directory instead of from the WinDbg installation, usually because a security product has pre-loaded it into the Python process. You might work around this by copying the affected DLLs from your WinDbg installation into your Python installation.

#### Setup

Installing WinDbg is highly recommended. If you wish to forego installing WinDbg, you can use the DLL provided with Windows, which is substantially less capable, by manually pointing this connector to `C:\Windows\system32`. If you do this, some commands, e.g. `.server`, will not be available.

If you have access to PyPI, setting up your Python 3 environment is done using Pip. Please note the version specifier for Protobuf.

-     python3 -m pip install pybag protobuf==3.20.3

If you are offline, or would like to use our provided packages, we still use Pip, but with a more complicated invocation:

-     cd C:\path\to\ghidra_
      version\Ghidra\Debug
      python3 -m pip install --no-index -f Debugger-rmi-trace\pypkg\dist -f Debugger-agent-dbgeng\pypkg\dist pybag protobuf

If you get an import error regarding `distutils`, it is due to a transitive dependency on a buggy version of `capstone`. Work around it by installing `setuptools`.

#### Options

- `python` command: This is the command or path to the Python interpreter. It must be version 3. Python 2 is not supported.
- Image: This is the path to the target binary image (EXE file). Ghidra will try to fill this in based on information gathered when the current program was imported. If the file exists and is executable on the local machine, it will be filled in automatically. Otherwise, it is up to you to locate it. NOTE: If you have patched the current program database, these changes are not applied to the target. You can either 1) apply the same patches to the target once it is running, or 2) export a patched copy of your image and direct this launcher to run it.
- Arguments: These are the command-line arguments to pass into the target process. These are passed as is into WinDbg's "`CreateProcess`" function.
- Use `dbgmodel`: If `dbgmodel.dll` is available on the system, this launcher will use it to populate the trace's object model. Without that DLL, the launcher will invent its own model, roughly approximating the same, using just the information available from `dbgeng.dll`. Disabling this option will prevent the launcher from using `dbgmodel.dll`, even when it is available.
- Path to `dbgeng.dll` directory: By default, the launcher allows the underlying `pybag` package to locate the Windows Debugger DLLs. This is typically found by examining the registry for a Windows Kits 10 installation. Otherwise, it may check its typical installation directory. This will not search the Windows system directory, but you can configure it manually here. This option allows you to override this search. For example, if you have installed WinDbg Preview or later from the Microsoft Store and wish to use its DLLs, you will need to fill in this option.

Once running, you are presented with a command-line interface in Ghidra's Terminal. This CLI accepts your usual WinDbg (kd) commands. You can escape from this CLI and enter a Python 3 REPL by entering "`.exit`". This is not an actual kd command, but our implementation understands this to mean exit the kd REPL. From the Python 3 REPL, you can access the underlying Python-based API `pybag`. This is an uncommon need, but may be useful for diagnostics and/or workarounds. To re-enter the kd REPL, enter "`repl()`". Alternatively, if you are trying to quit, but typed "`.exit`", just type "`quit()`" to terminate the session.

### dbgeng-ext

This launcher extends the base dbgeng launcher adding extra options (a la IDebugClient's CreateProcess2).

#### Options

- Dir: This is the starting directory for the process.
- Env: This is a composite string containg Environment Variable entries delineated by '/0' separators. For example, you could redefine USERNAME and USERPROFILE with the entry 'USERNAME=SomeUser/0USERPROFILE=C:\Users\SomeUser'.
- CreateFlags: Flags used when creating the process, typically either DEBUG_PROCESS(1) or DEBUG_ONLY_THIS_PROCESS(2) if you do not wish to follow spawned processes. Other possible values are defined by processes.h's CreateProcessCreationFlags.
- CreateFlags (Engine): Engine-specific flags used when creating the process (defined in dbgeng.h). Typically, these are set to 0.
- VerifierFlags (Engine): Flags used by the Application Verifier. Typically unused, but, if desired, CreateEngineFlags must include DEBUG_ECREATE_PROCESS_USE_VERIFIER_FLAGS(2).

### dbgeng-attach

This launcher allows the user to attach to a local running process. Options are the same as those for the base dbgeng, except for ProcessId and AttachFlags

#### Options

- ProcessId: The pid of the process you wish to attach to.
- AttachFlags: Flags used when attaching to the target process, typically DEBUG_ATTACH_PROCESS(0). Other possible values are defined in dbgeng.h and determine whether the attach should be invasive or not and the status of the process after attaching.

### dbgeng-remote

This launcher extends the base dbgeng launcher adding an option for connecting through a remote process server.

#### Options

- Connection: This is the connection string specifying the transport options for communicating with the remote server. A typical example might be 'tcp:port=12345,server=192.168.0.2'' for a process server launched on the machine at 192.168.0.2 using:

      dbgsrv -t tcp:port=12345

### dbgeng-kernel

This version of the dbgeng should be used for kernel-debugging of a remote machine. Options are the same as the base dbgeng, except for the connection-string arguments. For remote debugging, the target machine should be booted with the appropriate options, set using BCDEDIT or the equivalent, such as:

-     bcdedit /debug ON
      bdcedit /dbgsettings NET HOSTIP:IP PORT:54321 KEY:1.1.1.1

where IP= the address of the machine runing Ghidra.

#### Options

- Arguments: This is the connection string specifying the transport options for communicating with the remote target. A typical example might be 'net:port=54321,key=1.1.1.1'.'

### TTD (Time-Travel Debugging)

This is a nascent extension to our launcher for the Windows Debugger. The launcher itself functions well, but lacks full integration. It is not yet properly packaged for the Ghidra distribution, but is available in development environments. It also needs some additional protocol support, namely to integrate its notion of time travel with Ghidra's notion. For the time being, we map our time specifications as follows. MS TTD uses a tuple for its time specs, both displayed in hexadecimal, e.g., "B5:1A". The first is the "major," which we believe counts the events that warrant a snapshot. The second is the "minor," which we believe counts instructions executed since the major event. Thus, we would like to map the major to a Ghidra trace snapshot and the minor to steps of p-code emulation. For example, the "B5:1A" notation would map to "181:26". It should be no surprise the notations are similar, since both MS TTD and Ghidra (as well as several other "timeless" debuggers) use a snapshot-replay strategy to recover past machine states. However, we have not yet worked out how to have Ghidra cooperate with a back end in the replay part of this strategy. Currently, Ghidra will always apply p-code emulation, despite having a perfectly good and performant back end available. So, for the time being, we multiply the major number by 1000, thus reserving that many Ghidra snapshots between major events for MS TTD minor steps. Thus, the notation "B5:1A" will actually map to "181026", that is snapshot 181026 with no steps of p-code emulation. This hack will fall short if you visit a time where the minor number exceeds 999.

Furthermore, if you use the Ghidra Debugger UI to visit a past snapshot, the back end is not yet informed of your intent. You will probably only see stale records of the machine state. Instead, please use the kd commands from the Terminal to navigate through time. The back end (MS TTD) will perform the replay, record the snapshot, and command Ghidra to navigate there.

#### Options

This launcher has the same options as the WinDbg launcher, except that the DLL path must contain `dbgmodel.dll` and the scripts that implement TTD. These are most easily obtained by installing WinDbg Preview or later.

## Development and Diagnostic Launchers

We currently provide one launcher for Trace RMI API exploration and development:

### Raw Python

This launcher runs Python in a Terminal window, connects a Trace RMI client back to Ghidra, then starts a blank trace. Once running, it presents the Python interpreter, with the `ghidratrace` and `ghidratrace.client` packages imported into the local namespace. Thus, a developer can explore the API, invoke methods, and observer how Ghidra reacts.

#### Setup

If you have access to PyPI, setting up your Python 3 environment is done using Pip. Please note the version specifier for Protobuf.

-     python3 -m pip install protobuf==3.20.3

If you are offline, or would like to use our provided packages, we still use Pip, but with a more complicated invocation:

-     cd /path/to/ghidra_
      version/Ghidra/Debug
      python3 -m pip install --no-index -f Debugger-rmi-trace/pypkg/dist protobuf

#### Options

- `python` command: This is the command or path to `python` version 3. Python 2 is not supported.
- Ghidra Language: The LanguageID for the blank trace.
- Ghidra Compiler: The CompilerSpecID for the blank trace.