diff options
| author | Jordan Wiens <jordan@psifertex.com> | 2024-02-19 15:04:00 -0500 |
|---|---|---|
| committer | Jordan Wiens <jordan@psifertex.com> | 2024-02-23 11:14:06 -0500 |
| commit | 448f40be71dffa86a6581c3696627ccc1bdf74f2 (patch) | |
| tree | cd79923c85986c0135b41eb7432e54218f1a56e5 /docs/guide | |
| parent | 748c2295e31c03afa1d4b1b776a59f9fa9a48d34 (diff) | |
4.0 documentation
- Refactored Type Documentation
- Added Projects
- Added Type Archives
- Added New Sidebar Documentation
- Added String Concepts
- Added Light/Dark Mode
- Added New Tab Documentation
- Added BNIL Guide: HLIL docs
- Added new cookbook examples
- Added migration guide
- Added script for building docsets
- Added documentation for themes
- Updated all images to Ninja Edit
- API Docs : Documents BasicBlockEdge and BasicBlock
- API Docs : Documents CoreVariable, Variable, and VariableNameAndType
- API Docs : Corrects note on `BinaryView.update_analysis` and `BinaryView.update_analysis_and_wait` to represent that analysis is run by default for you now.
- Many, many other changes
Diffstat (limited to 'docs/guide')
| -rw-r--r-- | docs/guide/index.md | 590 | ||||
| -rw-r--r-- | docs/guide/migration/index.md | 21 | ||||
| -rw-r--r-- | docs/guide/migration/migrationguideghidra.md | 119 | ||||
| -rw-r--r-- | docs/guide/migration/migrationguideida.md | 66 | ||||
| -rw-r--r-- | docs/guide/objectivec.md | 4 | ||||
| -rw-r--r-- | docs/guide/plugins.md | 2 | ||||
| -rw-r--r-- | docs/guide/projects.md | 122 | ||||
| -rw-r--r-- | docs/guide/settings.md | 98 | ||||
| -rw-r--r-- | docs/guide/troubleshooting.md | 2 | ||||
| -rw-r--r-- | docs/guide/type.md | 363 | ||||
| -rw-r--r-- | docs/guide/types/basictypes.md | 173 | ||||
| -rw-r--r-- | docs/guide/types/cpp.md (renamed from docs/guide/cpp.md) | 18 | ||||
| -rw-r--r-- | docs/guide/types/debuginfo.md (renamed from docs/guide/debuginfo.md) | 2 | ||||
| -rw-r--r-- | docs/guide/types/index.md | 18 | ||||
| -rw-r--r-- | docs/guide/types/platformtypes.md | 42 | ||||
| -rw-r--r-- | docs/guide/types/type.md | 88 | ||||
| -rw-r--r-- | docs/guide/types/typearchives.md | 47 | ||||
| -rw-r--r-- | docs/guide/types/typeimportexport.md | 184 | ||||
| -rw-r--r-- | docs/guide/types/typelibraries.md | 37 |
19 files changed, 1358 insertions, 638 deletions
diff --git a/docs/guide/index.md b/docs/guide/index.md index 476e214d..58717818 100644 --- a/docs/guide/index.md +++ b/docs/guide/index.md @@ -1,15 +1,16 @@ -# User Manual +# User Guide -Welcome to the Binary Ninja User Manual. You'll notice two menus here. On the right is the table of contents for this main page of the user manual. On the left are links to larger topics that have their own pages, including: +Welcome to the Binary Ninja User Guide. You'll notice two menus here. On the right is the table of contents for this main page of the user manual. On the left are links to larger topics that have their own pages, including: - [Plugins](plugins.md) - [Settings](settings.md) -- [Types](type.md) -- [C++ Types](cpp.md) -- [Debug Info](debuginfo.md) -- [Debugger](debugger.md) -- [Objective C](objectivec.md) +- [Projects](projects.md) - [Troubleshooting](troubleshooting.md) +- [Objective-C](objectivec.md) +- [Debugger](debugger/index.md) +- [Migration Guide](migration/index.md) +- [Types](types/index.md) +[comment]: <> (When changing this list, make sure to update mkdocs.yml as well) ## Directories @@ -25,7 +26,7 @@ Binaries are installed in the following locations by default: - Windows (user install): `%LOCALAPPDATA%\Vector35\BinaryNinja` ???+ Warning "Tip" - If you want a silent install on windows, because we use the [NSIS](https://nsis.sourceforge.io/Docs/) installer, simply use: `BinaryNinjaInstaller.exe /S` + If you want a silent install on Windows, because we use the [NSIS](https://nsis.sourceforge.io/Docs/) installer, simply use: `BinaryNinjaInstaller.exe /S` ???+ Danger "Warning" Do not put any user content in the install-path of Binary Ninja. The auto-update process of Binary Ninja WILL remove any files included in these locations. @@ -40,7 +41,7 @@ While the default user folders are listed below, you can override these paths on The contents of the user folder includes: -- `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 +- `lastrun`: A text file containing the directory of the last Binary Ninja binary path -- very useful for plugins to resolve the install 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) @@ -55,19 +56,20 @@ The following files and folders may be created in the user folder but are not cr - `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 -- `themes/`: For user themes or user-modified versions of official themes -- `types/platform`: This folder can contain additional user [platform types](type.md#platform-types) -- `community-themes/`: Can also be used to store themes, useful to clone the [plugin theme collection](https://github.com/vector35/community-themes) directly into your user folder +- `themes/`: For user themes or user-modified versions of official themes (see [Creating Themes](../dev/themes.md)) +- `types/platform`: This folder can contain additional user [platform types](types/platformtypes.md) +- `typelib`: This folder can contain additional user [Type Libraries](../dev/annotation.md#type-libraries) +- `community-themes/`: Can also be used to store themes, particularly so you can clone the [community theme collection](https://github.com/vector35/community-themes) directly into your user folder ### QSettings Locations -Some settings such as window locations, saved checkboxes, recent file lists, disassembly settings, dialog histories are stored in QSettings. +Some settings such as window locations, saved checkboxes, recent file lists, disassembly settings, dialog histories are stored in `QSettings`. If you ever have the need to flush these, you can find the install locations as described in the [QT documentation](https://doc.qt.io/qt-6/qsettings.html#platform-specific-notes). ## License - +{ width="400" } 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](https://binary.ninja/support). @@ -79,9 +81,9 @@ Because Linux install locations can vary widely, we do not assume that Binary Ni ## Loading Files -You can load files in many ways: +{ width="600" } - +You can load files in many ways: 1. Drag-and-drop a file onto the Binary Ninja window (hold `[CMD/CTRL-SHIFT]` while dropping to use the `Open with Options` workflow) 2. Use the `File/Open` menu or `Open` button on the start screen (`[CMD/CTRL] o`) @@ -101,7 +103,7 @@ You can load files in many ways: ## Saving Files - +{ width="400" } There are five menu items that can be used to save some combination of a raw file or a file's analysis information. Analysis information is saved into files that end in `.bndb` and have the same prefix as the original file. The default behavior for each of the "save" menu choices is described below: @@ -116,17 +118,54 @@ There are five menu items that can be used to save some combination of a raw fil - If you choose to save the analysis database, it behaves similarly to "Save" above, except for the cases that save without prompt. In those cases, you will _always_ be prompted for a filename. - If you choose to save the file contents only, you will be prompted for a filename to which to save the current contents of the binary view, including any modifications. -3. "Save All" - Used to save multiple tabs worth of analysis data only. Does not save file contents. +3. "Save All" - Used to save multiple tabs worth of analysis data only. Does not save file contents. 4. "Save Analysis Database" - Will prompt to select a database to save analysis information if none is currently selected and in use, and will save without a prompt if one has already been selected. -  - 5. "Save Analysis Database With Options" - Allows for saving a `.bndb` without additional undo information, or by cleaning up some internal snapshot information to decrease the file size. +{ width="600" } + +## New Files + +When you create a new file, you're given the [hex view](index.md#hex-view) of an empty file. From here you can manually type in hexadecimal or ascii values, or paste in data in a variety of ways. To type in hex, make sure the left-side is focused, to type in ascii, just focus the right-side using the mouse or the "tab" key. The only way to enter a tab character into the ascii section is to enter "09" in the hex side. + +To paste, right click anywhere in the view, select "Paste From," and choose whichever option matches the data you copied. For example, the string `\x01\x02\x03\x04` can be pasted as an Escape String, while `01020304` is Raw Hex. + +From here, you can save the contents of your new binary to disk and reopen it for auto-analysis. Of course, you could also switch out of hex view and start creating functions yourself. + +## New Tab + +{ width="800" } + +The New Tab is the first view shown when starting the application. It contains a set of buttons with common actions for loading and creating files, +and a list of recent files you've opened. + +{ width="700" } + +A "Compact Mode" exists which presents only file paths. This can be enabled and disabled from the right-click menu. Additionally, within Binary Ninja settings, `CompactBase` mode can be enabled, which only shows the filenames. + +### Recent Files + +Recent files can be opened on double click. They can also be navigated using the arrow keys, and opened via pressing enter. Opening a recent file using `[SHIFT+ENTER]` will open that file with the Open With Options dialog. + +The Recent files list can be cleared via using the Command Palette (`[CTRL] + P`) action `Clear Recently Opened`. + +Hotkeys (macOS: `[CMD] + 0` - `[CMD] + 9`, Windows/Linux: `[CTRL] + 0` - `[CTRL + 9]`) can also be used to quickly open a file. The hotkey for a given entry will be shown on the right. + +### Commercial/Enterprise Features + +{ width="700" } + +On Commercial and Enterprise, the New Tab file list also contains a separate tab for Recent Projects. These tabs can be docked, rearranged, split, or unified, and their split is adjustable. Layout changes will be saved. + +While Projects themselves are presented in their own tab, files opened in Projects will be located in the usual Recent Files list. + +Project names are formatted as `[Project] Project Name Here` while project files are formatted as `[Project Name Here] File Name Here`. + ## Status Bar - <!-- this image needs updating to reflect new status bar --> +{ width="800" } The status bar provides current information about the open file as well as some interactive controls. Summary features are listed below: @@ -135,7 +174,7 @@ The status bar provides current information about the open file as well as some * Cursor offset or selection - interactive control that can be clicked to change its display format, or also to copy the current address or selection in a number of different formats (see the below screenshot) * File Contents Lock - interactive control to prevent accidental changes to the underlying file - <!-- this image needs updating to reflect new status bar --> + ## Analysis @@ -159,49 +198,238 @@ Additionally, using the [open with options](#loading-files) feature allows for c ## Navigating - -Navigating code in Binary Ninja is usually a case of just double-clicking where you want to go. Addresses, references, functions, jump edges etc, can all be double-clicked to navigate. Additionally, the `g` hotkey can navigate to a specific address in the current view. Syntax for this field is very flexible. Full expressions can be entered including basic arithmetic, dereferencing, and name resolution (function names, data variable names, segment names, etc). Numerics default to hexadecimal but that can be controlled as well if you wish to use octal decimal or other base/radix. Full documentation on the syntax of this field can be found [here](https://api.binary.ninja/binaryninja.binaryview-module.html?highlight=parse_expression#binaryninja.binaryview.BinaryView.parse_expression). +{ width="600" } +Navigating code in Binary Ninja is usually a case of just double-clicking where you want to go. Addresses, references, functions, jump edges etc., can all be double-clicked to navigate. Additionally, the `g` hotkey can navigate to a specific address in the current view. Syntax for this field is very flexible. Full expressions can be entered including basic arithmetic, dereferencing, and name resolution (function names, data variable names, segment names, etc.). Numerics default to hexadecimal, but that can be controlled as well if you wish to use octal decimal or other base/radix. Full documentation on the syntax of this field can be found [here](https://api.binary.ninja/binaryninja.binaryview-module.html?highlight=parse_expression#binaryninja.binaryview.BinaryView.parse_expression). -Additionally, middle-clicking (scroll-wheel clicking) items that can be double-clicked can be used to navigate to that location in a new Split Pane. Shift + middle-click can also be used to navigate to that location in a new Tab. These bindings can be configured in the Settings ([ui.middleClickNavigationAction](settings.md#ui.middleClickNavigationAction), [ui.middleClickShiftNavigationAction](settings.md#ui.middleClickShiftNavigationAction)). These "Split and Navigate" actions can also be accessed in the Context (right-click) menu, and can be separately bound to keys in the Keybindings view. +Additionally, middle-clicking (scroll-wheel clicking) items that can be double-clicked can be used to navigate to that location in a new Split Pane. Shift + middle-click can also be used to navigate to that location in a new Tab. These bindings can be configured in the Settings ([`ui.middleClickNavigationAction`](settings.md#ui.middleClickNavigationAction), [`ui.middleClickShiftNavigationAction`](settings.md#ui.middleClickShiftNavigationAction)). These "Split and Navigate" actions can also be accessed in the Context (right-click) menu, and can be separately bound to keys in the Keybindings view. There's also [many](#using-the-keyboard) keyboard-based navigation options. ### Switching Views - + -Switching views happens multiple ways. In some instances, it is automatic (clicking a data reference from graph view will navigate to linear view as data is not shown in the graph view), and there are multiple ways to manually change views as well. While navigating, you can use the view hotkeys (see below) to switch to a specific view at the same location as the current selection. Alternatively, the view menu in the header at the top of each pane can be used to change views without navigating to any given location. +Switching views happens multiple ways. In some instances, it is automatic, such as clicking a data reference from graph view. This will navigate to linear view as data is not shown in the graph view. While navigating, you can use the [view hotkeys](#default-hotkeys) to switch to a specific view at the same location as the current selection. Next you can use the [command palette](#command-palette). Additionally, the view menu in the header at the top of each pane can be used to change views without navigating to any given location. Finally, you can also use the `View` application menu. ## The Sidebar - +{ width = "800" } + +Once you have a file open, the sidebar lets you quickly access the most common features as sidebar panels and keeps them available while you work. These panels can be moved both upper left (1) and upper right (2) as well as to the bottom left (3), bottom right (4), and along the bottom left (5) and bottom right (5) in the middle. + + - 1-2: This section is where the majority of the primarily vertical panels reside. You can only have on larger item here at a time visible. The default behavior is for a click on another panel icon to hide the previous panel. However, this default can be overridden by using `[SHIFT]` click. If overridden, both the old panel and the new panel will be visible. + - 3-4: This section is primarily for smaller panels where you may wish to toggle multiple on or off. Clicking a panel here will toggle its visibility without impacting other panels. Note that despite 4 not having any items in it by default, when you drag a panel icon to this region, you'll see the separator that separates 1/2 from 3/4 appear. + - 5-6: Primarily for horizontal content, the bottom-most panel icon regions behave much like sections 1-2 except they are applied to two regions in the bottom of the window. Clicking a different icon in this region will switch to that panel, or hide that panel entirely if it is already selected. + +Here's a more detailed look into each of those panels: + +### Symbols + +The Symbols List is a powerful symbol organization and navigation tool. It allows sorting symbols by a variety of attributes, organizing them into folders (both manually, and automatically via the [API](https://api.binary.ninja/binaryninja.component-module.html#binaryninja.component.Component)), and much more. + +???+ Warning "Tip" + Searching in the symbol list doesn't require focusing the search box. That the filter list here (and in the string panel) is a "fuzzy" search. Each space-separated keyword is used as a substring match and order matters. So: "M C N" for example would match `MyClassName`. + +#### Columns + +{ width="600" } + +The Symbol List shows the following columns by default: + +- `Name`: the [short name](https://api.binary.ninja/binaryninja.types-module.html#binaryninja.types.CoreSymbol) of the symbol (can be changed to the [raw name](https://api.binary.ninja/binaryninja.types-module.html#binaryninja.types.CoreSymbol) in the menu icon for the Symbol List) +- `Address`: the virtual address for the symbol +- `Kind`: may be one of "Folder", Function", "Data", and "Bare Symbol" +- `Section`: the section of the binary the symbol appears in + +Additionally, the following columns are hidden by default and can be enabled by right-clicking the header: + +- `Total Bytes`: tn the case of functions, the sum of size of basic blocks + +These columns can be re-arranged, hidden, and used for sorting. + +Sort by a given column simply by clicking it. Click it again to toggle between ascending and descending sort order. + +Columns can be re-arranged via dragging. + +#### New Folder with Selection +"New Folder with Selection" will create a new folder containing the selected items. +When this is done within a folder, the folder will be created within the shared parent. + +{ width="600" } + +#### Via Dragging + +Dragging several items onto another non-folder item will create a folder containing the dragged items and the item they were dropped on. + +#### Moving Items into Folders + +Dragging several items onto or into a folder will move the items into that folder. + +#### "Remove from Folder" + +The "Remove from Folder" context menu option will move a given item or items to the root of the tree. + +### Types + +The Types View can be used as a sidebar panel or as a pane in the main view. The UI is exactly the same except for the default vertical versus horizontal. For more details, see the [Types View](types/basictypes.md#types-view) documentation. + +### Tags/Bookmarks + +{ width="600" } + +The tags panel allows you to both change existing tag categories, add your own categories, and also review any existing tags or bookmarks. Bookmarks are just tags with default hotkeys bound to them for both setting them and navigating them. The default keybinding to set a bookmark is `[CTRL-ALT] 1` through `[CTRL-ALT] 0` representing Bookmarks 1-10. The default hotkeys for navigating them are `[CTRL] 1` through `[CTRL] 0`. See the [keybindings](#custom-hotkeys) section for information on changing the default keybindings. + +### Memory Map + +{ width="600" } + +The "Memory Map" pane and sidebar widget show segments and sections currently present in the binary, allows some modification of automatically added sections, and allows adding, modifying, and deleting user segments and sections. + + + +To access it, use either the icon in the sidebar to open the panel, or use the view drop-down in the main pane, or use the command-palette! + +When a segment is selected (highlighted in blue) related sections will be outlined (white border). + +Likewise, when a section is selected, related segments will be outlined. + +The sorting order of segments and sections can be changed by clicking on any column header. + +### External Links + +{ width="400" } + +External Links allow files in projects to connect to one another, so you could, for example, have an analysis database of an executable as well as multiple libraries it imports and follow references between the two. See the [projects documentation](projects.md#external-links) for more information. + +### Mini-Graph + +{ width="400" } + +The Mini Graph only shows content when the currently selected main pane contains a [Graph view](#graph-view). The preview region is shown as a gray box that can be dragged to navigate the larger graph. + +### Cross References + +The Cross References view in the lower-left section of the sidebar shows all cross-references to the currently selected address, address range, variable or type. This pane will change depending on whether an entire line is selected (all cross-references to that address/type/variable are shown), or whether a specific token within the line is selected. For instance if you click on the symbol `memmove` in `call memmove` it will display all known cross-references to `memmove`, whereas if you click on the line the `call` instruction is on, you will only get cross-references to the address of the call instruction. Cross-references can be either incoming or outgoing, and they can be either data, code, type, or variable. + +{ width="600" } + +#### Code References + +Code references are references to or from code, but not necessarily _to_ code. Code References can reference, code, data, or structure types. Code References are inter-procedural, and unfortunately due to speed considerations we currently only show disassembly (rather than an IL) when displaying these types of references. In a future version we hope to address this limitation. + +#### Data References + +Data References are references created _by_ data (i.e. pointers), not necessarily _to_ data. Outgoing Data References are what is pointed to by the currently selected data. Incoming Data References are the set of data pointers which point to this address. + +#### Variable References + +Variable References are all the set of uses of a given variable. As these references are intraprocedural we're able to show the currently viewed IL in the preview. + +#### Type References + +Type References are references to types and type members made by other types, perhaps more accurately called Type-to-Type-References. + +#### Tree-based Layout +The cross-references pane comes in two different layouts: tree-based (default and shown above) and table-based (this can be toggled through the context menu or the command palette). The tree-based layout provides the most condensed view, allowing users to quickly see (for instance) how many references are present to the current selection overall and by function. It also allows collapsing to quickly hide uninteresting results. + +#### Table-based Layout + +{ width="600" } + +The table-based layout provides field-based sorting and multi-select. Clicking the `Filter` text expands the filter pane, showing options for filtering the current results. + +#### Cross-Reference Filtering + +{ width="500" } + +The first of the two drop down boxes allows the selection of incoming, outgoing, or both incoming and outgoing (default). The second allows selection of code, data, type, or variable or any combination thereof. The text box allows regular expression matching of results. When a filter is selected the `Filter` display changes from `Filter (<total-count>)` to `Filter (<total-filtered>/<total-count>)` + +#### Cross-Reference Pinning + +{ width="600" } + +By default, Binary Ninja's cross-reference pane is dynamic, allowing quick navigation to relevant references. Sometimes you might rather have the current references stick around, so they can be used as a sort of work-list. This workflow is supported in four different ways. First is the `Pin` checkbox (which is only visible if the `Filter` drop-down is open). This prevents the list of cross-references from being updated even after the current selection is changed. + +Alternatively clicking the `Pin Cross References to New Pane` button at the top right of the cross references pane in the sidebar, selecting `Pin Cross References` in the context menu or command palette, or using the `SHIFT+X` shortcut pops up a `Pinned Cross References` pane. This pane has a static address range which can only be updated through the `Pin Cross References` action. The third way would be to select (or multi-select in table view) a set of cross-references then right-click `Tag Selected Rows`. The tag pane can then be used to navigate those references. Tags allow for persistent lists to be saved to an analysis database whereas the other options only last for the current session. + +#### Cross-Reference Hotkeys + +* `x` - Focus the cross-references pane +* `[SHIFT] x` Create a new pinned cross-references pane +* `[OPTION/ALT] x` - Navigate to the next cross-reference +* `[OPTION/ALT-SHIFT] x` - Navigate to the previous cross-reference + +The following are only available when the cross-references pane is in focus: + +* `[CMD/CTRL] f` - Open the filter dialog +* `[ESC]` - Clear the search dialog +* `[CMD/CTRL] a` - Select all cross-references +* `[ARROW UP/DOWN]` - Select (but don't navigate) next/previous cross-reference +* `[ENTER]` - Navigate to the selected reference + +### Console + +{ width="800" } + +The Console panel by default only contains a single Python scripting console, however it is possible to create additional consoles using the `Create Python Console` command palette item. + +For many more details about using the python console, see below in the [Python console documentation](#script-python-console). + +### Variables + +{ width="400" } + +The Variables sidebar panel will show local variables from the currently selected function. Possible variable values include: + + - Register Variables (R) + - Stack Variables (S) + - Flag Variables (F) + - Data Variables (D) + + Note that this sidebar is sensitive to function. Possible value set values will be shown for variables based on the currently selected offset in the function. + +### Stack + +{ width="400" } + +The Stack sidebar panel shows the currently selected function's stack layout. You can create variables using the [usual](types/type.md#direct-ui-manipulation) hotkeys as well as using the right-click menu (which also shows the hotkeys). + +### Strings -Once you have a file open, the sidebar lets you quickly access the most common features and keeps them available while you work, including: +{ width="700" } -- symbols -- types -- function-specific local variables -- context-sensitive stack state -- strings -- tags/bookmarks -- a mini-graph of the current function -- cross-references to the current selection +The Strings sidebar panel shows all identified strings in the binary. See [working with strings](../dev/concepts.md#working-with-strings) for more information on how these strings are identified. + +### Find + +{ width="700" } + +The normal find dialog also exists as a sidebar panel that allows persistent, tabbed results. The `Filter` drop-down allows further filtering of identified results and supports regular expressions (though the main find search types do not). + +The search types are available from a drop-down next to the text input field and include: + + - Escaped: Escaped strings such as `OneString\x09\Tabsx09Another` + - Hex: All values much be valid hex characters such as `ebfffc390` and the bytes will only be searched for in this particular order + - Raw: A simple string search that matches the exact string as specified + - Text: Searches the decompilation or whatever view is currently selected for disassembly, BNIL, or Pseudo C + - Constant: Useful for searching for a constant where the byte ordering is handled for you, such as `0x01020304` + +### Logs + +{ width="700" } + +The log window lets you search and filter through logs. You can search by text or filter by loggers to identify messages of interest. By default, only the logs for a specific BinaryView that's open as well as any Global logs will show up but this setting can either be changed through the right-click menu or the drop down menu in the upper-right of the log window. ## Tiling Panes - +{ width="1000" } Binary Ninja displays binaries in panes, whether shown as disassembly, hex, IL, or decompiler output. Tiling these panes allows for a wide variety of information to be displayed at the same time. Each pane has display options at the top and can be split and synchronized with other panes (or groups of panes). The ☰ ("hamburger") menu in the top right of each pane allows for additional customization, including locking the pane to a single function. -<!-- -TODO: Document pane synchronization, splitting, etc in more detail. -### Synchronizing Panes ---> - ## Feature Map - +{ width="100" } The Feature Map is also displayed on the right of the main pane area. It provides a visual summary of the entire binary with different colors representing data variables, code, strings, functions/code, imports, externs, and libraries. It can be moved or hidden via the right-click menu. Note that these colors are theme-aware and will change if your theme does, but on the default Ninja Edit theme: @@ -216,15 +444,15 @@ The Feature Map is also displayed on the right of the main pane area. It provide ### Command Palette - +{ width="800" } One great feature for quickly navigating through a variety of options and actions is the `command palette`. Inspired by similar features in [Sublime](https://sublime-text-unofficial-documentation.readthedocs.io/en/sublime-text-2/extensibility/command_palette.html) and [VS Code](https://code.visualstudio.com/docs/getstarted/userinterface#_command-palette), the command-palette is a front end into an application-wide, context-sensitive action system that all actions, plugins, and hotkeys in the system are routed through. -To trigger it, simply use the `[CMD/CTRL] p` hotkey. Note that the command-palette is context-sensitive and therefore some actions (for example, `Display as - Binary`) may only be available depending on your current view or selection. This is also available to plugins. For example, a plugin may use [PluginCommand.register](https://api.binary.ninja/binaryninja.plugin-module.html#binaryninja.plugin.PluginCommand.register) with the optional `is_valid` callback to determine when the action should be available. +To trigger it, simply use the `[CMD/CTRL] p` hotkey. Note that the command-palette is context-sensitive and therefore some actions (for example, `Display as - Binary`) may only be available depending on your current view or selection. This is also available to plugins. For example, a plugin may use [`PluginCommand.register`](https://api.binary.ninja/binaryninja.plugin-module.html#binaryninja.plugin.PluginCommand.register) with the optional `is_valid` callback to determine when the action should be available. ### Custom Hotkeys - +{ width="800" } Any action in the [action system](#command-palette) can have a custom hotkey mapped to it. To access the keybindings menu, use the `[CMD/CTRL-SHIFT] b` hotkey, via the `Edit / Keybindings...` (`Binary Ninja / Preferences / Keybindings...` on macOS) menu, or the `Keybindings` [command palette](#command-palette) entry. Any overlapping keybindings will be highlighted. Click the `Keybinding` column header to sort by keybindings in order to see what bindings are overlapping. @@ -256,10 +484,11 @@ To search in the keybindings list, just click to make sure it's focused and star - `t` : Switch to type view - `y` : Change type of currently selected element - `a` : Change the data type to an ASCII string - - `[SHIFT] a` : Change the data type to a wchar_t string - - `[CTRL-SHIFT] a` : Change the data type to a wchar32_t string + - `[SHIFT] a` : Change the data type to a `wchar_t` string + - `[OPT-SHIFT] a` (macOS) : Change the data type to a `wchar32_t` string + - `[CTRL-SHIFT] a` (Windows/Linux) : Change the data type to a `wchar32_t` string - `1`, `2`, `4`, `8` : Change type directly to a data variable of the indicated widths - - `f` : Switch data variable between floating point types of various precisions + - `f` : Switch data variable between floating point types of varying precision - `d` : Switch between data variables of various widths - `r` : Change the data type to single ASCII character - `o` : Create a pointer data type @@ -269,17 +498,17 @@ To search in the keybindings list, just click to make sure it's focused and star - `[CMD-SHIFT] -` (macOS) : Graph view zoom out - `[CTRL-SHIFT] +` (Windows/Linux) : Graph view zoom in - `[CTRL-SHIFT] -` (Windows/Linux) : Graph view zoom out - - Other hotkeys specifically for working with types are listed in the [type guide](type.md#direct-ui-manipulation) + - Other hotkeys specifically for working with types are listed in the [type guide](types/type.md#direct-ui-manipulation) ## 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 +- 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`) @@ -287,15 +516,15 @@ Features of the graph view include: - 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 + - 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 - +{ 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. @@ -335,7 +564,7 @@ Current options include: ## 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. @@ -344,142 +573,18 @@ The hex view is particularly good for transforming data in various ways via the ???+ Warning "Tip" 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. -## Cross References Pane - -The Cross References view in the lower-left section of the sidebar shows all cross-references to the currently selected address, address range, variable or type. This pane will change depending on whether an entire line is selected (all cross-references to that address/type/variable are shown), or whether a specific token within the line is selected. For instance if you click on the symbol `memmove` in `call memmove` it will display all known cross-references to `memmove`, whereas if you click on the line the `call` instruction is on, you will only get cross-references to the address of the call instruction. Cross-references can be either incoming or outgoing, and they can be either data, code, type, or variable. - - - -### Code References - -Code references are references to or from code, but not necessarily _to_ code. Code References can reference, code, data, or structure types. Code References are inter-procedural, and unfortunately due to speed considerations we currently only show disassembly (rather than an IL) when displaying these types of references. In a future version we hope to address this limitation. - -### Data References - -Data References are references created _by_ data (i.e. pointers), not necessarily _to_ data. Outgoing Data References are what is pointed to by the currently selected data. Incoming Data References are the set of data pointers which point to this address. - -### Variable References - -Variable References are all the set of uses of a given variable. As these references are intra-procedural we're able to show the currently viewed IL in the preview. - -### Type References - -Type References are references to types and type members made by other types, perhaps more accurately called Type-to-Type-References. - -### Tree-based Layout -The cross-references pane comes in two different layouts: tree-based (default and shown above) and table-based (this can be toggled through the context menu or the command palette). The tree-based layout provides the most condensed view, allowing users to quickly see (for instance) how many references are present to the current selection overall and by function. It also allows collapsing to quickly hide uninteresting results. - -### Table-based Layout - - - -The table-based layout provides field-based sorting and multi-select. Clicking the `Filter` text expands the filter pane, showing options for filtering the current results. - -### Cross-Reference Filtering - - - -The first of the two drop down boxes allows the selection of incoming, outgoing, or both incoming and outgoing (default). The second allows selection of code, data, type, or variable or any combination thereof. The text box allows regular expression matching of results. When a filter is selected the `Filter` display changes from `Filter (<total-count>)` to `Filter (<total-filtered>/<total-count>)` - -### Cross-Reference Pinning - - - -By default Binary Ninja's cross-reference pane is dynamic, allowing quick navigation to relevant references. Sometimes you might rather have the current references stick around so they can be used as a sort of work-list. This workflow is supported in four different ways. First is the `Pin` checkbox (which is only visible if the `Filter` drop-down is open). This prevents the list of cross-references from being updated even after the current selection is changed. - -Alternatively clicking the `Pin Cross References to New Pane` button at the top right of the cross references pane in the sidebar, selecting `Pin Cross References` in the context menu or command palette, or using the `SHIFT+X` shortcut pops up a `Pinned Cross References` pane. This pane has a static address range which can only be updated through the `Pin Cross References` action. The third way would be to select (or multi-select in table view) a set of cross-references then right-click `Tag Selected Rows`. The tag pane can then be used to navigate those references. Tags allow for persistent lists to be saved to an analysis database whereas the other options only last for the current session. - - -### Cross-Reference Hotkeys - -* `x` - Focus the cross-references pane -* `[SHIFT] x` Create a new pinned cross-references pane -* `[OPTION/ALT] x` - Navigate to the next cross-reference -* `[OPTION/ALT-SHIFT] x` - Navigate to the previous cross-reference - -The following are only available when the cross-references pane is in focus: - -* `[CMD/CTRL] f` - Open the filter dialog -* `[ESC]` - Clear the search dialog -* `[CMD/CTRL] a` - Select all cross-references -* `[ARROW UP/DOWN]` - Select (but don't navigate) next/previous cross-reference -* `[ENTER]` - Navigate to the selected reference - ## Linear View - +{ width="1000" } Linear view is a hybrid view between a graph-based disassembly window and the raw hex view. It lists the entire binary's memory in a linear fashion and is especially useful when trying to find sections of a binary that were not properly identified as code or even just examining data. 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. -## Symbols List - -The Symbols List is a powerful symbol organization and navigation tool. It allows sorting symbols by a variety of attributes, -organizing them into folders (both manually, and automatically via the [API](https://api.binary.ninja/binaryninja.component-module.html#binaryninja.component.Component)), and much more. - -???+ Warning "Tip" - Searching in the symbol list doesn't require focusing the search box. That the filter list here (and in the string panel) is a "fuzzy" search. Each space-separated keyword is used as a substring match and order matters. So: "M C N" for example would match "MyClassName". - -### Columns - -The Symbol List shows the following columns by default: - -- `Name`: the [short name](https://api.binary.ninja/binaryninja.types-module.html#binaryninja.types.CoreSymbol) of the symbol (can be changed to the [raw name](https://api.binary.ninja/binaryninja.types-module.html#binaryninja.types.CoreSymbol) in the menu icon for the Symbol List) -- `Address`: the virtual address for the symbol -- `Kind`: may be one of "Folder", Function", "Data", and "Bare Symbol" -- `Section`: the section of the binary the symbol appears in - -Additionally, the following columns are hidden by default and can be enabled by right-clicking the header: - - - -- `Total Bytes`: tn the case of functions, the sum of size of basic blocks - -These columns can be re-arranged, hidden, and used for sorting. - -Sort by a given column simply by clicking it. Click it again to toggle between ascending and descending sort order. - -Rearrange columns by dragging them into the order you'd prefer: - - - -### New Folder with Selection -"New Folder with Selection" will create a new folder containing the selected items. -When this is done within a folder, the folder will be created within the shared parent. - - - -### Via Dragging - -Dragging several items onto another non-folder item will create a folder containing the dragged items and the item they were dropped on. - -### Moving Items into Folders - -Dragging several items onto or into a folder will move the items into that folder. - - - -### "Remove from Folder" - -The "Remove from Folder" context menu option will move a given item or items to the root of the tree. - -## Memory Map - - - -The "Memory Map" sidebar widget shows segments and sections currently present in the binary, allows some modification of automatically added sections, and allows adding, modifying, and deleting user segments and sections. - -When a segment is selected (highlighted in blue) related sections will be outlined (white border). - -Likewise, when a section is selected, related segments will be outlined. - -The sorting order of segments and sections can be changed by clicking on any column header. - ## Edit Function Properties Dialog - +{ width="600" } The “Edit Function Properties” dialog provides the ability to easily configure some of a function’s more advanced properties. It can be opened via the context menu when a function is focused in the graph or linear views, or via the command palette. An overview of the UI is as follows: @@ -497,6 +602,8 @@ The “Edit Function Properties” dialog provides the ability to easily configu 1. **Calling convention.** The calling convention this function uses. All calling conventions for the function’s architecture are available as choices. 1. **Stack adjustment.** How many _extra_ bytes does this function remove from the stack upon return? 1. **Has variable arguments.** Does this function accept a variable number of arguments? +1. **Can return.** Functions that cannot return will halt disassembly on branches where they are called +1. **Pure.** Functions that are pure are assumed to have no side effects and may be inlined if their return value is trivial 1. **Inline during analysis.** Causes the function to be [inlined](https://api.binary.ninja/binaryninja.function-module.html#binaryninja.function.Function.inline_during_analysis) during analysis. 1. **Clobbered registers.** The list of registers that this function clobbers; individual registers can be checked or unchecked. 1. **Return registers.** The list of registers that this function returns data in; individual registers can be checked or unchecked. @@ -504,7 +611,7 @@ The “Edit Function Properties” dialog provides the ability to easily configu ## High Level IL - +{ 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. @@ -512,31 +619,31 @@ You can control the way HLIL appears in the settings. The different options are shown below: - +{ width="500" } ## Pseudo C - +{ 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. +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 Binary Ninja tries to be conservative with eliminating unused variables on the stack. When the analysis finds a variable that cannot be eliminated but does not appear to be used, the assignment will appear grayed out in the decompiler output. The first two lines of the function below show this: - +{ width="500" } -In this case, these variables are actually unused and can be eliminated. You can tell Binary Ninja to do this by right clicking on the variable and choosing "Allow" from the "Dead Store Elimination" submenu. +In this case, these variables are actually unused and can be eliminated. You can tell Binary Ninja to do this by right-clicking on the variable and choosing "Allow" from the "Dead Store Elimination" submenu. - +{ width="500" } Performing this action on both variables in the example results in the following output: - +{ width="500" } ## Merging and Splitting Variables -Binary Ninja can not always determine when two variables are simple copies of one another. When this condition occurs these variables can be merged in one of two ways. +Binary Ninja automatically splits all variables that the analysis determines to be safely splittable. This allows the user to assign different types to different uses of the same register or memory location. Sometimes, however, the code is more clear if two or more of these variables are merged together into a single variable. ### Merge Variable Here @@ -544,9 +651,9 @@ The `Merge Variable Here` action is bound to the hotkey `+` (i.e. `Shift + =` ) ### Merge Variables -For more complicated situations you can select the variable in question and use the "Merge Variables" dialog. By default this dialog is bound to the `=` hotkey. The dialog provides you with a searchable list of variables that can be merged or unmerged. +For more complicated situations you can select the variable in question and use the "Merge Variables" dialog. By default, this dialog is bound to the `=` hotkey. The dialog provides you with a searchable list of variables that can be merged or unmerged. - +{ width="400" } There are 3 categories of variables that you can select from. @@ -556,9 +663,32 @@ There are 3 categories of variables that you can select from. Any of these merges can be undone if you determine them to be done in error by either using "Undo" or by bringing up this dialog again and unchecking the variables in question. +### Removing Merges + +To unmerge a variable, either select "Split Merged Variable" from the context menu, or reenter the "Merge Variables..." +dialog and deselect the variables that should no longer be merged. + +### Split Variables + +{ width="200" } + +Variables that have multiple definitions can be manually split into multiple variables by clicking on the +variable at a definition site and selecting "Split Variable at Definition" from the context menu. + +!!! Warning "Warning" + Splitting a variable manually can cause IL and decompilation to be incorrect. There are some + patterns where variables can be safely split semantically but analysis cannot determine that + it is safe, and this feature is provided to allow variable splitting to be performed in these + cases. + +Manually split variables will initially provide the selected definition as a separate variable, and all other +definitions will be automatically resolved into one or more other variables. If some of the definitions should +have been included as part of the same variable, use "Merge Variables..." from the context menu after splitting +to select which of the other definitions should be merged. + ## Script (Python) Console - +{ width="800" } The integrated script console is useful for small scripts that aren't worth writing as full plugins. @@ -567,7 +697,7 @@ To trigger the console, either use `<BACKTICK>`, or use the `View`/`Python Conso ???+ Warning "Tip" Note that `<BACKTICK>` will work in most contexts to open the console and focus its command line, unless the UI focus is in an editor widget. - +{ width="800" } When both the Script Console and the Log view are open, the title of both acts as a tab that can be dragged to either a tabbed view showing only one at a time (the default) or a split view showing both. Currently, the console and log views are part of a "Global Area", meaning they are always visible in the same position when switching between open binary tabs in the same window. This means they can only dock with each other, and not with the sidebar or the main pane view area. It is possible to open additional scripting consoles via the `Create Python Console` action in the [command palette](#command-palette), and these new consoles will appear as additional tabs in the topmost, leftmost tab in the global area. Note that `<BACKTICK>` will always focus the original main scripting console, and while any of the other created consoles can be closed (using the button that will appear when hovering over the right edge of its tab), the original one cannot be closed. @@ -581,37 +711,37 @@ The scripting console is not a full IDE, but it has several convenience features ### Magic Console Variables -The interactive python prompt also has several built-in "magic" functions and variables. Some are read-only, and some are writable to provide convenient interacitivty between the UI and console: +The interactive python prompt also has several built-in "magic" functions and variables. Some are read-only, and some are writable to provide convenient interactivity between the UI and console: - `here` / `current_address`: address of the current selection. It's settable too and will navigate the UI if changed - `current_selection`: a tuple of the start and end addresses of the current selection. It's settable and will change the current selection - `current_raw_offset`: the file offset that corresponds the current address. It's settable and will navigate to the corresponding file offset -- `bv` / `current_view` / : the current [BinaryView](https://api.binary.ninja/binaryninja.binaryview-module.html#binaryninja.binaryview.BinaryView) -- `current_function`: the current [Function](https://api.binary.ninja/binaryninja.function-module.html#binaryninja.function.Function) -- `current_basic_block`: the current [BasicBlock](https://api.binary.ninja/binaryninja.basicblock-module.html#binaryninja.basicblock.BasicBlock) -- `current_llil`: the current [LowLevelILFunction](https://api.binary.ninja/binaryninja.lowlevelil-module.html#binaryninja.lowlevelil.LowLevelILFunction) -- `current_mlil`: the current [MediumLevelILFunction](https://api.binary.ninja/binaryninja.mediumlevelil-module.html#binaryninja.mediumlevelil.MediumLevelILFunction) -- `current_hlil`: the current [HighLevelILFunction](https://api.binary.ninja/binaryninja.highlevelil-module.html#binaryninja.highlevelil.HighLevelILFunction) +- `bv` / `current_view` / : the current [`BinaryView`](https://api.binary.ninja/binaryninja.binaryview-module.html#binaryninja.binaryview.BinaryView) +- `current_function`: the current [`Function`](https://api.binary.ninja/binaryninja.function-module.html#binaryninja.function.Function) +- `current_basic_block`: the current [`BasicBlock`](https://api.binary.ninja/binaryninja.basicblock-module.html#binaryninja.basicblock.BasicBlock) +- `current_llil`: the current [`LowLevelILFunction`](https://api.binary.ninja/binaryninja.lowlevelil-module.html#binaryninja.lowlevelil.LowLevelILFunction) +- `current_mlil`: the current [`MediumLevelILFunction`](https://api.binary.ninja/binaryninja.mediumlevelil-module.html#binaryninja.mediumlevelil.MediumLevelILFunction) +- `current_hlil`: the current [`HighLevelILFunction`](https://api.binary.ninja/binaryninja.highlevelil-module.html#binaryninja.highlevelil.HighLevelILFunction) - `write_at_cursor(data)`: function that writes data to the start of the current selection - `get_selected_data()`: function that returns the data in the current selection -- `current_il_index`: the current index of the IL instruction. It can be LLIL/MLIL/HLIL depending which one is shown in the UI -- `current_il_instruction`: the current IL instruction. It can be LLIL/MLIL/HLIL depending which one is shown in the UI -- `current_il_function`: the current IL function. It can be LLIL/MLIL/HLIL depending which one is shown in the UI -- `current_il_basic_block`: the current IL basic block. It can be LLIL/MLIL/HLIL depending which one is shown in the UI -- `current_token`: the current selected [InstructionTextToken](https://api.binary.ninja/binaryninja.architecture-module.html#binaryninja.architecture.InstructionTextToken). None if no token is selected -- `current_data_var`: the current selected [DataVariable](https://api.binary.ninja/binaryninja.binaryview-module.html#binaryninja.binaryview.DataVariable). None if no data variable is selected -- `current_sections`: the list of [Section](https://api.binary.ninja/binaryninja.binaryview-module.html#binaryninja.binaryview.Section)s that the current address is in. This the list can be empty -- `current_segment`: the [Segment](https://api.binary.ninja/binaryninja.binaryview-module.html#binaryninja.binaryview.Segment) that the current address is in. +- `current_il_index`: the current index of the IL instruction. It can be LLIL/MLIL/HLIL depending on which one is shown in the UI +- `current_il_instruction`: the current IL instruction. It can be LLIL/MLIL/HLIL depending on which one is shown in the UI +- `current_il_function`: the current IL function. It can be LLIL/MLIL/HLIL depending on which one is shown in the UI +- `current_il_basic_block`: the current IL basic block. It can be LLIL/MLIL/HLIL depending on which one is shown in the UI +- `current_token`: the current selected [`InstructionTextToken`](https://api.binary.ninja/binaryninja.architecture-module.html#binaryninja.architecture.InstructionTextToken). None if no token is selected +- `current_data_var`: the current selected [`DataVariable`](https://api.binary.ninja/binaryninja.binaryview-module.html#binaryninja.binaryview.DataVariable). None if no data variable is selected +- `current_sections`: the list of [`Section`](https://api.binary.ninja/binaryninja.binaryview-module.html#binaryninja.binaryview.Section)s that the current address is in. This the list can be empty +- `current_segment`: the [`Segment`](https://api.binary.ninja/binaryninja.binaryview-module.html#binaryninja.binaryview.Segment) that the current address is in. - `current_comment`: the comment at the current address. Writing to it sets comment at the current address -- `current_symbol`: the [Symbol](https://api.binary.ninja/binaryninja.types-module.html#binaryninja.types.Symbol) at the current address. None if there is no symbol -- `current_symbols`: the list of [Symbol](https://api.binary.ninja/binaryninja.types-module.html#binaryninja.types.Symbol)s at the current address -- `current_var`: the current selected [Variable](https://api.binary.ninja/binaryninja.variable-module.html?highlight=variable#binaryninja.variable.Variable) in a function. Not to be confused with `current_data_var` -- `current_ui_context`: the current [UIContext](https://api.binary.ninja/cpp/class_u_i_context.html) -- `current_ui_view_frame`: the current [ViewFrame](https://api.binary.ninja/cpp/class_view_frame.html) -- `current_ui_view`: the current [View](https://api.binary.ninja/cpp/class_view.html) -- `current_ui_action_handler`: the current [UIActionHandler](https://api.binary.ninja/cpp/class_u_i_action_handler.html) -- `current_ui_view_location`: the current [ViewLocation](https://api.binary.ninja/cpp/class_view_location.html) -- `current_ui_action_context`: the current [UIActionContext](https://api.binary.ninja/cpp/struct_u_i_action_context.html) +- `current_symbol`: the [`Symbol`](https://api.binary.ninja/binaryninja.types-module.html#binaryninja.types.Symbol) at the current address. None if there is no symbol +- `current_symbols`: the list of [`Symbol`](https://api.binary.ninja/binaryninja.types-module.html#binaryninja.types.Symbol)s at the current address +- `current_var`: the current selected [`Variable`](https://api.binary.ninja/binaryninja.variable-module.html?highlight=variable#binaryninja.variable.Variable) in a function. Not to be confused with `current_data_var` +- `current_ui_context`: the current [`UIContext`](https://api.binary.ninja/cpp/class_u_i_context.html) +- `current_ui_view_frame`: the current [`ViewFrame`](https://api.binary.ninja/cpp/class_view_frame.html) +- `current_ui_view`: the current [`View`](https://api.binary.ninja/cpp/class_view.html) +- `current_ui_action_handler`: the current [`UIActionHandler`](https://api.binary.ninja/cpp/class_u_i_action_handler.html) +- `current_ui_view_location`: the current [`ViewLocation`](https://api.binary.ninja/cpp/class_view_location.html) +- `current_ui_action_context`: the current [`UIActionContext`](https://api.binary.ninja/cpp/struct_u_i_action_context.html) ### startup.py @@ -631,7 +761,7 @@ The "Run Script..." option in the File Menu allows loading a python script from within the console. It can also be run via the Command Palette or bound to a key. The script will have access to the same variables the Python console does, including the built-in special functions and -variables defined by BinaryNinja, and any variables you have already defined within the console. It may be helpful to +variables defined by Binary Ninja, and any variables you have already defined within the console. It may be helpful to think of it as an equivalent to pasting the contents of the script within the console. While `__name__` in the console is set to `'__console__'`, within a script it will be set to `'__main__'`. `__file__` is not @@ -650,7 +780,7 @@ Note 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. - +{ 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: @@ -662,10 +792,10 @@ For more detailed information on using plugins, see the [plugin guide](plugins.m ## Loading PDBs -Binary Ninja supports loading PDB files through a built in PDB loader. It will automatically search for a corresponding PDB file whenever you load a Windows executable or library that was compiled with a PDB. The PDB loader will search a variety of places for PDBs, in the following order, if the files exist and match the guid in the analyzed file: +Binary Ninja supports loading PDB files through a built-in PDB loader. It will automatically search for a corresponding PDB file whenever you load a Windows executable or library that was compiled with a PDB. The PDB loader will search a variety of places for PDBs, in the following order, if the files exist and match the GUID in the analyzed file: -1. Look in symbol servers defined in the `_NT_SYMBOL_PATH` environment variable, as defined by [Microsoft's documentation](https://learn.microsoft.com/en-us/windows/win32/debug/using-symsrv). -2. Look for the file at the path specified in the loaded binary. E.g. when `C:\Users\foo\foo.exe` was compiled, it stored `C:\Users\foo\foo.pdb` as metadata inside `foo.exe`, so `C:\Users\foo\foo.pdb` will be loaded if it exists (and matches the guid). +1. Look in symbol servers defined in the `_NT_SYMBOL_PATH` environment variable, as defined by [Microsoft's documentation](https://learn.microsoft.com/en-us/windows/win32/debug/using-symsrv). +2. Look for the file at the path specified in the loaded binary. E.g. when `C:\Users\foo\foo.exe` was compiled, it stored `C:\Users\foo\foo.pdb` as metadata inside `foo.exe`, so `C:\Users\foo\foo.pdb` will be loaded if it exists (and matches the guid). 3. Look in the same directory as the opened file/bndb (e.g. If you have opened `C:\foo.exe` or `C:\foo.bndb`, the PDB plugin looks for `C:\foo.pdb`) 4. Look in the local symbol store. This is the directory specified by `pdb.files.localStoreAbsolute` in the settings, if it exists. Otherwise, this is a folder relative to the Binary Ninja user directory, specified by the `pdb.files.localStoreRelative` setting (and possibly the `BN_USER_DIRECTORY` environment variable). This directory has the structure `<symbol store>\foo.pdb\<guid>\foo.pdb`, equivalent to a regular symbol server. 5. Attempt to connect and download the PDB from the list of symbol servers specified in setting `pdb.files.symbolServerList`, in order. @@ -688,15 +818,15 @@ The PDB loader comes with a couple configuration options which enable and disabl Binary Ninja now comes with a debugger plugin that can debug executables on Windows, Linux, and macOS. -For more detailed information on plugins, see the [debugger guide](debugger.md). +For more detailed information on plugins, see the [debugger guide](debugger/index.md). ## Updates Binary Ninja automatically updates itself by default. This functionality can be disabled in the `Update Channel` dialog (`[CMD/CTRL] p`, `Update Channel`, or under the `Preferences` sub menu available under `Edit` on Linux and Windows, and the Application menu on macOS) preferences by turning off the `Update to latest version automatically` option. Regardless of whether automatic updates are enabled, it is always possible to check for updates by selecting `Check for Updates...` from either the command palette or under `Help` menu on Linux and Windows, and the Application menu on macOS. -Updates are silently downloaded in the background and when complete an option to restart is displayed in the status bar. When an update is available but has not been applied, a blue up arrow will appear in the status bar. Clicking this arrow will apply the update once it ensures it has the lastest update, downloading it if necessary. Once the update is complete, a green arrow will appear in its place with the message "Restart to Apply Update". Even if the arrow is not clicked, once the arrow is green, Binary Ninja will replace itself with the new version as it launches whenever it is restarted. +Updates are silently downloaded in the background and when complete an option to restart is displayed in the status bar. When an update is available but has not been applied, a blue up arrow will appear in the status bar. Clicking this arrow will apply the update once it ensures it has the latest update, downloading it if necessary. Once the update is complete, a green arrow will appear in its place with the message "Restart to Apply Update". Even if the arrow is not clicked, once the arrow is green, Binary Ninja will replace itself with the new version as it launches whenever it is restarted. -On windows, this is achieved through a separate launcher that loads first and replaces the installation before launching the new version which you'll notice as a separate window. On macOS and Linux, the original installation is overwritten after the update occurs as these operating systems allow files to be replaced while running. The update on restart is thus immediate. +On Windows, this is achieved through a separate launcher that loads first and replaces the installation before launching the new version which you'll notice as a separate window. On macOS and Linux, the original installation is overwritten after the update occurs as these operating systems allow files to be replaced while running. The update on restart is thus immediate. Note ???+ Warning "Tip" @@ -704,7 +834,7 @@ Note ### Development Branch -Binary Ninja [stable builds](https://binary.ninja/changelog) releases happen on semi-regular intervals throughout the year. However, we also make development builds available to customers with active support. Simply use the update dialog, and select one of the "Development" channels in the `Update Channel` field. +Binary Ninja [stable builds](https://binary.ninja/changelog) releases happen on semiregular intervals throughout the year. However, we also make development builds available to customers with active support. Simply use the update dialog, and select one of the "Development" channels in the `Update Channel` field. ## Support diff --git a/docs/guide/migration/index.md b/docs/guide/migration/index.md new file mode 100644 index 00000000..83309c50 --- /dev/null +++ b/docs/guide/migration/index.md @@ -0,0 +1,21 @@ +# Migrating from Other Tools + +Thank you for trying Binary Ninja! We know that it can be a bit different from what you're used to, so this page dedicated to getting you oriented in your new favorite decompiler! + +If you haven't already installed Binary Ninja, you can follow our [installation guide](../../getting-started.md#installing-binary-ninja). + +And be sure to check out some of our additional resource below before you click away! + +We have quick start guides for the following: + +- [New Users](../../getting-started.md) +- [IDA Pro Users](migrationguideida.md) +- [Ghidra Users](migrationguideghidra.md) + +## Additional Resources + +We love our community! Feel free to hang with us and chat in our [Public Slack Server](https://slack.binary.ninja). Our community is great about answering questions for each other, but one of our engineers will often get to your question first as well. We have a lot of different channels for different levels of engineers, different interests, topics, and so on. + +Our community has also generated a tremendous number of [community plugins](https://github.com/Vector35/community-plugins) that provide support for new architectures, automate different types of analysis, and even some that provide new and advanced visualizations for your programs. That repo also contains instructions for how to get your own plugin into our [plugin manager](../plugins.md#plugin-manager). + +If you think you've found a bug or have a suggestion for us, tell us over on [GitHub](https://github.com/Vector35/binaryninja-api). There are [discussions](https://github.com/Vector35/binaryninja-api/discussions) over there if you'd prefer to ask us something on GitHub instead of Slack. GitHub also hosts the vast majority of our [API and scripting examples](../../dev/cookbook.md) to help you start automating tasks! If you're really passionate about getting something fixed, we have [a _ton_ of open source repos](https://github.com/Vector35/binaryninja-api?tab=readme-ov-file#related-repositories) to contribute to, including every single one of our core architecture plugins. diff --git a/docs/guide/migration/migrationguideghidra.md b/docs/guide/migration/migrationguideghidra.md new file mode 100644 index 00000000..88f32675 --- /dev/null +++ b/docs/guide/migration/migrationguideghidra.md @@ -0,0 +1,119 @@ +# Migrating from Ghidra + +## Starting Binary Ninja + +Binary Ninja starts with the [New Tab Page](../index.md#new-tab) open. From here, you can optionally [start a project](../projects.md#creating-a-project) to work with multiple files, navigate your offline docs from the help menu, or just [open existing files](../index.md#loading-files) (including drag-and-drop!). + +## Decompiler Settings + +Binary Ninja likes to stay out of your way as much as possible, but sometimes you need to dig into the settings and change how a file is analyzed. If you have a file that can be opened with default settings, you won't get prompted for any additional input. Binary Ninja will automatically analyze the entire file — including running [linear sweep](https://binary.ninja/2017/11/06/architecture-agnostic-function-detection-in-binaries.html) — and provide you with linear decompilation for the whole file (like Ghidra's linear disassembly, but as decomp by default). + +If you're opening a [Universal Mach-O](https://en.wikipedia.org/wiki/Universal_binary), the Open with Options dialogue will appear so that you can choose which architecture to open (in the top right). If you have a default architecture you want to open whenever you open a universal binary, you can set your preference in a setting called [Universal Mach-O Architecture Preference](../settings.md#all-settings). You'll also see the Open with Options dialogue when Binary Ninja is unable to recognize the file type or otherwise needs user input to analyze the file (can't find the entry point, needs you to provide some memory mappings, etc). + +It's worth digging into Binary Ninja's [settings](../settings.md) and seeing what's available to tune, but if you ever want to change a setting for a single binary, you can Open (it) with Options. Go to File -> Open with Options, and any settings you change will apply to only that file. + +<!-- TODO : Can you analyze a file while Ghidra is running its analysis? +## Analyzing While Analyzing --> + +## Keybindings + +Binary Ninja's keybindings are very different from Ghidra. Thankfully, [Binary Ninja's action system](https://binary.ninja/2024/02/15/command-palette.html) allows you to easily find actions and view the keybindings extremely easily. It'll also save you from digging through unfamiliar right-click menus while helping you learn any new keybindings. All actions can have their keybinding set, changed, or removed in the [keybindings menu](../index.md#default-hotkeys). + +Some of the most useful default keybindings are as follows: + +Analysis Keybindings: + +| Action | Keybinding | +|----------------------|--------------------| +| Rename | `N` | +| Set Type | `Y` | +| Go to | `G` | +| Toggle Disasm/Decomp | `[TAB]` | +| Toggle Graph/Linear | `[SPACE]` | +| Toggle Hex View | `H` | +| Insert Comment | `;` | +| Manage Plugins | `[CTRL/⌘-SHIFT-B]` | +| Open Command Palette | `[CTRL/⌘-P]` | +| Open Python Console | `\`` | + +Types Keybindings: + +| Action | Keybinding | +|----------------------|------------| +| Set Type | Y | +| Make C String | A | +| Make Magic Struct | S | +| Open Types Menu | T | +| Make 1-byte elements | 1 | +| Make 2-byte elements | 2 | +| Make 4-byte elements | 4 | +| Make 8-byte elements | 8 | +| Make array | * | + +Common System Keybindings: + +| Action | Keybinding | +|-------------------|--------------------| +| Open File | `[CTRL/⌘-O]` | +| Open with Options | `[CTRL/⌘-SHIFT-O]` | +| Save | `[CTRL/⌘-S]` | +| Undo | `[CTRL/⌘-Z]` | +| Redo | `[CTRL/⌘-SHIFT-Z]` | +| Find | `[CTRL/⌘-F]` | +| Open Settings | `[CTRL/⌘-,]` | +| Open Keybindings | `[CTRL/⌘-SHIFT-B]` | + +## Layout + +Binary Ninja's layout is also a bit different from what you're used to in Ghidra, but thankfully Binary Ninja's UI is flexible enough to allow us to build something that will feel familiar. + +### Theme + +This doesn't exactly have to do with your layout, but it go a long way towards making the interface feel a bit more familiar. We have an expansive list of [community themes](https://github.com/Vector35/community-themes), and [a guide](../../dev/themes.md) and a [blog post](https://binary.ninja/2021/07/08/creating-great-themes.html) on how to make your own. The built-in "Classic" theme should feel nostalgic, but if you're looking for a light theme that's slightly easier on the eyes, try out Summer or Solarized Light. + +### Feature Map + +Binary Ninja's [feature map](../index.md#feature-map) lives on the right side of your main view area. If you'd rather not see it, you can right-click it and select "Hide Feature Map." + +### Sidebars + +Our sidebars have a whole host of customization options, so make sure to check out [their dedicated docs](../index.md#the-sidebar) to maximize your workflow. + +That said, I'll walk you through how to set up your sidebars to get it looking very similar to what you're used to in Ghidra. + +#### Program Tree + +But first, there are a couple caveats. Binary Ninja does not have an exact 1-to-1 widget for everything in Ghidra. The Program Tree is one of those elements; it's a little bit like our memory map, but it's also kinda not. Our new Binary Ninja layout assumes you've closed the program tree in Ghidra. Now Binary Ninja and Ghidra's sidebars are starting to match by having the symbols view on the top (which we start as a flat listing for you to organize into file yourself), and a different sidebar panel below it. Be sure to check out the options in the Symbols list's hamburger menu (the three lines in the top right). + +#### Cross References and Types Manager + +We show cross references by default, but you can toggle that just by clicking it off on the left side under the divider line. If you want to match how Ghidra has it's types showing on the bottom, you can simply drag the types widget to beneath the divider line on the left side. Whenever you open your sidebar, both areas will open together. The Types sidebar also shows you the full type definition when you select a type. + +#### Main Area + +Time for the main event! + +Ghidra shows you a linear view on the left, and single-function-at-a-time decompilation on the right. We already gave you linear decompilation of the whole Binary here by default, so there are three last things to do: + +1. Create a new pane by pressing the icon in the top right that looks like a rectangle with a line through it. The two panes are now synced by address, as you’d expect. +2. In the left pane, find the drop down that says "High Level IL", and switch down to disassembly. You should now have linear disassembly on the left, and linear decompilation on the right. +3. The final touch is to go back to the decompilation pane on the right and find the hamburger menu for that pane in the top right, and then select “Single Function View.” + +Now the UI should be looking extremely familiar. Read our last couple of tips below, don't forget to use the command palette to find what you want to do, and you'll be off analyzing binaries in no time! + +#### Saving Layouts + +Now that you've done all this hard work to make the perfect layout, it would be a shame to lose it! Thankfully, we make it easy. Go to the `Window` → `Layout` → `Save Current Layout...` and give it a name, or select `Save Current Layout as Default`. Named layouts let you quickly swap between different kinds of work. + +## What You'll Love + +...about switching to Binary Ninja! We know leaving your old tool behind can be hard, and there will be things you miss, but we think there are a lot of features packed into Binary Ninja that you'll love. Here are a couple we think you'll appreciate: + + - [Updates every day](../index.md#updates) on the dev branch (nearly) - accepted PRs can be in everyone's hands within hours. + - [Our awesome native Python API](../../dev/cookbook.md) (and [C++](https://api.binary.ninja/cpp/), and [Rust](https://dev-rust.binary.ninja/)) + - [The speed](https://binary.ninja/2022/05/31/3.1-the-performance-release.html) + - ...not needing to manage Java installations + +--- + +Don't forget to check out our [additional resources](index.md#additional-resources)! diff --git a/docs/guide/migration/migrationguideida.md b/docs/guide/migration/migrationguideida.md new file mode 100644 index 00000000..88914439 --- /dev/null +++ b/docs/guide/migration/migrationguideida.md @@ -0,0 +1,66 @@ +# Migrating from IDA + +## Starting Binary Ninja + +Binary Ninja starts with the [New Tab Page](../index.md#new-tab) open. From here, you can optionally [start a project](../projects.md#creating-a-project) to work with multiple files, [create new files](../index.md#new-files) to paste in data, or just [open existing files](../index.md#loading-files) (including drag-and-drop!). + +## Decompiler Settings + +Binary Ninja likes to stay out of your way as much as possible, but sometimes you need to dig into the settings and change how a file is analyzed. If you have a file that can be opened with default settings, you won't get prompted for any additional input. Binary Ninja will automatically analyze the entire file — including running [linear sweep](https://binary.ninja/2017/11/06/architecture-agnostic-function-detection-in-binaries.html) — and provide you with linear decompilation for the whole file (like IDA's linear disassembly, but as decomp by default). + +If you're opening a [Universal Mach-O](https://en.wikipedia.org/wiki/Universal_binary), the Open with Options dialogue will appear so that you can choose which architecture to open (in the top right). If you have a default architecture you want to open whenever you open a universal binary, you can set your preference in a setting called [Universal Mach-O Architecture Preference](../settings.md#all-settings). You'll also see the Open with Options dialogue when Binary Ninja is unable to recognize the file type or otherwise needs user input to analyze the file (can't find the entry point, needs you to provide some memory mappings, etc). + +It's worth digging into Binary Ninja's [settings](../settings.md) and seeing what's available to tune, but if you ever want to change a setting for a single binary, you can Open (it) with Options. Go to File -> Open with Options, and any settings you change will apply to only that file. + +<!-- TODO : Can you analyze a file while IDA is running its analysis? +## Analyzing While Analyzing --> + +## Keybindings + +Most of the keybindings you're used to are the same. Any "actions" (renaming, setting types, opening cross-references, etc) you might want to perform can be found in the [command palette](../index.md#command-palette), which will save you from digging through unfamiliar right-click menus and help you learn any new keybindings. You can even [add your own actions](https://binary.ninja/2024/02/15/command-palette.html#how-do-i-register-actions-with-the-command-palette-myself) with ease. All actions can have their keybinding set, changed, or removed in the [keybindings menu](../index.md#default-hotkeys). + +Some major exceptions are: + +- Save is `[CTRL/⌘-S]`. +- All our find options are under `[CTRL/⌘-F]`. +- The "subviews" keybindings are: + - `T` for Types + - `H` to toggle to/from Hex View + - `[TAB]` to toggle to/from disassembly + +## Theme + +We like our dark themes, but understand they're not for everyone. We have an expansive list of [community themes](https://github.com/Vector35/community-themes), and [a guide](../../dev/themes.md) and a [blog post](https://binary.ninja/2021/07/08/creating-great-themes.html) on how to make your own. The built-in "Classic" theme should feel nostalgic, but if you're looking for a light theme that's slightly easier on the eyes, try out Summer or Solarized Light. + +## Layout + +Binary Ninja's layout is very similar to what you're used to in IDA, but there's one setting you might want to change and a handful of improvements to look out for as well. + +### Feature Map + +If you want the [feature map](../index.md#feature-map) back to where you're used to, right-click it, find "Feature Map Location" and change it to the top. That said, take notice that Binary Ninja's feature map is 2d: both directions you move your cursor changes the address in Binary Ninja. The exact number of bytes that fit across the width of the feature map scales to the size of the binary. You can disable this in the right-click menu by selecting "Linear Feature Map." + +We also have an entropy map, if you need it, but it's tucked away in [triage view](https://binary.ninja/2019/04/01/hackathon-2019-summary.html#triage-mode-rusty). + +### Sidebars + +Our sidebars have a whole host of customization options, so make sure to check out [their dedicated docs](../index.md#the-sidebar) to maximize your workflow. + +#### Main Area + +Binary Ninja shows you linear decompilation by default for the whole binary. However, some people strongly prefer the "single function at a time" workflow, so we made an option for that too. Find the small hamburger menu (the three line pop-out menu) in the top right of your view and select “Single Function View.” + +Check out the [tiling panes](../index.md#tiling-panes) docs for more information. + +## What You'll Love + +...about switching to Binary Ninja! We know leaving your old tool behind can be hard, and there will be things you miss, but we think there are a lot of features packed into Binary Ninja that you'll love. Here are a couple we think you'll appreciate: + + - Decompilation for every architecture, including [ones you bring yourself](https://binary.ninja/2020/01/08/guide-to-architecture-plugins-part1.html) + - [Updates every day](../index.md#updates) on the dev branch (nearly) + - [Our awesome native Python API](../../dev/cookbook.md) (and [C++](https://api.binary.ninja/cpp/), and [Rust](https://dev-rust.binary.ninja/)) + - [**So** much open source](https://github.com/Vector35/binaryninja-api?tab=readme-ov-file#related-repositories) (that includes our architecture modules!) + +--- + +Don't forget to check out our [additional resources](index.md#additional-resources)! diff --git a/docs/guide/objectivec.md b/docs/guide/objectivec.md index f101d7a5..4178fc0e 100644 --- a/docs/guide/objectivec.md +++ b/docs/guide/objectivec.md @@ -31,14 +31,14 @@ analysis. _If you have already marked up Objective-C structures or modified function types yourself, be aware that they may be overwritten when this action is run._ - + ### Workflow To utilize function call cleanup, the workflows feature must be enabled, and the Objective-C workflow must be chosen when loading a binary for analysis. - + This will automatically apply structure analysis as the binary is analyzed and also translate `objc_msgSend` calls to direct method calls, where possible. diff --git a/docs/guide/plugins.md b/docs/guide/plugins.md index e7e8ec48..0807f069 100644 --- a/docs/guide/plugins.md +++ b/docs/guide/plugins.md @@ -12,7 +12,7 @@ Note that plugins installed via the [PluginManager API](https://api.binary.ninja ## Plugin 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: diff --git a/docs/guide/projects.md b/docs/guide/projects.md new file mode 100644 index 00000000..8f4366c1 --- /dev/null +++ b/docs/guide/projects.md @@ -0,0 +1,122 @@ +# Projects + +Projects provide a way to keep and organize related binaries, databases, and resources in a managed format. + +???+ Important "Supported Editions" + Projects are only available in the Commercial and Enterprise editions of Binary Ninja + +## Creating a Project + +A new project can be created by either selecting `New Project` from the new tab page or `File > New Project` from the application toolbar. After creation, the new project will be opened automatically. + +## Opening a Project + +Existing projects can be opened by: + +- Opening the `.bnpm` (or `.bnpr` on macOS) like any other file in Binary Ninja +- Double-clicking the project from the "Recent Projects" list in a new tab + +When a project is first opened, a new window will be created for it. This window is permanently tied to this project, meaning that it will only contain files associated with this project. + +## Structure on Disk + +A project has a few components stored on disk: + +- A top-level `.bnpr` directory that contains everything +- A `project.bnpm` project metadata file +- Optionally a `settings.json` file if project settings have been modified +- A `data` directory that contains the data for files in the project + +## Project Browser + +The primary method of interaction with a project is through the "Project Browser" UI. + + + +1. The name of the project +2. Edit project details +3. Description of project +4. Import files to the project +5. Import a folder to the project +6. View and modify project-level settings +7. Tab for project file tree +8. Tab for Recent project file list +9. Refresh project +10. Filter the current view for files and folders +11. Project contents tree +12. Info widget showing details about the currently selected items +13. Description of currently selected item + +### Adding Files to a Project + +There are a handful of ways to add files to a project: + +- Drag and drop files and folders directly into the project browser +- Using the `Import Files` button, select files to add to the currently selected folder +- Using the `Import Folder` button, select a folder to recursively import under the selected folder + +### Exporting Files from a Project + +To export files/folders from a project, select any number of files and folders in the project browser and choose `Export Selected` from the context menu or `Project Browser - Export Selected` from the command palette. + +### Batch Analysis + +Files in a project can be batch-analyzed easily from the project browser. Simply select the files to analyze and choose `Analyze Selected` from the context menu or `Project Browser - Analyze Selected` from the command palette. This will create a BNDB for each selected file, unless it is a BNDB itself. + +## Project Settings + +Project level settings let you set project-wide settings that apply to every file in the project. See the [settings documentation](settings.md) for more information. + +## External Links + +{ width="400" } + +In the `External Links` sidebar widget, there is a top level entry for each defined `External Library`. Additionally, there is a special top-level entry: `<No Library>`, that contains all `External Locations` that are yet to be assigned to an `External Library`. + + + +### External Libraries + +An External Library represents a full library, optionally backed by a project file (e.g. `libc.so` which is backed by `libc.bndb`). + + +#### Creating an External Library + +{ width="800" } + +Creating an `External Library` can be done via context menu or command palette action `Create External Library...` with the `External Links` sidebar widget focused. This will open a dialog that lets you specify the name and (optionally) the file backing the new library. `External Libraries` are identified by a unique name that is immutable after creation. + + +#### Editing an External Library + +Editing an existing `External Library` can be done via context menu or command palette action `Edit External Library...` with a library entry selected. This uses the same dialog as creation, but the "name" field is not editable. + + +#### Removing an External Library + +Removing an `External Library` can be done via context menu or command palette action `Remove External Library...` with a library entry selected. This will delete the `External Library`, and all associated `External Locations` will have their library unassigned. + + +### External Locations + +An External Location represents a symbol in a `Binary View` that points to an external target address and/or symbol in an `External Library` (e.g. `strcpy` points to `strcpy` in `libc.so`). When attempting to navigate to the symbol that is the source of an `External Location` with an `External Library` assigned, you will instead navigate to the destination address or symbol in the `External Library`, if it is backed by a file. + + +#### Creating an External Location + +{ width="600" } + + +Creating an `External Location` can be done via context menu or command palette action `Create External Location...` with the `External Links` sidebar widget focused. This will open a dialog that lets you specify the internal symbol that is the source of the link, (optionally) the library that the `External Location` points to, and the external symbol and/or address. `External Locations` must always have at least one of the external symbol or address populated. + + +#### Editing an External Location + +Editing an `External Location` can be done via context menu or command palette action `Edit External Location...` with a location entry selected. This uses the same dialog as creation, but the "internal symbol" field is not editable. + +To easily change the assigned library for one or more `External Locations`, you can select and drag them to the desired `External Library` top-level entry. + + +#### Removing an External Location + +Removing an `External Location` can be done via context menu or command palette action `Remove External Location...` with a location entry selected. diff --git a/docs/guide/settings.md b/docs/guide/settings.md index 7a8714fe..02284f73 100644 --- a/docs/guide/settings.md +++ b/docs/guide/settings.md @@ -2,7 +2,7 @@ ## UI - +{ width="800" } Binary Ninja provides various settings which are available via the `[CMD/CTRL] ,` hotkey for *User* settings and the `[CMD/CTRL] .` hotkey for *Resource* settings which apply to the current BinaryView. These settings allow a wide variety of customization of the user interface and functional aspects of the analysis environment. @@ -30,29 +30,30 @@ All settings are uniquely identified with an identifier string. Identifiers are ## All Settings |Category|Setting|Description|Type|Default|Scope|Key| |---|---|---|---|---|---|---| +|analysis|Alternate Type Propagation|Enable an alternate approach for function type propagation. This setting is experimental and may be useful for some binaries.|`boolean`|`True`|[`SettingsProjectScope`, `SettingsResourceScope`, `SettingsUserScope`]|<a id='analysis.alternateTypePropagation'>analysis.alternateTypePropagation</a>| +|analysis|Automatic Name Variables|Automatically name variables according to their usage.|`boolean`|`True`|[`SettingsProjectScope`, `SettingsResourceScope`, `SettingsUserScope`]|<a id='analysis.autoNameVariables'>analysis.autoNameVariables</a>| |analysis|Disallow Branch to String|Enable the ability to halt analysis of branch targets that fall within a string reference. This setting may be useful for malformed binaries.|`boolean`|`False`|[`SettingsProjectScope`, `SettingsResourceScope`, `SettingsUserScope`]|<a id='analysis.conservative.disallowBranchToString'>analysis.conservative.disallowBranchToString</a>| +|analysis|Correlated Memory Value Propagation|Attempt to propagate the value of an expression from a memory definition to a usage. Currently this feature is simplistic and the scope is a single basic block. This setting is experimental and may be useful for some binaries.|`boolean`|`True`|[`SettingsProjectScope`, `SettingsResourceScope`, `SettingsUserScope`]|<a id='analysis.correlatedMemoryValuePropagation'>analysis.correlatedMemoryValuePropagation</a>| |analysis|Purge Original Filename Path|When saving a database, remove all path information from the Original Filename field|`boolean`|`False`|[`SettingsProjectScope`, `SettingsUserScope`]|<a id='analysis.database.purgeOriginalFilenamePath'>analysis.database.purgeOriginalFilenamePath</a>| |analysis|Purge Snapshots|When saving a database, purge old snapshots keeping only the current snapshot.|`boolean`|`False`|[`SettingsProjectScope`, `SettingsUserScope`]|<a id='analysis.database.purgeSnapshots'>analysis.database.purgeSnapshots</a>| |analysis|Purge Undo History|When saving a database, purge current and existing undo history.|`boolean`|`False`|[`SettingsProjectScope`, `SettingsUserScope`]|<a id='analysis.database.purgeUndoHistory'>analysis.database.purgeUndoHistory</a>| |analysis|Suppress Reanalysis|Disable function reanalysis on database load when the product version or analysis settings change.|`boolean`|`False`|[`SettingsProjectScope`, `SettingsResourceScope`, `SettingsUserScope`]|<a id='analysis.database.suppressReanalysis'>analysis.database.suppressReanalysis</a>| |analysis|External Debug Info File|Separate file to attempt to parse and import debug information from.|`string`| |[`SettingsProjectScope`, `SettingsResourceScope`, `SettingsUserScope`]|<a id='analysis.debugInfo.external'>analysis.debugInfo.external</a>| |analysis|Import Debug Information|Attempt to parse and apply debug information from each file opened.|`boolean`|`True`|[`SettingsProjectScope`, `SettingsResourceScope`, `SettingsUserScope`]|<a id='analysis.debugInfo.internal'>analysis.debugInfo.internal</a>| -|analysis|Alternate Type Propagation|Enable an alternate approach for function type propagation. This setting is experimental and may be useful for some binaries.|`boolean`|`True`|[`SettingsProjectScope`, `SettingsResourceScope`, `SettingsUserScope`]|<a id='analysis.experimental.alternateTypePropagation'>analysis.experimental.alternateTypePropagation</a>| -|analysis|Correlated Memory Value Propagation|Attempt to propagate the value of an expression from a memory definition to a usage. Currently this feature is simplistic and the scope is a single basic block. This setting is experimental and may be useful for some binaries.|`boolean`|`True`|[`SettingsProjectScope`, `SettingsResourceScope`, `SettingsUserScope`]|<a id='analysis.experimental.correlatedMemoryValuePropagation'>analysis.experimental.correlatedMemoryValuePropagation</a>| |analysis|Early Stack Constant Propagation|Propagate constants stored on the stack during Low Level IL analysis. This allows stack offsets to be resolved when stack pointer updates use constants placed on the stack.|`string`|`inlined`|[`SettingsProjectScope`, `SettingsResourceScope`, `SettingsUserScope`]|<a id='analysis.experimental.earlyStackConstantPropagation'>analysis.experimental.earlyStackConstantPropagation</a>| | | | enum: Do not perform early constant propagation for stack variables|`enum`|`off`| | | | | | enum: Only perform early constant propagation when one or more functions have been inlined into the function|`enum`|`inlined`| | | | | | enum: Always perform early constant propagation for stack variables|`enum`|`on`| | | |analysis|Gratuitous Function Update|Force the function update cycle to always end with an IncrementalAutoFunctionUpdate type.|`boolean`|`False`|[`SettingsProjectScope`, `SettingsResourceScope`, `SettingsUserScope`]|<a id='analysis.experimental.gratuitousFunctionUpdate'>analysis.experimental.gratuitousFunctionUpdate</a>| -|analysis|Heuristic Value Range Clamping|Use DataVariable state inferencing to help determine the possible size of a lookup table.|`boolean`|`True`|[`SettingsProjectScope`, `SettingsResourceScope`, `SettingsUserScope`]|<a id='analysis.experimental.heuristicRangeClamp'>analysis.experimental.heuristicRangeClamp</a>| |analysis|Keep Dead Code Branches|Keep unreachable code branches and associated basic blocks in HLIL.|`boolean`|`False`|[`SettingsProjectScope`, `SettingsResourceScope`, `SettingsUserScope`]|<a id='analysis.experimental.keepDeadCodeBranches'>analysis.experimental.keepDeadCodeBranches</a>| -|analysis|Return Value Propagation|Propagate and use constant return values from functions in the caller in order to simplify downstream expressions.|`boolean`|`True`|[`SettingsProjectScope`, `SettingsResourceScope`, `SettingsUserScope`]|<a id='analysis.experimental.returnValuePropagation'>analysis.experimental.returnValuePropagation</a>| -|analysis|Translate Windows CFG Calls|Attempt to identify and translate calls to `_guard_dispatch_icall_nop` to improve analysis of control flow guard binaries.|`boolean`|`True`|[`SettingsProjectScope`, `SettingsResourceScope`, `SettingsUserScope`]|<a id='analysis.experimental.translateWindowsCfgCalls'>analysis.experimental.translateWindowsCfgCalls</a>| |analysis|Extract Types From Mangled Names|Attempt to extract types from mangled names using the demangler. This can lead to recovering inaccurate parameters.|`boolean`|`True`|[`SettingsProjectScope`, `SettingsResourceScope`, `SettingsUserScope`]|<a id='analysis.extractTypesFromMangledNames'>analysis.extractTypesFromMangledNames</a>| |analysis|Always Analyze Indirect Branches|When using faster analysis modes, perform full analysis of functions containing indirect branches.|`boolean`|`True`|[`SettingsProjectScope`, `SettingsResourceScope`, `SettingsUserScope`]|<a id='analysis.forceIndirectBranches'>analysis.forceIndirectBranches</a>| +|analysis|Heuristic Value Range Clamping|Use DataVariable state inferencing to help determine the possible size of a lookup table.|`boolean`|`True`|[`SettingsProjectScope`, `SettingsResourceScope`, `SettingsUserScope`]|<a id='analysis.heuristicRangeClamp'>analysis.heuristicRangeClamp</a>| |analysis|Aggressive Condition Complexity Removal Threshold|High Level IL tuning parameter.|`number`|`64`|[`SettingsProjectScope`, `SettingsResourceScope`, `SettingsUserScope`]|<a id='analysis.hlil.aggressiveConditionComplexityRemovalThreshold'>analysis.hlil.aggressiveConditionComplexityRemovalThreshold</a>| +|analysis|Graph Optimizer Limit|High Level IL tuning parameter.|`number`|`64`|[`SettingsProjectScope`, `SettingsResourceScope`, `SettingsUserScope`]|<a id='analysis.hlil.graphOptimizerLimit'>analysis.hlil.graphOptimizerLimit</a>| |analysis|Max Condition Complexity|High Level IL tuning parameter.|`number`|`1024`|[`SettingsProjectScope`, `SettingsResourceScope`, `SettingsUserScope`]|<a id='analysis.hlil.maxConditionComplexity'>analysis.hlil.maxConditionComplexity</a>| |analysis|Max Condition Reduce Iterations|High Level IL tuning parameter.|`number`|`1024`|[`SettingsProjectScope`, `SettingsResourceScope`, `SettingsUserScope`]|<a id='analysis.hlil.maxConditionReduceIterations'>analysis.hlil.maxConditionReduceIterations</a>| +|analysis|Maximum Expression Count|High Level IL tuning parameter.|`number`|`1048576`|[`SettingsProjectScope`, `SettingsResourceScope`, `SettingsUserScope`]|<a id='analysis.hlil.maxExpressionCount'>analysis.hlil.maxExpressionCount</a>| |analysis|Max Intermediate Condition Complexity|High Level IL tuning parameter.|`number`|`1048576`|[`SettingsProjectScope`, `SettingsResourceScope`, `SettingsUserScope`]|<a id='analysis.hlil.maxIntermediateConditionComplexity'>analysis.hlil.maxIntermediateConditionComplexity</a>| |analysis|Eliminate Pure Calls during HLIL Optimization|Whether or not pure calls (calls to functions with no side-effects) are removed during HLIL optimizations.|`boolean`|`True`|[`SettingsProjectScope`, `SettingsResourceScope`, `SettingsUserScope`]|<a id='analysis.hlil.pureCallElimination'>analysis.hlil.pureCallElimination</a>| |analysis|Strict Memory Ordering|Prevents reordering of memory reads during HLIL optimization.|`boolean`|`False`|[`SettingsProjectScope`, `SettingsResourceScope`, `SettingsUserScope`]|<a id='analysis.hlil.strictMemoryOrdering'>analysis.hlil.strictMemoryOrdering</a>| @@ -77,6 +78,8 @@ All settings are uniquely identified with an identifier string. Identifiers are |analysis|Low Entropy Threshold for Linear Sweep|Regions in the binary at or below this threshold are not included in the search space for linear sweep.|`number`|`0.025`|[`SettingsProjectScope`, `SettingsResourceScope`, `SettingsUserScope`]|<a id='analysis.linearSweep.entropyThresholdLow'>analysis.linearSweep.entropyThresholdLow</a>| |analysis|Max Linear Sweep Work Queues|The number of binary regions under concurrent analysis.|`number`|`64`|[`SettingsProjectScope`, `SettingsResourceScope`, `SettingsUserScope`]|<a id='analysis.linearSweep.maxWorkQueues'>analysis.linearSweep.maxWorkQueues</a>| |analysis|Permissive Linear Sweep|Permissive linear sweep searches all executable segments regardless of read/write permissions. By default, linear sweep searches sections that are ReadOnlyCodeSectionSemantics, or if no sections are defined, segments that are read/execute.|`boolean`|`False`|[`SettingsProjectScope`, `SettingsResourceScope`, `SettingsUserScope`]|<a id='analysis.linearSweep.permissive'>analysis.linearSweep.permissive</a>| +|analysis|Program's Exit Symbol List|A list of common 'exit' symbols to search for when 'Navigate to Program's Main' is enabled.|`array`|[`_cexit`, `_exit`, `_o__cexit`, `_o_exit`, `common_exit`, `doexit`, `exit`]|[`SettingsUserScope`]|<a id='analysis.mainFunctionDetection.exitSymbols'>analysis.mainFunctionDetection.exitSymbols</a>| +|analysis|Program's Main Symbol List|A list of common 'main' symbols to search for when 'Navigate to Program's Main' is enabled.|`array`|[`WinMain`, `_main`, `main`, `wWinMain`]|[`SettingsUserScope`]|<a id='analysis.mainFunctionDetection.mainSymbols'>analysis.mainFunctionDetection.mainSymbols</a>| |analysis|Load/Store Splitting|Controls splitting of oversized variable field accesses into appropriately sized accesses|`string`|`validFieldsOnly`|[`SettingsProjectScope`, `SettingsResourceScope`, `SettingsUserScope`]|<a id='analysis.mlil.loadStoreSplitting'>analysis.mlil.loadStoreSplitting</a>| | | | enum: Do not split oversized accesses to fields|`enum`|`off`| | | | | | enum: Split oversized accesses to valid fields and hide accessed gaps/alignment/padding bytes|`enum`|`validFieldsOnly`| | | @@ -88,10 +91,12 @@ All settings are uniquely identified with an identifier string. Identifiers are | | | enum: Perform full analysis of the binary.|`enum`|`full`| | | |analysis|Builtin Outlining of Constant Expressions|Enable outlining of constant expression compiler emitted builtins.|`boolean`|`True`|[`SettingsProjectScope`, `SettingsResourceScope`, `SettingsUserScope`]|<a id='analysis.outlining.builtins'>analysis.outlining.builtins</a>| |analysis|Autorun Pointer Sweep|Automatically run pointer sweep when opening a binary for analysis.|`boolean`|`True`|[`SettingsProjectScope`, `SettingsResourceScope`, `SettingsUserScope`]|<a id='analysis.pointerSweep.autorun'>analysis.pointerSweep.autorun</a>| +|analysis|Return Value Propagation|Propagate and use constant return values from functions in the caller in order to simplify downstream expressions.|`boolean`|`True`|[`SettingsProjectScope`, `SettingsResourceScope`, `SettingsUserScope`]|<a id='analysis.returnValuePropagation'>analysis.returnValuePropagation</a>| |analysis|Autorun Function Signature Matcher|Automatically run the function signature matcher when opening a binary for analysis.|`boolean`|`True`|[`SettingsProjectScope`, `SettingsResourceScope`, `SettingsUserScope`]|<a id='analysis.signatureMatcher.autorun'>analysis.signatureMatcher.autorun</a>| |analysis|Auto Function Analysis Suppression|Enable suppressing analysis of automatically discovered functions.|`boolean`|`False`|[`SettingsProjectScope`, `SettingsResourceScope`, `SettingsUserScope`]|<a id='analysis.suppressNewAutoFunctionAnalysis'>analysis.suppressNewAutoFunctionAnalysis</a>| |analysis|Tail Call Heuristics|Attempts to recover function starts that may be obscured by tail call optimization (TCO). Specifically, branch targets within a function are analyzed as potential function starts.|`boolean`|`True`|[`SettingsProjectScope`, `SettingsResourceScope`, `SettingsUserScope`]|<a id='analysis.tailCallHeuristics'>analysis.tailCallHeuristics</a>| |analysis|Tail Call Translation|Performs tail call translation for jump instructions where the target is an existing function start.|`boolean`|`True`|[`SettingsProjectScope`, `SettingsResourceScope`, `SettingsUserScope`]|<a id='analysis.tailCallTranslation'>analysis.tailCallTranslation</a>| +|analysis|Translate Windows CFG Calls|Attempt to identify and translate calls to `_guard_dispatch_icall_nop` to improve analysis of control flow guard binaries.|`boolean`|`True`|[`SettingsProjectScope`, `SettingsResourceScope`, `SettingsUserScope`]|<a id='analysis.translateWindowsCfgCalls'>analysis.translateWindowsCfgCalls</a>| |analysis|Padding Threshold|Specify the minimum number of undefined bytes in a structure type before __padding notation is used when rendering the type to text. This setting does not affect exporting types to a file, where the __padding notation will always be used.|`number`|`1024`|[`SettingsProjectScope`, `SettingsResourceScope`, `SettingsUserScope`]|<a id='analysis.types.paddingThreshold'>analysis.types.paddingThreshold</a>| |analysis|Type Parser|Specify the implementation used for parsing types from text.|`string`|`ClangTypeParser`|[`SettingsProjectScope`, `SettingsResourceScope`, `SettingsUserScope`]|<a id='analysis.types.parserName'>analysis.types.parserName</a>| | | | |`enum`|`ClangTypeParser`| | | @@ -102,7 +107,8 @@ All settings are uniquely identified with an identifier string. Identifiers are |analysis|UTF-16 Encoding|Whether or not to consider UTF-16 code points when searching for strings.|`boolean`|`True`|[`SettingsProjectScope`, `SettingsResourceScope`, `SettingsUserScope`]|<a id='analysis.unicode.utf16'>analysis.unicode.utf16</a>| |analysis|UTF-32 Encoding|Whether or not to consider UTF-32 code points when searching for strings.|`boolean`|`True`|[`SettingsProjectScope`, `SettingsResourceScope`, `SettingsUserScope`]|<a id='analysis.unicode.utf32'>analysis.unicode.utf32</a>| |analysis|UTF-8 Encoding|Whether or not to consider UTF-8 code points when searching for strings.|`boolean`|`True`|[`SettingsProjectScope`, `SettingsResourceScope`, `SettingsUserScope`]|<a id='analysis.unicode.utf8'>analysis.unicode.utf8</a>| -|arch|MIPS Disassembly Pseudo-Op|Enable use of pseudo-op instructions in MIPS disassembly.|`boolean`|`True`|[`SettingsProjectScope`, `SettingsResourceScope`, `SettingsUserScope`]|<a id='arch.mips.disassembly.pseudo_ops'>arch.mips.disassembly.pseudo_ops</a>| +|arch|AARCH64 Alignment Requirement|Require instructions be on 4-byte aligned addresses to be disassembled.|`boolean`|`True`|[`SettingsProjectScope`, `SettingsResourceScope`, `SettingsUserScope`]|<a id='arch.aarch64.disassembly.alignRequired'>arch.aarch64.disassembly.alignRequired</a>| +|arch|MIPS Disassembly Pseudo-Op|Enable use of pseudo-op instructions in MIPS disassembly.|`boolean`|`True`|[`SettingsProjectScope`, `SettingsResourceScope`, `SettingsUserScope`]|<a id='arch.mips.disassembly.pseudoOps'>arch.mips.disassembly.pseudoOps</a>| |arch|x86 Disassembly Case|Specify the case for opcodes, operands, and registers.|`boolean`|`True`|[`SettingsUserScope`]|<a id='arch.x86.disassembly.lowercase'>arch.x86.disassembly.lowercase</a>| |arch|x86 Disassembly Separator|Specify the token separator between operands.|`string`|`, `|[`SettingsUserScope`]|<a id='arch.x86.disassembly.separator'>arch.x86.disassembly.separator</a>| |arch|x86 Disassembly Syntax|Specify disassembly syntax for the x86/x86_64 architectures.|`string`|`BN_INTEL`|[`SettingsUserScope`]|<a id='arch.x86.disassembly.syntax'>arch.x86.disassembly.syntax</a>| @@ -113,12 +119,13 @@ All settings are uniquely identified with an identifier string. Identifiers are |corePlugins|ARMv7 Architecture|Enable the built-in ARMv7 architecture module.|`boolean`|`True`|[`SettingsUserScope`]|<a id='corePlugins.architectures.armv7'>corePlugins.architectures.armv7</a>| |corePlugins|MIPS Architecture|Enable the built-in MIPS architecture module.|`boolean`|`True`|[`SettingsUserScope`]|<a id='corePlugins.architectures.mips'>corePlugins.architectures.mips</a>| |corePlugins|PowerPC Architecture|Enable the built-in PowerPC architecture module.|`boolean`|`True`|[`SettingsUserScope`]|<a id='corePlugins.architectures.powerpc'>corePlugins.architectures.powerpc</a>| +|corePlugins|RISC-V Architecture|Enable the built-in RISC-V architecture module.|`boolean`|`True`|[`SettingsUserScope`]|<a id='corePlugins.architectures.riscv'>corePlugins.architectures.riscv</a>| |corePlugins|x86/x86_64 Architecture|Enable the built-in x86/x86_64 architecture module.|`boolean`|`True`|[`SettingsUserScope`]|<a id='corePlugins.architectures.x86'>corePlugins.architectures.x86</a>| |corePlugins|Crypto Plugin|Enable the built-in crypto plugin.|`boolean`|`True`|[`SettingsUserScope`]|<a id='corePlugins.crypto'>corePlugins.crypto</a>| |corePlugins|Database Viewer (Debug)|Enable the built-in Database Viewer plugin. Be aware this is a debug feature and may not be well-behaved.|`boolean`|`False`|[`SettingsUserScope`]|<a id='corePlugins.databaseViewer'>corePlugins.databaseViewer</a>| |corePlugins|Debugger|Enable the built-in debugger plugin.|`boolean`|`True`|[`SettingsUserScope`]|<a id='corePlugins.debugger'>corePlugins.debugger</a>| -|corePlugins|DWARF Export Plugin|Enable the experimental DWARF export plugin.|`boolean`|`True`|[`SettingsUserScope`]|<a id='corePlugins.dwarfExport'>corePlugins.dwarfExport</a>| -|corePlugins|DWARF Import Plugin|Enable the experimental DWARF import plugin.|`boolean`|`True`|[`SettingsUserScope`]|<a id='corePlugins.dwarfImport'>corePlugins.dwarfImport</a>| +|corePlugins|DWARF Export Plugin|Enable the DWARF export plugin.|`boolean`|`True`|[`SettingsUserScope`]|<a id='corePlugins.dwarfExport'>corePlugins.dwarfExport</a>| +|corePlugins|DWARF Import Plugin|Enable the DWARF import plugin.|`boolean`|`True`|[`SettingsUserScope`]|<a id='corePlugins.dwarfImport'>corePlugins.dwarfImport</a>| |corePlugins|PDB Import Plugin|Enable the built-in PDB import plugin.|`boolean`|`True`|[`SettingsUserScope`]|<a id='corePlugins.pdbImport'>corePlugins.pdbImport</a>| |corePlugins|DECREE Platform|Enable the built-in DECREE platform module.|`boolean`|`True`|[`SettingsUserScope`]|<a id='corePlugins.platforms.decree'>corePlugins.platforms.decree</a>| |corePlugins|EFI Platform|Enable the built-in EFI platform module.|`boolean`|`True`|[`SettingsUserScope`]|<a id='corePlugins.platforms.efi'>corePlugins.platforms.efi</a>| @@ -126,7 +133,9 @@ All settings are uniquely identified with an identifier string. Identifiers are |corePlugins|Linux Platform|Enable the built-in Linux platform module.|`boolean`|`True`|[`SettingsUserScope`]|<a id='corePlugins.platforms.linux'>corePlugins.platforms.linux</a>| |corePlugins|macOS Platform|Enable the built-in macOS platform module.|`boolean`|`True`|[`SettingsUserScope`]|<a id='corePlugins.platforms.mac'>corePlugins.platforms.mac</a>| |corePlugins|Windows Platform|Enable the built-in Windows platform module.|`boolean`|`True`|[`SettingsUserScope`]|<a id='corePlugins.platforms.windows'>corePlugins.platforms.windows</a>| +|corePlugins|Windows Kernel Platform|Enable the built-in Window Kernel platform module.|`boolean`|`True`|[`SettingsUserScope`]|<a id='corePlugins.platforms.windows_kernel'>corePlugins.platforms.windows_kernel</a>| |corePlugins|Triage Plugin|Enable the built-in triage plugin.|`boolean`|`True`|[`SettingsUserScope`]|<a id='corePlugins.triage'>corePlugins.triage</a>| +|corePlugins|Type Archive Inspector (Debug)|Enable the built-in Type Archive Inspector plugin. Be aware this is a debug feature and may not be well-behaved.|`boolean`|`False`|[`SettingsUserScope`]|<a id='corePlugins.typeArchiveViewer'>corePlugins.typeArchiveViewer</a>| |corePlugins|ELF View|Enable the built-in ELF view module.|`boolean`|`True`|[`SettingsUserScope`]|<a id='corePlugins.view.elf'>corePlugins.view.elf</a>| |corePlugins|Mach-O View|Enable the built-in Mach-O view module.|`boolean`|`True`|[`SettingsUserScope`]|<a id='corePlugins.view.macho'>corePlugins.view.macho</a>| |corePlugins|PE/COFF View|Enable the built-in PE/COFF view module.|`boolean`|`True`|[`SettingsUserScope`]|<a id='corePlugins.view.pe'>corePlugins.view.pe</a>| @@ -190,6 +199,7 @@ All settings are uniquely identified with an identifier string. Identifiers are |python|Python Virtual Environment Site-Packages|The 'site-packages' directory for your python virtual environment.|`string`| |[`SettingsUserScope`]|<a id='python.virtualenv'>python.virtualenv</a>| |rendering|Show variable and integer annotations|Show variable and integer annotations in disassembly i.e. {var_8}|`boolean`|`True`|[`SettingsUserScope`]|<a id='rendering.annotations'>rendering.annotations</a>| |rendering|Show All Expression Types in Debug Reports|Enables the "Show All Expression Types" option in debug reports.|`boolean`|`False`|[`SettingsUserScope`]|<a id='rendering.debug.types'>rendering.debug.types</a>| +|rendering|Add New Lines Around Scopes|Add extra newlines in HLIL between closing scopes and the following instructions.|`number`|`0`|[`SettingsUserScope`]|<a id='rendering.hlil.newLinesAroundScopes'>rendering.hlil.newLinesAroundScopes</a>| |rendering|HLIL Scoping Style|Controls the display of new scopes in HLIL.|`string`|`default`|[`SettingsUserScope`]|<a id='rendering.hlil.scopingStyle'>rendering.hlil.scopingStyle</a>| | | | enum: Default BNIL scoping style.|`enum`|`default`| | | | | | enum: Braces around scopes, same line.|`enum`|`braces`| | | @@ -212,10 +222,11 @@ All settings are uniquely identified with an identifier string. Identifiers are |triage|Always Prefer Triage Summary View|Always prefer opening binaries in Triage Summary view, even when performing full analysis.|`boolean`|`False`|[`SettingsProjectScope`, `SettingsResourceScope`, `SettingsUserScope`]|<a id='triage.preferSummaryView'>triage.preferSummaryView</a>| |triage|Prefer Triage Summary View for Raw Files|Prefer opening raw files in Triage Summary view.|`boolean`|`False`|[`SettingsProjectScope`, `SettingsResourceScope`, `SettingsUserScope`]|<a id='triage.preferSummaryViewForRaw'>triage.preferSummaryViewForRaw</a>| |ui|Allow Welcome Popup|By default, the welcome window will only show up when it has changed and this install has not seen it. However, disabling this setting will prevent even that.|`boolean`|`True`|[`SettingsUserScope`]|<a id='ui.allowWelcome'>ui.allowWelcome</a>| -|ui|Enable the new Symbols UI (Experimental)|Enables the new Symbols UI. The upgraded UI supports Folders, displaying addresses, and much more. Be aware that this is a feature preview and may still have issues.|`boolean`|`False`|[`SettingsProjectScope`, `SettingsUserScope`]|<a id='ui.components.enabled'>ui.components.enabled</a>| |ui|Dock Window Title Bars|Enable to display title bars for dockable windows attached to a main window.|`boolean`|`True`|[`SettingsUserScope`]|<a id='ui.docks.titleBars'>ui.docks.titleBars</a>| +|ui|Developer Tools|Enables Qt UI development tooling. Requires a restart and creates a new sidebar icon that can be enabled.|`boolean`|`False`|[`SettingsUserScope`]|<a id='ui.experimental.uiDeveloperTools'>ui.experimental.uiDeveloperTools</a>| |ui|Feature Map|Enable the feature map which displays a visual overview of the BinaryView.|`boolean`|`True`|[`SettingsProjectScope`, `SettingsResourceScope`, `SettingsUserScope`]|<a id='ui.featureMap.enable'>ui.featureMap.enable</a>| |ui|Feature Map File-Backed Only Mode|Exclude mapped regions that are not backed by a load file.|`boolean`|`False`|[`SettingsProjectScope`, `SettingsResourceScope`, `SettingsUserScope`]|<a id='ui.featureMap.fileBackedOnly'>ui.featureMap.fileBackedOnly</a>| +|ui|Linear Feature Map|Show feature map in one dimension instead of two.|`boolean`|`False`|[`SettingsProjectScope`, `SettingsResourceScope`, `SettingsUserScope`]|<a id='ui.featureMap.linear'>ui.featureMap.linear</a>| |ui|Feature Map Location|Location of the feature map.|`string`|`right`|[`SettingsUserScope`]|<a id='ui.featureMap.location'>ui.featureMap.location</a>| | | | enum: Feature map appears on the right side of the window.|`enum`|`right`| | | | | | enum: Feature map appears at the top of the window.|`enum`|`top`| | | @@ -235,13 +246,13 @@ All settings are uniquely identified with an identifier string. Identifiers are | | | |`enum`|`Universal`| | | | | | |`enum`|`PE`| | | | | | |`enum`|`COFF`| | | -|ui|Programmer's Main Symbol List|A list of common 'main' symbols to search for when 'Navigate to Programmer's Main' is enabled.|`array`|[`main`, `_main`, `WinMain`]|[`SettingsUserScope`]|<a id='ui.files.navigation.mainSymbols'>ui.files.navigation.mainSymbols</a>| |ui|Navigate to Programmer's Main|Detect and navigate to the 'main' function, rather than the entry point, after opening a binary.|`boolean`|`True`|[`SettingsUserScope`]|<a id='ui.files.navigation.preferMain'>ui.files.navigation.preferMain</a>| |ui|Restore Recent Open with Options|Restores previously modified settings in the 'Open with Options' dialog when opening or reopening files (databases excluded). Load options are only included when reopening the same file.|`string`|`disable`|[`SettingsUserScope`]|<a id='ui.files.restore.viewOptions'>ui.files.restore.viewOptions</a>| | | | enum: Only restore settings for files with existing history.|`enum`|`strict`| | | | | | enum: Restore settings for files with existing history and propagate most recently used settings for new files.|`enum`|`flexible`| | | | | | enum: Disable the settings history for 'Open with Options'.|`enum`|`disable`| | | |ui|Restore View State for File|Restores the last view state when reopening a file. The view state includes the layout and location.|`boolean`|`True`|[`SettingsUserScope`]|<a id='ui.files.restore.viewState'>ui.files.restore.viewState</a>| +|ui|'Save All' for Databases Only|Only save existing databases when using 'Save All'|`boolean`|`False`|[`SettingsUserScope`]|<a id='ui.files.saveAllOnlyDatabases'>ui.files.saveAllOnlyDatabases</a>| |ui|Font Antialiasing Style|Which antialiasing style should be used when drawing fonts.|`string`|`subpixel`|[`SettingsUserScope`]|<a id='ui.font.antialiasing'>ui.font.antialiasing</a>| | | | enum: Perform subpixel antialiasing on fonts.|`enum`|`subpixel`| | | | | | enum: Avoid subpixel antialiasing on fonts if possible.|`enum`|`grayscale`| | | @@ -249,11 +260,11 @@ All settings are uniquely identified with an identifier string. Identifiers are | | | enum: No font antialiasing.|`enum`|`none`| | | |ui|Application Font Name|The font to be used in UI elements, e.g. buttons, text fields, etc.|`string`|`Inter`|[`SettingsUserScope`]|<a id='ui.font.app.name'>ui.font.app.name</a>| |ui|Application Font Size|The desired font size (in points) for interface elements.|`number`|`12`|[`SettingsUserScope`]|<a id='ui.font.app.size'>ui.font.app.size</a>| -|ui|Emoji Font Name|The font to be used in for rendering emoji.|`string`|`Segoe UI Emoji` (Windows), `Apple Color Emoji` (macOS), `Noto Color Emoji` (Linux)|[`SettingsUserScope`]|<a id='ui.font.emoji.name'>ui.font.emoji.name</a>| +|ui|Emoji Font Name|The font to be used in for rendering emoji.|`string`|`Apple Color Emoji`|[`SettingsUserScope`]|<a id='ui.font.emoji.name'>ui.font.emoji.name</a>| |ui|Emoji Font Style|The subfamily of the emoji font that should be used.|`string`| |[`SettingsUserScope`]|<a id='ui.font.emoji.style'>ui.font.emoji.style</a>| |ui|Allow Bold View Fonts|Should bold view fonts be allowed?|`boolean`|`True`|[`SettingsUserScope`]|<a id='ui.font.view.bold'>ui.font.view.bold</a>| |ui|View Font Name|The font to be used in disassembly views, the hex editor, and anywhere a monospaced font is appropriate.|`string`|`Roboto Mono`|[`SettingsUserScope`]|<a id='ui.font.view.name'>ui.font.view.name</a>| -|ui|View Font Size|The desired font size (in points) for the view font.|`number`|`12` (macOS), `10` (Windows), `11` (Linux)|[`SettingsUserScope`]|<a id='ui.font.view.size'>ui.font.view.size</a>| +|ui|View Font Size|The desired font size (in points) for the view font.|`number`|`12`|[`SettingsUserScope`]|<a id='ui.font.view.size'>ui.font.view.size</a>| |ui|View Line Spacing|How much additional spacing should be inserted between baselines in views.|`number`|`1`|[`SettingsUserScope`]|<a id='ui.font.view.spacing'>ui.font.view.spacing</a>| |ui|View Font Style|The subfamily (e.g. Regular, Medium) of the view font that should be used.|`string`| |[`SettingsUserScope`]|<a id='ui.font.view.style'>ui.font.view.style</a>| |ui|Input Field History Limit|Controls the number of history entries to store for input dialogs.|`number`|`50`|[`SettingsUserScope`]|<a id='ui.inputHistoryCount'>ui.inputHistoryCount</a>| @@ -274,6 +285,10 @@ All settings are uniquely identified with an identifier string. Identifiers are | | | enum: Split to new pane and navigate|`enum`|`NewPane`| | | | | | enum: Split to new tab and navigate|`enum`|`NewTab`| | | | | | enum: Split to new window and navigate|`enum`|`NewWindow`| | | +|ui|New Tab Compact Mode|Display mode for files in Recent File list|`string`|`Normal`|[`SettingsUserScope`]|<a id='ui.newtab.compactMode'>ui.newtab.compactMode</a>| +| | | enum: Show both basename and full path.|`enum`|`Normal`| | | +| | | enum: Show only the basename|`enum`|`CompactBase`| | | +| | | enum: Show only the filepath|`enum`|`CompactFile`| | | |ui|Desired Maximum Columns for Split Panes|Number of horizontal splits (columns) before defaulting to a vertical split.|`number`|`2`|[`SettingsUserScope`]|<a id='ui.panes.columnCount'>ui.panes.columnCount</a>| |ui|Show Pane Headers|Enable to display headers containing the current view and options at the top of every pane. When headers are disabled, use the Command Palette or keyboard shortcuts to manage panes.|`boolean`|`True`|[`SettingsUserScope`]|<a id='ui.panes.headers'>ui.panes.headers</a>| |ui|Preferred Location for New Panes|Default corner for placement of new panes. Split will occur horizontally up to the maximum column setting, then vertically in the corner specified by this setting.|`string`|`bottomRight`|[`SettingsUserScope`]|<a id='ui.panes.newPaneLocation'>ui.panes.newPaneLocation</a>| @@ -296,39 +311,49 @@ All settings are uniquely identified with an identifier string. Identifiers are | | | |`enum`|`Target`| | | |ui|Scripting Provider History Size|Specify the maximum number of lines contained in the scripting history.|`number`|`1000`|[`SettingsUserScope`]|<a id='ui.scripting.historySize'>ui.scripting.historySize</a>| |ui|Display Settings Identifiers|Display setting identifiers in the UI settings view.|`boolean`|`False`|[`SettingsUserScope`]|<a id='ui.settings.displayIdentifiers'>ui.settings.displayIdentifiers</a>| -|ui|Default Sidebar Content on Open|Specify a sidebar widget to automatically activate in the content area when opening a file.|`string`|`Symbols`|[`SettingsUserScope`]|<a id='ui.sidebar.defaultContentWidget'>ui.sidebar.defaultContentWidget</a>| +|ui|Default Sidebar Content on Open|Specify the sidebar widgets to automatically activate when opening a file.|`array`|[`Cross References`, `Symbols`]|[`SettingsUserScope`]|<a id='ui.sidebar.defaultWidgets'>ui.sidebar.defaultWidgets</a>| | | | |`enum`|`None`| | | | | | |`enum`|`Symbols`| | | | | | |`enum`|`Types`| | | -| | | |`enum`|`Variables`| | | -| | | |`enum`|`Stack`| | | -| | | |`enum`|`Strings`| | | | | | |`enum`|`Tags`| | | | | | |`enum`|`Memory Map`| | | +| | | |`enum`|`External Links`| | | | | | |`enum`|`Debugger`| | | -|ui|Default Sidebar Reference on Open|Specify a sidebar widget to automatically activate in the reference area when opening a file.|`string`|`Cross References`|[`SettingsUserScope`]|<a id='ui.sidebar.defaultReferenceWidget'>ui.sidebar.defaultReferenceWidget</a>| -| | | |`enum`|`None`| | | | | | |`enum`|`Mini Graph`| | | | | | |`enum`|`Cross References`| | | +| | | |`enum`|`Other (Compatibility)`| | | +| | | |`enum`|`Console`| | | +| | | |`enum`|`Variables`| | | +| | | |`enum`|`Stack`| | | +| | | |`enum`|`Strings`| | | +| | | |`enum`|`Find`| | | +| | | |`enum`|`Log`| | | +| | | |`enum`|`Debugger Modules`| | | +| | | |`enum`|`Stack Trace`| | | +|ui|Extend Left Sidebar to Bottom of Window|When the left sidebar is open, the sidebar contents will extend to the bottom of the window. If not set, the bottom area will extend to the left edge of the window even when the left sidebar is open.|`boolean`|`True`|[`SettingsUserScope`]|<a id='ui.sidebar.extendLeftToBottom'>ui.sidebar.extendLeftToBottom</a>| +|ui|Extend Right Sidebar to Bottom of Window|When the right sidebar is open, the sidebar contents will extend to the bottom of the window. If not set, the bottom area will extend to the right edge of the window even when the right sidebar is open.|`boolean`|`False`|[`SettingsUserScope`]|<a id='ui.sidebar.extendRightToBottom'>ui.sidebar.extendRightToBottom</a>| +|ui|Sidebar Icon Size|Size of the icons in the sidebar.|`string`|`standard`|[`SettingsUserScope`]|<a id='ui.sidebar.iconSize'>ui.sidebar.iconSize</a>| +| | | enum: Compact icons to maximize available screen space.|`enum`|`compact`| | | +| | | enum: Default icon size.|`enum`|`standard`| | | +| | | enum: Large icons for more visibility.|`enum`|`large`| | | +|ui|Left Sidebar Reference Area Toggle Mode|Clicking on sidebar icons below the divider in the left sidebar will toggle the visibility of the icon clicked, regardless of how many sidebar icons are already active in that area. This mode can be used regardless of this setting by shift clicking the sidebar icon.|`boolean`|`True`|[`SettingsUserScope`]|<a id='ui.sidebar.leftReferenceAreaToggleMode'>ui.sidebar.leftReferenceAreaToggleMode</a>| |ui|Sidebar Mode|Select how the sidebar should react to tab changes.|`string`|`perTab`|[`SettingsUserScope`]|<a id='ui.sidebar.mode'>ui.sidebar.mode</a>| | | | enum: Sidebar layout and size is per tab and is remembered when moving between tabs.|`enum`|`perTab`| | | | | | enum: Sidebar widgets are per tab but the size of the sidebar is static and does not change.|`enum`|`staticSize`| | | | | | enum: Sidebar layout is fully static and stays in the current layout when moving between tabs.|`enum`|`static`| | | |ui|Open Sidebar on Startup|Open sidebar to default widgets when Binary Ninja is initially launched.|`boolean`|`False`|[`SettingsUserScope`]|<a id='ui.sidebar.openOnStartup'>ui.sidebar.openOnStartup</a>| -|ui|Show Exported Data Variables|Show exported data variables in the symbol list.|`boolean`|`False`|[`SettingsProjectScope`, `SettingsUserScope`]|<a id='ui.symbolList.showExportedDataVars'>ui.symbolList.showExportedDataVars</a>| -|ui|Show Exported Functions|Show exported functions in the symbol list.|`boolean`|`True`|[`SettingsProjectScope`, `SettingsUserScope`]|<a id='ui.symbolList.showExportedFunctions'>ui.symbolList.showExportedFunctions</a>| -|ui|Show Imports|Show imports in the symbol list.|`boolean`|`True`|[`SettingsProjectScope`, `SettingsUserScope`]|<a id='ui.symbolList.showImports'>ui.symbolList.showImports</a>| -|ui|Show Local Data Variables|Show local data variables in the symbol list.|`boolean`|`False`|[`SettingsProjectScope`, `SettingsUserScope`]|<a id='ui.symbolList.showLocalDataVars'>ui.symbolList.showLocalDataVars</a>| -|ui|Show Local Functions|Show local functions in the symbol list.|`boolean`|`True`|[`SettingsProjectScope`, `SettingsUserScope`]|<a id='ui.symbolList.showLocalFunctions'>ui.symbolList.showLocalFunctions</a>| +|ui|Right Sidebar Reference Area Toggle Mode|Clicking on sidebar icons below the divider in the right sidebar will toggle the visibility of the icon clicked, regardless of how many sidebar icons are already active in that area. This mode can be used regardless of this setting by shift clicking the sidebar icon.|`boolean`|`True`|[`SettingsUserScope`]|<a id='ui.sidebar.rightReferenceAreaToggleMode'>ui.sidebar.rightReferenceAreaToggleMode</a>| |ui|Max Tab Filename Length|Truncate filenames longer than this in tab titles.|`number`|`25`|[`SettingsUserScope`]|<a id='ui.tabs.maxFileLength'>ui.tabs.maxFileLength</a>| |ui|Color Blind Mode|Choose colors that are visible to those with red/green color blindness.|`boolean`|`False`|[`SettingsUserScope`]|<a id='ui.theme.colorBlind'>ui.theme.colorBlind</a>| -|ui|Show Entry/Exit Indicators on Blocks|Draws an extra line to indicate which blocks in Graph View are entry / exit points in the function. Blocks that do not return have their indicators drawn in a different color.|`boolean`|`True`|[`SettingsUserScope`]|<a id='ui.theme.entryExitBlockIndicators'>ui.theme.entryExitBlockIndicators</a>| -|ui|Theme|Customize the appearance and style of Binary Ninja.|`string`|`Dark`|[`SettingsUserScope`]|<a id='ui.theme.name'>ui.theme.name</a>| +|ui|Theme|Customize the appearance and style of Binary Ninja.|`string`|`Ninja Edit`|[`SettingsUserScope`]|<a id='ui.theme.name'>ui.theme.name</a>| | | | |`enum`|`Classic`| | | | | | |`enum`|`Dark`| | | | | | |`enum`|`High Contrast`| | | | | | |`enum`|`Ninja Dark`| | | +| | | |`enum`|`Ninja Edit`| | | | | | |`enum`|`Reflection`| | | +| | | |`enum`|`Slushee Dark`| | | +| | | |`enum`|`Slushee Light`| | | | | | |`enum`|`Solarized Dark`| | | | | | |`enum`|`Solarized Light`| | | | | | |`enum`|`Summer`| | | @@ -337,7 +362,7 @@ All settings are uniquely identified with an identifier string. Identifiers are |ui|Comment Width|Maximum width of comment before wrapping, in characters. A value of 0x0 means no wrapping.|`number`|`80`|[`SettingsUserScope`]|<a id='ui.view.common.commentWidth'>ui.view.common.commentWidth</a>| |ui|Disassembly Width|Maximum width of disassembly output, in characters. Not used in cases where disassembly width is automatically calculated, e.g. Linear View.|`number`|`80`|[`SettingsUserScope`]|<a id='ui.view.common.disassemblyWidth'>ui.view.common.disassemblyWidth</a>| |ui|Maximum Symbol Name Length|Maximum allowed length of symbol names (in characters) before truncation is used.|`number`|`64`|[`SettingsUserScope`]|<a id='ui.view.common.maxSymbolWidth'>ui.view.common.maxSymbolWidth</a>| -|ui|Graph View IL Carousel|Specify the IL view types and order for use with the 'Cycle IL' actions in Graph view.|`array`|[`Disassembly`, `LowLevelIL`, `MediumLevelIL`, `HighLevelIL`]|[`SettingsUserScope`]|<a id='ui.view.graph.carousel'>ui.view.graph.carousel</a>| +|ui|Graph View IL Carousel|Specify the IL view types and order for use with the 'Cycle IL' actions in Graph view.|`array`|[`Disassembly`, `HighLevelIL`, `LowLevelIL`, `MediumLevelIL`]|[`SettingsUserScope`]|<a id='ui.view.graph.carousel'>ui.view.graph.carousel</a>| | | | |`enum`|`Disassembly`| | | | | | |`enum`|`LowLevelIL`| | | | | | |`enum`|`LiftedIL`| | | @@ -349,6 +374,7 @@ All settings are uniquely identified with an identifier string. Identifiers are | | | |`enum`|`HighLevelIL`| | | | | | |`enum`|`HighLevelILSSAForm`| | | | | | |`enum`|`PseudoC`| | | +|ui|Show Entry/Exit Indicators on Blocks|Draws an extra line to indicate which blocks in Graph View are entry / exit points in the function. Blocks that do not return have their indicators drawn in a different color.|`boolean`|`True`|[`SettingsUserScope`]|<a id='ui.view.graph.entryExitBlockIndicators'>ui.view.graph.entryExitBlockIndicators</a>| |ui|Default IL for Graph View|Default IL for graph view. Other settings (e.g. 'ui.files.restore.viewState') have precedence over the default behavior.|`string`|`Disassembly`|[`SettingsUserScope`]|<a id='ui.view.graph.il'>ui.view.graph.il</a>| | | | |`enum`|`Disassembly`| | | | | | |`enum`|`LowLevelIL`| | | @@ -389,10 +415,20 @@ All settings are uniquely identified with an identifier string. Identifiers are | | | |`enum`|`HighLevelIL`| | | | | | |`enum`|`HighLevelILSSAForm`| | | | | | |`enum`|`PseudoC`| | | -|ui|Default filter for types view|Default type filter to use in types view.|`string`|`user`|[`SettingsProjectScope`, `SettingsResourceScope`, `SettingsUserScope`]|<a id='ui.view.types.defaultTypeFilter'>ui.view.types.defaultTypeFilter</a>| -| | | |`enum`|`all`| | | -| | | |`enum`|`user`| | | -|ui|TypeView Line Numbers|Controls the display of line numbers in the types view.|`boolean`|`True`|[`SettingsUserScope`]|<a id='ui.view.types.lineNumbers'>ui.view.types.lineNumbers</a>| +|ui|Display Raw Symbol Name|Display the original, unaltered name of a symbol as extracted from a load file. The name may be mangled.|`boolean`|`False`|[`SettingsProjectScope`, `SettingsResourceScope`, `SettingsUserScope`]|<a id='ui.view.symbols.displayRawNames'>ui.view.symbols.displayRawNames</a>| +|ui|Display Short Symbol Name|Display a shortened version of the full, human-readable representation of the symbol name.|`boolean`|`False`|[`SettingsProjectScope`, `SettingsResourceScope`, `SettingsUserScope`]|<a id='ui.view.symbols.displayShortNames'>ui.view.symbols.displayShortNames</a>| +|ui|Hide Auto Symbols|Hide all symbols that are not explicitly defined by a user.|`boolean`|`False`|[`SettingsProjectScope`, `SettingsResourceScope`, `SettingsUserScope`]|<a id='ui.view.symbols.hideAutoSymbols'>ui.view.symbols.hideAutoSymbols</a>| +|ui|Symbols Hierarchy Mode|Enables hierarchical organization of symbols in the UI.|`boolean`|`True`|[`SettingsProjectScope`, `SettingsUserScope`]|<a id='ui.view.symbols.hierarchyMode'>ui.view.symbols.hierarchyMode</a>| +|ui|Seamless Navigation|Enables uninterrupted navigation on item selection without losing focus.|`boolean`|`False`|[`SettingsProjectScope`, `SettingsResourceScope`, `SettingsUserScope`]|<a id='ui.view.symbols.seamlessNavigation'>ui.view.symbols.seamlessNavigation</a>| +|ui|Show Exported Data Variables|Show exported data variables in the symbols view.|`boolean`|`False`|[`SettingsProjectScope`, `SettingsResourceScope`, `SettingsUserScope`]|<a id='ui.view.symbols.showExportedDataVariables'>ui.view.symbols.showExportedDataVariables</a>| +|ui|Show Exported Functions|Show exported functions in the symbols view.|`boolean`|`True`|[`SettingsProjectScope`, `SettingsResourceScope`, `SettingsUserScope`]|<a id='ui.view.symbols.showExportedFunctions'>ui.view.symbols.showExportedFunctions</a>| +|ui|Show Folders First|Show folders at the top of the view when sorting items in symbols view.|`boolean`|`False`|[`SettingsProjectScope`, `SettingsResourceScope`, `SettingsUserScope`]|<a id='ui.view.symbols.showFoldersFirst'>ui.view.symbols.showFoldersFirst</a>| +|ui|Show Imports|Show imports in the symbols view.|`boolean`|`True`|[`SettingsProjectScope`, `SettingsResourceScope`, `SettingsUserScope`]|<a id='ui.view.symbols.showImports'>ui.view.symbols.showImports</a>| +|ui|Show Local Data Variables|Show local data variables in the symbols view.|`boolean`|`False`|[`SettingsProjectScope`, `SettingsResourceScope`, `SettingsUserScope`]|<a id='ui.view.symbols.showLocalDataVariables'>ui.view.symbols.showLocalDataVariables</a>| +|ui|Show Local Functions|Show local functions in the symbols view.|`boolean`|`True`|[`SettingsProjectScope`, `SettingsResourceScope`, `SettingsUserScope`]|<a id='ui.view.symbols.showLocalFunctions'>ui.view.symbols.showLocalFunctions</a>| +|ui|Maximum Lines for Wrapping in Editor|The maximum number of lines in rendered types before line wrapping is always disabled.|`number`|`10000`|[`SettingsUserScope`]|<a id='ui.view.types.maxLinesForWrapping'>ui.view.types.maxLinesForWrapping</a>| +|ui|Maximum Types in Editor|The maximum number of types to render in the type editor in Types View.|`number`|`100`|[`SettingsUserScope`]|<a id='ui.view.types.maxTypesInEditor'>ui.view.types.maxTypesInEditor</a>| +|ui|Enable the new Type Browser UI|Enables the new Types UI, with support for using Type Archives and Type Libraries from the UI.|`boolean`|`True`|[`SettingsUserScope`]|<a id='ui.view.types.useTypeBrowser'>ui.view.types.useTypeBrowser</a>| |ui|Possible Value Set Function Complexity Limit|Function complexity limit for showing possible value set information. Complexity is calculated as the total number of outgoing edges in the function's MLIL SSA form.|`number`|`25`|[`SettingsProjectScope`, `SettingsResourceScope`, `SettingsUserScope`]|<a id='ui.view.variables.pvsComplexityLimit'>ui.view.variables.pvsComplexityLimit</a>| |ui|File Path in Window Title|Controls whether the window title includes the full file path for the current file.|`boolean`|`False`|[`SettingsUserScope`]|<a id='ui.window.title.showPath'>ui.window.title.showPath</a>| |updates|Update Channel Preferences|Select update channel and version.|`string`|`None`|[]|<a id='updates.channelPreferences'>updates.channelPreferences</a>| diff --git a/docs/guide/troubleshooting.md b/docs/guide/troubleshooting.md index 740c1ee0..83fd3a0b 100644 --- a/docs/guide/troubleshooting.md +++ b/docs/guide/troubleshooting.md @@ -204,7 +204,7 @@ The following environment variables may be helpful when troubleshooting issues: ## File Associations -With the addition of projects and type archives, Binary Ninja now includes support for `.bnpr` (project folders, openable on MacOS), `.bnpm` (project metadata, openable on all platforms), and `.bnta` (type archives, openable on all platforms) file formats. If installed fresh, these file associations will automatically be created. However, when using the built-in updater, the association is not currently added. To manually create the association, use the following: +With the addition of [projects](../guide/projects.md) and [type archives](../guide/types/typearchives.md), Binary Ninja now includes support for `.bnpr` (project folders, openable on MacOS), `.bnpm` (project metadata, openable on all platforms), and `.bnta` (type archives, openable on all platforms) file formats. If installed fresh, these file associations will automatically be created. However, when using the built-in updater, the association is not currently added. To manually create the association, use the following: ### MacOS file associations diff --git a/docs/guide/type.md b/docs/guide/type.md deleted file mode 100644 index 15a77d2a..00000000 --- a/docs/guide/type.md +++ /dev/null @@ -1,363 +0,0 @@ -# Working with Types, Structures, and Symbols - -This document is organized into two sections describing how to work with types in Binary Ninja. The [first section](#basic-types) is how apply and create types. - -The second [section](#working-with-types) is how to interact with any type, regardless of its source. - -For more about type libraries, signature library, and how to interact with types through the API, see the [applying annotations](../dev/annotation.md) section of the developer guide. - -## Basic Types - -The biggest culprit of bad decompilation is often missing type information. Therefore, some of the most important actions you can take while reverse engineering is renaming symbols/variables, applying types, and creating new types to apply. - -### Renaming Symbols and Variables - - - -Some binaries helpfully have symbol information in them which makes reverse engineering easier. Of course, even if the binary doesn't come with symbol information, you can always add your own. From the UI, just select the function, variable, member, or register you want to change and press `n`. This works on variables as well. - -### Applying Structures and Types - -Simply select an appropriate token (variable or memory address), and press `y` to bring up the change type dialog. Types can be applied on both disassembly and all levels of IL. Any variables that are shared between the ILs will be updated as types are applied. - - - -## Types View - -To see all types in a Binary View, use the types view. It can be accessed from the menu `View > Types`. Alternatively, you can access it with the `t` hotkey from most other views, or using `[CMD/CTRL] p` to access the command-palette and typing "types". This is the most common interface for creating structures, unions and types using C-style syntax. - -The types view is also available in the sidebar with the `{…}` icon. - -For many built-in file formats you'll notice that common headers are already enumerated in the types view. These headers are applied when viewing the binary in [linear view](./index.md#linear-view) and will show the parsed binary data into that structure or type making them particularly useful for binary parsing even of non-executable file formats. - - - -### Structure Access Annotations - -Types view now annotates code references to structure offsets. It uses the same convention as in the graph/linear view. For example, the `__offset(0x8).q` token means the code references the offset 0x8 of this structure, and the size of the access is a qword. This will make it easier to see which offsets of a structure are being used, and aid in the process of creating structure members. - - - -### Shortcuts - -From within the Types view, you can use the following hotkeys to create new types, structures, or unions. Alternatively, you can use the right-click menu to access these options and more. - - - -* `s` - Create new structure -* `i` - Create new type -* `[SHIFT] s` - Creating a new union -* `1`, `2`, `4`, `8`: The number hotkeys will create a create an integer of the specified size. This additionally works on selections. -* `d`: If you want to cycle through the different integer sizes, repeatedly pressing `d` has the same effect as pressing the numbers in order. -* `-`: To quickly toggle integers between signed and unsigned integers, you can use the `-` hotkey. - - -The shortcuts for editing existing elements are: - -* `y` - Edit type / field -* `n` - Rename type / field -* `l` - Set structure size -* `u` - undefine field - -### Attributes - -Structs support the attribute `__packed` to indicate that there is no padding. Additionally, function prototypes support the following keywords to indicate their calling convention or other features: - -``` text -__cdecl -__stdcall -__fastcall -__convention -__noreturn -``` - -To use the `__convention` keyword, pass in the convention name as a parameter argument: - -``` -__convention("customconvention") -``` - - -#### Examples - -``` C -enum _flags -{ - F_X = 0x1, - F_W = 0x2, - F_R = 0x4 -}; -``` - -``` C -struct Header __packed -{ - char *name; - uint32_t version; - void (* callback)(); - uint16_t size; - enum _flags flags; -}; -``` - - -## Working With Types - -There are two main ways to interact with types from within a binary view. The first is to use the [types view](#types-view), and the second is to take advantage of the [smart structures workflow](#smart-structures-workflow) or otherwise annotate types directly in a disassembly or IL view. - -### Direct UI manipulation - -The simplest way to directly manipulate types in disassembly is by viewing an existing variable or sequence of bytes in linear view and using the following hotkeys: - - - - `1`, `2`, `4`, `8`: The number hotkeys will create a data variable at the current location if none exists, and then change the size of the variable to an integer in the size of bytes specified in the hotkey. - - `d`: If you want to cycle through the different integer sizes, repeatedly pressing `d` has the same effect as pressing the numbers in order. - - `-`: To quickly toggle integers between signed and unsigned integers, you can use the `-` hotkey. - - `a`: This hotkey sets or creates the current variable to a character array up until and including the next null byte. - - `o`: `o` will set or create the current variable to be a pointer reference. - - `*`: If you have a selection of identical variables, `*` will convert them into an array of elements. If you have no selection, the "Create Array" dialog will be shown allowing you to create an array of specific type and count at the current location. - - - `s`: `s` is a magic hotkey described in the next section in greater detail - - `m`: Used to apply an enumeration display at an integer (more details [below](#enumeration-selector)) - - Note that you can apply these types to a region of memory as well, not just a single variable. So selecting a large block of bytes and pressing `2` `*` for example will create an array of `int16_t` sized elements. - -### Enumeration Selector - - - -The Enum Dialog, with a default hotkey of `m` can be used to both change the type for data variables, arguments, and local variables to an enum type and also to change the Display Type of constant integers to any matching enumeration members. - -When used on an integer, all matching enumeration members will be shown. - -1. Filter box to search large lists of matching enums -1. "New Enum" button to allow creation of a new enum -1. Enum preview (can also be used to edit an existing enum by double clicking a given line) -1. Currently selected enum/member (when the enum is selected, the preview will update, and you can also right-click here to change the type) -1. Name of currently selected enum -1. Checkbox (set by default) that hides enums with no matching members for the current integer. - -However in instances where the hotkey is used on other variables, the display will only be used to apply the enum type to the selection and does not allow editing. - - - -### Smart Structures Workflow - -"Smart Structures" feature enables automatic creation of a structure and its members directly from the disassembly/IL view using the `s` hotkey. -It simplifies the traditional workflow in which the user first creates a type in the types view and then applies it to disassembly. -It works in the following ways: - -| View | Selection | Current Type | Behavior | -|--------------------|--------------------------------------------------------------|----------------------|-----------------------------------------------------------------------------------| -| Linear/Graph | A variable | Not a struct/struct\* | Create structure dialog | -| Linear/Graph | A variable that is the result an allocation routine | Not a struct/struct\* | Create structure with allocation size | -| Linear/Graph/Types | A variable, data variable, or a type name | struct/struct\* | Create all members for structure | -| Linear/Graph/Types | A StructOffsetToken token, e.g., `__offset(0x18)` | N/A | Create current member for structure | - -Below are detailed explanation of it: - -1. In linear/graph view, if the selection is a variable that is not a structure, a dialog pops up and asks you to create a structure. You can specify the structure's name and size. There is also a checkbox that asks you whether the variable's type should be the structure itself or a pointer to the structure. -2. In linear/graph view, if the selection is a variable that is not a structure, and it happens to be the result of a memory allocation routine, e.g., `malloc`, a new structure will be created and its size is automatically determined (if possible). The variable's type will be a pointer to the structure. -3. In linear/graph/types view, If you select a variable whose type is a structure, or a pointer to a structure, BN will try to create all structure field at any offset that has been accessed in the code. -4. In linear/graph/types view, If you select a StructOffsetToken, BN will try to create a structure member at the current offset. - -The automatic member creation mentioned in #3 and #4 takes into consideration both incoming and outgoing type information for the accessed offsets and selects the most confident one as the type for the offset. -When no type information can be used to create the structure member, we fall back to creating an integer type based on the size of accesses. For example, if we see an access of size 4, we will create an `int32_t`. In case there are different sizes of accesses, we do not create the member. You will need to examine the conflicting size information and decide how to create a member. - - - -Consider the following example (created using [taped](../files/taped) from the 2011 Ghost in the Shellcode CTF if you'd like to play along at home): - -| Step | Preview | -|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------| -| Go to address `0x8048e20` and switch to HLIL. | <img src="../img/taped/1.png" alt="Structure Workflow 1"/> | -| Select variable `var_18` and press `s`. <br/>Since `calloc` is a known allocation routine and the allocation size can be determined to be 0x30, a new structure, `struct_1` is created with size 0x30. | <img src="../img/taped/2.png" alt="Structure Workflow 2"/> | -| Select an offset, e.g., `__offset(0x4).d` and press `s`. A member will be automatically created. | <img src="../img/taped/3.png" alt="Structure Workflow 3"/> | -| Alternatively, select the `var_18` or the type name `struct_1` and press `s`. All members in the `struct_1` will be automatically created. | <img src="../img/taped/4.png" alt="Structure Workflow 4"/> | -| Viewing the automatically created structure members. | <img src="../img/taped/5.png" alt="Structure Workflow 5"/> | - - -The `s` hotkey also works when working with structures in the linear view. Its behavior differs based on the current selection: - - -| Selection | Behavior | -|--------------------------------------------------------------|-----------------------------------------------------------------------------------| -| A single byte | Create structure dialog | -| A range of bytes | Create structure with selection size | -| A range of bytes covering existing data variables | Create structure with selection size and add existing data vars as struct members | - - -In linear view, if the selection is a single byte outside any function, it will pop up the create structure dialog. If the selection is a range of bytes, a structure of the selection size is created and the start of the selection. If the selection covers any existing data variables, these data variables will become members within the newly created structure. - -This also works within data variables with structure type. For example, if the selection is a range of bytes within a structure, a new structure will be created within the existing structure. - - -### Import BNDB File - -The Import BNDB File feature imports types from a previous BNDB into your currently open file. In addition, it will apply types for matching symbols in functions and variables. Import BNDB *will not* port symbols from a BNDB with symbols to one without -- the names must already match. Matching functions and porting symbols is beyond the scope of this feature. - - - -#### Usage - -To use this feature select `Import From BNDB` from the `Analysis` menu, use the [command palette](index.md#command-palette), or [bind a hotkey](index.md#custom-hotkeys) and select the BNDB you'd like to import. Wait for the BNDB to load then you'll be presented with a list of things to import. - -* Types - Various types to be imported from the source BNDB -* Functions - Attempt to find target functions whose symbol already matches the symbol of the source BNDB and apply their type -* Function to Imports - Attempt to find target Imports whose symbol matches the Functions symbols in the source BNDB and apply their type -* Data Variables - Attempt to find target DataVariables with symbols that match DataVariables in the source BNDB and apply their type - -This feature enables a number of workflows: - -#### Porting Analysis Between Target Versions - -If you're working with version 1 of a file which has symbols and you now want to port your work over to version 2 (as long as they both have symbols). This isn't going to be perfect as this feature isn't interactive and doesn't take into account changes in parameter counts or ordering, so *use this with caution*. - -#### Quickly Defining Externs - -If you have a binary with externs which don't have TypeLibraries this can allow you to quickly import them (and their types) from another source, this is especially effective when you have debug information for the dependent libraries - -### Import Header File - -If you already have a collection of headers containing types you want to use, you can import them directly. You can specify the compiler flags that would be used if a compiler were compiling a source file that uses this header. Specifically this means you can/should specify: - -- `-isystem<path>` for various system header paths -- `-I<path>` for various user header paths -- `-D<macro>=<value>` for macro definitions -- `-x c -std=c99` to specify C99 mode -- Other Clang-compatible command-line flags are accepted (eg `-fms-extensions`, `-fms-compatibility`, etc) - -You can specify that types from system headers, accessed via `#include <header.h>`, will be in the results. Otherwise, only files from user headers, accessed via `#include "header.h"` will be used. - -You can also specify Define Binary Ninja Macros, which makes the type parser include the various parser extensions that Binary Ninja allows in the Type View editors, eg `__packed`, `__padding`, `__syscall`, etc. You probably only want to use this option when importing a header file exported using [Export Header File](#export-header-file). - -After specifying the file(s) and flag(s), pressing Preview will give a list of all the types and functions defined in the file(s). You may check or uncheck the box next to any of the types/functions to control whether they will be imported to your analysis. - -If there were any parse errors, those will be shown instead of a list of types. Generally speaking, what this means is you're missing either header search paths or compile definitions. See the section below on [finding system headers](#finding-system-headers). - -After pressing Import, all the checked types/functions will be added to your analysis. Imported types will override any existing types you had defined so they are disabled by default as indicated via the `Exists Already` column. Imported functions will replace signatures of any functions in your analysis whose name matches signatures found in the header. - - - -#### Finding System Headers - -Since you need to specify the include paths for system headers, you will need to deduce them for the target platform of your analysis. Here are a few tricks that may help: - -##### Systems with GCC/Clang (macOS, Linux, etc) - -On these systems, you can run a command to print the default search path for compilation: - - gcc -Wp,-v -E - - clang -Wp,-v -E - - -For the directories printed by this command, you should include them with `-isystem<path>` in the order specified. - -For example on macOS, with Xcode 13: - - $ clang -Wp,-v -E - - clang -cc1 version 13.0.0 (clang-1300.0.29.3) default target arm64-apple-darwin21.6.0 - ignoring nonexistent directory "/Applications/Xcode.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX.sdk/usr/local/include" - ignoring nonexistent directory "/Applications/Xcode.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX.sdk/Library/Frameworks" - #include "..." search starts here: - #include <...> search starts here: - /usr/local/include - /Applications/Xcode.app/Contents/Developer/Toolchains/XcodeDefault.xctoolchain/usr/lib/clang/13.0.0/include - /Applications/Xcode.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX.sdk/usr/include - /Applications/Xcode.app/Contents/Developer/Toolchains/XcodeDefault.xctoolchain/usr/include - /Applications/Xcode.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX.sdk/System/Library/Frameworks (framework directory) - End of search list. - -From this example, the flags would be: (note: not including the framework directory line) - - -isystem/usr/local/include - -isystem/Applications/Xcode.app/Contents/Developer/Toolchains/XcodeDefault.xctoolchain/usr/lib/clang/13.0.0/include - -isystem/Applications/Xcode.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX.sdk/usr/include - -isystem/Applications/Xcode.app/Contents/Developer/Toolchains/XcodeDefault.xctoolchain/usr/include - -Another example on Arch Linux: - - $ gcc -Wp,-v -E - - ignoring nonexistent directory "/usr/lib/gcc/x86_64-pc-linux-gnu/12.2.0/../../../../x86_64-pc-linux-gnu/include" - #include "..." search starts here: - #include <...> search starts here: - /usr/lib/gcc/x86_64-pc-linux-gnu/12.2.0/include - /usr/local/include - /usr/lib/gcc/x86_64-pc-linux-gnu/12.2.0/include-fixed - /usr/include - End of search list. - -From this example, the flags would be: - - -isystem/usr/lib/gcc/x86_64-pc-linux-gnu/12.2.0/include - -isystem/usr/local/include - -isystem/usr/lib/gcc/x86_64-pc-linux-gnu/12.2.0/include-fixed - -isystem/usr/include - -##### For Windows - -For windows, there's no easy command to list all the include paths so you have to piece them together from the `Include Directory` property in a Visual Studio project. You also want to include `-x c -std=c99` since Windows headers include lots of C++ types that the type importer currently does not support. - -You will end up with something like the following for user mode: - - -x c -std=c99 - -isystem"C:\Program Files (x86)\Microsoft Visual Studio\2019\Professional\VC\Tools\MSVC\14.28.29333\include" - -isystem"C:\Program Files (x86)\Windows Kits\10\Include\10.0.19041.0\ucrt" - -isystem"C:\Program Files (x86)\Windows Kits\10\Include\10.0.19041.0\shared" - -isystem"C:\Program Files (x86)\Windows Kits\10\Include\10.0.19041.0\um" - -Or, for kernel mode: - - -x c -std=c99 - -isystem"C:\Program Files (x86)\Microsoft Visual Studio\2019\Professional\VC\Tools\MSVC\14.28.29333\include" - -isystem"C:\Program Files (x86)\Windows Kits\10\Include\10.0.19041.0\ucrt" - -isystem"C:\Program Files (x86)\Windows Kits\10\Include\10.0.19041.0\shared" - -isystem"C:\Program Files (x86)\Windows Kits\10\Include\10.0.19041.0\km" - -##### Cross-Platform Targets - -If you are analyzing a target that is for a different operating system, you need to both find the header include paths for that system, and copy (or mount) them to a location accessible by the computer running Binary Ninja. - -### Export Header File - -If you want to compile code using the structures you defined during your analysis, you can export all the types to a C-compatible header file that can be used via `#include` by a C compiler. You can also import this header in another analysis session via [Import Header File](#import-header-file), just be sure to enable `Define Binary Ninja Macros` when doing so. - -## Platform Types - -Binary Ninja pulls type information from a variety of sources. The highest-level source are the platform types loaded for the given platform (which includes operating system and architecture). There are two sources of platform types. The first are shipped with the product in a [binary path](./index.md#directories). The second location is in your [user folder](./index.md#user-folder) and is intended for you to put custom platform types. - -???+ Danger "Warning" - Do NOT make changes to platform types in the binary path as they will be overwritten any time Binary Ninja updates. - -Platform types are used to define types that should be available to all programs available on that particular platform. They are only for global common types. Consider, for example, that you might want to add the following on windows: - -``` -typedef uint8_t u8; -``` - -You could write this type into: - -``` -/home/user/.binaryninja/types/platform/windows-x86.c -``` - -And any time you opened a 32bit windows binary, that type would be available to use. However, please note that these are not substitutes for [Type Libraries](../dev/annotation.md#type-libraries). Type Libraries are used to provide a collection of types for a given library such as a libc, or common DLL. - -???+ Warning "Tip" - If you don't know the specific platform (and thus filename) you need to create for a given file, just enter `bv.platform` in the scripting console. - -### Common Types - -You may wish to provide types that are common across multiple architectures or platforms. The easiest way to do this is to use a `#include "filename.c"` line in the specific platform so that any common types will be loaded. - -For example, something like: - -``` -$ pwd -/home/user/.binaryninja/types/platform -$ cat windows-x86.c -#include "windows.c" -$ cat windows-x86_64.c -#include "windows.c" -$ cat windows.c -typedef uint8_t u8; -``` diff --git a/docs/guide/types/basictypes.md b/docs/guide/types/basictypes.md new file mode 100644 index 00000000..b9530ddb --- /dev/null +++ b/docs/guide/types/basictypes.md @@ -0,0 +1,173 @@ +# Basic Type Editing + +The biggest culprit of bad decompilation is often missing type information. Therefore, some of the most important actions you can take while reverse engineering is renaming symbols/variables, applying types, and creating new types to apply. + +## Renaming Symbols and Variables + + + +Some binaries helpfully have symbol information in them which makes reverse engineering easier. Of course, even if the binary doesn't come with symbol information, you can always add your own. From the UI, just select the function, variable, member, or register you want to change and press `n`. + +## Applying / Changing Structures and Types + +Simply select an appropriate token (function, parameter, variable or memory address), and press `y` to bring up the change type dialog. Types can be applied on both disassembly and all levels of IL. Any variables that are shared between the ILs will be updated as types are applied. + + + +## Types View + + + +The Types View is the main view for organizing and modifying types in Binary Ninja. +You can access it in a number of different ways: + +- Open it in the sidebar with the {T} icon +- Open it in the sidebar in the Command Palette under "Focus Types" +- Switch the current view pane to it by selecting "Types" under the view type menu +- Switch the current view pane in the Command Palette under "Types" + +The Types View comprises two main views: the [Type List](#the-type-list) and the [Type Editor](#the-type-editor). +There is also a search box that filters the Type List, and a menu button that shows the context menu +for the active view. + +### The Type List + + + +The Type List shows you both the types available in your analysis session and types from +the [various other places](#type-containers) related to your analysis that can be imported. +Types you select in the Type List will be shown in the Type Editor view, and you can view +multiple types at once by clicking with Shift or Ctrl (Cmd on macOS). Selected types will +show cross-references in the [cross-references sidebar pane](../index.md#cross-references). +You can edit selected types in the Type Editor, or if you double-click a type +(or use Change Type in the context menu), you can edit them as C source. + +Types in the list have their class indicated by icons: + +* **S**: Structure types +* **C**: Class types (a variant of structure types) +* **U**: Union types (a variant of structure types) +* **E**: Enumeration types +* **T**: All other types + +#### Type List Actions + +* Type Creation + * **Create Types from C Source** - Open a text box where you can enter C source type and structure definitions + * **Create New Structure** - Create a new blank structure type + * **Create New Enumeration** - Create a new blank enumeration type + * **Create New Union** - Create a new blank union type +* Type Editing + * **Rename Type** - Rename the currently selected type + * **Change Type** - Edit the currently selected type in a text box with C source +* Type Archives + * **Create Type Archive** - Create a [Type Archive](typearchives.md) and attach it to your analysis + * **Attach Type Archive** - Attach an existing [Type Archive](typearchives.md) to your analysis + * **Detach Type Archive** - Detach an attached [Type Archive](typearchives.md) and disassociate all types from it + * **Push Types to Archive** - Push the selected types to a [Type Archive](typearchives.md) + * **Pull Types from Archive** - Pull the selected types from a [Type Archive](typearchives.md) + * **Disassociate Types from Archive** - Disassociate, or break connections between, the selected types and their associated [Type Archive](typearchives.md) +* Type Libraries + * **Import Type** - Import a type from a [Type Library](../../dev/annotation.md#type-libraries) into your analysis + * **Import Type by GUID** - (Windows binary analyses only) Import a COM type by its GUID + * **Add Type Library** - Add an existing [Type Library](../../dev/annotation.md#type-libraries) to your analysis +* Settings + * **Search** - Change how the search box filters types + * **Type Names** - Search only filters by names of types (default) + * **Type and Member Names** - Search filters by both names of types and names of members in structure types + * **Full Definition Text** - Search filters by matching the full text representation of types (can be slow for large numbers of types) + +#### Type Containers + +All of the type containers described in the [type introduction](index.md) are available in the Types View along with `User Types` in a section of its own. + +* **User Types**: In your analysis: Types created by you, either manually or through actions/plugins +* **System Types**: In your analysis: Types created by analysis or imported during analysis, such as from Libraries or Debug Info +* **Archive**: Types in an attached [Type Archive](typearchives.md). You can edit and delete them, without affecting the types in your analysis, and you can push/pull them into your analysis. +* **Library**: Types in a [Type Library](../../dev/annotation.md#type-libraries). You cannot edit them, but you can import them into your analysis. +* **Debug Info**: Types found in [Debug Info](debuginfo.md). You cannot edit them here, but they are copied into the System Types where you can edit them. +* **Platform**: Types from the analyzed binary's [Platform](platformtypes.md). You cannot edit them here, but they are copied into the System Types where you can edit them. + + + +### The Type Editor + +The Type Editor is the primary interface for editing types used in your analysis. It shows +whichever types you select in the Type List above, and allows you to edit them in many ways. +Types are shown in C syntax with various [annotations](#type-annotations). Structure members +have their offsets indicated on the left, and empty space between structure members is shown +with `??` marks indicating individual bytes. Selecting members in a structure will show +[cross-references](../index.md#cross-references) to those members, and double-clicking +the name of a type will take you to its definition. + +#### Type Editor Actions + +* Modifying Types + * **Change Type** - Edit an entire type, or structure member, as C source + * **Rename** - Rename a type or structure member + * **Undefine** - Delete a type from your analysis, or delete a structure member + * **Set Structure Size** - Manually specify a structure's size, alignment, and packing +* Creating Structure Members + * **Type > Make 8-bit Integer** - Create `uint8_t` members in selection + * **Type > Make 16-bit Integer** - Create `uint16_t` members in selection + * **Type > Make 32-bit Integer** - Create `uint32_t` members in selection + * **Type > Make 64-bit Integer** - Create `uint64_t` members in selection + * **Type > Invert Integer Sign** - Toggle integer signedness, e.g. between `uint8_t` and `int8_t` + * **Type > Cycle Integer Size** - Change integer member size in order: `uint8_t`, `uint16_t`, `uint32_t`, `uint64_t` + * **Type > Make 32-bit Float** - Create `float` members in selection + * **Type > Make 64-bit Float** - Create `double` members in selection + * **Type > Cycle Float Size** - Change float member size in order: `float`, `double` + * **Type > Make Pointer** - Create `void*` members in selection + * **Type > Make C String** - Create `char*` members in selection + * **Type > Make UTF-16 String** - Create `wchar16*` members in selection + * **Type > Make UTF-32 String** - Create `wchar32*` members in selection +* Utility + * **Add Cross Reference from** - Manually add a cross-reference to a type (or member) from an address in the analysis +* Settings + * **Show Inherited Members** - When working with [structures with inheritance](cpp.md#derived-classes), show members from base classes in child classes + * **Wrap Lines** - Soft-wrap long text lines + +### Type Annotations + +The Types view now annotates code references to structure offsets. It uses the same convention as in the graph/linear view. For example, the `__offset(0x8).q` token means the code references the offset 0x8 bytes into this structure, and the size of the access is a qword. This will make it easier to see which offsets of a structure are being used, and aid in the process of creating structure members. + +## Attributes + +Structs support the attribute `__packed` to indicate that there is no padding. Additionally, function prototypes support the following keywords to indicate their calling convention or other features: + +``` text +__cdecl +__stdcall +__fastcall +__convention +__noreturn +``` + +To use the `__convention` keyword, pass in the convention name as a parameter argument: + +``` +__convention("customconvention") +``` + + +## Examples + +``` C +enum _flags +{ + F_X = 0x1, + F_W = 0x2, + F_R = 0x4 +}; +``` + +``` C +struct Header __packed +{ + char *name; + uint32_t version; + void (* callback)(); + uint16_t size; + enum _flags flags; +}; +``` diff --git a/docs/guide/cpp.md b/docs/guide/types/cpp.md index 1da8d817..455e59fd 100644 --- a/docs/guide/cpp.md +++ b/docs/guide/types/cpp.md @@ -16,17 +16,17 @@ A derived class can be defined using the Create Structure dialog. From the Types dialog can be opened with a default hotkey of `s` or by using the add menu on the right of the sidebar. - + First, enter the offset and name of the base structure below the "Base structures" list. The offset should be where in the derived structure to place the base structure's members, which will usually be zero for single inheritance. - + Click the add button to add the base structure to the new structure. - + The offset will automatically update to be just after the added structure in case you need to add additional base structures. Click the Create button to create the new structure. @@ -146,11 +146,11 @@ struct __base(Foo, 0) Bar ## Template Simplifier -The [`analysis.types.templateSimplifier`](settings.md#analysis.types.templateSimplifier) setting can be helpful when working with C++ symbols. +The [`analysis.types.templateSimplifier`](../settings.md#analysis.types.templateSimplifier) setting can be helpful when working with C++ symbols. <div class="juxtapose"> - <img src="../img/before-template-simplification.png" data-label="Before Simplification"/> - <img src="../img/after-template-simplification.png" data-label="After Simplification"/> + <img src="../../img/before-template-simplification.png" data-label="Before Simplification"/> + <img src="../../img/after-template-simplification.png" data-label="After Simplification"/> </div> ## Example @@ -342,7 +342,7 @@ adding `Animal` as a base structure and then adding `Flying`. The Create Structu automatically adjust the offset as you add structures. The dialog should look like this after the base structures are added: - + After defining and adding the additional member, the `Bird` structure looks like this: @@ -574,7 +574,7 @@ when navigating the C++ program. For example, clicking on the `make_sound` membe structure will populate the cross references view with the list of functions that implement the method: - + These cross references are aware of context when viewed from code. For example, in the following function: @@ -596,7 +596,7 @@ void Cat::approach(struct Cat* this) Clicking on `make_sound` will populate the cross references with *only* the functions that are in `Cat` or derived classes of `Cat`: - + ## Offset Pointers diff --git a/docs/guide/debuginfo.md b/docs/guide/types/debuginfo.md index 0c10943b..c994843c 100644 --- a/docs/guide/debuginfo.md +++ b/docs/guide/types/debuginfo.md @@ -8,7 +8,7 @@ Currently debug info plugins are limited to types, function signatures, and data Out of the box, Binary Ninja supports PDBs and DWARF. -For PDBs, Binary Ninja will automatically try to source from specified local folders and Microsoft's symbol server ([see the PDB settings for more information](settings.md#all-settings)). +For PDBs, Binary Ninja will automatically try to source from specified local folders and Microsoft's symbol server ([see the PDB settings for more information](../settings.md#all-settings)). For DWARF, this includes DWARF information compiled in to ELF binaries, DWARF information in external ELF files (`.dwo`, `.debug`, etc), DWARF information compiled in to Mach-O's, and DWARF information in external `.dSYM` files as well. Support for DWARF information in PEs is [planned](https://github.com/Vector35/binaryninja-api/issues/1555). diff --git a/docs/guide/types/index.md b/docs/guide/types/index.md new file mode 100644 index 00000000..acf1046c --- /dev/null +++ b/docs/guide/types/index.md @@ -0,0 +1,18 @@ +# Working with Types, Structures, and Symbols + +There's so many things to learn about working with Types in Binary Ninja that we've organized it into several sections! + +- [Basic Type Editing](basictypes.md): Brief overview of the basics +- [Working with Types](type.md): Interacting with types in disassembly and decompilation +- [Importing/Exporting Types](typeimportexport.md): How to import or export types from header files, archives, or other BNDBs + +Additionally, several types of containers for type information are documented here: + +- [Debug Info](debuginfo.md): Debug Info can provide additional type information (examples include DWARF and PDB files) +- [Type Libraries](typelibraries.md): Type Libraries contain types from commonly-used dynamic libraries +- [Platform Types](platformtypes.md): Types that automatically apply to a platform +- [Type Archives](typearchives.md): How you can use type archives to share types between analysis databases +- [Signature Libraries](../../dev/annotation.md#signature-library): Signature libraries are used to match names of functions with signatures for code that is statically compiled +- [Platform Types](platformtypes.md): Platform types are base types that apply to all binaries on a particular platform + +Additionally, make sure to see the [applying annotations](../../dev/annotation.md) section of the developer guide for information about using the API with types and covering the creation of many of the items described below.
\ No newline at end of file diff --git a/docs/guide/types/platformtypes.md b/docs/guide/types/platformtypes.md new file mode 100644 index 00000000..286615e6 --- /dev/null +++ b/docs/guide/types/platformtypes.md @@ -0,0 +1,42 @@ +# Platform Types + +Binary Ninja pulls type information from a variety of sources. The highest-level source are the platform types loaded for the given platform (which includes operating system and architecture). There are two sources of platform types. The first are shipped with the product in a [binary path](../index.md#directories). The second location is in your [user folder](../index.md#user-folder) and is intended for you to put custom platform types. + +???+ Danger "Warning" + Do NOT make changes to platform types in the binary path as they will be overwritten any time Binary Ninja updates. + +Platform types are used to define types that should be available to all programs available on that particular platform. They are only for global common types. Consider, for example, that you might want to add the following on windows: + +``` +typedef uint8_t u8; +``` + +You could write this type into: + +``` +/home/user/.binaryninja/types/platform/windows-x86.c +``` + +And any time you opened a 32bit windows binary, that type would be available to use. However, please note that these are not substitutes for [Type Libraries](../../dev/annotation.md#type-libraries). Type Libraries are used to provide a collection of types for a given library such as a libc, or common DLL. + +???+ Warning "Tip" + If you don't know the specific platform (and thus filename) you need to create for a given file, just enter `bv.platform` in the scripting console. + +## Common Types + +You may wish to provide types that are common across multiple architectures or platforms. The easiest way to do this is to use a `#include "filename.c"` line in the specific platform so that any common types will be loaded. + +The base path for these files is in your [user folder](../index.md#user-folder) inside of a "types/platform" subfolder. + +For example, something like: + +``` +$ pwd +/home/user/.binaryninja/types/platform +$ cat windows-x86.c +#include "windows.c" +$ cat windows-x86_64.c +#include "windows.c" +$ cat windows.c +typedef uint8_t u8; +``` diff --git a/docs/guide/types/type.md b/docs/guide/types/type.md new file mode 100644 index 00000000..5526efa1 --- /dev/null +++ b/docs/guide/types/type.md @@ -0,0 +1,88 @@ +# Working with Types, Structures, and Symbols in Decompilation + +There are two main ways to interact with types in decompilation or disassembly. The first is to use the [types view](basictypes.md#types-view), and the second is to take advantage of the [smart structures workflow](#smart-structures-workflow) or otherwise annotate types directly in a disassembly or IL view. + +## Direct UI manipulation + +The simplest way to directly manipulate types in disassembly is by viewing an existing variable or sequence of bytes in linear view and using the following hotkeys: + + - `1`, `2`, `4`, `8`: The number hotkeys will create a data variable at the current location if none exists, and then change the size of the variable to an integer in the size of bytes specified in the hotkey. + - `d`: If you want to cycle through the different integer sizes, repeatedly pressing `d` has the same effect as pressing the numbers in order. + - `-`: To quickly toggle integers between signed and unsigned integers, you can use the `-` hotkey. + - `a`: This hotkey sets or creates the current variable to a character array up until and including the next null byte. + - `o`: `o` will set or create the current variable to be a pointer reference. + - `*`: If you have a selection of identical variables, `*` will convert them into an array of elements. If you have no selection, the "Create Array" dialog will be shown allowing you to create an array of specific type and count at the current location. + + - `s`: `s` is a magic hotkey described in the next section in greater detail + - `m`: Used to apply an enumeration display at an integer (more details [below](#enumeration-selector)) + + Note that you can apply these types to a region of memory as well, not just a single variable. So selecting a large block of bytes and pressing `2` `*` for example will create an array of `int16_t` sized elements. + +## Enumeration Selector + + + +The Enum Dialog, with a default hotkey of `m` can be used to both change the type for data variables, arguments, and local variables to an enum type and also to change the Display Type of constant integers to any matching enumeration members. + +When used on an integer, all matching enumeration members will be shown. + +1. Filter box to search large lists of matching enums +1. "New Enum" button to allow creation of a new enum +1. Enum preview (can also be used to edit an existing enum by double clicking a given line) +1. Currently selected enum/member (when the enum is selected, the preview will update, and you can also right-click here to change the type) +1. Name of currently selected enum +1. Checkbox (set by default) that hides enums with no matching members for the current integer. + +However in instances where the hotkey is used on other variables, the display will only be used to apply the enum type to the selection and does not allow editing. + +## Smart Structures Workflow + + + +"Smart Structures" feature enables automatic creation of a structure and its members directly from the disassembly/IL view using the `s` hotkey. +It simplifies the traditional workflow in which the user first creates a type in the types view and then applies it to disassembly. +It works in the following ways: + +| View | Selection | Current Type | Behavior | +|--------------------|--------------------------------------------------------------|----------------------|-----------------------------------------------------------------------------------| +| Linear/Graph | A variable | Not a struct/struct\* | Create structure dialog | +| Linear/Graph | A variable that is the result an allocation routine | Not a struct/struct\* | Create structure with allocation size | +| Linear/Graph/Types | A variable, data variable, or a type name | struct/struct\* | Create all members for structure | +| Linear/Graph/Types | A StructOffsetToken token, e.g., `__offset(0x18)` | N/A | Create current member for structure | + +Below are detailed explanation of it: + +1. In linear/graph view, if the selection is a variable that is not a structure, a dialog pops up and asks you to create a structure. You can specify the structure's name and size. There is also a checkbox that asks you whether the variable's type should be the structure itself or a pointer to the structure. +2. In linear/graph view, if the selection is a variable that is not a structure, and it happens to be the result of a memory allocation routine, e.g., `malloc`, a new structure will be created and its size is automatically determined (if possible). The variable's type will be a pointer to the structure. +3. In linear/graph/types view, If you select a variable whose type is a structure, or a pointer to a structure, BN will try to create all structure field at any offset that has been accessed in the code. +4. In linear/graph/types view, If you select a StructOffsetToken, BN will try to create a structure member at the current offset. + +The automatic member creation mentioned in #3 and #4 takes into consideration both incoming and outgoing type information for the accessed offsets and selects the most confident one as the type for the offset. +When no type information can be used to create the structure member, we fall back to creating an integer type based on the size of accesses. For example, if we see an access of size 4, we will create an `int32_t`. In case there are different sizes of accesses, we do not create the member. You will need to examine the conflicting size information and decide how to create a member. + + + +Consider the following example (created using [taped](../../files/taped) from the 2011 Ghost in the Shellcode CTF if you'd like to play along at home): + +| Step | Preview | +|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------| +| Go to address `0x8048e20` and switch to HLIL. | <img src="../../img/taped/1.png" alt="Structure Workflow 1"/> | +| Select variable `var_18` and press `s`. <br/>Since `calloc` is a known allocation routine and the allocation size can be determined to be 0x30, a new structure, `struct_1` is created with size 0x30. | <img src="../../img/taped/2.png" alt="Structure Workflow 2"/> | +| Select an offset, e.g., `__offset(0x4).d` and press `s`. A member will be automatically created. | <img src="../../img/taped/3.png" alt="Structure Workflow 3"/> | +| Alternatively, select the `var_18` or the type name `struct_1` and press `s`. All members in the `struct_1` will be automatically created. | <img src="../../img/taped/4.png" alt="Structure Workflow 4"/> | +| Viewing the automatically created structure members. | <img src="../../img/taped/5.png" alt="Structure Workflow 5"/> | + + +The `s` hotkey also works when working with structures in the linear view. Its behavior differs based on the current selection: + + +| Selection | Behavior | +|--------------------------------------------------------------|-----------------------------------------------------------------------------------| +| A single byte | Create structure dialog | +| A range of bytes | Create structure with selection size | +| A range of bytes covering existing data variables | Create structure with selection size and add existing data vars as struct members | + + +In linear view, if the selection is a single byte outside any function, it will pop up the create structure dialog. If the selection is a range of bytes, a structure of the selection size is created and the start of the selection. If the selection covers any existing data variables, these data variables will become members within the newly created structure. + +This also works within data variables with structure type. For example, if the selection is a range of bytes within a structure, a new structure will be created within the existing structure. diff --git a/docs/guide/types/typearchives.md b/docs/guide/types/typearchives.md new file mode 100644 index 00000000..ce605c0d --- /dev/null +++ b/docs/guide/types/typearchives.md @@ -0,0 +1,47 @@ +# Type Archives + +Type Archives are files you can use to share types between analysis databases. You can create them and manage their contents in [Types View](./basictypes.md#the-type-list). + +{ width="400" } + +## Creating and Attaching + +Using the context menu in the [Type List](basictypes.md#the-type-list) in Types View, you can create Type Archives using **Create Type Archive**. Simply pick a file location, and one will be created and attached to your analysis. Once you have done this, you can attach that Type Archive to other analyses in the same menu, by instead using **Attach Type Archive**. If you don't want to use a specific Type Archive in your analysis, you can right-click it in the Type List and use **Detach Type Archive**, which will remove any associations made to types it contains, but will not remove any types in your analysis. + +???+ Tip "Tip" + Type Archives have an associated Platform (e.g. windows-x86_64), which will determine + various Platform-specific type details, like pointer width. You may attach a + Type Archive to files with a different Platform, but note that these details may + cause issues with any types pulled from the Type Archive. + +Attached Type Archives are remembered in saved analysis databases, and will be attached on reopen, provided the file still exists. If the Type Archive file is moved (or deleted), then the Type List will report the Type Archive as Disconnected (but still attached). You can reconnect the Type Archive by using **Connect Type Archive** and pointing Binary Ninja at the new location of the Type Archive file. + +Enterprise users can create Type Archives in Remote Projects in the same manner, and all changes made to Type Archives in Remote Projects will be automatically synced with the Collaboration Server. Updates made by you are sent immediately, whereas updates made by other users on your server are fetched periodically in the background every 30 seconds (configurable by the `collaboration.autoPollInterval` setting). Once changes have been fetched, you can pull them into your analysis in the same way as described below. You may also attach Type Archives created outside your Remote Project, but note they will not be synced to the Collaboration Server. + +## Managing Types + +Once you have one or more Type Archives created and attached, you can start using them to store and share types between your analyses: + +1. In one analysis, create some types and use **Push Types to Archive** to add them to a Type Archive +2. In another analysis, you can use **Pull Types from Archive** to import those types from the Type Archive +3. Now, in either analysis, you can [make changes to those types](basictypes.md#the-type-editor) and once again use **Push Types to Archive** to send the changes to the Type Archive +4. And after doing so, you can open the other analysis and use **Pull Types from Archive** to receive those changes from the Type Archive +5. If you push changes to a Type Archive and, before pulling them in the other analysis, change them there as well, you will have to choose which version of the individual types you want to use. Either push or pull the specific types and, when prompted, confirm your choice to use that version. + +If you want to rename a type in the Type Archive, you can use **Rename Type** in the context menu in the Type List. You can either rename it in your analysis, and then push the type, or rename it directly in the Type Archive, and then pull the type. Note that renaming a type will cause updates for other types that reference it, which may also need to be pushed or pulled afterward. + +If you want to delete a type in the Type Archive, you can select it in the Type List under the Type Archive, and use **Undefine Type**. This will not delete it from your analysis, and indeed if you had instead deleted it from your analysis, it would not have been deleted in the Type Archive. If you delete the type in either place, the association will no longer apply and changes made to the type will not be shown as needing to be pushed or pulled. + +If you want to manually disassociate a type in your analysis from a Type Archive, you can use **Disassociate Types from Archive**, and then no changes made to that type, either in the analysis, or in the Type Archive, will be shown as needing to be pushed or pulled. + +{ width="500" } + +When you have pushed or pulled types from a Type Archive, you will see their status reflected in the Type List: + +1. Normal type, not associated with a Type Archive +2. Type associated with a Type Archive with no changes +3. Type associated with a Type Archive with changes made in the analysis that can be pushed to the Type Archive +4. Type associated with a Type Archive with changes made in the Type Archive that can be pulled into the analysis +5. Type associated with a Type Archive with changes made both in the analysis and the Type Archive, that will need you to choose which version to keep +6. Type associated with a Type Archive that is missing + diff --git a/docs/guide/types/typeimportexport.md b/docs/guide/types/typeimportexport.md new file mode 100644 index 00000000..43fbfa90 --- /dev/null +++ b/docs/guide/types/typeimportexport.md @@ -0,0 +1,184 @@ +# Importing Type Information + +Type information can be imported from a variety of sources. If you have header files, you can [import a header](#import-header-file). If your types exist in an existing BNDB, you can use [import from a bndb](#import-bndb-file). With the introduction of [type archives](typearchives.md) we recommend migrating away from importing via BNDB to type archives as they allow types to remain synced between different databases. + +## Import BNDB File + +The Import BNDB File feature imports types from a previous BNDB into your currently open file. In addition, it will apply types for matching symbols in functions and variables. Import BNDB *will not* port symbols from a BNDB with symbols to one without -- the names must already match. Matching functions and porting symbols is beyond the scope of this feature. + + + +### Usage + +To use this feature select `Import From BNDB` from the `Analysis` menu, use the [command palette](../index.md#command-palette), or [bind a hotkey](../index.md#custom-hotkeys) and select the BNDB you'd like to import. Wait for the BNDB to load then you'll be presented with a list of things to import. + +* Types - Various types to be imported from the source BNDB +* Functions - Attempt to find target functions whose symbol already matches the symbol of the source BNDB and apply their type +* Function to Imports - Attempt to find target Imports whose symbol matches the Functions symbols in the source BNDB and apply their type +* Data Variables - Attempt to find target DataVariables with symbols that match DataVariables in the source BNDB and apply their type + +This feature enables a number of workflows: + +### Porting Analysis Between Target Versions + +If you're working with version 1 of a file which has symbols and you now want to port your work over to version 2 (as long as they both have symbols). This isn't going to be perfect as this feature isn't interactive and doesn't take into account changes in parameter counts or ordering, so *use this with caution*. + +### Quickly Defining Externs + +If you have a binary with externs which don't have TypeLibraries this can allow you to quickly import them (and their types) from another source, this is especially effective when you have debug information for the dependent libraries + +## Import Header File + +If you already have a collection of headers containing types you want to use, you can import them directly. You can specify the compiler flags that would be used if a compiler were compiling a source file that uses this header. Specifically this means you can/should specify: + +- `-isystem<path>` for various system header paths +- `-I<path>` for various user header paths +- `-D<macro>=<value>` for macro definitions +- `-x c -std=c99` to specify C99 mode +- Other Clang-compatible command-line flags are accepted (eg `-fms-extensions`, `-fms-compatibility`, etc) + +You can specify that types from system headers, accessed via `#include <header.h>`, will be in the results. Otherwise, only files from user headers, accessed via `#include "header.h"` will be used. + +You can also specify Define Binary Ninja Macros, which makes the type parser include the various parser extensions that Binary Ninja allows in the Type View editors, eg `__packed`, `__padding`, `__syscall`, etc. You probably only want to use this option when importing a header file exported using [Export Header File](#export-header-file). + +After specifying the file(s) and flag(s), pressing Preview will give a list of all the types and functions defined in the file(s). You may check or uncheck the box next to any of the types/functions to control whether they will be imported to your analysis. + +If there were any parse errors, those will be shown instead of a list of types. Generally speaking, what this means is you're missing either header search paths or compile definitions. See the section below on [finding system headers](#finding-system-headers). + +After pressing Import, all the checked types/functions will be added to your analysis. Imported types will override any existing types you had defined so they are disabled by default as indicated via the `Exists Already` column. Imported functions will replace signatures of any functions in your analysis whose name matches signatures found in the header. + + + +### Finding System Headers + +Since you need to specify the include paths for system headers, you will need to deduce them for the target platform of your analysis. Here are a few tricks that may help: + +#### Systems with GCC/Clang (macOS, Linux, etc) + +On these systems, you can run a command to print the default search path for compilation: + + gcc -Wp,-v -E - + clang -Wp,-v -E - + +For the directories printed by this command, you should include them with `-isystem<path>` in the order specified. + +For example on macOS, with Xcode 13: + + $ clang -Wp,-v -E - + clang -cc1 version 13.0.0 (clang-1300.0.29.3) default target arm64-apple-darwin21.6.0 + ignoring nonexistent directory "/Applications/Xcode.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX.sdk/usr/local/include" + ignoring nonexistent directory "/Applications/Xcode.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX.sdk/Library/Frameworks" + #include "..." search starts here: + #include <...> search starts here: + /usr/local/include + /Applications/Xcode.app/Contents/Developer/Toolchains/XcodeDefault.xctoolchain/usr/lib/clang/13.0.0/include + /Applications/Xcode.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX.sdk/usr/include + /Applications/Xcode.app/Contents/Developer/Toolchains/XcodeDefault.xctoolchain/usr/include + /Applications/Xcode.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX.sdk/System/Library/Frameworks (framework directory) + End of search list. + +From this example, the flags would be: (note: not including the framework directory line) + + -isystem/usr/local/include + -isystem/Applications/Xcode.app/Contents/Developer/Toolchains/XcodeDefault.xctoolchain/usr/lib/clang/13.0.0/include + -isystem/Applications/Xcode.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX.sdk/usr/include + -isystem/Applications/Xcode.app/Contents/Developer/Toolchains/XcodeDefault.xctoolchain/usr/include + +Another example on Arch Linux: + + $ gcc -Wp,-v -E - + ignoring nonexistent directory "/usr/lib/gcc/x86_64-pc-linux-gnu/12.2.0/../../../../../../../../x86_64-pc-linux-gnu/include" + #include "..." search starts here: + #include <...> search starts here: + /usr/lib/gcc/x86_64-pc-linux-gnu/12.2.0/include + /usr/local/include + /usr/lib/gcc/x86_64-pc-linux-gnu/12.2.0/include-fixed + /usr/include + End of search list. + +From this example, the flags would be: + + -isystem/usr/lib/gcc/x86_64-pc-linux-gnu/12.2.0/include + -isystem/usr/local/include + -isystem/usr/lib/gcc/x86_64-pc-linux-gnu/12.2.0/include-fixed + -isystem/usr/include + +##### For Windows + +For windows, there's no easy command to list all the include paths so you have to piece them together from the `Include Directory` property in a Visual Studio project. You also want to include `-x c -std=c99` since Windows headers include lots of C++ types that the type importer currently does not support. + +You will end up with something like the following for user mode: + + -x c -std=c99 + -isystem"C:\Program Files (x86)\Microsoft Visual Studio\2019\Professional\VC\Tools\MSVC\14.28.29333\include" + -isystem"C:\Program Files (x86)\Windows Kits\10\Include\10.0.19041.0\ucrt" + -isystem"C:\Program Files (x86)\Windows Kits\10\Include\10.0.19041.0\shared" + -isystem"C:\Program Files (x86)\Windows Kits\10\Include\10.0.19041.0\um" + +Or, for kernel mode: + + -x c -std=c99 + -isystem"C:\Program Files (x86)\Microsoft Visual Studio\2019\Professional\VC\Tools\MSVC\14.28.29333\include" + -isystem"C:\Program Files (x86)\Windows Kits\10\Include\10.0.19041.0\ucrt" + -isystem"C:\Program Files (x86)\Windows Kits\10\Include\10.0.19041.0\shared" + -isystem"C:\Program Files (x86)\Windows Kits\10\Include\10.0.19041.0\km" + +Note that some header files might require manually including a specific `windows.h` header which necessitates specifying a target platform to get the appropriate includes: + + --target=x86_64-pc-windows-msvc + -x c -std=c99 + -include"C:\Program Files (x86)\Windows Kits\10\Include\10.0.19041.0\um\windows.h" + -isystem"C:\Program Files (x86)\Microsoft Visual Studio\2019\Professional\VC\Tools\MSVC\14.28.29333\include" + -isystem"C:\Program Files (x86)\Windows Kits\10\Include\10.0.19041.0\ucrt" + -isystem"C:\Program Files (x86)\Windows Kits\10\Include\10.0.19041.0\shared" + -isystem"C:\Program Files (x86)\Windows Kits\10\Include\10.0.19041.0\um" + + +##### Cross-Platform Targets + +If you are analyzing a target that is for a different operating system, you need to both find the header include paths for that system, and copy (or mount) them to a location accessible by the computer running Binary Ninja. + +### Export Header File + +If you want to compile code using the structures you defined during your analysis, you can export all the types to a C-compatible header file that can be used via `#include` by a C compiler. You can also import this header in another analysis session via [Import Header File](#import-header-file), just be sure to enable `Define Binary Ninja Macros` when doing so. + +## Platform Types + +Binary Ninja pulls type information from a variety of sources. The highest-level source are the platform types loaded for the given platform (which includes operating system and architecture). There are two sources of platform types. The first are shipped with the product in a [binary path](../index.md#directories). The second location is in your [user folder](../index.md#user-folder) and is intended for you to put custom platform types. + +???+ Danger "Warning" + Do NOT make changes to platform types in the binary path as they will be overwritten any time Binary Ninja updates. + +Platform types are used to define types that should be available to all programs available on that particular platform. They are only for global common types. Consider, for example, that you might want to add the following on windows: + +``` +typedef uint8_t u8; +``` + +You could write this type into: + +``` +/home/user/.binaryninja/types/platform/windows-x86.c +``` + +And any time you opened a 32bit windows binary, that type would be available to use. However, please note that these are not substitutes for [Type Libraries](../../dev/annotation.md#type-libraries). Type Libraries are used to provide a collection of types for a given library such as a libc, or common DLL. + +???+ Warning "Tip" + If you don't know the specific platform (and thus filename) you need to create for a given file, just enter `bv.platform` in the scripting console. + +### Common Types + +You may wish to provide types that are common across multiple architectures or platforms. The easiest way to do this is to use a `#include "filename.c"` line in the specific platform so that any common types will be loaded. + +For example, something like: + +``` +$ pwd +/home/user/.binaryninja/types/platform +$ cat windows-x86.c +#include "windows.c" +$ cat windows-x86_64.c +#include "windows.c" +$ cat windows.c +typedef uint8_t u8; +``` diff --git a/docs/guide/types/typelibraries.md b/docs/guide/types/typelibraries.md new file mode 100644 index 00000000..28e0b4fb --- /dev/null +++ b/docs/guide/types/typelibraries.md @@ -0,0 +1,37 @@ +# Type Libraries + +Type Libraries are collections of type information (structs, enums, function types, etc.), corresponding to specific dynamic libraries that are imported into your analysis. You can browse and import them in the [Types View](./basictypes.md#the-type-list). + +__image of Type List showing a couple imported type libraries, with one expanded showing its types__ + +## Usage + +Most of your usage of Type Libraries will be performed automatically by Binary Ninja when you analyze a binary. They are automatically imported based on the libraries that your binary uses. Any library functions or global variables your binary references will have their type signature imported, and any structures those functions and variables reference are imported as well. + +__image of linear view showing a bunch of imported functions from a type library__ + +Compared to [Platform Types](./platformtypes.md), only Type Libraries needed by your binary will be imported into your analysis. If you want to manually import additional Type Libraries (e.g. if your binary dynamically loads a library), you can use the **Import Type Library** action in [Types View](./basictypes.md#the-type-list). Just pick a Type Library from the list shown, and it will be added to the list where you can import types from it. + +If you want to use types from a Type Library that have not yet been imported, you can select them in the [Types View](./basictypes.md#the-type-list) and use the **Import Types** action. They will be copied into your analysis's System Types and you can use them in your own structure and function annotations. + +## Design and Purpose + +Type Libraries contain details about a specific library that is imported by binaries. They contain information about the types used in the library: +* Types + * Structures, Classes, Unions + * Enumerations + * Typedefs +* Objects + * Function Signatures + * Global Variables + +Type Libraries are named after the source library they are providing types for. When a binary is opened, Binary Ninja finds all of its linked library dependencies, and looks up Type Libraries for them. Those with a File Name or Alternative Name matching the exact text of a library used by the binary will be imported into the analysis. You can see this process in the Log: + + elf: searching for 'libc.so.6' in type libraries + Type library 'libc.so.6' imported + +The [Developer Guide](../../dev/typelibraries.md) contains more details about the implementation details of the Type Library format. + +## Creating and Modifying + +Type Libraries are read-only by design, so while you cannot modify the ones built into Binary Ninja, you can create your own and use them as replacements. While there is no User Interface for doing this, there are plenty of APIs available. Check the [Developer Guide](../../dev/typelibraries.md) for details on how to create a Type Library. |