Skip to content

Commit

Permalink
Merge pull request #18 from zznop/16-docs
Browse files Browse the repository at this point in the history
16 docs
  • Loading branch information
Brandon Miller authored Dec 24, 2019
2 parents 236e4b6 + f3fc99a commit 7c30da8
Show file tree
Hide file tree
Showing 16 changed files with 77 additions and 110 deletions.
7 changes: 7 additions & 0 deletions LICENSE
Original file line number Diff line number Diff line change
@@ -0,0 +1,7 @@
Copyright (c) 2019 [email protected]

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.
11 changes: 11 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,3 +1,14 @@
# bnida

## Description

bnida is a suite of plugins that provide the ability to transfer analysis data between IDA Pro and Binary Ninja
databases.

## Documentation

Documentation can be found [here](https://zznop.github.io/bnida)

## License

This project is released under the MIT license.
30 changes: 3 additions & 27 deletions binja/binja_import.py
Original file line number Diff line number Diff line change
Expand Up @@ -103,7 +103,7 @@ def import_function_comments(self, comments, sections):
"""

for addr, comment in comments.items():
addr = self.adjust_addr(sections, int(func_addr))
addr = self.adjust_addr(sections, int(addr))
if addr is None:
continue

Expand Down Expand Up @@ -182,31 +182,6 @@ def get_architectures(self):

return archs

def set_raw_binary_params(self, sections):
"""
Prompt the user for the processor and create sections
:param sections: Dictionary containing section info
"""

archs = self.get_architectures()
arch_choices = list(archs.keys())
arch_field = ChoiceField('Default Platform', arch_choices)
input_fields = [arch_field, ]
section_fields = {}
for name, section in sections.items():
section_fields[name] = IntegerField(name + ' offset')
input_fields.append(section_fields[name])

get_form_input(input_fields, 'Processor and Sections')

# Set the default platform
self.bv.platform = archs[arch_choices[arch_field.result]].standalone_platform

# Create the sections
for name, section_field in section_fields.items():
self.bv.add_user_section(name, section_field.result, sections[name]['end'] - sections[name]['start'])

def run(self):
"""
Open JSON file and apply analysis data to BN database
Expand All @@ -215,7 +190,8 @@ def run(self):
print('[*] Importing analysis data from {}'.format(self.options.json_file))
json_array = self.open_json_file(self.options.json_file)
if self.bv.platform is None:
self.set_raw_binary_params(json_array['sections'])
print('[!] Platform has not been set, cannot import analysis data')
return

self.import_functions(json_array['functions'], json_array['sections'])
self.import_function_comments(json_array['func_comments'], json_array['sections'])
Expand Down
139 changes: 56 additions & 83 deletions docs/README.md
Original file line number Diff line number Diff line change
@@ -1,105 +1,78 @@
## bnida allows you to transfer analysis data between IDA Pro and Binary Ninja!
# Overview

## How does it work?
bnida consists of (2) IDA Pro scripts and (2) Binary Ninja (BN) plugins that use IDAPython and BN Python API's to do
"one-shot" transfers of analysis data across IDA and BN databases. These scripts/plugins include:

bnida consists of IDA Pro and Binary Ninja plugins that export and import analysis data from a JSON file. This is done
by leveraging each platform's Python API. Plugin files
include:
* `binja_export.py` - BNDB to JSON file
* `binja_import.py` - JSON file to BNDB
* `ida_export.py` - IDB to JSON file
* `ida_import.py` - JSON file to IDB
* `binja_export.py` - Exports analysis data from a BN database to a bnida JSON file.
* `binja_import.py` - Imports analysis data from a bnida JSON file into a BN database.
* `ida_export.py` - Exports analysis data from an IDA database to a bnida JSON file.
* `ida_import.py` - Imports analysis data from a bnida JSON file into a IDA database.

### Before
All four scripts are designed to support a single, common JSON file format. This not only allows for transfers between
BN and IDA platorms, but also BN<->BN and IDA<->IDA too. This is especially useful if there is a desire to share
analysis data with someone using an older version of IDA who can't open your newer IDA database. The JSON file itself
is also easy to digest with custom tooling, since almost every programming language contains a JSON library. Currently,
bnida supports transferring the following analysis data:
* Functions
* Function comments
* Address comments
* Symbols
* Structures (beta)

![BN Before](public/before.PNG "Before Loading Analysis Data")
Section information is also exported to the JSON file and used for adjusting offsets during imports.

### After
# Installation

![BN After](public/after.PNG "After Loading Analysis Data")
This section describes how to install bnida scripts on a Windows operating system. The process is similar on Linux.

## Getting Started
1. Clone the [repository](https://github.com/zznop/bnida).

### Setup and Configuration
2. Copy the IDA scripts to `C:\Program Files\IDA {version}\plugins` and configure a hotkey. (or keep them where they are
if you prefer to run them as scripts with `Alt+F7`).

To use bnida, clone the [repository](https://github.com/zznop/bnida) into your Binary Ninja plugins folder. Then,
I recommend moving the IDA plugins (`ida_export.py` and `ida_import.py`), to `C:\Program Files\IDA 7.1\plugins` (Windows)
and configure a hotkey to execute each IDAPython script. To do so, follow
[this](http://www.mopsled.com/2016/add-shortcut-for-idapython-script-ida-pro/) blog post.
If you don't want to bother with that, no problem. You can run `ida_export.py` or `ida_import.py` by simply typing
`Alt+F7` to execute a script file.
3. Copy the BN plugins to the Binary Ninja plugins folder at `%AppData%\Binary Ninja\plugins`

### IDA to Binary Ninja
Optionally, you can keep the files where they are in the cloned repository and simply create symbolic links.

1. Open your IDA database (or load a binary and allow analysis to complete)
```
C:\Users\zznop\AppData\Roaming\Binary Ninja\plugins>mklink binja_export.py C:\Users\zznop\projects\bnida\binja\binja_export.py
symbolic link created for binja_export.py <<===>> C:\Users\zznop\projects\bnida\binja\binja_export.py
```

2. Type `Alt+F7` and select the `ida_export.py`
# Transferring Analysis Data

##### Run IDA Export Script

![Run IDA Export](public/ida-run-script.PNG "Run ida_export.py script")
bnida can be used to transfer analysis data from BN to BN, IDA to IDA, BN to IDA, or IDA to BN. The following sections
describe how to use bnida plugins in IDA Pro and Binary Ninja.

3. Input the file path for the JSON file that will be created
## IDA Pro

4. Click Ok. Analysis data will be written to the JSON file
`ida_export.py` and `ida_import.py` are used to export/import analysis data into/from IDA databases. To export from an
IDA database, press `ALT+F7` and open `ida_export.py`. When prompted, enter the file path for the bnida JSON file to be
generated and click "save". The script should create the file and populate it with data from your IDA database.
Similarly, to import data into an IDA database, run `ida_import.py`. When prompted, select the bnida JSON file and click
"save". Both IDA scripts print debug output to the output window.

##### IDA Analysis Data JSON

![IDA Analysis Data JSON](public/ida-exported-json.PNG "IDA Analysis Data JSON")
![IDA Export](public/ida_export.gif "ida_export.py")

5. Open your BN database for the same binary (or load a binary and allow analysis to complete)
6. Click `tools->Import data to BN`
## Binary Ninja

##### Run Binja Import Plugin

![Run Binja Import](public/bn-tools-import-data.PNG "Run binja_import.py Plugin")
`binja_export.py` and `binja_import.py` are used to export/import analysis data into/from Binary Ninja databases. To
export from a BN database, click `Tools->bnida: Export data`. When prompted, enter the file path for the bnida JSON file
that will be generated and click "OK". The plugin should run in the background and create the bnida JSON file.
Likewise, to import data click `Tools->bnida: Import data`. When prompted, open the bnida JSON file. The plugin should
run in the background and apply the analysis data in the bnida JSON file to the open BN database.

7. Enter the file path to the JSON file
![Binja Import](public/binja_import.gif "binja_import.py")

##### Supply File Path to IDA JSON

![Enter JSON File](public/bn-import-file-input.PNG "File path to IDA JSON")
# Raw Binaries

8. Click ok. Your database will then be updated with the analysis data from IDA.
During imports, bnida adjusts offsets based on the symbol's/comment's/function's section base address. This is done to
allow data imports to succeed even if the binary has been rebased. This design works excellent with PE and ELF binaries
where section info is in headers and sections are applied by the loaders. In the case of raw binaries (i.e. flat
firmware images), sections must be applied manually. It is important to ensure that sections have been applied at the
same offsets across databases prior to attempting to transfer analysis data.

### Binary Ninja to IDA

BN to IDA transfers require a similar process. The steps are as follows:

1. Open your Binary Ninja database (or load a binary and allow analysis to complete)
2. Click `tools->Export data from BN`
3. Input the file path for the JSON file that will be created
4. Click Ok. Analysis data will be written to the JSON file
5. Open your IDA database for the same binary (or load the binary and allow analysis to complete)
6. Type `Alt+F7` or click `File->Script File` and select the `ida_import.py`
7. Select the JSON file
8. Click ok. Your database will then be updated with the analysis data from BN.

## Additional Information

### Handling Flat Files

bnida calculates offsets between IDA and BN relative to the base address of the symbol's section. This is done to
account for potential base address differences between the platforms. This design works excellent with PE and ELF
executable file formats where the section names are defined in headers (which ensures section names are uniform).
However, with flat files (such as kernel images) where defining sections are left to the user, it is important to ensure
that section names are identical between the BNDB and IDB. Currently, `binja_import.py` contains a feature that allows
you to define the offsets for sections contained in the exported IDA JSON data. After selecting the JSON file, it checks
if the default processor has been set. If it has not been set, a input box will appear. The input box prompts the user
to define the default processor and set the base address for each section found in the JSON file.

##### Binja Import Prompt for Defining Sections

![Defining Sections](public/flat-file-section-definition.PNG "Defining Sections")

Sections can be defined manually using the Binary Ninja API and the script console, if needed. To create a section, use
`BinaryView.add_user_section(name, start, length)`. To validate that the section was created, navigate to linear view
and scroll to the top of the binary.

##### Add a Section Manually

![Create Section Manually](public/bn-add-section.PNG "BN Add User Section")

##### BN Sections View

![BN Sections](public/bn-sections.PNG "BN Sections")
In addition to sections, ensure that the platform has been set in Binary Ninja before attempting to import analysis data
into a raw binary database. This can be done by loading the binary with options or using the Python API to set
`bv.platform`. This is required so that the importer plugin can create functions. Likewise, ensure the correct processor
is set in IDA before import.
Binary file removed docs/public/after.PNG
Binary file not shown.
Binary file removed docs/public/before.PNG
Binary file not shown.
Binary file added docs/public/binja_import.gif
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file removed docs/public/bn-add-section.PNG
Binary file not shown.
Binary file removed docs/public/bn-import-file-input.PNG
Binary file not shown.
Binary file removed docs/public/bn-sections.PNG
Binary file not shown.
Binary file removed docs/public/bn-tools-import-data.PNG
Binary file not shown.
Binary file removed docs/public/flat-file-section-definition.PNG
Binary file not shown.
Binary file removed docs/public/ida-export-save.PNG
Binary file not shown.
Binary file removed docs/public/ida-exported-json.PNG
Binary file not shown.
Binary file removed docs/public/ida-run-script.PNG
Binary file not shown.
Binary file added docs/public/ida_export.gif
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.

0 comments on commit 7c30da8

Please sign in to comment.