287 lines
16 KiB
HTML
287 lines
16 KiB
HTML
<!DOCTYPE html>
|
|
<!--[if IE 8]><html class="no-js lt-ie9" lang="en" > <![endif]-->
|
|
<!--[if gt IE 8]><!--> <html class="no-js" lang="en" > <!--<![endif]-->
|
|
<head>
|
|
<meta charset="utf-8">
|
|
<meta http-equiv="X-UA-Compatible" content="IE=edge">
|
|
<meta name="viewport" content="width=device-width, initial-scale=1.0">
|
|
|
|
<meta name="author" content="Vector 35 Inc">
|
|
<link rel="shortcut icon" href="../img/favicon.ico">
|
|
<title>Using and Writing Plugins - Binary Ninja User Documentation</title>
|
|
<link href='https://fonts.googleapis.com/css?family=Lato:400,700|Roboto+Slab:400,700|Inconsolata:400,700' rel='stylesheet' type='text/css'>
|
|
|
|
<link rel="stylesheet" href="../css/theme.css" type="text/css" />
|
|
<link rel="stylesheet" href="../css/theme_extra.css" type="text/css" />
|
|
<link rel="stylesheet" href="//cdnjs.cloudflare.com/ajax/libs/highlight.js/9.12.0/styles/github.min.css">
|
|
<link href="../docs.css?1535411025" rel="stylesheet">
|
|
|
|
<script>
|
|
// Current page data
|
|
var mkdocs_page_name = "Using and Writing Plugins";
|
|
var mkdocs_page_input_path = "guide/plugins.md";
|
|
var mkdocs_page_url = "/guide/plugins.html";
|
|
</script>
|
|
|
|
<script src="../js/jquery-2.1.1.min.js" defer></script>
|
|
<script src="../js/modernizr-2.8.3.min.js" defer></script>
|
|
<script src="//cdnjs.cloudflare.com/ajax/libs/highlight.js/9.12.0/highlight.min.js"></script>
|
|
<script src="//cdnjs.cloudflare.com/ajax/libs/highlight.js/9.12.0/languages/cpp.min.js"></script>
|
|
<script src="//cdnjs.cloudflare.com/ajax/libs/highlight.js/9.12.0/languages/python.min.js"></script>
|
|
<script>hljs.initHighlightingOnLoad();</script>
|
|
|
|
<script>
|
|
(function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){
|
|
(i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o),
|
|
m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m)
|
|
})(window,document,'script','https://www.google-analytics.com/analytics.js','ga');
|
|
|
|
ga('create', 'UA-72420552-3', 'docs.binary.ninja');
|
|
ga('send', 'pageview');
|
|
</script>
|
|
|
|
</head>
|
|
|
|
<body class="wy-body-for-nav" role="document">
|
|
|
|
<div class="wy-grid-for-nav">
|
|
|
|
|
|
<nav data-toggle="wy-nav-shift" class="wy-nav-side stickynav">
|
|
<div class="wy-side-nav-search">
|
|
<a href="../index.html" class="icon icon-home"> Binary Ninja User Documentation</a>
|
|
<div role="search">
|
|
<form id ="rtd-search-form" class="wy-form" action="../search.html" method="get">
|
|
<input type="text" name="q" placeholder="Search docs" title="Type search term here" />
|
|
</form>
|
|
</div>
|
|
</div>
|
|
|
|
<div class="wy-menu wy-menu-vertical" data-spy="affix" role="navigation" aria-label="main navigation">
|
|
<ul class="current">
|
|
|
|
|
|
<li class="toctree-l1">
|
|
|
|
<a class="" href="../index.html">Home</a>
|
|
</li>
|
|
|
|
<li class="toctree-l1">
|
|
|
|
<a class="" href="../getting-started.html">Getting Started Guide</a>
|
|
</li>
|
|
|
|
<li class="toctree-l1">
|
|
|
|
<span class="caption-text">User Guide</span>
|
|
<ul class="subnav">
|
|
<li class=" current">
|
|
|
|
<a class="current" href="plugins.html">Using and Writing Plugins</a>
|
|
<ul class="subnav">
|
|
|
|
<li class="toctree-l3"><a href="#plugins">Plugins</a></li>
|
|
|
|
<ul>
|
|
|
|
<li><a class="toctree-l4" href="#using-plugins">Using Plugins</a></li>
|
|
|
|
<li><a class="toctree-l4" href="#writing-plugins">Writing Plugins</a></li>
|
|
|
|
</ul>
|
|
|
|
|
|
</ul>
|
|
</li>
|
|
<li class="">
|
|
|
|
<a class="" href="troubleshooting.html">Troubleshooting</a>
|
|
</li>
|
|
</ul>
|
|
</li>
|
|
|
|
<li class="toctree-l1">
|
|
|
|
<span class="caption-text">Developer Guide</span>
|
|
<ul class="subnav">
|
|
<li class="">
|
|
|
|
<a class="" href="../dev/documentation.html">Contributing Documentation</a>
|
|
</li>
|
|
<li class="">
|
|
|
|
<a class="" href="../dev/bnil-llil.html">BNIL Guide: LLIL</a>
|
|
</li>
|
|
</ul>
|
|
</li>
|
|
|
|
<li class="toctree-l1">
|
|
|
|
<span class="caption-text">About</span>
|
|
<ul class="subnav">
|
|
<li class="">
|
|
|
|
<a class="" href="../about/license.html">License</a>
|
|
</li>
|
|
<li class="">
|
|
|
|
<a class="" href="../about/open-source.html">Open Source</a>
|
|
</li>
|
|
</ul>
|
|
</li>
|
|
|
|
</ul>
|
|
</div>
|
|
|
|
</nav>
|
|
|
|
<section data-toggle="wy-nav-shift" class="wy-nav-content-wrap">
|
|
|
|
|
|
<nav class="wy-nav-top" role="navigation" aria-label="top navigation">
|
|
<i data-toggle="wy-nav-top" class="fa fa-bars"></i>
|
|
<a href="../index.html">Binary Ninja User Documentation</a>
|
|
</nav>
|
|
|
|
|
|
<div class="wy-nav-content">
|
|
<div class="rst-content">
|
|
<div role="navigation" aria-label="breadcrumbs navigation">
|
|
<ul class="wy-breadcrumbs">
|
|
<li><a href="../index.html">Docs</a> »</li>
|
|
|
|
|
|
|
|
<li>User Guide »</li>
|
|
|
|
|
|
|
|
<li>Using and Writing Plugins</li>
|
|
<li class="wy-breadcrumbs-aside">
|
|
|
|
</li>
|
|
</ul>
|
|
<hr/>
|
|
</div>
|
|
<div role="main">
|
|
<div class="section">
|
|
|
|
<h1 id="plugins">Plugins<a class="headerlink" href="#plugins" title="Permanent link">¶</a></h1>
|
|
<p>Plugins really show off the power of Binary Ninja. This guide should help give you an overview of both using and writing plugins.</p>
|
|
<p>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 <a href="https://github.com/Vector35/binaryninja-api/tree/dev/examples">C++ examples</a> are included in the API repository. </p>
|
|
<h2 id="using-plugins">Using Plugins<a class="headerlink" href="#using-plugins" title="Permanent link">¶</a></h2>
|
|
<p>Plugins are loaded from the user's plugin folder: </p>
|
|
<ul>
|
|
<li>OS X: <code>~/Library/Application Support/Binary Ninja/plugins/</code></li>
|
|
<li>Linux: <code>~/.binaryninja/plugins/</code></li>
|
|
<li>Windows: <code>%APPDATA%\Binary Ninja\plugins</code></li>
|
|
</ul>
|
|
<p>Note that plugins installed via the <a href="https://api.binary.ninja/binaryninja.pluginmanager-module.html">PluginManager API</a> are installed in the <code>repositories</code> folder in the same path as the previous <code>plugin</code> folder listed above. You should not need to manually touch anything in that folder, but should access them via the API instead. </p>
|
|
<h3 id="manual-installation">Manual installation<a class="headerlink" href="#manual-installation" title="Permanent link">¶</a></h3>
|
|
<p>You can manually install a plugin either by adding a folder which contains it (the plugin folder must contain an <code>__init__.py</code> at the top of the folder, or a python file can be included directly in the plugin folder though this is not recommended).</p>
|
|
<p>Note, if manually cloning the <a href="https://github.com/Vector35/binaryninja-api">api repository</a>, make sure to:</p>
|
|
<div class="codehilite"><pre><span></span>git submodule update --init --recursive
|
|
</pre></div>
|
|
|
|
|
|
<p>after cloning or else the submodules will not actually be downloaded. </p>
|
|
<h3 id="installing-via-the-api">Installing via the API<a class="headerlink" href="#installing-via-the-api" title="Permanent link">¶</a></h3>
|
|
<p>(NOTE THAT THIS API IS TEMPORARILY DISABLED TO BETTER SUPPORT A WIDER VARIETY OF LINUX DISTRIBUTIONS)</p>
|
|
<p>Binary Ninja now offers a <a href="https://api.binary.ninja/binaryninja.pluginmanager-module.html">PluginManager API</a> which can simplify the process of finding and installing plugins. From the console:</p>
|
|
<div class="codehilite"><pre><span></span>>>> 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': [<binaryninja-bookmarks not-installed/disabled>, <binaryninja-msp430 not-installed/disabled>, <binaryninja-radare2 not-installed/disabled>, <binaryninja-spu not-installed/disabled>, <binja-avr not-installed/disabled>, <binja_smali not-installed/disabled>, <binjatron not-installed/disabled>, <binoculars not-installed/disabled>, <easypatch not-installed/disabled>, <liil installed/enabled>, <list_comments not-installed/disabled>, <x64dbgbinja not-installed/disabled>]}
|
|
>>> mgr.install_plugin("easypatch")
|
|
True
|
|
>>> mgr.enable_plugin("easypatch")
|
|
True
|
|
</pre></div>
|
|
|
|
|
|
<p>Then just restart, and your plugin will be loaded. </p>
|
|
<h3 id="installing-prerequisites">Installing Prerequisites<a class="headerlink" href="#installing-prerequisites" title="Permanent link">¶</a></h3>
|
|
<p>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 <code>sys.path</code> 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:</p>
|
|
<div class="codehilite"><pre><span></span><span class="kn">import</span> <span class="nn">pip</span>
|
|
<span class="n">pip</span><span class="o">.</span><span class="n">main</span><span class="p">([</span><span class="s1">'install'</span><span class="p">,</span> <span class="s1">'--quiet'</span><span class="p">,</span> <span class="s1">'packagename'</span><span class="p">])</span>
|
|
</pre></div>
|
|
|
|
|
|
<p><em>--quiet is required to minimize some of the normal output of pip that doesn't work within the context of our scripting console</em></p>
|
|
<p>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.</p>
|
|
<h3 id="troubleshooting">Troubleshooting<a class="headerlink" href="#troubleshooting" title="Permanent link">¶</a></h3>
|
|
<p>Troubleshooting many Binary Ninja problems is helped by enabling debug logs and logging the output to a file. Just launch Binary Ninja with </p>
|
|
<div class="codehilite"><pre><span></span>/Applications/Binary\ Ninja.app/Contents/MacOS/binaryninja -d -l /tmp/bnlog.txt
|
|
</pre></div>
|
|
|
|
|
|
<p>And check <code>/tmp/bnlog.txt</code> when you're done. </p>
|
|
<h2 id="writing-plugins">Writing Plugins<a class="headerlink" href="#writing-plugins" title="Permanent link">¶</a></h2>
|
|
<p>First, take a look at some of the <a href="https://github.com/Vector35/binaryninja-api/tree/dev/python/examples">example</a> plugins, or some of the <a href="https://github.com/Vector35/community-plugins">community</a> plugins to get a feel for different APIs you might be interested in. Of course, the full <a href="https://api.binary.ninja/">API</a> docs are online and available offline via the <code>Help</code>/<code>Open API Reference...</code>.</p>
|
|
<p>To start, we suggest you download the <a href="https://github.com/Vector35/sample_plugin">sample plugin</a> as a template since it contains all of the elements you're likely to need.</p>
|
|
<ul>
|
|
<li>Begin by editing the <code>plugin.json</code> file </li>
|
|
<li>Next, update the <code>LICENSE</code></li>
|
|
<li>For small scripts, you can include all the code inside of <code>__init__.py</code>, though we recommend for most larger scripts that init just act as an initializer and call into functions organized appropriately in other files.</li>
|
|
</ul>
|
|
<h3 id="plugin-debugging-mode">Plugin Debugging Mode<a class="headerlink" href="#plugin-debugging-mode" title="Permanent link">¶</a></h3>
|
|
<p>Available via the [preferences] dialog, enabling plugin debugging mode will not only enable additional IL types via the UI.</p>
|
|
<h3 id="ui-elements">UI Elements<a class="headerlink" href="#ui-elements" title="Permanent link">¶</a></h3>
|
|
<p>While it is possible to use Qt to directly create <a href="https://github.com/NOPDev/BinjaDock">UI enhancements</a> 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.</p>
|
|
<p>The officially supported mechanism (until the 1.2 release which will include much more featureful UI API enhancements) are available from the <a href="https://api.binary.ninja/binaryninja.interaction-module.html">interaction API</a> and shown off in the <a href="https://github.com/Vector35/binaryninja-api/blob/dev/python/examples/angr_plugin.py">angr</a> and <a href="https://github.com/kenoph/nampa">nampa</a> plugins.</p>
|
|
<h3 id="testing">Testing<a class="headerlink" href="#testing" title="Permanent link">¶</a></h3>
|
|
<p>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 <code>import binaryninja</code> after <a href="https://github.com/Vector35/binaryninja-api/blob/dev/scripts/install_api.py">installing the API</a>. (install_api.py is included in every install in the installation folder)</p>
|
|
<p>For the Personal edition, we recommend simply commenting out the <code>register_</code> 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 <code>reload</code> 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. </p>
|
|
|
|
</div>
|
|
</div>
|
|
<footer>
|
|
|
|
<div class="rst-footer-buttons" role="navigation" aria-label="footer navigation">
|
|
|
|
<a href="troubleshooting.html" class="btn btn-neutral float-right" title="Troubleshooting">Next <span class="icon icon-circle-arrow-right"></span></a>
|
|
|
|
|
|
<a href="../getting-started.html" class="btn btn-neutral" title="Getting Started Guide"><span class="icon icon-circle-arrow-left"></span> Previous</a>
|
|
|
|
</div>
|
|
|
|
|
|
<hr/>
|
|
|
|
<div role="contentinfo">
|
|
<!-- Copyright etc -->
|
|
|
|
<p>(<a href="https://creativecommons.org/licenses/by/3.0/">cc</a>) Vector 35 Inc</p>
|
|
|
|
</div>
|
|
|
|
Built with <a href="http://www.mkdocs.org">MkDocs</a> using a <a href="https://github.com/snide/sphinx_rtd_theme">theme</a> provided by <a href="https://readthedocs.org">Read the Docs</a>.
|
|
</footer>
|
|
|
|
</div>
|
|
</div>
|
|
|
|
</section>
|
|
|
|
</div>
|
|
|
|
<div class="rst-versions" role="note" style="cursor: pointer">
|
|
<span class="rst-current-version" data-toggle="rst-current-version">
|
|
|
|
|
|
<span><a href="../getting-started.html" style="color: #fcfcfc;">« Previous</a></span>
|
|
|
|
|
|
<span style="margin-left: 15px"><a href="troubleshooting.html" style="color: #fcfcfc">Next »</a></span>
|
|
|
|
</span>
|
|
</div>
|
|
<script>var base_url = '..';</script>
|
|
<script src="../js/theme.js" defer></script>
|
|
<script src="../search/main.js" defer></script>
|
|
|
|
</body>
|
|
</html>
|