Skip to content

Commit

Permalink
[ext_bn] Binary Ninja support
Browse files Browse the repository at this point in the history
  • Loading branch information
bootleg committed Jan 5, 2021
1 parent 74f2513 commit 0ad9bc7
Show file tree
Hide file tree
Showing 8 changed files with 1,267 additions and 7 deletions.
76 changes: 69 additions & 7 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@

**ret-sync** stands for Reverse-Engineering Tools SYNChronization. It is a set
of plugins that help to synchronize a debugging session
(WinDbg/GDB/LLDB/OllyDbg/OllyDbg2/x64dbg) with a disassembler (IDA/Ghidra).
(WinDbg/GDB/LLDB/OllyDbg/OllyDbg2/x64dbg) with a disassembler (IDA/Ghidra/Binary Ninja).
The underlying idea is simple: take the best from both worlds (static and
dynamic analysis).

Expand Down Expand Up @@ -44,6 +44,7 @@ that I developed and maintained during my stay at
- [Installation](#installation)
- [IDA extension](#ida-extension)
- [Ghidra extension](#ghidra-extension)
- [Binary Ninja extension](#binary-ninja-extension)
- [WinDbg extension](#windbg-extension)
- [GNU gdb (GDB) installation](#gnu-gdb-gdb-installation)
- [LLDB installation](#lldb-installation)
Expand All @@ -54,6 +55,7 @@ that I developed and maintained during my stay at
- [**ret-sync** debugger commands](#ret-sync-debugger-commands)
- [IDA usage](#ida-usage)
- [Ghidra usage](#ghidra-usage)
- [Binary Ninja usage](#binary-ninja-usage)
- [WinDbg usage](#windbg-usage)
- [GNU gdb (GDB) usage](#gnu-gdb-gdb-usage)
- [LLDB usage](#lldb-usage)
Expand Down Expand Up @@ -82,6 +84,7 @@ And the disassembler plugins:

* `ext_ida/SyncPlugin.py`
* `ext_ghidra/dist/ghidra_*_retsync.zip`: Ghidra plugin
* `ext_bn/retsync`: Binary Ninja plugin


# General prerequisites
Expand Down Expand Up @@ -322,6 +325,35 @@ A status window is also available from ``Windows`` -> ``RetSyncPlugin``. You
generally want to drop it on the side to integrate it with the Ghidra
environment windows.


## Binary Ninja extension

Binary Ninja support is experimental, make sure to backup your analysis
databases.

### Binary Ninja prerequisites

**ret-sync** requires Binary Ninja version 2.2 at minimum as well as Python 3
(Python 2 is not supported).


### Install the Binary Ninja extension

**ret-sync** is not yet distributed through the Binary Ninja's Plugin Manager;
a manual installation is required. Simply copy that content of the `ext_bn`
folder into Binary Ninja's plugins folder, for example:

`%APPDATA%\Binary Ninja\plugins`

After restarting Binary Ninja, the following output should be present in the
console window:

```
[sync] commands added
Loaded python3 plugin 'retsync'
```


## WinDbg extension

### Build the WinDbg extension
Expand Down Expand Up @@ -537,9 +569,9 @@ As a reminder it is possible to alias by default using the ``.sync`` configurati
Two buttons are also available in the Debug toolbar to toggle global and
Hex-Rays syncing.

### IDA bindings over WinDbg commands
### IDA bindings over debugger commands

``Syncplugin.py`` also registers WinDbg command wrapper hotkeys.
``Syncplugin.py`` also registers debugger command wrapper hotkeys.

* ``F2`` - Set breakpoint at cursor address
* ``F3`` - Set one-shot breakpoint at cursor address
Expand Down Expand Up @@ -575,7 +607,7 @@ the result as above.
* ``Alt-R`` - Restart syncing
* ``Alt-Shift-R`` - Reload configuration

### Ghidra bindings over WinDbg
### Ghidra bindings over debugger commands

Bindings over debugger commands are also implemented. They are similar to the
ones from IDA's extension (except the "Go" command).
Expand All @@ -589,6 +621,32 @@ ones from IDA's extension (except the "Go" command).
* ``F10`` - Single step
* ``F11`` - Single trace


## Binary Ninja usage

### Binary Ninja global shortcuts

**ret-sync** defines these global shortcuts in Binary Ninja:

* ``Alt-S`` - Enable syncing
* ``Alt-Shift-S`` - Disable syncing


### Binary Ninja shortcuts

Bindings over debugger commands are also implemented. They are similar to the
ones from IDA's extension.

* ``F2`` - Set breakpoint at cursor address
* ``Ctrl-F2`` - Set hardware breakpoint at cursor address
* ``Alt-F3`` - Set one-shot breakpoint at cursor address
* ``Ctrl-F3`` - Set one-shot hardware breakpoint at cursor address
* ``Alt-F2`` - Translate (rebase in debugger) current cursor address
* ``Alt-F5`` - Go
* ``F10`` - Single step
* ``F11`` - Single trace


## WinDbg usage

### WinDbg plugin commands
Expand Down Expand Up @@ -918,7 +976,7 @@ While mostly focus on dynamic analysis, it is of-course possible to use other to

# Known Bugs/Limitations

- Tested with Python 2.7/3.7, IDA 7.4SP1 (Windows, Linux and Mac OS X), Ghidra 9.1.2, GNU gdb (GDB) 8.1.0 (Debian), lldb 310.2.37.
- Tested with Python 2.7/3.7, IDA 7.5 (Windows, Linux and Mac OS X), Ghidra 9.2, Binary Ninja 2.2.2487, GNU gdb (GDB) 8.1.0 (Debian), lldb 310.2.37.
- **THERE IS NO AUTHENTICATION/ENCRYPTION** whatsoever between the parties; you're on your own.
- Self modifying code is out of scope.

Expand All @@ -940,6 +998,7 @@ With IDA:
- Graph window redrawing is quite slow for big graphs.
- **ret-sync** shortcuts conflicts in Linux environments.


# License

**ret-sync** is free software: you can redistribute it and/or modify
Expand All @@ -955,11 +1014,14 @@ GNU General Public License for more details.
You should have received a copy of the GNU General Public License
along with this program. If not, see http://www.gnu.org/licenses/.

The Binary Ninja plugin is released under the MIT licence.


# Greetz

Hail to Bruce Dang, StalkR, @Ivanlef0u, Damien Aumaître, Sébastien Renaud and
Kévin Szkudlapski, @_m00dy_, @saidelike, Xavier Mehrenberger, ben64, Raphaël
Rigo, Jiss for their kindness, help, feedbacks and thoughts. Ilfak Guilfanov,
Igor Skochinsky and Arnaud Diederen for their help with IDA's internals and
outstanding support. Finally, thank you also to all the contributors and
everyone who reported issues/bugs.
outstanding support. Thank you to Jordan Wiens and Vector 35. Finally, thank
you also to all the contributors and everyone who reported issues/bugs.
44 changes: 44 additions & 0 deletions ext_bn/retsync/README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,44 @@
# ret-sync (v0.1.0)
Author: **Alexandre Gazet**

_Helper plugin to synchronize Binary Ninja with a debugging session_

## Description:

This plugin is a part of ret-sync, a set of plugins that help to synchronize a debugging session (WinDbg/GDB/LLDB/OllyDbg/OllyDbg2/x64dbg) with a disassembler (IDA/Ghidra/Binary Ninja).


## Installation Instructions

### Windows



### Linux



### Darwin



## Minimum Version

This plugin requires the following minimum version of Binary Ninja:

* 2



## Required Dependencies

The following dependencies are required for this plugin:



## License

This plugin is released under a MIT license.
## Metadata Version

2
61 changes: 61 additions & 0 deletions ext_bn/retsync/__init__.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,61 @@
#!/usr/bin/env python3

"""
Copyright (C) 2020, Alexandre Gazet.
This file is part of ret-sync plugin for Binary Ninja.
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
"""

from collections import namedtuple

from PySide2.QtCore import Qt
from PySide2.QtGui import QKeySequence
from binaryninjaui import UIAction, UIActionHandler

from .sync import SyncPlugin
from .retsync.rsconfig import rs_log


def add_commands(plugin):
DbgAction = namedtuple('DbgAction', 'name, key_seq, handler')
plugin_actions = (
DbgAction("SyncEnable", QKeySequence(Qt.ALT + Qt.Key_S), UIAction(plugin.cmd_sync)),
DbgAction("SyncDisable", QKeySequence(Qt.ALT + Qt.SHIFT + Qt.Key_S), UIAction(plugin.cmd_syncoff)),
DbgAction("SyncGo", QKeySequence(Qt.ALT + Qt.Key_F5), UIAction(plugin.cmd_go)),
DbgAction("SyncStepOver", QKeySequence(Qt.Key_F10), UIAction(plugin.cmd_so)),
DbgAction("SyncStepInto", QKeySequence(Qt.Key_F11), UIAction(plugin.cmd_si)),
DbgAction("SyncTranslate", QKeySequence(Qt.ALT + Qt.Key_F2), UIAction(plugin.cmd_translate)),
DbgAction("SyncBp", QKeySequence(Qt.Key_F2), UIAction(plugin.cmd_bp)),
DbgAction("SyncHwBp", QKeySequence(Qt.CTRL + Qt.Key_F2), UIAction(plugin.cmd_hwbp)),
DbgAction("SyncBpOneShot", QKeySequence(Qt.ALT + Qt.Key_F3), UIAction(plugin.cmd_bp1)),
DbgAction("SyncHwBpOneShot", QKeySequence(Qt.CTRL + Qt.Key_F3), UIAction(plugin.cmd_hwbp1))
)

for action in plugin_actions:
UIAction.registerAction(action.name, action.key_seq)
UIActionHandler.globalActions().bindAction(action.name, action.handler)

rs_log('commands added')


retsync_plugin = SyncPlugin()
retsync_plugin.init_widget()
add_commands(retsync_plugin)
24 changes: 24 additions & 0 deletions ext_bn/retsync/plugin.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,24 @@
{
"pluginmetadataversion": 2,
"name": "ret-sync",
"type": ["helper" ],
"api": ["python3"],
"description": "Helper plugin to synchronize Binary Ninja with a debugging session",
"longdescription": "This plugin is a part of ret-sync, a set of plugins that help to synchronize a debugging session (WinDbg/GDB/LLDB/OllyDbg/OllyDbg2/x64dbg) with a disassembler (IDA/Ghidra/Binary Ninja).",
"license": {
"name": "MIT",
"text": "Copyright (c) 2020 Alexandre Gazet.\n\nPermission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the \"Software\"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:\n\nThe above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.\n\nTHE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE."

},
"platforms": ["Windows", "Linux", "Darwin"],
"installinstructions" : {
"Windows":"",
"Linux":"",
"Darwin":""
},
"dependencies": {
},
"version": "0.1.0",
"author": "Alexandre Gazet",
"minimumbinaryninjaversion": 2
}
Empty file.

0 comments on commit 0ad9bc7

Please sign in to comment.