From e5be1fc1b4f36a62226e00fa03a2726779026a3b Mon Sep 17 00:00:00 2001 From: Jordan Wiens Date: Tue, 4 Jul 2017 00:15:44 -0400 Subject: initial plugin using writing documentation --- docs/guide/plugins.md | 102 ++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 102 insertions(+) (limited to 'docs/guide') diff --git a/docs/guide/plugins.md b/docs/guide/plugins.md index e69de29b..9c67d44f 100644 --- a/docs/guide/plugins.md +++ b/docs/guide/plugins.md @@ -0,0 +1,102 @@ +# Plugins + +Plugins really show off the power of Binary Ninja. This guide should help give you an overview of both using and writing plugins. + +The most common Binary Ninja plugins are Python which we are covering here. That said, there are some C++ plugins which must be built for the appropriate native architecture and will usually include build instructions for each platform. Several [C++ examples] are included in the API repository. + +## Using Plugins + +Plugins are loaded from the user's plugin folder: + +- OS X: `~/Library/Application Support/Binary Ninja/plugins/` +- Linux: `~/.binaryninja/plugins/` +- Windows: `%APPDATA%\Binary Ninja\plugins` + +Note that plugins installed via the [PluginManager API] are installed in the `repositories` folder in the same path as the previous `plugin` folder listed above. You should not need to manually touch anything in that folder, but should access them via the API instead. + +### Manual installation + +You can manually install a plugin either by adding a folder which contains it (the plugin folder must contain an `__init__.py` at the top of the folder, or a python file can be included directly in the plugin folder though this is not recommended). + +Note, if manually cloning the [api repository](https://github.com/Vector35/binaryninja-api), make sure to: + +``` +git submodule update --init --recursive +``` + +after cloning or else the submodules will not actually be downloaded. + +### Installing via the API + +Binary Ninja now offers a [PluginManager API] which can simplify the process of finding and installing plugins. From the console: + +``` +>>> mgr = RepositoryManager() +>>> dir(mgr) +['__class__', '__delattr__', '__dict__', '__doc__', '__format__', '__getattribute__', '__hash__', '__init__', '__module__', '__new__', '__reduce__', '__reduce_ex__', '__repr__', '__setattr__', '__sizeof__', '__str__', '__subclasshook__', '__weakref__', 'add_repository', 'check_for_updates', 'default_repository', 'disable_plugin', 'enable_plugin', 'handle', 'install_plugin', 'plugins', 'repositories', 'uninstall_plugin', 'update_plugin'] +>>> mgr.plugins +{'default': [, , , , , , , , , , , ]} +>>> mgr.install_plugin(easypatch) +True +>>> mgr.enable(easypatch) +True +``` + +Then just restart, and your plugin will be loaded. + +### Installing Prerequisites + +Because Windows ships with an embedded version of Python, if you want to install plugins inside that Python, you'll need to either adjust your `sys.path` to include the locations for the other libraries (making sure they're compatible with the built-in version), or else install them directly in the environment via: + +``` +import pip +pip.main(['install', '--quiet', 'packagename']) +``` + +_--quiet is required to minimize some of the normal output of pip that doesn't work within the context of our scripting console_ + +For both OS X and Linux, Binary Ninja can utilize the built in system Python so any installed packages should be available there via whatever typical mechanism you use. + +### Troubleshooting + +Troubleshooting many Binary Ninja problems is helped by enabling debug logs and logging the output to a file. Just launch Binary Ninja with + +``` +/Applications/Binary\ Ninja.app/Contents/MacOS/binaryninja -d -l /tmp/bnlog.txt +``` + +And check `/tmp/bnlog.txt` when you're done. + +## Writing Plugins + +First, take a look at some of the [example] plugins, or some of the [community] plugins to get a feel for different APIs you might be interested in. Of course, the full [API] docs are online and available offline via the `Help`/`Open API Reference...`. + +To start, we suggest you download the [sample plugin] as a template since it contains all of the elements you're likely to need. + +- Begin by editing the `plugin.json` file +- Next, update the `LICENSE` +- For small scripts, you can include all the code inside of `__init__.py`, though we recommend for most larger scripts that init just act as an initializer and call into functions organized appropriately in other files. + +### UI Elements + +While it is possible to use Qt to directly create [UI enhancements] to Binary Ninja, we don't recommend it. First, there's a chance that we'll change UI platforms in the future (in particular because Qt's QWidget performance is actually getting worse with newer versions and they're trying to move everyone to QTQuick which might as well be Electron). Secondly, it is much more difficult for other users to install your plugin given the much more complicated dependencies and cross-platform headache of setup. + +The officially supported mechanism (until the 1.2 release which will include much more featureful UI API enhancements) are available from the [interaction API] and shown off in the [angr] and [nampa] plugins. + +### Testing + +It's useful to be able to reload your plugin during testing. On the Commercial edition of Binary Ninja, this is easily accomplished with a stand-alone headless install using `import binaryninja` after [installing the API]. (install_api.py is included in every install in the installation folder) + +For the Personal edition, we recommend simply commenting out the `register_` function normally used to register the plugin via whatever mechanism it uses and instead simply using the built-in Python console along with the python `reload` function to load new changes and test them by directly calling functions in the module. This work-around unfortunately is not supported for Binary View or Architecture plugins which unfortunately do require a restart to test if not running on Commercial. + +[PluginManager API]: https://api.binary.ninja/binaryninja.pluginmanager-module.html +[example]: https://github.com/Vector35/binaryninja-api/tree/dev/python/examples +[community]: https://github.com/Vector35/community-plugins +[C++ examples]: https://github.com/Vector35/binaryninja-api/tree/dev/examples +[API]: https://api.binary.ninja/ +[sample plugin]: https://github.com/Vector35/sample_plugin +[UI enhancements]: https://github.com/NOPDev/BinjaDock +[interaction API]: https://api.binary.ninja/binaryninja.interaction-module.html +[angr]: https://github.com/Vector35/binaryninja-api/blob/dev/python/examples/angr_plugin.py +[nampa]: https://github.com/kenoph/nampa +[installing the API]: https://github.com/Vector35/binaryninja-api/blob/dev/scripts/install_api.py -- cgit v1.3.1 From b6389ae036311a4b2d0af2c130d05e01ceeced3f Mon Sep 17 00:00:00 2001 From: Jordan Wiens Date: Mon, 21 Aug 2017 20:08:14 -0500 Subject: debian troubleshooting doc update --- docs/guide/troubleshooting.md | 9 +++++++++ 1 file changed, 9 insertions(+) (limited to 'docs/guide') diff --git a/docs/guide/troubleshooting.md b/docs/guide/troubleshooting.md index efd9fab9..5ff30218 100644 --- a/docs/guide/troubleshooting.md +++ b/docs/guide/troubleshooting.md @@ -48,6 +48,15 @@ cd ~/binaryninja QT_PLUGIN_PATH=./qt ./binaryninja ``` +### Debian + +For Debian variants that (Kali, eg) don't match packages with Ubuntu LTS or the latest stable, the following might fix problems with libssl and libcrypto: + +``` +$ cd binaryninja/plugins +$ ln -s libssl.so libssl.so.1.0.0 +$ ln -s libcrypto.so libcrypto.so.1.0.0 +``` ## API -- cgit v1.3.1 From 60c6b1a7675c15bf570ae63c94d8aac0eee5414e Mon Sep 17 00:00:00 2001 From: Jordan Wiens Date: Mon, 21 Aug 2017 20:26:34 -0500 Subject: add gentoo troubleshooting --- docs/guide/troubleshooting.md | 5 +++++ 1 file changed, 5 insertions(+) (limited to 'docs/guide') diff --git a/docs/guide/troubleshooting.md b/docs/guide/troubleshooting.md index 5ff30218..d8930d41 100644 --- a/docs/guide/troubleshooting.md +++ b/docs/guide/troubleshooting.md @@ -58,6 +58,10 @@ $ ln -s libssl.so libssl.so.1.0.0 $ ln -s libcrypto.so libcrypto.so.1.0.0 ``` +### Gentoo + +One Gentoo user [reported][issue672] a failed SSL certificate when trying to update. The solution was to copy over `/etc/ssl/certs/ca-certificates.crt` from another Linux distribution. + ## API - If the GUI launches but the license file is not valid when launched from the command-line, check that you're using the right version of Python. Only a 64-bit Python 2.7 is supported at this time. Additionally, the [personal][purchase] edition does not support headless operation. @@ -69,3 +73,4 @@ $ ln -s libcrypto.so libcrypto.so.1.0.0 [support]: https://binary.ninja/support.html [faq]: https://binary.ninja/faq.html [purchase]: https://binary.ninja/purchase.html +[issue672]: https://github.com/Vector35/binaryninja-api/issues/672 -- cgit v1.3.1 From d38a8d23d331c464e6d5089000ebf641ef855110 Mon Sep 17 00:00:00 2001 From: Jordan Wiens Date: Mon, 21 Aug 2017 20:58:14 -0500 Subject: new troubleshooting tips --- docs/guide/troubleshooting.md | 18 ++++++++++++++++-- 1 file changed, 16 insertions(+), 2 deletions(-) (limited to 'docs/guide') diff --git a/docs/guide/troubleshooting.md b/docs/guide/troubleshooting.md index d8930d41..a640d47e 100644 --- a/docs/guide/troubleshooting.md +++ b/docs/guide/troubleshooting.md @@ -9,17 +9,31 @@ ## Bug Reproduction Running Binary Ninja with debug logging will make your bug report more useful. + ``` ./binaryninja --debug --stderr-log ``` +Alternatively, it might be easier to save debug logs to a file instead: + +``` +./binaryninja -d -l logfile.txt +``` + +(note that both long and short-form of the command-line arguments are demonstrated in the above examples) + ## Plugin Troubleshooting -While third party plugins are not officially supported, there are a number of troubleshooting tips that can help identify the cause. The most importat is to enable debug logging as suggested in the previous section. This will often highlight problems with python paths or any other issues that prevent plugins from running. +While third party plugins are not officially supported, there are a number of troubleshooting tips that can help identify the cause. The most important is to enable debug logging as suggested in the previous section. This will often highlight problems with python paths or any other issues that prevent plugins from running. + +Additionally, if you're having trouble running a plugin in headless mode (without a GUI calling directly into the core), make sure you'er running the Commercial version of Binary Ninja as the Student/Non-Commercial edition does not support headless processing. + +Next, if running a python plugin, make sure the python requirements are met by your existing installation. Note that on windows, the bundled python is used and python requirements should be installed either by manually copying the modules to the `plugins` [folder](/getting-started/#directories). + ## License Problems -- If experiencing problems with Windows UAC permissions during an update, the easiest fix is to completely un-install and [recover][recover] the latest installer and license. Preferences are saved outside the installation folder and are preserved, though you might want to remove your [license](/getting-started/index.html#license). +- If experiencing problems with Windows UAC permissions during an update, the easiest fix is to completely un-install and [recover][recover] the latest installer and license. Preferences are saved outside the installation folder and are preserved, though you might want to remove your [license](/getting-started/#license). - If you need to change the email address on your license, contact [support]. ## Linux -- cgit v1.3.1 From 207640bcbc5d0ee8639c2b6de0bef9e3c4eadeeb Mon Sep 17 00:00:00 2001 From: Jordan Wiens Date: Mon, 21 Aug 2017 21:54:23 -0500 Subject: updated docs --- docs/getting-started.md | 39 ++++++++++++++++++++++++++++++++------- docs/guide/type.md | 2 ++ 2 files changed, 34 insertions(+), 7 deletions(-) (limited to 'docs/guide') diff --git a/docs/getting-started.md b/docs/getting-started.md index 46dee008..d91eb046 100644 --- a/docs/getting-started.md +++ b/docs/getting-started.md @@ -2,18 +2,45 @@ Welcome to Binary Ninja. This introduction document is meant to quickly guide you over some of the most common uses of Binary Ninja. -![license popup >](/images/license-popup.png "License Popup") +## Directories -## License +Binary Ninja uses two main locations. The first is the install path of the binary itself and the second is the user folders for user-installed content. -When you first run Binary Ninja, it will prompt you for your license key. You should have received your license key via email after your purchase. If not, please contact [support]. +### Binary Path + +Binaries are installed in the following locations by default: + +- OS X: `/Applications/Binary Ninja.app` +- Windows: `C:\Program Files\Vector35\BinaryNinja` +- Linux: Wherever you extract it! (No standard location) -Once the license key is installed, you can change it, back it up, or otherwise inspect it simply by looking in: +!!! Warning "Warning" + Do not put any user content in the install-path of Binary Ninja. The auto-update process of Binary Ninja may replace any files included in these folders. + +### User Folder + +The base locations of user folders are: - OS X: `~/Library/Application Support/Binary Ninja` - Linux: `~/.binaryninja` - Windows: `%APPDATA%\Binary Ninja` +Contents of the user folder includes: + +- `settings.json`: Advanced settings (see [settings](#settings)) +- `lastrun`: A text file containing the directory of the last BinaryNinja binary path -- very useful for plugins to resolve the install locations in non-default settings or on linux. +- `plugins/`: Folder containing all manually installed user plugins +- `repositories/`: Folder containing files and plugins managed by the [Plugin Manager API](https://api.binary.ninja/binaryninja.pluginmanager-module.html) + +![license popup >](/images/license-popup.png "License Popup") + +## License + +When you first run Binary Ninja, it will prompt you for your license key. You should have received your license key via email after your purchase. If not, please contact [support]. + +Once the license key is installed, you can change it, back it up, or otherwise inspect it simply by looking inside the base of the user folder for `license.dat`. + + ## Linux Setup Because linux install locations can vary widely, we do not assume a Binary Ninja has been installed in any particular folder on linux. Rather, you can simply run `binaryninja/scripts/linux-setup.sh` after extracting the zip and various file associations, icons, and other settings will be set up. Run it with `-h` to see the customization options. @@ -252,6 +279,4 @@ Below is an example `settings.json` setting various options: ``` ## Getting Support -Vector 35 offers a number of ways to get Binary Ninja [support]. - -[support]: https://binary.ninja/support/ +Vector 35 offers a number of ways to get Binary Ninja [support](https://binary.ninja/support/). diff --git a/docs/guide/type.md b/docs/guide/type.md index e69de29b..65121864 100644 --- a/docs/guide/type.md +++ b/docs/guide/type.md @@ -0,0 +1,2 @@ +# Types and Structures + -- cgit v1.3.1