diff --git a/docs/guide/remote-debugging.md b/docs/guide/remote-debugging.md index 174ecb5..9e84215 100644 --- a/docs/guide/remote-debugging.md +++ b/docs/guide/remote-debugging.md @@ -2,9 +2,9 @@ ## Support Status -Right now, we support Windows remote debugging from Windows, and Linux/macOS remote debugging from all platforms. Remote debugging of Windows executable from Linux/macOS is a planned feature. +We currently support Windows remote debugging from Windows and Linux/macOS remote debugging from all platforms. Remote debugging of Windows executables from Linux/macOS is a planned feature. -We also support gdbserver/lldb-server remote debugging from all platforms. Currently, the gdbserver support is limited to remote android debugging, and support for other targets, e.g., qiling, VMWare, QEMU, etc., will be added later. +We also support gdbserver/lldb-server remote debugging from all platforms. | Target 🔽 Host ▶️ | macOS | Linux | Windows | |-----------------------|---------|---------|---------| @@ -16,175 +16,225 @@ We also support gdbserver/lldb-server remote debugging from all platforms. Curre ## Debug Server v.s. Remote Process -There are two types of remote debugging, i.e, via a `debug server`, or a `remote process`. +There are two types of remote debugging: via a `debug server` or a `remote process`. -A remote process is straight-forward -- it is a process that runs on the remote host. The debugger connects to it and then debugs it. If you have used `gdbserver` or `debugserver` previously, you probably already know about it. +A remote process is straightforward -- it is a process that runs on the remote host. The debugger connects to it and then debugs it. If you have used `gdbserver` or `debugserver` previously, you probably already know about it. -A debug server is a server that runs on the remote host. The debugger connects to it and can instruct the debug server to launch a proces as needed. Then the debugger can connect to the running process and debug it. -One advantage of using a debug server is that the user does not need to access the remote host to launch the target repeately -- it can be done within the debugger. +A debug server is a server that runs on the remote host. The debugger connects to it and can instruct the debug server to launch a process as needed. Then the debugger can connect to the running process and debug it. +One advantage of using a debug server is that the user does not need to access the remote host to launch the target repeatedly—this can be done within the debugger. Moreover, a debug server often offers more functionalities than launching a remote process. For example, the `lldb-server` supports reading and writing the remote file system, as well as executing shell commands on the remote host. -We recommend using debug server whenever possible and only use the remote process as a backup. +We recommend using a debug server whenever possible and only use the remote process as a backup. For now, `DbgEng` adapter supports debug server, and `LLDB` adapter supports both debug server and remote process. -## Preparing Remote Host +## Windows Remote Debugging -### Windows +This section explains how to remotely debug a process running on Windows. Right now this is only possible to do from +another Windows machine. We know this is a highly useful feature to be able to do so from Linux or macOS, and please +feel free to track our progress: +[issue 1](https://github.com/Vector35/debugger/issues/70), [issue 2](https://github.com/Vector35/debugger/issues/613). -- Download and extract [debugger-win32.zip](https://github.com/Vector35/debugger/releases/download/1.0/debugger-win32.zip) -- Find the `plugins/dbgeng` folder in it -- If you wish to debug a x64 program, copy the `amd64` folder to the remote host. -- If you wish to debug a x86 program, copy the `x86` folder to the remote host. -- There should be a `dbgsrv.exe` folder you just copied. +### Preparing the Remote Host -### macOS +- Download or copy [debugger-win32.zip](https://github.com/Vector35/debugger/releases/download/1.0/debugger-win32.zip) + to the remote host +- Extract it -- Download and extract [debugger-darwin.zip](https://github.com/Vector35/debugger/releases/download/1.0/debugger-darwin.zip). -- Find the `lldb` folder at `debugger-darwin/plugins/lldb` and copy it to the remote host. -- Note, the entire lldb folder must be copied. Only copying the `lldb-server` or `debugserver` executable does not work. +### Launching the Debug Server -### Linux +To start a remote debugging session, launch the `dbgsrv.exe` on the remote machine as described below: -There are two ways to prepare a Linux remote host, i.e., using lldb-server (recommended) or using gdbserver. +- Determine whether the target program is x64 or x86 + - If the target is x64, then use the `dbgsrv.exe` in `debugger-win32\plugins\dbgeng\amd64` + - If the target is x86, then use the `dbgsrv.exe` in `debugger-win32\plugins\dbgeng\x86` + - If the version of `dbgsrv.exe` does not match the program, the debugger will behave unexpectedly +- Launch the dbgsrv by running `dbgsrv.exe -t tcp:port=,server=` + - `IP_ADDRESS:PORT` is the IP and port the Binary Ninja will later connect to + - For example, `dbgsrv.exe -t tcp:port=12345,server=192.168.72.25` + - Note, the `server=` part cannot be omitted. +- If this is done for the first time, the Windows firewall will pop up a confirmation dialog. Allow the operation. +- If the operation succeeds, the `dbgsrv.exe` will keep running in the background. If any error occurs, it will show a + message box. +- If the target program requires Administrative privilege to run, run `dbgsrv.exe` from a command prompt with + Administrative privilege -#### lldb-server (recommended) -- Download and extract [debugger-linux.zip](https://github.com/Vector35/debugger/releases/download/1.0/debugger-linux.zip). -- Find the `lldb` folder at `debugger-linux/plugins/lldb` and copy it to the remote host. -- Note, the entire lldb folder must be copied. Only copying the `lldb-server` executable does not work. -- One can also use the `lldb-server` or `gdbserver` that comes with the host system's Linux distribution. However, that might cause compatability issues. +### Connecting to the Debug Server -#### gdbserver +Now, connect to a debug server in Binary Ninja using DbgEng adapter. -Install the `gdb` using the system package manager, e.g., `sudo apt install gdbserver`. +- Open the binary you wish to debug +- Click "Debugger" -> "Connect to Debug Server" in the main window menu bar +- In the dialog, type in the IP and port to connect to: -### iOS +![](../../img/debugger/debugserver.png) + +- Click `Accept`. A message box will show up if the connection is successful -Setting up an iOS device or emulator for debugging is challenging. A step-by-step guide is out of scope here. We assume the user is familiar with the setup, or already having a proper setup that works with lldb. +Now you can launch or connect to a process on the remote host. It works similarly as if you launch or attach to +a process locally. -We will provide a detailed guide on this later. +### Launching a Process on the Remote Host -The high level steps are: +- Click "Debugger" -> "Debug Adapter Settings..." in the main window menu bar -- Extract the `debugserver` executable from the developer disk image that comes with the XCode. -- Sign it with a proper entitlements plist to enable it to debug all processes. -- Upload the signed debugserver to the remote system. +![](../../img/debugger/remoteadaptersettings.png) -### Android +- Specify the executable path and working directory on the remote machine. This is likely different from the local path + which is shown by default +- Launch the target -Setting up an Android device or emulator for debugging requires a few steps. A step-by-step guide is out of scope here. We assume the user is familiar with the setup, or already having a proper setup that works with gdb. +### Attaching to a Process on the Remote Host -We will provide a detailed guide on this later. +- Click "Debugger" -> "Attach To Process..." in the menu bar +- Select the process to attach to +- If the process is not listed, you might need to run `dbgsrv.exe` with Administrator privilege +- Click "Attach" to attach to the process and start debugging -The high level steps are: +When connected to the debug server, the debugger can launch or connect to a process multiple times using the same +connection. There is no need to relaunch and reconnect to the debug server after the target exits. -- Install the Android NDK -- Find the `gdbserver` or `gdbserver64` executable in NDK -- Upload it to the remote host +To disconnect from the debug server, click "Debugger" -> "Disconnect from Debug Server". After that, if we launch the +target, it will execute on the local machine. Be careful! -## Launching the Debug Server or Remote Process +## Linux Remote Debugging (Using Debug Server) -### Windows +This section explains how to remotely debug a process running on Linux. This can be done from all platforms, i.e., +Windows, Linux, and macOS. -To start a remote debugging session, first launch the `dbgsrv.exe` on the remote machine. +There are two ways to do Linux remote debugging, i.e., using a debug server or a remote process. Debug server is the +recommended way. However, if it does not work for you, you can try using the remote process approach or using +`gdbserver`, which are documented later. -- First determine whether the target is x64 or x86. If the target is x64, then use the `dbgsrv.exe` in the x64 DbgEng installation folder. If the target is x86, then use the `dbgsrv.exe` in the x86 DbgEng installation folder. If the version of `dbgsrv.exe` does not match the target, the debugger will behave unexpectedly. -- Launch the dbgsrv by running `dbgsrv.exe -t tcp:port=,server=`, where `IP_ADDRESS:PORT` is the IP and port the Binary Ninja will connect to. For example, `dbgsrv.exe -t tcp:port=12345,server=192.168.72.25`. Note, the `server=` part cannot be omitted. -- If this is done for the first time, the Window firewall will pop up a confirmation dialog. Allow the operation. -- If the operation succeeds, the `dbgsrv.exe` will keep running in the background. If any error occurs, it will show a message box. +### Preparing the Remote Host -### macOS +- Download or copy [debugger-linux.zip](https://github.com/Vector35/debugger/releases/download/1.0/debugger-linux.zip) + to the remote host +- Extract it +- One can also use the `lldb-server` that can be installed via a package manager. However, it may have compatibility + issues. -#### Debug Server +### Launching the Debug Server -- cd debugger-darwin/plugins/lldb -- ./lldb-server p --server --listen 0.0.0.0:31337 +- `cd debugger-linux/plugins/lldb` +- `./lldb-server p --server --listen 0.0.0.0:31337` -Specifying `0.0.0.0` instructs lldb-server to listen on all interfaces. You can also specify a particular IP address of an interface. +Specifying `0.0.0.0` instructs lldb-server to listen on all interfaces. You can also specify a particular IP address of +an interface that the Binary Ninja debugger will later connect to. -#### Remote Process -- cd debugger-darwin/plugins/lldb -- To launch a new process, run `./debugserver 0.0.0.0:31337 /path/to/helloworld foo bar`, where `/path/to/helloworld` is the path of the executable, and `foo bar` are two arguments. -- To attach to a running process by PID, run `./debugserver 0.0.0.0:31337 --attach=1234`, where `1234` is the PID of the target process. +### Connecting to the Debug Server +- Open the binary you wish to debug +- Click "Debugger" -> "Connect to Debug Server" in the main window menu bar +- In the dialog, type in the IP and port to connect to: -### Linux +![](../../img/debugger/debugserver-lldb.png) -#### Debug Server (LLDB) +- There is a `Platform` dropdown menu. Select `remote-linux` in it -- cd debugger-linux/plugins/lldb -- ./lldb-server p --server --listen 0.0.0.0:31337 +![](../../img/debugger/platform-list.png) -Specifying `0.0.0.0` instructs lldb-server to listen on all interfaces. You can also specify a particular IP address of an interface. +- Click `Accept`. A message box will show up if the connection is successful. -#### Remote Process (LLDB) +### Launching a Process on the Remote Host -- cd debugger-linux/plugins/lldb -- To launch a new process, run `./lldb-server g 0.0.0.0:31337 -- /path/to/helloworld foo bar`, where `/path/to/helloworld` is the path of the executable, and `foo bar` are two arguments. -- To attach to a running process by PID, run `./lldb-server g 0.0.0.0:31337 --attach 1234`, where `1234` is the PID of the target process. +- Open the `Debug Adapter Settings` dialog +- Set the `Working Directory` to the *remote* directory that you wish to launch the process in. Do not leave the path + unchanged since it will then be a local path, and there will be an error during launch. +- Do NOT change the `Executable Path` to a remote path. Set it to the local path where the executable is in. During + launch, LLDB will copy the executable to the remote host, put it in the working directory we supplied above, and + launch it. Setting a remote path here will cause errors. LLDB is smart enough to check the hash of the file so that it + will only copy the file once. +- Launch the target -#### Debug Server (GDB) +### Attaching to a Process on the Remote Host -`gdbserver` can work as a debug server as well. +- Click "Debugger" -> "Attach To Process..." in the menu bar +- Select the process to attach to +- If the process is not listed, you might need to run `lldb-server` with sudo +- Click "Attach" to attach to the process -- gdbserver --multi 0.0.0.0:31337 +When connected to the debug server, the debugger can launch the executable multiple times using the same connection. There is no need to relaunch and reconnect to the debug server after the target exits. -#### Remote Process (GDB) +To disconnect from the debug server, click "Debugger" -> "Disconnect from Debug Server". After that, if we launch the target, it will execute on the local machine. Be careful! -One can also use `gdbserver` to launch or attach to a remote process. Since the version of gdbserver varies, there might be compatability issues, though. -- To launch a new process, run `gdbserver 0.0.0.0:31337 -- /path/to/helloworld foo bar`, where `/path/to/helloworld` is the path of the executable, and `foo bar` are two arguments. -- To attach to a running process by PID, run `gdbserver 0.0.0.0:31337 --attach 1234`, where `1234` is the PID of the target process. +## Linux Remote Debugging (using Remote Process) -### iOS +If the debug server does not work, you can try Linux remote debugging via the remote process approach. This uses +`lldb-server` in GDB mode and might be simpler to configure. -- ssh into the remote host -- To launch a new process, run `./debugserver 0.0.0.0:31337 /path/to/helloworld foo bar`, where `/path/to/helloworld` is the path of the executable, and `foo bar` are two arguments. -- To attach to a running process by PID, run `./debugserver 0.0.0.0:31337 --attach=1234`, where `1234` is the PID of the target process. -- Targets launched/attached by `debugserver` are considered remote process. Follow the `Connecting to a Remote Process` section to connect to it. +### Preparing the Remote Host -### Android +- Download or copy [debugger-linux.zip](https://github.com/Vector35/debugger/releases/download/1.0/debugger-linux.zip) + to the remote host +- Extract it +- One can also use the `lldb-server` that can be installed via a package manager. However, it may have compatibility + issues. -- ssh into the remote host -- To launch a new process, run `gdbserver 0.0.0.0:31337 -- /path/to/helloworld foo bar`, where `/path/to/helloworld` is the path of the executable, and `foo bar` are two arguments. -- To attach to a running process by PID, run `gdbserver 0.0.0.0:31337 --attach 1234`, where `1234` is the PID of the target process. -- Targets launched/attached by `gdbserver` are considered remote process. Follow the `Connecting to a Remote Process` section to connect to it. +### Launching or Attaching to a Remote Process +- `cd debugger-linux/plugins/lldb` +- To launch a new process, run `./lldb-server g 0.0.0.0:31337 -- /path/to/helloworld foo bar` + - `/path/to/helloworld` is the path of the executable + - `foo bar` are two arguments +- To attach to a running process by PID, run `./lldb-server g 0.0.0.0:31337 --attach 1234` + - `1234` is the PID of the target process +Specifying `0.0.0.0` instructs lldb-server to listen on all interfaces. You can also specify a particular IP address of +an interface that the Binary Ninja debugger will later connect to. -## Connecting to a Debug Server (DBGENG Adapter) -Now, connect to a debug server in Binary Ninja using DbgEng adapter. +### Connecting to the Remote Process - Open the binary you wish to debug -- Click "Debugger" -> "Connect to Debug Server" in the main window menu bar +- Click "Debugger" -> "Connect to Remote Process" in the main window menu bar - In the dialog, type in the IP and port to connect to: -![](../../img/debugger/debugserver.png) +![](../../img/debugger/remoteprocess.png) -- Click `Accept`. A message box will show up if the connection is successful. -- Now one can launch the target in the same way as local debugging. However, since the path of the executable on the remote machine is very likely to be different from the path on the local machine. We need to specify its path. -- Click "Debugger" -> "Launch/Connect Settings" in the main window menu bar +- For the `Plugin` dropdown menu, select `gdb-remote` accordingly. +- Click `Accept`. +- The debugger will now connect to the process launched or attached to in the previous step and start debugging -![](../../img/debugger/remoteadaptersettings.png) +When using the remote process mode, when the debugging stops (the target exits or gets killed), the connection is +automatically closed. There is no extra steps needed to close the connection. -- Specify the executable path on the remote machine -- Launch the target +If you wish to debug the target again, you will need to repeat the steps above to launch or attach to a remote process. -One can also attach to a process running on the remote machine via its PID. In that case, there is no need to specify the executable path. -When connected to the debug server, the debugger can launch the executable multiple times using the same connection. There is no need to relaunch and reconnect to the debug server after the target exits. -To disconnect from the debug server, click "Debugger" -> "Disconnect from Debug Server". After that, if we launch the target, it will execute on the local machine. Be careful! -## Connecting to a Debug Server (LLDB Adapter) +## MacOS Remote Debugging (Using Debug Server) -Connecting to a debug server using LLDB adapter is slightly different from using DbgEng adapter. +This section explains how to remotely debug a process running on MacOS. This can be done from all platforms, i.e., +Windows, Linux, and macOS. + +There are two ways to do MacOS remote debugging, i.e., using a debug server or a remote process. Debug server is the +recommended way. However, if it does not work for you, you can try using the remote process approach documented below. + +### Preparing the Remote Host + +- Download or copy [debugger-darwin.zip](https://github.com/Vector35/debugger/releases/download/1.0/debugger-darwin.zip) + to the remote host +- Extract it + + +### Launching the Debug Server + +- `cd debugger-darwin/plugins/lldb` +- `./lldb-server p --server --listen 0.0.0.0:31337` + +Specifying `0.0.0.0` instructs lldb-server to listen on all interfaces. You can also specify a particular IP address of +an interface that Binary Ninja debugger will later connect to. + + +### Connecting to the Debug Server - Open the binary you wish to debug - Click "Debugger" -> "Connect to Debug Server" in the main window menu bar @@ -192,19 +242,29 @@ Connecting to a debug server using LLDB adapter is slightly different from using ![](../../img/debugger/debugserver-lldb.png) -- There is a `Platform` dropdown menu. We need to select an appropriate platform so that LLDB can work properly: +- There is a `Platform` dropdown menu. Select `remote-macos` in it ![](../../img/debugger/platform-list.png) -If the remote host is a macOS system, select `remote-macosx`. If the remote host is a Linux system, select `remote-linux`. If the remote host is a gdbserver with `--multi` command line option, select `remote-gdb-server`. Note, despite that there exists an `remote-windows` entry, LLDB's debug server does not work on Windows at the moment. +- Click `Accept`. A message box will show up if the connection is successful. +### Launching a Process on the Remote Host -- Click `Accept`. A message box will show up if the connection is successful. -- Open the `Debug Adapter Settings` dialog, and set the `Working Directory` to the *remote* directory that you wish to launch the process in. Do not leave the path unchanged since it will then be a local path, and there will be an error during launch. -- Do NOT change the `Executable Path` to a remote path. Set it to the local path where the executable is in. During launch, LLDB will copy the executable to the remote host, put it in the working directory we supplied above, and launch it. Setting a remote path here will cause errors. LLDB is smart enough to check the hash of the file so that it will only copy the file once. +- Open the `Debug Adapter Settings` dialog +- Set the `Working Directory` to the *remote* directory that you wish to launch the process in. Do not leave the path + unchanged since it will then be a local path, and there will be an error during launch. +- Do NOT change the `Executable Path` to a remote path. Set it to the local path where the executable is in. During + launch, LLDB will copy the executable to the remote host, put it in the working directory we supplied above, and + launch it. Setting a remote path here will cause errors. LLDB is smart enough to check the hash of the file so that it + will only copy the file once. - Launch the target -One can also attach to a process running on the remote machine via its PID. In that case, there is no need to change the current working directory. +### Attaching to a Process on the Remote Host + +- Click "Debugger" -> "Attach To Process..." in the menu bar +- Select the process to attach to +- If the process is not listed, you might need to run `lldb-server` with sudo +- Click "Attach" to attach to the process When connected to the debug server, the debugger can launch the executable multiple times using the same connection. There is no need to relaunch and reconnect to the debug server after the target exits. @@ -212,13 +272,174 @@ To disconnect from the debug server, click "Debugger" -> "Disconnect from Debug -## Connecting to a Remote Process +## macOS Remote Debugging (using Remote Process) + +If the debug server does not work, you can try macOS remote debugging via the remote process approach. This uses +`lldb-server` in GDB mode and might be simpler to configure. + +### Preparing the Remote Host + +- Download or copy [debugger-darwin.zip](https://github.com/Vector35/debugger/releases/download/1.0/debugger-darwin.zip) + to the remote host +- Extract it +- One can also use the `lldb-server` that can be installed via a package manager. However, it may have compatibility + issues. + +### Launching or Attaching to a Remote Process + +- `cd debugger-darwin/plugins/lldb` +- To launch a new process, run `./lldb-server g 0.0.0.0:31337 -- /path/to/helloworld foo bar` + - `/path/to/helloworld` is the path of the executable + - `foo bar` are two arguments +- To attach to a running process by PID, run `./lldb-server g 0.0.0.0:31337 --attach 1234` + - `1234` is the PID of the target process + +Specifying `0.0.0.0` instructs lldb-server to listen on all interfaces. You can also specify a particular IP address of +an interface that the Binary Ninja debugger will later connect to. + + +### Connecting to the Remote Process - Open the binary you wish to debug -- Click "Debugger" -> "Connect to Debug Server" in the main window menu bar +- Click "Debugger" -> "Connect to Remote Process" in the main window menu bar - In the dialog, type in the IP and port to connect to: ![](../../img/debugger/remoteprocess.png) -- For the `Plugin` dropdown menu, select `gdb-remote` or `debugserver/lldb` accordingly. -- Click `Accept`. \ No newline at end of file +- For the `Plugin` dropdown menu, select `gdb-remote` accordingly. +- Click `Accept`. +- The debugger will now connect to the process launched or attached to in the previous step and start debugging + +When using the remote process mode, when the debugging stops (the target exits or gets killed), the connection is +automatically closed. There is no extra steps needed to close the connection. + +If you wish to debug the target again, you will need to repeat the steps above to launch or attach to a remote process. + + + +## GDB Server Remote Debugging + +GDB server is a widely used mechanism for remote debugging. On Linux systems, there is a `gdbserver` executable that can +be installed and executed. Many other projects, e.g., QEMU, also include a gdb stub that speaks the same protocol. + +Please note that although the "GDB server" has a "server" in its name, normally it operates as a remote process. In other +words, the debugging is one-shot, that when the target exits, the connection gets closed. If you wish to debug it +again, you need to start the GDB server again. + +### Launching GDB Server + +- On Linux, to launch a new process, run `gdbserver 0.0.0.0:31337 -- /path/to/helloworld foo bar` + - `/path/to/helloworld` is the path of the executable + - `foo bar` are two arguments +- On Linux, to attach to a running process by PID, run `gdbserver 0.0.0.0:31337 --attach 1234` + - `1234` is the PID of the target process +- For QEMU, add `-s -S` to the command line + - For example, `qemu-system-x86_64 -drive file=disk.img,format=raw -bios bios.bin -s -S` + - `-s` starts QEMU with a GDB server listening on TCP port 1234 + - `-S` starts QEMU in a paused state, allowing you to connect with GDB before the virtual CPU starts executing + - You can specify a different port to listen on by replacing `-s` with `-gdb tcp::port` +- For other tools that also speak the GDB remote debugging protocol, please refer to their documentation on how to + configure it + + +### Connecting to GDB Server + +- Open the binary you wish to debug +- Click "Debugger" -> "Connect to Remote Process" in the main window menu bar +- In the dialog, type in the IP and port to connect to: + +![](../../img/debugger/remoteprocess.png) + +- For the `Plugin` dropdown menu, select `gdb-remote` accordingly. +- Click `Accept`. +- The debugger will now connect to the process launched or attached to in the previous step and start debugging + +Recent versions of the GDB server also support a debug server mode, which can be active using +`gdbserver --multi 0.0.0.0:31337`. However, the Binary Ninja debugger does not yet support connecting to the GDB server in +this mode. + + + + +## iOS Remote Debugging + +Binary Ninja debugger supports debugging an iOS app running on a real device or an emulator. The process is +similar to macOS remote debugging, except that we need to run `debugserver` on the device rather than `lldb-server`. + +### Preparation + +Setting up an iOS device or emulator for debugging is challenging. A step-by-step guide is out of scope here. +We assume the user can already debug an iOS app using the LLDB command line and wish to debug it within the Binary Ninja +debugger. + +The high-level steps are: + +- Get SSH access to the device. This can be done by either jailbreaking the device or using an emulator +- Extract the `debugserver` executable from the developer disk image that comes with the XCode +- Sign it with a proper entitlements plist to enable it to debug all processes +- Upload the signed `debugserver` to the remote system + + +### Launching or Attaching to the target + +- SSH into the remote host +- To launch a new process, run `./debugserver 0.0.0.0:31337 /path/to/helloworld foo bar` + - `/path/to/helloworld` is the path of the executable + - `foo bar` are two arguments +- To attach to a running process by PID, run `./debugserver 0.0.0.0:31337 --attach=1234` + - `1234` is the PID of the target process + + +### Connecting to the target + +- Open the binary you wish to debug +- Click "Debugger" -> "Connect to Debug Server" in the main window menu bar +- In the dialog, type in the IP and port entered in the previous step: + +![](../../img/debugger/remoteprocess.png) + +- For the `Plugin` dropdown menu, select `debugserver/lldb` +- Click `Accept`. + + + + +## Android Remote Debugging + +Binary Ninja debugger supports debugging an Android app running on a real device or an emulator. The process is +similar to GDB server remote debugging. + +### Preparation + +Setting up an Android device or emulator for debugging requires a few steps. A step-by-step guide is out of scope here. +We assume the user can already debug an Android app using the GDB command line and wish to debug it within the Binary +Ninja debugger. + +The high-level steps are: + +- Get SSH access to the device. This can be done by either rooting a real device or using an emulator +- Install the Android NDK on your computer +- Find the `gdbserver` or `gdbserver64` executable in NDK +- Upload it to the remote host + + +### Launching or Attaching to the target + +- SSH into the remote host +- To launch a new process, run `gdbserver 0.0.0.0:31337 -- /path/to/helloworld foo bar` + - `/path/to/helloworld` is the path of the executable + - `foo bar` are two arguments +- To attach to a running process by PID, run `gdbserver 0.0.0.0:31337 --attach 1234` + - `1234` is the PID of the target process + + +### Connecting to the target + +- Open the binary you wish to debug +- Click "Debugger" -> "Connect to Debug Server" in the main window menu bar +- In the dialog, type in the IP and port entered in the previous step: + +![](../../img/debugger/remoteprocess.png) + +- For the `Plugin` dropdown menu, select `gdb-remote` +- Click `Accept`.