diff --git a/docs/dev/plugins.md b/docs/dev/plugins.md index cd320784d..a9b74b270 100644 --- a/docs/dev/plugins.md +++ b/docs/dev/plugins.md @@ -14,18 +14,37 @@ To start, we suggest you download the [sample plugin](https://github.com/Vector3 - For small scripts, you can include all the code inside `__init__.py`, though we recommend for larger scripts that `__init__.py` just act as an initializer and calls into functions organized appropriately in other files. - If you have python dependencies, create a [requirements.txt](https://pip.pypa.io/en/latest/cli/pip_freeze/) listing any python dependencies. -### Submitting to the Plugin Manager +### Plugin Description Display -If your plugin was created as described above, there's only two steps to get it submitted to the plugin manager! +Binary Ninja displays plugin descriptions differently depending on the contents of the `plugin.json` file. + +- If `longdescription` exists **and is longer than 100 characters**, the Extension Manager displays the `longdescription`. +- If `longdescription` is missing, or is **100 characters or fewer**, the Extension Manager instead displays the contents of the plugin repository's `README.md`. + +**Tip:** If you want the Extension Manager to display your full README as the plugin description, leave the `longdescription` field blank. When longdescription is omitted, Binary Ninja falls back to displaying the contents of your `README.md`, which generally provides a richer and better-formatted description of your plugin. + +### Images in README Files + +When you include images for preview in the Extension Manager, be aware that animated gifs are not fully supported. They will be rendered as static images of the first frame. + +Additionally, all images should be included using FULL GitHub URLs as they will not render in the Extension Manager without that. + +For example: + +![](https://raw.githubusercontent.com/Vector35/6502/refs/heads/master/media/nes.png) + +### Submitting to the Extension Manager + +If your plugin was created as described above, there's only two steps to get it submitted to the Extension Manager! 1. First, create a release either [manually](https://binary.ninja/2019/07/04/plugin-manager-2.0.html#5-create-a-release) or using our [release helper](https://github.com/Vector35/release_helper). -1. Next, just [file an issue](https://github.com/Vector35/community-plugins/issues/new/choose) letting us know about your plugin. +2. Next, just [file an issue](https://github.com/Vector35/community-plugins/issues/new/choose) letting us know about your plugin. For future releases all you need to do is increment the version and create a new release. ### Using Your Own Plugin Repository -The simplest way to run your own plugin repository using the new V2 plugin manager is to use the [mock server](https://github.com/Vector35/binaryninja-api/blob/dev/python/examples/mock_extension_server.py) helper script (a copy is available offline as well in the install path, in the python exapmle scripts subfolder). +The simplest way to run your own plugin repository using the new Extension Manager is to use the [mock server](https://github.com/Vector35/binaryninja-api/blob/dev/python/examples/mock_extension_server.py) helper script (a copy is available offline as well in the install path, in the python exapmle scripts subfolder). Once you've created your test repository, use the `pluginManager.unofficialName` and `pluginManager.unofficialUrl` settings to add your third-party repository. @@ -381,9 +400,9 @@ There are a few other options you can use to assist in debugging: As a footnote, it should be noted that most of the team at Vector 35 use VSCode as a bare text editor and use command-line lldb or gdb to debug their code. Shout-outs to people trying to get this working in Vim. -## Submitting to the plugin manager +## Submitting to the Extension Manager -While native plugins are not fully supported in the plugin manager at this time, it's possible to work around this limitation by pre-building a native plugin for all three platforms and using a python plugin that acts as a loader for the native plugin. Additionally, you can submit a plugin as "view_only" which helps with discoverability. +While native plugins are not fully supported in the Extension Manager at this time, it's possible to work around this limitation by pre-building a native plugin for all three platforms and using a python plugin that acts as a loader for the native plugin. Additionally, you can submit a plugin as "view_only" which helps with discoverability. ## Examples diff --git a/docs/guide/index.md b/docs/guide/index.md index 26d13b5a7..2b9286ca9 100644 --- a/docs/guide/index.md +++ b/docs/guide/index.md @@ -34,7 +34,7 @@ The contents of the user folder includes: - `lastrun`: A text file containing the directory of the last Binary Ninja binary path -- very useful for plugins to resolve the installation locations in non-default settings or on Linux - `license.dat`: License file - `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) +- `repositories/`: Folder containing files and plugins managed by the [Extension Manager API](https://api.binary.ninja/binaryninja.pluginmanager-module.html) - `settings.json`: User settings file (see [settings](settings.md)) The following files and folders may be created in the user folder but are not created by default without some additional action: @@ -42,7 +42,7 @@ The following files and folders may be created in the user folder but are not cr - `keybindings.json`: Custom key bindings (see [key bindings](#custom-hotkeys)) - `startup.py`: Default Python commands run once the UI is loaded in the context of the scripting console - `signatures/`: Any user-created signatures can be stored in platform-specific sub-folders in this location -- `pythonVER/`: Any pip dependencies from plugin manager plugins are installed to the appropriate Python version subfolder such as `python310`, or `python311` +- `pythonVER/`: Any pip dependencies from Extension Manager plugins are installed to the appropriate Python version subfolder such as `python310`, or `python311` - `symbols/`: Used to store automatically downloaded PDBs - `update/`: Used to store update caches for pending updates - `snippets/`: Used to store snippets created using the official Snippet plugin @@ -243,13 +243,13 @@ The status of currently installed plugins will be displayed in the bottom right. ![plugin status ><](../img/plugin-status-widget.png "Plugin Status Widget"){ width="400" } -Pressing each of the icons will navigate you to the Plugin Manager with the corresponding filter: +Pressing each of the icons will navigate you to the Extension Manager with the corresponding filter: - Green Circle: `@installed` - Error Symbol: `@failed_to_load` - Update Icon: `@update_available` -Pressing the gear or using the hotkeys (macOS: `[CMD+SHIFT] + M`, Windows/Linux: `[CTRL+SHIFT] + M`) will open the plugin manager with no filters, so you can browse available plugins. +Pressing the gear or using the hotkeys (macOS: `[CMD+SHIFT] + M`, Windows/Linux: `[CTRL+SHIFT] + M`) will open the Extension Manager with no filters, so you can browse available plugins. ### Commercial/Ultimate Features @@ -662,68 +662,6 @@ To search in the keybindings list, just click to make sure it's focused and star - `[CTRL-SHIFT] -` (Windows/Linux) : Graph view zoom out - Other hotkeys specifically for working with types are listed in the [type guide](types/type.md#direct-ui-manipulation) -## Graph View - -![graph view](../img/graphview.png "Graph View"){ width="800" } - -Binary Ninja offers a graph view that groups the basic blocks of disassembly into visually distinct blocks with edges showing control flow between them. - -Features of the graph view include: - -- Ability to double-click edges to quickly jump between locations -- Zoom (CTRL-mouse wheel) -- Zoom to Fit - Zooms out until the whole graph is visible (`w`) -- Zoom to Cursor - Zooms to 100% at the position of the cursor (`z`) -- Vertical Scrolling (Side scroll bar as well as mouse wheel) -- Horizontal Scrolling (Bottom scroll bar as well as SHIFT-mouse wheel) -- Individual highlighting of arguments, addresses, immediate values, types, etc. -- Full type signature of current function shown in an interactive header: - - Selecting elements in the header highlights them in the graph view - - Change type (`y`) and Rename (`n`) shortcuts work on elements in the header - - Reanalyze function button on left edge of the header -- Edge colors indicate whether the path is the true (green) or false (red) case of a conditional jump (a color-blind option in the preferences is useful for those with red-green color blindness) and blue for unconditional branches -- Context menu that can trigger some function-wide actions as well as some specific to the highlighted instruction (such as inverting branch logic or replacing a specific function with a NOP) - -## View Options - -![options >](../img/options.png "View options"){ width="400" } - -Each of the views (Hex, Graph, Linear) have a variety of options configurable from the ☰ menu on the top right of the view pane. - -Current options include: - -- Hex (and Linear View where hex values are shown) - - Background highlight - - None - - Column - - Byte value - - Color highlight - - None - - ASCII and printable - - Modification - - Contrast - - Normal - - Medium - - Highlight -- Graph & Linear Views - - Expand Long Opcode - - Indent HLIL Function Body (HLIL only) - - Show Address - - Show Call Parameter Names (MLIL/HLIL only) - - Show Function Address - - Show Opcode Bytes - - Show Register Set Highlighting - - Show Type Casts (`[SHIFT+CMD/CTRL] + C`) - - Show Variable Types - - At Assignment (MLIL graph only) - - At Top of Function - - Single Function View - - Advanced - - Show All Expression Types (MLIL/HLIL only) - - Show IL Flag Usage (Lifted IL only) - - Show IL Opcodes - - Show Stack Pointer Value (LLIL only) - ## Triage Summary ![triage summary](../img/triagesummary.png "Triage Summary"){ width="800" } @@ -805,31 +743,80 @@ clickable to navigate to the virtual address. Strings can be double-clicked to navigate to them, and the table can be sorted or the list filtered by typing in the search box. -## Byte Overview +## Views +Binary Ninja provides multiple views for analyzing a binary. Views can be switched using the view selector in the top-left corner of the main window. +![views](../img/views.png "Views"){ width="400" } -![byte overview](../img/byteoverview.png "Byte Overview"){ width="800" } +## View Options -The Byte Overview (or "Bytes" when selected in the view switcher) shows the binary (mapped or raw, depending on the -top-level selection) as a [Code Page 437](https://en.wikipedia.org/wiki/Code_page_437) view. This view is commonly used -by malware analysis researchers using the [Hiew](http://hiew.ru) tool. +![options >](../img/options.png "View options"){ width="400" } -While this view is less feature-rich than the Hex view, it allows for a much higher information density as every byte is -represented by one character as opposed to four total characters when in Hex view (including the space between hex -digits and the ASCII representation). +Each view provides options for customizing how information is displayed. View options can be accessed from the ☰ menu in the top-right corner of the view pane. -## Hex View +### Hex View Options -![hex](../img/hex.png "hex view"){ width="800" } +These options control the appearance of bytes and data displayed in Hex View. Some options are also available in Linear View when hex values are shown. -The hexadecimal view is useful for viewing raw binary files that may or may not even be executable binaries and allows direct editing of the binary contents in place, regardless of the type of the binary. Any changes made in hex view will be reflected in all other [open views](#tiling-panes) of the same binary. The lock button on the right edge of the bottom status bar must be toggled off (🔓) to perform any direct editing in hex view -- this is to prevent unintended modification of the binary by accidental pasting or typing. +#### Background Highlight -The hex view is particularly good for transforming data in various ways via the `Copy as`, `Transform`, and `Paste from` menus. Note that like any other edits, `Transform` menu options will transform the data in-place, but unlike other means of editing the binary, the transformation dialog will work even when the lock button is toggled on (🔒). +Controls the background highlighting applied to displayed bytes. -If you're using the hex view for a Binary View like ELF, Mach-O or PE, you probably want to make sure you're also in the `Raw` view if you want to see the file as it exists on disk in hex view. +- **None** - Disables background highlighting. +- **Column** - Highlights the column containing the selected byte. +- **Byte Value** - Highlights bytes based on their value. -### Live Preview +#### Color Highlight -Any changes made in the Hex view will take effect immediately in any other views open into the same file (new views can be created via the `Split to new tab`, or `Split to new window` options under `View`, or via [splitting panes](#tiling-panes)). This can, however, cause large amounts of re-analysis so be warned before making large edits or transformations in a large binary file. +Controls additional color highlighting applied to displayed bytes. + +- **None** - Disables color highlighting. +- **ASCII and Printable** - Highlights printable ASCII characters. +- **Modification** - Highlights modified bytes. + +#### Contrast + +Controls the contrast level used for highlighted bytes. + +- **Normal** - Uses the default contrast level. +- **Medium** - Applies increased contrast. +- **Highlight** - Applies the highest contrast level. + +### Graph and Linear View Options + +These options control how information is displayed in Graph View and Linear View. + +#### Display + +- **Expand Long Opcode** - Displays long instructions in their expanded form. +- **Show Address** - Displays instruction addresses. +- **Show Function Address** - Displays the starting address of each function. +- **Show Opcode Bytes** - Displays the raw instruction bytes alongside the disassembly. + +#### Variables and Types + +- **Show Call Parameter Names (MLIL/HLIL only)** - Displays parameter names for function calls. +- **Show Type Casts** (`Shift`+`Cmd`/`Ctrl`+`C`) - Displays explicit type casts in MLIL and HLIL views. +- **Show Variable Types** - Displays inferred variable types. + +Variable types can be displayed in one of two locations: + +- **At Assignment (MLIL Graph only)** - Displays variable types at the point where they are assigned. +- **At Top of Function** - Displays variable types at the beginning of the function. + +#### Layout + +- **Indent HLIL Function Body (HLIL only)** - Indents the body of High Level IL functions to improve readability. +- **Single Function View** - Restricts the view to the currently selected function. + +#### Advanced + +These options expose additional Intermediate Language information useful during advanced analysis. + +- **Show All Expression Types (MLIL/HLIL only)** - Displays all available expression type information. +- **Show IL Flag Usage (Lifted IL only)** - Displays flag usage in Lifted IL. +- **Show IL Opcodes** - Displays Intermediate Language opcode names. +- **Show Register Set Highlighting** - Highlights register set information in the current view. +- **Show Stack Pointer Value (LLIL only)** - Displays the stack pointer value for each Low Level IL instruction. ## Linear View @@ -839,6 +826,64 @@ Linear view is a hybrid view between a graph-based disassembly window and the ra Linear view is commonly used for identifying and adding type information for unknown data. To this end, as you scroll, you'll see data and code interspersed. Much like the graph view, you can turn on and off addresses via the command palette `Show Address` or the ☰ menu on the top right of the linear view pane. Many other [options](#view-options) are also available. +### High Level IL + +![HLIL Scoping Options >](../img/hlil-scope.png "HLIL Scoping Options"){ width="400" } + +Binary Ninja features a decompiler that produces High Level IL (HLIL) as output. HLIL is not intended to be a representation of the code in C, but some users prefer to have a more C-like scoping style. + +You can control the way HLIL appears in the settings. + +The different options are shown below: + +![HLIL Scoping Display](../img/hlil-braces.png "HLIL Scoping Display"){ width="500" } + +### Pseudo C + +![Pseudo C](../img/pseudo-c.png "Pseudo C View"){ width="800" } + +Binary Ninja offers an option to render the HLIL as a decompilation to "Pseudo C". This decompilation is intended to be more familiar to the user than the HLIL. It is not necessarily intended to be "compliant" C or even recompilable. In some cases, it may be possible to edit it into a form that a C compiler will accept, but the amount of effort required will vary widely, and no guarantee is made that it will be possible in all cases. + + +## Graph View + +![graph view](../img/graphview.png "Graph View"){ width="800" } + +Binary Ninja offers a graph view that groups the basic blocks of disassembly into visually distinct blocks with edges showing control flow between them. + +Features of the graph view include: + +- Ability to double-click edges to quickly jump between locations +- Zoom (CTRL-mouse wheel) +- Zoom to Fit - Zooms out until the whole graph is visible (`w`) +- Zoom to Cursor - Zooms to 100% at the position of the cursor (`z`) +- Vertical Scrolling (Side scroll bar as well as mouse wheel) +- Horizontal Scrolling (Bottom scroll bar as well as SHIFT-mouse wheel) +- Individual highlighting of arguments, addresses, immediate values, types, etc. +- Full type signature of current function shown in an interactive header: + - Selecting elements in the header highlights them in the graph view + - Change type (`y`) and Rename (`n`) shortcuts work on elements in the header + - Reanalyze function button on left edge of the header +- Edge colors indicate whether the path is the true (green) or false (red) case of a conditional jump (a color-blind option in the preferences is useful for those with red-green color blindness) and blue for unconditional branches +- Context menu that can trigger some function-wide actions as well as some specific to the highlighted instruction (such as inverting branch logic or replacing a specific function with a NOP) + + +## Hex View + +![hex](../img/hex.png "hex view"){ width="800" } + +The hexadecimal view is useful for viewing raw binary files that may or may not even be executable binaries and allows direct editing of the binary contents in place, regardless of the type of the binary. Any changes made in hex view will be reflected in all other [open views](#tiling-panes) of the same binary. The lock button on the right edge of the bottom status bar must be toggled off (🔓) to perform any direct editing in hex view -- this is to prevent unintended modification of the binary by accidental pasting or typing. + +The hex view is particularly good for transforming data in various ways via the `Copy as`, `Transform`, and `Paste from` menus. Note that like any other edits, `Transform` menu options will transform the data in-place, but unlike other means of editing the binary, the transformation dialog will work even when the lock button is toggled on (🔒). + +If you're using the hex view for a Binary View like ELF, Mach-O or PE, you probably want to make sure you're also in the `Raw` view if you want to see the file as it exists on disk in hex view. + + +### Live Preview + +Any changes made in the Hex view will take effect immediately in any other views open into the same file (new views can be created via the `Split to new tab`, or `Split to new window` options under `View`, or via [splitting panes](#tiling-panes)). This can, however, cause large amounts of re-analysis so be warned before making large edits or transformations in a large binary file. + + ## Edit Function Properties Dialog ![Edit Function Properties Dialog >](../img/efp-dialog-diagram.png "Edit Function Properties Dialog"){ width="600" } @@ -903,23 +948,6 @@ This element is a table containing a row for each register stack (e.g. x87) in t This dropdown selects the [function-level workflow](https://docs.binary.ninja/dev/workflows.html#workflow) which is used to analyze this function. -## High Level IL - -![HLIL Scoping Options >](../img/hlil-scope.png "HLIL Scoping Options"){ width="400" } - -Binary Ninja features a decompiler that produces High Level IL (HLIL) as output. HLIL is not intended to be a representation of the code in C, but some users prefer to have a more C-like scoping style. - -You can control the way HLIL appears in the settings. - -The different options are shown below: - -![HLIL Scoping Display](../img/hlil-braces.png "HLIL Scoping Display"){ width="500" } - -## Pseudo C - -![Pseudo C](../img/pseudo-c.png "Pseudo C View"){ width="800" } - -Binary Ninja offers an option to render the HLIL as a decompilation to "Pseudo C". This decompilation is intended to be more familiar to the user than the HLIL. It is not necessarily intended to be "compliant" C or even recompilable. In some cases, it may be possible to edit it into a form that a C compiler will accept, but the amount of effort required will vary widely, and no guarantee is made that it will be possible in all cases. ## Dead Store Elimination @@ -1126,9 +1154,9 @@ See the [plugin development guide](../dev/plugins.md#debugging-using-other-ides) ## Using Plugins -Plugins can be installed by one of two methods. First, they can be installed via the Plugin Manager accessed via the `Plugins` / `Manage Plugins` menu or `[CMD/CTRL] m` hotkey. +Plugins can be installed by one of two methods. First, they can be installed via the Extension Manager accessed via the `Plugins` / `Manage Plugins` menu or `[CMD/CTRL] m` hotkey. -![plugin manager](../img/plugin-manager.png "Plugin Manager"){ width="1000" } +![Extension Manager](../img/plugin-manager.png "Extension Manager"){ width="1000" } Second, they can be manually installed by adding the plugin (either a `.py` file or a folder implementing a Python module with a `__init__.py` file) to the appropriate path: diff --git a/docs/guide/plugins.md b/docs/guide/plugins.md index c53c59036..6a5269566 100644 --- a/docs/guide/plugins.md +++ b/docs/guide/plugins.md @@ -10,11 +10,11 @@ Plugins are loaded from the user's plugin folder: Note that plugins installed via the [PluginManager API](https://api.binary.ninja/binaryninja.pluginmanager-module.html) are installed in the `repositories` folder in the same path as the previous `plugin` folder listed above. You should not need to manually adjust anything in that folder, but should access them via the API instead. -## Plugin Manager +## Extension Manager -![Plugin Manager](../img/plugin-manager.png "Plugin Manager"){ width="1000" } +![Extension Manager](../img/plugin-manager.png "Extension Manager"){ width="1000" } -Plugins can be installed directly via the GUI from Binary Ninja. You can launch the plugin manager via any of the following methods: +Plugins can be installed directly via the GUI from Binary Ninja. You can launch the Extension Manager via any of the following methods: - (Linux/Windows) `[CTRL-SHIFT-M]` - (macOS) `[CMD-SHIFT-M]` @@ -25,14 +25,14 @@ Plugins can be installed directly via the GUI from Binary Ninja. You can launch Or: - - (Linux/Windows) `[CTRL-P]` / `Plugin Manager` / `[ENTER]` - - (macOS) `[CMD-P]` / `Plugin Manager` / `[ENTER]` + - (Linux/Windows) `[CTRL-P]` / `Manage Plugins` / `[ENTER]` + - (macOS) `[CMD-P]` / `Manage Plugins` / `[ENTER]` Note that some plugins may show `Force Install` instead of the normal `Install` button. If that's the case, it means the plugin does not specifically advertise support for your platform or version of python. Often times the plugin will still work, but you must override a warning to confirm installation and be aware that the plugin may not be compatible. -### Plugin Manager Searching +### Extension Manager Searching -In addition to finding plugins by name or description content, the search box in the plugin manager also supports a number of helpful search keywords to filter through the list of plugins as it continues to grow: +In addition to finding plugins by name or description content, the search box in the Extension Manager also supports a number of helpful search keywords to filter through the list of plugins as it continues to grow: - `@installed` to only show installed plugins - `@enabled` to only show enabled plugins @@ -62,7 +62,7 @@ after cloning or else the necessary submodules will not actually be downloaded. ### Installing via the API -Binary Ninja includes a [PluginManager API](https://api.binary.ninja/binaryninja.pluginmanager-module.html) which can simplify the process of finding and installing plugins. From the console: +Binary Ninja includes a [ExtensionManager API](https://api.binary.ninja/binaryninja.pluginmanager-module.html) which can simplify the process of finding and installing plugins. From the console: ```python >>> mgr = RepositoryManager() @@ -87,7 +87,7 @@ Then just restart and the newly-enabled plugin will be loaded. ### Installing Prerequisites -Binary Ninja can automatically install pip requirements for python plugins installed using the plugin manager. If the plugin author has included a `requirements.txt` file, the plugin manager will automatically install those dependencies. +Binary Ninja can automatically install pip requirements for python plugins installed using the Extension Manager. If the plugin author has included a `requirements.txt` file, the Extension Manager will automatically install those dependencies. The `Install python3 module` action (available from the [command palette](index.md#command-palette)) can be used to install python3 modules to the local [python folder](index.md#user-folder). diff --git a/docs/img/views.png b/docs/img/views.png new file mode 100644 index 000000000..eb3ff548e Binary files /dev/null and b/docs/img/views.png differ