Skip to content

Commit 8111cb4

Browse files
xusheng6xusheng6
committed
Update debugger docs
1 parent ff91629 commit 8111cb4

21 files changed

+315
-129
lines changed

‎README.md

+19-24
Original file line numberDiff line numberDiff line change
@@ -4,30 +4,25 @@ This is the repository for Binary Ninja Debugger. The debugger is written in C++
44

55
## Platform and Target Support
66

7-
This is the current comparability matrix of the debugger. The horizontal lines stand for where we run BN and the vertical lines stand for the targets.
8-
9-
| Target 🔽 Host ▶️ | macOS | Linux | Windows | Note |
10-
|-----------------------|--------------------|--------------------|--------------------|------|
11-
| macOS | Yes (Local/Remote) | Yes (Remote) | Yes (Remote) | |
12-
| Linux | Yes (Remote) | Yes (Local/Remote) | Yes (Remote) | |
13-
| Windows | Planned | Planned | Yes (Local/Remote) | |
14-
| GDB Server | Yes | Yes | Yes | (1) |
15-
| LLDB Server | Yes | Yes | Yes | |
16-
| Windows Kernel | TBD | TBD | Planned | |
17-
| DebugAdapter Protocol | Planned | Planned | Planned | |
18-
19-
Explanation:
20-
- `Yes` means the feature is supported.
21-
- `Planned` means that we plan to implement it.
22-
- `TBD` means that we have not decided whether to support it, or how to support it.
23-
- `No` means it is not possible to do, at least for now.
24-
25-
Notes:
26-
27-
(1). Right now, we only support gdbserver with android remote debugging. Support for other gdbserver or gdb stub, e.g., qiling, VMWare, QEMU, will be added later.
28-
29-
The progress is tracked in [this issue](https://github.com/Vector35/debugger/issues/122).
30-
7+
This is the current comparability matrix of the debugger. The columns stand for where we run BN and the rows stand for the targets.
8+
9+
| Target 🔽 Host ▶️ | macOS | Linux | Windows | Note |
10+
|--------------------------------------|---------------------------------------------------------|---------------------------------------------------------|---------------------------------------------------------|------|
11+
| macOS user | Yes (Local/Remote) | Yes (Remote) | Yes (Remote) | |
12+
| Linux user | Yes (Remote) | Yes (Local/Remote) | Yes (Remote) | |
13+
| Windows user | [#70](https://github.com/Vector35/debugger/issues/70) | [#70](https://github.com/Vector35/debugger/issues/70) | Yes (Local/Remote) | |
14+
| GDB Server | Yes | Yes | Yes | |
15+
| GDB RSP (QEMU/VMWare/Qiling/Android) | Yes | Yes | Yes | |
16+
| GDB Machine Interface | [#170](https://github.com/Vector35/debugger/issues/170) | [#170](https://github.com/Vector35/debugger/issues/170) | [#170](https://github.com/Vector35/debugger/issues/170) | |
17+
| LLDB Server | Yes | Yes | Yes | |
18+
| iOS/debugserver | Yes | Yes | Yes | |
19+
| Windows Kernel | No | No | Yes (Local/Remote) | |
20+
| Windows TTD (WinDbg) | No | No | Yes (Local) | |
21+
| Linux TTD (rr) | Yes (Remote) | Yes (Local/Remote) | Yes (Remote) | |
22+
| Windows Dump File | No | No | Yes (Local) | |
23+
| Corellium | Yes (Remote) | Yes (Remote) | Yes (Remote) | |
24+
25+
The progress is also tracked in issue [#122](https://github.com/Vector35/debugger/issues/122).
3126

3227

3328

‎build.md

+2-2
Original file line numberDiff line numberDiff line change
@@ -14,10 +14,10 @@ git checkout dev
1414
# or git checkout commit_hash
1515
```
1616

17-
- Download LLDB development build for your OS at https://github.com/Vector35/lldb-artifacts/releases - make sure that the correct LLDB version is downloaded (`grep 'LLVM_VERSION ' core/CMakeLists.txt` can help)
17+
- Download LLDB development build for your OS at https://github.com/Vector35/lldb-artifacts/releases/latest - make sure that the correct LLDB version is downloaded (`grep 'LLVM_VERSION ' core/CMakeLists.txt` can help)
1818
- Extract the zip archive to `~/libclang`
1919

20-
- Download Qt development build for your OS at https://github.com/Vector35/qt-artifacts/releases.
20+
- Download Qt development build for your OS at https://github.com/Vector35/qt-artifacts/releases/latest.
2121
- Extract the zip archive to `~/Qt`
2222

2323
- Build the debugger

‎core/debugger.cpp

+2-11
Original file line numberDiff line numberDiff line change
@@ -56,15 +56,6 @@ static void RegisterSettings()
5656
{
5757
Ref<Settings> settings = Settings::Instance();
5858
settings->RegisterGroup("debugger", "Debugger");
59-
/*
60-
61-
Removed blockPython -- we can re-add it once this debugger is enabled by
62-
default
63-
64-
Leaving this function for migration of the settings popup.
65-
66-
*/
67-
6859
settings->RegisterSetting("debugger.stopAtSystemEntryPoint",
6960
R"({
7061
"title" : "Stop At System Entry Point",
@@ -112,7 +103,7 @@ static void RegisterSettings()
112103
})");
113104
settings->RegisterSetting("debugger.tryUnloadWrongDbgEngDLL",
114105
R"({
115-
"title" : "Attempt to unload the DLL with wrong path",
106+
"title" : "Attempt to unload the DbgEng DLLs from wrong path",
116107
"type" : "boolean",
117108
"default" : false,
118109
"description" : "Attempt to unload the already loaded DLL if they are from a wrong path. You may turn this on if the DbgEng DLLs, e.g., dbghelp.dll, is loaded from a wrong path, but it happens early than the debugger initialization",
@@ -125,7 +116,7 @@ static void RegisterSettings()
125116
"title" : "Stack Variable Annotations",
126117
"type" : "boolean",
127118
"default" : false,
128-
"description" : "Add stack variable annotations",
119+
"description" : "Annotate stack variables in linear view",
129120
"ignore" : ["SettingsProjectScope", "SettingsResourceScope"]
130121
})");
131122

‎docs/guide/corellium-remote-debugging.md

+30
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
# Corellium Remote Debugging
2+
3+
[Corellium](https://www.corellium.com/) is a leading solution for virtual devices. It exposes a hypervisor-level
4+
debugger that enables the debugging of the entire device. Binary Ninja debugger has a dedicated debug adapter to
5+
connect to it. Below is a guide to set it up.
6+
7+
8+
## Preparation
9+
10+
- Create a virtual device following the Corellium documentation
11+
- In the "Connect" page, download the OpenVPN configuration file and connect to the [VPN](https://support.corellium.com/features/connect/vpn)
12+
- In the "Connect" page, find the gdb connection string, e.g., `lldb --one-line "gdb-remote 10.11.1.4:4000"`. Take
13+
note of the IP address and port
14+
- Download and install the [Debug Accelerator](https://support.corellium.com/features/connect/debug-accelerator)
15+
- Run `/path/to/debug_accelerator 10.11.1.1:4000 127.0.0.1:4000`, where the first address is the remote ip:port to
16+
connect to, and the second one is a local ip:port to listen on
17+
18+
## Connect to the Debugger from Binary NInja
19+
20+
- In Menu, click "File" -> "Create New Mapped Data"
21+
- In the dialog that pops up, select an architecture that matches your target, which should be `aarch64`
22+
- In Menu, click "Debugger" -> "Connect to Remote Process..."
23+
- In the "Debug Adapter Settings" dialog, Select the `Corellium` adapter
24+
- Type in the local ip:port that the debug accelerator is operating on, e.g., `127.0.0.1:4000`
25+
- Click "Accept"
26+
27+
Note, the above guide is for the cloud version of Corellium. If you have a
28+
[Desktop Appliance](https://support.corellium.com/environments/desktop-appliance), then you can skip the VPN connection
29+
and the debug accelerator -- the local connection is often times faster without it.
30+

‎docs/guide/dbgeng-ttd.md

+10-6
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,9 @@
1-
# Time Travel Debugging
1+
# Time Travel Debugging (Windows)
22

33
Time travel debugging (TTD) allows you to record an execution trace of a program or system and replay it back and forth.
44
It can speed up the process of reverse engineering/vulnerability research, and deal with certain tasks that are not easy to handle in regular forward debugging.
55

6-
Several tools implement TTD. As of now, Binary Ninja debugger integrates with the WinDbg/DbgEng TTD so that you can replay and analyze a trace recorded by WinDbg.
6+
Several tools implement TTD. On Windows, Binary Ninja debugger integrates with the WinDbg/DbgEng TTD so that you can replay and analyze a trace recorded by WinDbg.
77
The combination of TTD and your familiar reverse engineer tool would hopefully supercharge the ability to time travel and make your workflow even more effective.
88

99
Below is a guide to set it up.
@@ -54,9 +54,12 @@ all types of recording supported by WinDbg (e.g., attach to a running process an
5454

5555
### Record a TTD Trace in Binary Ninja
5656

57+
- Make sure you have WinDbg property installed and configured
5758
- Open the file you wish to trace in Binary Ninja (optional)
5859
- Click Menu -> "Debugger" -> "Record TTD Trace"
59-
- <img src="../../img/debugger/ttd_record.png" width="600px">
60+
61+
<img src="../../img/debugger/ttd_record.png" width="600px">
62+
6063
- In the "TTD Record" dialog, configure the recording as you wish:
6164
- Executable Path: the path of the executable to trace
6265
- Working Directory: the working directory to launch the executable in
@@ -85,8 +88,8 @@ https://learn.microsoft.com/en-us/windows-hardware/drivers/debugger/time-travel-
8588

8689
- Open the .exe or .dll file in Binary Ninja
8790
- Click `Debugger` -> `Debug Adapter Settings`
88-
- For `Adapter Type`, select `DBGENG_TTD`
89-
- For `Executable Path`, select the trace file recorded in the previous step
91+
- Select `DBGENG_TTD` as the debug adapter
92+
- For `Trace Path`, select the trace file recorded in the previous step
9093
- E.g., `C:/Users/xushe/Documents/helloworld01.run`
9194
- Click `Accept`
9295

@@ -107,9 +110,10 @@ https://learn.microsoft.com/en-us/windows-hardware/drivers/debugger/time-travel-
107110
- t-: step into back
108111
- g-u: step out back
109112
- The [!position](https://learn.microsoft.com/en-us/windows-hardware/drivers/debugger/time-travel-debugging-extension-positions) command prints the `position` of all active threads
110-
- The [!tt](https://learn.microsoft.com/en-us/windows-hardware/drivers/debugger/time-travel-debugging-extension-tt) command navigates to a `position` in the trace
113+
- The [!tt navigation](https://learn.microsoft.com/en-us/windows-hardware/drivers/debugger/time-travel-debugging-extension-tt) command navigates to a `position` in the trace
111114
- E.g., `!tt 1A0:12F`
112115
- While using the debugger, when the target stops, the current position will be printed in the debugger console
116+
- The new [!tt breakpoint](https://learn.microsoft.com/en-us/windows-hardware/drivers/debuggercmds/time-travel-debugging-extension-tt#tt-break-commands) now supports breaking the target when a memory is read/written/executed, a register value is changed, or a module has been loaded, both in forward and backward direction. This is very powerful and worth checking out!
113117

114118

115119
## Feedback and Suggestions

‎docs/guide/gdbrsp-ttd.md

+50
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,50 @@
1+
# Time Travel Debugging (Linux)
2+
3+
Time travel debugging (TTD) allows you to record an execution trace of a program or system and replay it back and forth.
4+
It can speed up the process of reverse engineering/vulnerability research, and deal with certain tasks that are not easy to handle in regular forward debugging.
5+
6+
Several tools implement TTD. On Linux, Binary Ninja debugger has a GDB RSP adapter which can be used to replay/debug the
7+
trace produced by [rr](https://rr-project.org/).
8+
The combination of TTD and your familiar reverse engineer tool would hopefully supercharge the ability to time travel
9+
and make your workflow even more effective.
10+
11+
Below is a guide to set it up.
12+
13+
## Install rr
14+
15+
- Download and install the latest release from https://github.com/rr-debugger/rr/releases
16+
17+
## Record an rr Trace
18+
19+
- Record a trace with `rr your_program arg1 arg2`
20+
- This saves the trace into the default directory (`$HOME/.local/share/rr`). To specify a custom directory,
21+
use `-o target_dir`
22+
- For more options during the record, check out `rr record -h`
23+
24+
## Replay an rr Trace
25+
26+
- Run `rr replay -h 0.0.0.0 -s 31337`
27+
- This will instruct rr to spawn a GDB stub and listen on port 31337 of all interfaces
28+
- It will replay the last recorded trace. To replay a different trace, specify the trace directory on the command line
29+
- For more options during the replay, check out `rr replay -h`
30+
31+
## Connect to the gdb stub in Binary Ninja
32+
33+
- Open the binary file in Binary Ninja (optional)
34+
- Click Menu -> "Debugger" -> "Connect To Remote Process", the `Debug Adapter Settings` will popup
35+
- Select `GDB RSP` as the debug adapter
36+
- Type in the `IP Address` and `Port` in the previous step
37+
- Click `Accept`
38+
39+
<img src="../../img/debugger/gdbrsp_ttd.png" width="600px">
40+
41+
42+
## Debug the rr Trace
43+
44+
- Once connected, the debugger should be paused within the loader (ld)
45+
- Now resume the target once, and the target should be paused at the program entry point
46+
- Most of the debugger functionalities should work in the very same way as a forward debugging
47+
- The control buttons in the debugger sidebar widget shows four new buttons for reverse debugging on the right side:
48+
- <img src="../../img/debugger/ttd_buttons.png" width="600px">
49+
- These new buttons are in red color and flipped
50+
- You can hover over the button to see what they do and the keybindings for them

0 commit comments

Comments
 (0)