You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Binary Ninja Debugger Plugin (**BNDP**) is a plugin for Binary Ninja implementing debug functionality. It can be used from within the GUI or outside (headless). It officially supports 64-bit Windows, Linux, and MacOS targets. Its extensible design makes it easily adapted to other platforms.
@@ -27,7 +65,7 @@ Binary Ninja Debugger Plugin (**BNDP**) is a plugin for Binary Ninja implementin
27
65
28
66
## Plugin Acquisition and Installation
29
67
30
-
BNDP is a python package and is acquired via github (http://github.com/vector35/debugger), by the Plugin Manager from within Binary Ninja, or by ordinary file and directory copying.
68
+
BNDP is a python package and is acquired via GitHub (http://github.com/vector35/debugger), by the Plugin Manager from within Binary Ninja, or by ordinary file and directory copying.
31
69
32
70
It must be placed in the Binary Ninja plugin path, which varies based on platform. Please refer to [Using Plugins](https://docs.binary.ninja/getting-started.html#using-plugins) section within the [Getting Started Guide](https://docs.binary.ninja/getting-started.html) in the [Binary Ninja User Documentation](https://docs.binary.ninja/).
33
71
@@ -62,17 +100,17 @@ A view with debugger-related menu items will appear:
62
100
63
101
64
102
65
-
Click the dropdown menu arrow near `Run` for additional settings. Click `Run` to execute the target. The other buttons will activate if the target is initialized successfully. Buttons `Resume`, `Step Into`, etc. work as expected. To set a breakpoint, select an address, right click, choose Debugger, then `Toggle Breakpoint`.
103
+
Click the drop-down menu arrow near `Run` for additional settings. Click `Run` to execute the target. The other buttons will activate if the target is initialized successfully. Buttons `Resume`, `Step Into`, etc. work as expected. To set a breakpoint, select an address, right click, choose Debugger, then `Toggle Breakpoint`.
66
104
67
105
68
106
69
-
The same step is used to clear the breakpoint. To view modules, registers, etc. select `View` from the applicatation's main menu and then the desired view:
107
+
The same step is used to clear the breakpoint. To view modules, registers, etc. select `View` from the application's main menu and then the desired view:
70
108
71
109
72
110
73
111
## Headless Mode
74
112
75
-
The API attempts to hide target details behing a uniform interface called DebugAdapter. Start by importing the parent DebugAdapter and the appropriate child for your platform and creating an instance:
113
+
The API attempts to hide target details behind a uniform interface called DebugAdapter. Start by importing the parent DebugAdapter and the appropriate child for your platform and creating an instance:
76
114
77
115
```python
78
116
from debugger import DebugAdapter, lldb
@@ -147,7 +185,7 @@ BNDP is a convenient means to interact with various debugger **backends**. It do
147
185
148
186
The backends vary considerably, so a large part of BNDP's task is to present a unified interface by which these backends can be used.
149
187
150
-
This is achieved using debug **adapters**, named so because they adapt whatever ideosyncracies a backend has to the ideal interface we envision in `DebugAdapter.py`. Each adaptation of a backend is a subclass of `DebugAdapter`, for example `DebugAdapterGdb` and `DebugAdapterLLDB` communicate with gdb and lldb backends, respectively.
188
+
This is achieved using debug **adapters**, named so because they adapt whatever idiosyncrasies a backend has to the ideal interface we envision in `DebugAdapter.py`. Each adaptation of a backend is a subclass of `DebugAdapter`, for example `DebugAdapterGdb` and `DebugAdapterLLDB` communicate with gdb and lldb backends, respectively.
151
189
152
190
## Standard Backends
153
191
@@ -179,7 +217,7 @@ Higher level operations like "step over" are provided by some backends (like **d
179
217
180
218
# API
181
219
182
-
Prerequisite reading: "Design" section
220
+
Prerequisite reading: [Design](#Design)
183
221
184
222
The API is centered around the `DebugAdapter` class. You can subclass it to interface with a new **backend**.
185
223
@@ -212,7 +250,7 @@ These functions start and end a session. A session can be started by executing a
212
250
213
251
### Target Info Methods
214
252
215
-
Acquire the target's architecture, execution path, process ID, and load address. Note that these are not always applicable for certain targets. For example, pid does not make sense when connected to a full system BOCHS emulation.
253
+
Acquire the target's architecture, execution path, process ID, and load address. Note that these are not always applicable for certain targets. For example, PID does not make sense when connected to a full system BOCHS emulation.
216
254
217
255
```
218
256
def target_arch(self)
@@ -223,14 +261,14 @@ Acquire the target's architecture, execution path, process ID, and load address.
223
261
224
262
See `BNDP_ROOT/DebugAdapter.py`.
225
263
226
-
### Thread Methods
264
+
### Thread Methods
227
265
```
228
266
def thread_list(self):
229
267
def thread_selected(self):
230
268
def thread_select(self, tidx):
231
269
```
232
270
233
-
### Breakpoint Methods
271
+
### Breakpoint Methods
234
272
```
235
273
def breakpoint_set(self, address)
236
274
def breakpoint_clear(self, address)
@@ -261,7 +299,7 @@ See `BNDP_ROOT/DebugAdapter.py`.
261
299
262
300
## Subclassing DebugAdapter
263
301
264
-
The DebugAdapter wants to present a general debug interface, hiding the ideosyncracies of whatever **backend** it is connected to. Often you will have to "shape" the behavior of the backend to aim for this ideal.
302
+
The DebugAdapter wants to present a general debug interface, hiding the idiosyncrasies of whatever **backend** it is connected to. Often you will have to "shape" the behavior of the backend to aim for this ideal.
265
303
266
304
For example, in Windows, setting a breakpoint always succeeds, no matter the address. It's only at the next go/step/step that bad addresses will raise a write exception because that's when the engine actually writes the 0xCC byte. But the designed behavior of `breakpoint_set()` in DebugAdapter is to write immediately, and provide instant response to the caller if the breakpoint wasn't set correctly. So a `WriteProcessMemory()` is used as a probe, and if it succeeds, the adapter pretends the breakpoint is as good as set.
267
305
@@ -273,13 +311,10 @@ The stubs implemented by gdbserver and debugserver will not step over an address
273
311
274
312
The following differences were noted during development and are not an exhaustive list:
275
313
276
-
lldb has single reg reads with 'p' packet, but in gdb registers must be read in group with 'g' packet.
277
-
278
-
lldb can have its registers polled with 'qRegisterInfo' packet, but gdb uses only XML target description.
279
-
280
-
lldb has single reg writes with 'P' packet, gdb doesn't, and registers must be written in group with 'G' packet.
281
-
282
-
lldb can list solibs and executable image with 'jGetLoadedDynamicLibrariesInfos' packet, gdb still looks to /proc/pid/maps.
314
+
- lldb has single reg reads with 'p' packet, but in gdb registers must be read in group with 'g' packet.
315
+
- lldb can have its registers polled with 'qRegisterInfo' packet, but gdb uses only XML target description.
316
+
- lldb has single reg writes with 'P' packet, gdb doesn't, and registers must be written in group with 'G' packet.
317
+
- lldb can list `so` libs and executable image with 'jGetLoadedDynamicLibrariesInfos' packet, gdb still looks to /proc/pid/maps.
283
318
284
319
## Troubleshooting new GDB Backends
285
320
@@ -289,31 +324,33 @@ Prove functionality first with `BNDP_ROOT/cli.py` then with the GUI.
289
324
290
325
### Network Monitoring
291
326
292
-
For gdbserver and debugserver, monitoring packets can be indispensible.
327
+
For gdbserver and debugserver, monitoring packets can be indispensable.
293
328
294
-
Use tcpdump: `tcpdump -i lo0 -A -s0 'port 31337'`.
295
-
Use `./tools/sniffrsp.py` to monitor traffic between you and gdbserver/debugserver.
296
-
Use wireshark.
329
+
-Use tcpdump: `tcpdump -i lo0 -A -s0 'port 31337'`
330
+
-Use `./tools/sniffrsp.py` to monitor traffic between you and gdbserver/debugserver
Monitoring, then mimicing behavior from working tools is often faster than starting at the docs:
343
+
Monitoring, then mimicking behavior from working tools is often faster than starting at the docs:
309
344
310
-
`(lldb) process connect connect://localhost:31337`
345
+
```
346
+
(lldb) process connect connect://localhost:31337
347
+
```
311
348
312
349
# Glossary
313
350
314
-
**backend** - This is the code that is actually instrumenting (eg: writing breakpoint bytes, setting the trap flag) in targets. Examples are Microsoft's [debugger engine](https://docs.microsoft.com/en-us/windows-hardware/drivers/debugger/debugger-engine-overview), gdbserver, debugserver, or MAME.
This is the code that is actually instrumenting (eg: writing breakpoint bytes, setting the trap flag) in targets. Examples are Microsoft's [debugger engine](https://docs.microsoft.com/en-us/windows-hardware/drivers/debugger/debugger-engine-overview), gdbserver, debugserver, or MAME.
0 commit comments