diff options
| author | Jordan Wiens <jordan@psifertex.com> | 2022-10-17 06:23:08 -0400 |
|---|---|---|
| committer | Jordan Wiens <jordan@psifertex.com> | 2022-10-17 06:23:08 -0400 |
| commit | 4942700ca3387b64cc6443a80bac60b470588bb9 (patch) | |
| tree | 7ab0b29c72e9146734b3cb24d062dff148c2b8ec | |
| parent | fba5ef5a7cb2c0f76cf2531adddda9d3023c2357 (diff) | |
documentation overhaul
29 files changed, 1324 insertions, 1098 deletions
diff --git a/api-docs/source/conf.py b/api-docs/source/conf.py index 404348f0..5477a0f9 100644 --- a/api-docs/source/conf.py +++ b/api-docs/source/conf.py @@ -77,7 +77,7 @@ def cleansource(): def generaterst(): pythonrst = open("index.rst", "w") - pythonrst.write('''Binary Ninja Python API Documentation + pythonrst.write('''Binary Ninja Python API Reference ===================================== Welcome to the Binary Ninja API documentation. The below methods are available diff --git a/docs/about/index.md b/docs/about/index.md new file mode 100644 index 00000000..eab75260 --- /dev/null +++ b/docs/about/index.md @@ -0,0 +1,13 @@ +# About + +Binary Ninja is a registered trademark of [Vector 35](https://vector35.com/) and is available under multiple licenses [licenses](license.md) depending on your purchase. + +Vector 35 is proud to both [use](open-source.md) and contribute to a number of open source products as well as release many components of Binary Ninja as [open source](https://github.com/orgs/Vector35/repositories?q=&type=source&language=&sort=) as well. + +Vector 35 (Officially, Vector 35 Inc) is a Delaware C Corp with their primary office in Melbourne, FL and a mailing address of: + +``` +Vector 35 +PO Box 971 +Melbourne, FL 32902-0971 +``` diff --git a/docs/dev/batch.md b/docs/dev/batch.md index 679df21a..0f30749f 100644 --- a/docs/dev/batch.md +++ b/docs/dev/batch.md @@ -6,7 +6,7 @@ This document describes some general tips and tricks for effective batch process ## Install the API -First, make sure to run the [install_api.py](https://github.com/Vector35/binaryninja-api/tree/dev/scripts) script. Note that the script is shipped with Binary Ninja already, just look in your [binary path](../getting-started.md#binary-path) inside of the `scripts` subfolder. Run it like: +First, make sure to run the [install_api.py](https://github.com/Vector35/binaryninja-api/tree/dev/scripts) script. Note that the script is shipped with Binary Ninja already, just look in your [binary path](../guide/#binary-path) inside of the `scripts` subfolder. Run it like: ``` python3 ~/binaryninja/scripts/install_api.py diff --git a/docs/dev/concepts.md b/docs/dev/concepts.md new file mode 100644 index 00000000..eae79854 --- /dev/null +++ b/docs/dev/concepts.md @@ -0,0 +1,23 @@ +# Important Concepts + +## Mapping between ILs + +ILs in general are critical to how Binary Ninja analyzes binaries and we have much more [in-depth](bnil-overview.md) documentation for BNIL (or Binary Ninja Intermediate Language -- the name given to the family of ILs that Binary Ninja uses). However, one important concept to summarize here is that the translation between each layer of IL is many-to-many. Going from disassembly to LLIL to MLIL can result in more or less instructions at each step. Additionally, at higher levels, data can be copied, moved around, etc. You can see this in action in the UI when you select a line of HLIL and many LLIL or disassembly instructions are highlighted. + +APIs that query these mappings are plural. So for example, while `current_hlil.llil` will give a single mapping, `current_hlil.llils` will return a list that may contain multiple mappings. + + + +## Operating on IL versus Native + +Generally speaking, scripts should operate on ILs. The available information far surpasses the native addresses and querying properties and using APIs almost always beats directly manipulating bytes. However, when it comes time to change the binary, there are some operations that can only be done at a simple virtual address. So for example, the [comment](https://api.binary.ninja/binaryninja.binaryview-module.html#binaryninja.binaryview.BinaryView.set_comment_at) or [tag](https://api.binary.ninja/binaryninja.binaryview-module.html#binaryninja.binaryview.BinaryView.add_user_data_tag) APIs (among others) work off of native addressing irrespective of IL level. + +## Instruction Index vs Expression Index + +It is easy to confuse ExpressionIndex and InstructionIndex properties in the API. While they [are both integers](https://github.com/Vector35/binaryninja-api/blob/dev/python/highlevelil.py#L49-L50) they mean different things and it's important to keep them straight. The Instruction Index is a unique index for that given IL level for that given function. However, because BNIL is [tree-based](bnil-overview.md), when there are nested expresses the expression index may be needed. These indexes are also unique per-function and per-IL level, but they are _distinct_ from instruction indexes even though they may occasionally be similar since they each start at 0 for a given function! + +## UI Elements + +There are several ways to create UI elements in Binary Ninja. The first is to use the simplified [interaction](https://api.binary.ninja/binaryninja.interaction-module.html) API which lets you make simple UI elements for use in GUI plugins in Binary Ninja. As an added bonus, they all have fallbacks that will work in headless console-based applications as well. Plugins that use these API include the [angr](https://github.com/Vector35/binaryninja-api/blob/dev/python/examples/angr_plugin.py) and [nampa](https://github.com/kenoph/nampa) plugins. + +The second and more powerful (but more complicated) mechanism is to leverage the _binaryninjaui_ module. Additional documentation is forthcoming, but there are several examples ([1](https://github.com/Vector35/kaitai), [2](https://github.com/Vector35/snippets), [3](https://github.com/Vector35/binaryninja-api/tree/dev/python/examples/triage)), and most of the APIs are backed by the [documented C++ headers](https://api.binary.ninja/cpp). Additionally, the generated _binaryninjaui_ module is shipped with each build of binaryninja and the usual python `dir()` instructions are helpful for exploring its capabilities.
\ No newline at end of file diff --git a/docs/dev/cookbook.md b/docs/dev/cookbook.md new file mode 100644 index 00000000..465a5ebe --- /dev/null +++ b/docs/dev/cookbook.md @@ -0,0 +1,68 @@ +# Cookbook + +One of the best ways to learn a complicated API is to simply find the right example! First, here's a huge number of other sources of larger programs if you don't find what you're looking for in the below simple examples: + + - [Official Plugins](https://github.com/vector35/official-plugins): Official Plugins written and maintained by Vector 35 + - [Community Plugins](https://github.com/vector35/community-plugins): Over 100 plugins contributed by the Binary Ninja community + - [Gist Collection](https://gist.github.com/psifertex/6fbc7532f536775194edd26290892ef7): Jordan's collection of python examples usually created for (or contributed by) customers + - [Offline examples](https://github.com/Vector35/binaryninja-api/tree/dev/python/examples): These examples are especially useful because they're included in your offline install as well, just look in the examples/python subfolder wherever Binary Ninja installed + + That said, most of those examples tend to be more complex and so the following recipes are meant to be simple but useful building-blocks with which to learn useful techniques: + +## Recipies + +### Accessing cross references + +This recipe is useful for iterating over all of the HLIL cross-references of a given interesting function: + +```python +for ref in current_function.caller_sites: + print(ref.hlil) +``` + +But what if you don't have that function yet? + +### Getting a function by name + +```python +bv.get_functions_by_name('_start') +``` + +### Finding the function with the most bytes + +```python +max(bv.functions, key=lambda x: x.total_bytes) +``` + +### Finding the most "connected" function + +As defined by having the highest sum of incoming and outgoing calls. Adjust accordingly. + +```python +max(bv.functions, key=lambda x: len(x.callers + x.callees)) +``` + +### Querying possible values of a function parameter + +Is that memcpy length a bit too big? + +```python +for ref in current_function.caller_sites: + if isinstance(ref.hlil, Call) and len(ref.hlil.params) >= 3: + print(ref.hlil.params[2]) + # For bonus points, query the range analysis +``` + +### Search for a good nop-slide? + +```python +bv.find_next_data(0, b"\x90" * 10) +``` + +### Change a function's type signature + +Make sure to check out the much more in-depth [type guide](../guide/type.md#using-the-api) as well. + +```python +current_function.function_type = Type.function(Type.void(), []) +``` diff --git a/docs/dev/documentation.md b/docs/dev/documentation.md index 16a1c9ee..b524d7fb 100644 --- a/docs/dev/documentation.md +++ b/docs/dev/documentation.md @@ -26,7 +26,7 @@ To contribute to the Binary Ninja documentation, first sign the [contribution li ## Changing Changing documentation for the API itself is fairly straight forward. Use [doxygen style comment blocks](https://www.stack.nl/~dimitri/doxygen/manual/docblocks.html) in C++ and C, and [restructured text blocks](http://thomas-cokelaer.info/tutorials/sphinx/docstring_python.html) for python for the source. The user documentation is located in the `api/docs/` folder and the API documentation is generated from the config in the `api/api-docs` folder. -!!! Tip "Tip" +???+ Warning "Tip" When updating user documentation, the `mkdocs serve` feature is particularly helpful. [contribution license agreement]: https://binary.ninja/cla.pdf diff --git a/docs/dev/api.md b/docs/dev/index.md index 8cc01543..d379de0d 100644 --- a/docs/dev/api.md +++ b/docs/dev/index.md @@ -1,9 +1,18 @@ # Using the Binary Ninja API +Welcome to the Binary Ninja API documentation. Much like the [User Manual](/guide/), some larger sections have been split off into their own sections on the left, while the table of contents for this documentation is on the right. + ## Language Specific Bindings The Binary Ninja API is available through a [Core API](#core-api), through the [C++ API](#c-api), through a [Python API](#python-api), and a [Rust API](#rust-api). +### Python API + +The most heavily documented of all of the APIs, the Python API serves as a useful documentation for the other APIs. Here's a list of the most important Python API documentation resources: + + - [Writing Python Plugins](plugins.md) + - [Python API](https://api.binary.ninja/) + - [API Source](https://github.com/Vector35/binaryninja-api/tree/dev/python) ### Core API @@ -19,24 +28,9 @@ The C++ API is what the Binary Ninja UI itself is built using so it's a robust a - [Build Instructions](https://github.com/Vector35/binaryninja-api#building) - [C++ / UI API Documentation](https://api.binary.ninja/cpp/) - -### Python API - -The most heavily documented of all of the APIs, the Python API serves as a useful documentation for the other APIs. Here's a list of the most important Python API documentation resources: - - - [Writing Python Plugins](plugins.md) - - [Python API](https://api.binary.ninja/) - - [API Source](https://github.com/Vector35/binaryninja-api/tree/dev/python) - ### Rust API -The Rust API is still experimental and lacks complete coverage for all core APIs. Instructions on using are available in: +The Rust API is still experimental and lacks complete coverage for all core APIs. Documentation is available at: - [Rust API](https://github.com/Vector35/binaryninja-api/tree/dev/rust) - -## UI Elements - -There are several ways to create UI elements in Binary Ninja. The first is to use the simplified [interaction](https://api.binary.ninja/binaryninja.interaction-module.html) API which lets you make simple UI elements for use in GUI plugins in Binary Ninja. As an added bonus, they all have fallbacks that will work in headless console-based applications as well. Plugins that use these API include the [angr](https://github.com/Vector35/binaryninja-api/blob/dev/python/examples/angr_plugin.py) and [nampa](https://github.com/kenoph/nampa) plugins. - -The second and more powerful (but more complicated) mechanism is to leverage the _binaryninjaui_ module. Additional documentation is forthcoming, but there are several examples ([1](https://github.com/Vector35/kaitai), [2](https://github.com/Vector35/snippets), [3](https://github.com/Vector35/binaryninja-api/tree/dev/python/examples/triage)), and most of the APIs are backed by the [documented C++ headers](https://api.binary.ninja/cpp). Additionally, the generated _binaryninjaui_ module is shipped with each build of binaryninja and the usual python `dir()` instructions are helpful for exploring its capabilities. diff --git a/docs/dev/plugins.md b/docs/dev/plugins.md index e1839fc4..981cb148 100644 --- a/docs/dev/plugins.md +++ b/docs/dev/plugins.md @@ -29,7 +29,7 @@ Once you've created your test repository, use the `pluginManager.unofficialName` The [`add_repository`](https://api.binary.ninja/binaryninja.pluginmanager-module.html#binaryninja.pluginmanager.RepositoryManager.add_repository) API can also be used to add the repository, though it [may require manual creation of the repository folder](https://github.com/Vector35/binaryninja-api/issues/2987). ## Testing -It's useful to be able to reload your plugin during testing. On the Commercial edition of Binary Ninja, this is easily accomplished with a stand-alone headless install using `import binaryninja` after [installing the API](https://github.com/Vector35/binaryninja-api/blob/dev/scripts/install_api.py). (install_api.py is included in each platforms respective [installation folder](../getting-started.md#binary-path)) +It's useful to be able to reload your plugin during testing. On the Commercial edition of Binary Ninja, this is easily accomplished with a stand-alone headless install using `import binaryninja` after [installing the API](https://github.com/Vector35/binaryninja-api/blob/dev/scripts/install_api.py). (install_api.py is included in each platforms respective [installation folder](../guide/#binary-path)) For other plugins, we recommend the following workflow from the scripting console which enables easy iteration and testing: diff --git a/docs/dev/themes.md b/docs/dev/themes.md index 37fedfc7..6c97ff6b 100644 --- a/docs/dev/themes.md +++ b/docs/dev/themes.md @@ -2,7 +2,7 @@ User themes are loaded from JSON files (with the `.bntheme` extension) found in the `themes` or `community-themes` subdirectories of your [user -folder](/getting-started.md#user-folder). The full path to these folders +folder](../guide/index.md#user-folder). The full path to these folders effectively being the following: - macOS: `~/Library/Application Support/Binary Ninja/{themes,community-themes}` diff --git a/docs/dev/workflows.md b/docs/dev/workflows.md index 17e190dc..106f7087 100644 --- a/docs/dev/workflows.md +++ b/docs/dev/workflows.md @@ -110,6 +110,8 @@ A Workflow starts in the unregistered state from either creating a new empty Wor The Analysis Context provides access to the current analysis hierarchy along with APIs to query and inform new analysis information. +<! --- + --- # Execution Model --- @@ -170,3 +172,5 @@ The Analysis Context provides access to the current analysis hierarchy along wit --- # Extended Analysis Descriptions --- + +--- >
\ No newline at end of file diff --git a/docs/docs.css b/docs/docs.css index 23c7446d..fb2a1745 100644 --- a/docs/docs.css +++ b/docs/docs.css @@ -1,13 +1,3 @@ -/* -code { -color: #000; -} - -.article pre code { -background: rgba(0, 0, 0, 0); -} - */ - .juxtapose { margin-bottom: 1rem; } @@ -20,31 +10,17 @@ code, .admonition.warning .admonition-title, .admonition.warning { background-color: #d73726 !important; + border-color: #d73726; color: #fff !important; } -.admonition.tip .admonition-title, -.admonition.tip { - background: #6e6e6e !important; +.md-typeset.admonition.tip .admonition-title, +.md-typeset.admonition.tip { + background-color: #6e6e6e !important; + border-color: #6e6e6e !important; color: #fff !important; } -a, -.rst-content div a code, -a code { - color: #d73726; -} - -a:visited, -a:visited code { - color: #990000; -} - -a:hover, -a:hover code { - color: #ff8080; -} - img[alt$=">"] { float: right; display: inline-block; @@ -65,6 +41,8 @@ img[alt$="><"] { float: none!important; } + +/* @media only screen and (min-width: 76.25em) { .md-main__inner { max-width: none; @@ -82,6 +60,7 @@ img[alt$="><"] { max-width: 100%; } } +*/ pre { overflow-x: auto; @@ -159,30 +138,88 @@ div[class^="inline-slides"]>div[id^="image-slider-container"] { flex-shrink: 1; } -h3#all-settings + p + div table tbody tr > td:nth-child(2) { +h3#all-settings+p+div table tbody tr>td:nth-child(2) { max-width: 300px; overflow: auto; word-break: break-word; white-space: break-spaces; } -h3#all-settings + p + div table tbody tr > td:nth-child(3) { +h3#all-settings+p+div table tbody tr>td:nth-child(3) { max-width: 600px; overflow: auto; word-break: break-word; white-space: break-spaces; } -h3#all-settings + p + div table tbody tr > td:nth-child(5) { +h3#all-settings+p+div table tbody tr>td:nth-child(5) { max-width: 300px; overflow: auto; word-break: break-word; white-space: break-spaces; } -h3#all-settings + p + div table tbody tr > td:nth-child(6) { +h3#all-settings+p+div table tbody tr>td:nth-child(6) { max-width: 500px; overflow: auto; word-break: break-word; white-space: break-spaces; } + +.md-header { + background-color: #d73726; +} + +.md-tabs { + background-color: #d73726; + color: #ffffff; +} + +.headerlink, +.md-typeset a, +.md-nav__link, +.md-nav__item { + color: #d73726; +} + +a.md-tabs__link, +a.md_tabs__link:visited { + color: #ffffff; +} + +.md_tabs__link:hover { + color: #cccccc; +} + +.headerlink:hover, +.md-typeset a:hover, +.md-nav__link:hover, +.md-nav__item:hover { + color: #000000; +} + +.md-source, +.md-source:visited, +.md-header__button, +.md-header__button:visited { + color: #ffffff; +} + + +/* TODO: Cleanup above hacks and replace with fully theme-aware code like below. */ + +[data-md-color-scheme="binja"] { + --md-primary-fg-color: #d73726; + --md-primary-bg-color: #ffffff; + --md-primary-fg-color--light: #ECB7B7; + --md-primary-fg-color--dark: #990000; + --md-code-fg-color: rgb(215, 55, 38); + --md-code-bg-color: hsla(0, 0%, 96%, 1); +} + + +/* Experimenting +.md-sidebar--secondary { + order: 0; +} +*/
\ No newline at end of file diff --git a/docs/getting-started.md b/docs/getting-started.md index f2385981..4fec347e 100644 --- a/docs/getting-started.md +++ b/docs/getting-started.md @@ -1,1049 +1,94 @@ # Getting Started -Welcome to Binary Ninja. This introduction document is meant to quickly guide you over some of the most common uses of Binary Ninja. +Welcome to Binary Ninja. This introduction document is meant to quickly guide you over some of the most common uses of Binary Ninja. If you're interested in more detailed information, check out the [User Manual](/guide/). -## Directories + +## Installing Binary Ninja -Binary Ninja uses two main locations. The first is the install path of the binary itself and the second is the user folders for user-installed content. +The download links you receive after purchasing expire after 72hrs but as long as you have [active support](https://binary.ninja/faq/#updates) you can [request download links](https://binary.ninja/recover/) any time! +### Linux -### Binary Path +Because Linux install locations can vary widely, we do not assume that Binary Ninja has been installed in any particular folder on Linux. Instead, first unzip the installation zip wherever you wish to install BN, and then run `binaryninja/scripts/linux-setup.sh`. This sets up file associations, icons, and adds BN's Python library to your python path. Run it with `-h` to see the customization options. +### MacOS -Binaries are installed in the following locations by default: +To install on MacOS, simply drag-and-drop the app bundle from the DMG to the desired location. -- macOS: `/Applications/Binary Ninja.app` -- Windows (global install): `C:\Program Files\Vector35\BinaryNinja` -- Windows (user install): `%LOCALAPPDATA%\Vector35\BinaryNinja` -- Linux: Wherever you extract it! (No standard location) +### Windows -!!! Warning "Warning" - Do not put any user content in the install-path of Binary Ninja. The auto-update process of Binary Ninja may replace any files included in these folders. - -### User Folder - -The base locations of user folders are: - -- macOS: `~/Library/Application Support/Binary Ninja` -- Linux: `~/.binaryninja` -- Windows: `%APPDATA%\Binary Ninja` - -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. -- `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) -- `settings.json`: User settings file (see [settings](#settings)) - -The following files and folders may be created in the user folder but are not created by default without some additional action: -- `keybindings.json`: Custom key bindings (see [key bindings](#custom-hotkeys)) -- `startup.py`: Default python commands run once the UI is loaded in the context of the scripting console -- `signatures/`: Any user-signatures can be stored in this location which is not created by default -- `pythonVER/`: Any pip dependencies from plugin manager plugins are installed to the appropriate python version subfolder such as `python310` -- `symbols/`: Store PDBs downloaded -- `update/`: Used to store update caches for pending updates -- `snippets/`: Used to store snippets created using the Snippet plugin -- `themes/`: For user themes or user-modified versions of official themes -- `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 - - - -### QSettings Locations - -Some settings such as window locations, saved checkboxes, recent file lists, disassembly settings, dialog histories. - -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-5/qsettings.html#platform-specific-notes). +To install on Windows, use the installer linked from the email you received after purchase. You'll only choose whether to install globally or to your local user during the install process. ## License -When you first run Binary Ninja, it will prompt you for your license key. You should have received your license key via email after your purchase. If not, please contact [support](https://binary.ninja/support). - -Once the license key is installed, you can change it, back it up, or otherwise inspect it simply by looking inside the base of the user folder for `license.dat`. - -## Linux Setup - -Because Linux install locations can vary widely, we do not assume that Binary Ninja has been installed in any particular folder on Linux. Rather, you can simply run `binaryninja/scripts/linux-setup.sh` after extracting the zip and various file associations, icons, and other settings will be set up. Run it with `-h` to see the customization options. - -## Loading Files - -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`) -3. Use the `File/Open with Options` menu which allows you to customize the analysis options (`[CMD/CTRL-SHIFT] o`) -4. Open a file from the Triage picker (`File/Open for Triage`) which enables several minimal analysis options and shows a summary view first -5. Click an item in the recent files list (hold `[CMD/CTRL-SHIFT]` while clicking to use the `Open with Options` workflow) -6. Press the number key associated with an item from the recent files list (0-9, where 0 represents file 10 on the recent list, optionally holding `[CMD/CTRL-SHIFT]` to use the `Open with Options` workflow) -7. Run Binary Ninja with an optional command-line parameter -8. Open a file from a URL via the `[CMD/CTRL] l` hotkey -9. Open a file using the `binaryninja:` URL handler. For security reasons, the URL handler requires you to confirm a warning before opening a file via the URL handler. URLs additionally support deep linking using the `expr` query parameter where expression value is a valid parsable expression such as those possible in the [navigation dialog](#navigating), and fully documented in the [`parse_expression`](https://api.binary.ninja/binaryninja.binaryview-module.html?highlight=parse_expression#binaryninja.binaryview.BinaryView.parse_expression) API. Below a few examples are provided: - * URLs For referencing files on the local file system. - * `binaryninja:///bin/ls?expr=sub_2830` - open the given file and navigate to the function: `sub_2830` - * `binaryninja:///bin/ls?expr=.text` - open the given file and navigate to the start address of the `.text` section - * `binaryninja:///bin/ls?expr=.text+6b` - open the given file and navigate to the hexadecimal offset `6b` from the `.text` section. - * URLs For referencing remote file files either the URL should be prefixed with `binaryninja:` and optionally suffixed with the `expr` query parameter - * `binaryninja:file://<remote_path>?expr=[.data + 400]` - Download the remote file and navigate to the address at `.data` plus `0x400` - -## Saving Files - - - -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: - -1. "Save" - This menu is the only one bound to a hotkey by default and it is intended to be the "do what I probably want" option. - - If you have edited the contents of a file and have not yet confirmed the file name to save over, this will ask you to save the file contents and prompt for a file name (check the save dialog title text to confirm this). - - If you have edited the file contents and _have_ previously specified the file name, this option will save those changes to that file without a prompt. - - If you have not edited the contents of the file but have added any analysis information (created functinos, comments, changed names types, etc), you will be asked for the name of the `.bndb` analysis database if one does not already exist. - - If an existing analysis database does exist and is in use, the existing database will be saved without a prompt. - - Finally, if you have changed both file contents and analysis information, you'll be prompted as to which you wish to save. - -2. "Save As" - Will prompt to save the analysis database or just the file contents. - - 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. - -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. - - <!-- this image is getting floated down into the next section --> - -## Status Bar - - <!-- this image needs updating to reflect new status bar --> - -The status bar provides current information about the open file as well as some interactive controls. Summary features are listed below: - -* Update Notification - perform updates, download status, and restart notification -* Analysis progress - ongoing analysis progress of current active file -* Cursor offset or selection -* File Contents Lock - interactive control to prevent accidental changes to the underlying file - -## Analysis - -As soon as you open a file, Binary Ninja begins its auto-analysis which is fairly similar to decompiling the entire binary. - -Even while Binary Ninja is analyzing a binary, the UI should be responsive. Not only that, but because the analysis prioritizes user-requested analysis, you can start navigating a binary immediately and wherever you are viewing will be prioritized for analysis. The current progress through a binary is shown in the status bar (more details are available via `bv.analysis_info` in the Python console), but note that the total number of items left to analyze will go up as well as the binary is processed and more items are discovered that require analysis. - -Analysis proceeds through several phases summarized below: - -* Phase 1 - Initial Recursive Descent -* Phase 2 - Call Target Analysis (Part of Linear Sweep) -* Phase 3.x - Control Flow Graph Analysis (Part of Linear Sweep) - -Errors or warnings during the load of the binary are also shown in the status bar, each with an appropriate icon. The most common warnings are from incomplete lifting and can be safely ignored. If the warnings include a message like `Data flow for function at 0x41414141 did not terminate`, then please report the binary to the [bug database](https://github.com/Vector35/binaryninja-api/issues). - -### Analysis Speed - -If you wish to speed up analysis, you have several options. The first is to use the `File/Open for Triage` menu which activates the Triage file picker. By default, [Triage mode](https://binary.ninja/2019/04/01/hackathon-2019-summary.html#triage-mode-rusty) will enable a faster set of default analysis options that doesn't provide as much in-depth analysis but is significantly faster. - -Additionally, using the [open with options](#loading-files) feature allows for customization of a number of analysis options on a per-binary basis. See [all settings](#all-settings) under the `analysis` category for more details. - -## Interacting - -### 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). - -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](#ui.middleClickNavigationAction), [ui.middleClickShiftNavigationAction](#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. - -### The Sidebar - - - -Once you have a file open, the sidebar lets you quickly access the most common features and keeps them available while you work, including: -- 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 - -### Tiling Panes - - - -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. - -The Feature Map is also displayed on the right, and gives 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. +When you first run Binary Ninja, it will prompt you for your license key. You should have received your license key via the same email that included your download links. If not, please contact [support](https://binary.ninja/support). -### Switching Views - <!-- this image needs updating to the pane header --> +## Opening Files -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. +While there are [more ways than shown here](/guide/#loading-files), the most common ways to open a file are: -### Command Palette + - Drag-and-drop + - File Open + - Run via CLI - +But you can also change how analysis happens using [open with options](/guide/#loading-files). -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. +## UI Basics -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 +By default, you'll see four main areas in Binary Ninja: - +1. Symbol List (one of many [sidebars](guide/#the-sidebar)) +1. [Cross References](guide/#cross-references-pane) +1. Main View (defaults to High Level IL and can have many [panes](guide/#tiling-panes)) +1. [Feature Map](guide/#feature-map) -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. +Not enabled by default but can be made visible is the global area which includes the [scripting console](guide/#script-python-console) and log window. -!!! Tip "Tip" - To search in the keybindings list, just click to make sure it's focused and start typing! +Make sure to check out the many view options available in the various ☰ ("hamburger") menus. However, most configuration settings are available in the [settings](guide/#settings) menu. (`[CMD/CTRL] ,` is the hotkey for settings) + in the top right of each pane allows for additional customization, including locking the pane to a single function. -!!! Tip "Tip" - It is also possible to edit the `keybindings.json` file in your user folder directly in a text editor. +### Interacting -!!! Tip "Note" - On macOS, within the `keybindings.json`, `Ctrl` refers to the Command key, while `Meta` refers to the Option key. This is a remapping performed by Qt to make cross-platform keybindings easier to define. + -### Default Hotkeys +One of the most useful features of Binary Ninja is that everything can be quickly and easily accessed through a [command-palette](/guide/#command-palette) (`[CMD/CTRL] p`). You'll be surprised how often it saves you from looking through menus to find out just what you need. Also, any action in the command-palette can be changed to a [custom hotkey](/guide/#custom-hotkeys). That said, here are a few of the more useful default hotkeys: - - `h` : Switch to hex view - - `p` : Create a function - `[ESC]` : Navigate backward - - `[CMD] [` (macOS) : Navigate backward - - `[CMD] ]` (macOS) : Navigate forward - - `[CTRL] [` (Windows/Linux) : Navigate backward - - `[CTRL] ]` (Windows/Linux) : Navigate forward - `[SPACE]` : Toggle between linear view and graph view - `[F5]`, `[TAB]` : Toggle between decompilation (HLIL) and disassembly view - - `g` : Go To Address dialog + - `g` : Go to an address or symbol - `n` : Name a symbol - - `u` : Undefine an existing symbol (only for removing new user-defined names) - - `e` : Edits an instruction (by modifying the original binary -- currently only enabled for x86, and x64) - - `x` : Focuses the cross-reference pane - - `;` : Adds a comment - - `i` : Cycles between disassembly, LLIL, MLIL and HLIL in graph view - - `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 + - `;` : Add a comment + - `i` : Cycle between disassembly, LLIL, MLIL and HLIL + - `y` : Change type of the currently selected element - `1`, `2`, `4`, `8` : Change type directly to a data variable of the indicated widths - - `d` : Switches between data variables of various widths + - `d` : Switch between data variables of various widths - `r` : Change the data type to single ASCII character - `o` : Create a pointer data type - - `[CMD-SHIFT] +` (macOS) : Graph view zoom in - - `[CMD-SHIFT] -` (macOS) : Graph view zoom out - - `[CTRL-SHIFT] +` (Windows/Linux) : Graph view zoom in - - `[CTRL-SHIFT] -` (Windows/Linux) : Graph view zoom out - - `=` : Merge variables - - Other hotkeys specifically for working with types are in the [type guide](guide/type.md#direct-ui-manipulation) - -### Graph View - - - -Binary Ninja offers a graph view that groups the basic blocks of disassembly into visually distinct blocks with edges showing control flow between them. - - - -Features of the graph view include: - -- Ability to double click edges to quickly jump between locations -- Zoom (CTRL-mouse wheel) -- Zoom to Fit - Zooms out until the whole graph is visible (`w`) -- Zoom to Cursor - Zooms to 100% at the position of the cursor (`z`) -- Vertical Scrolling (Side scroll bar as well as mouse wheel) -- Horizontal Scrolling (Bottom scroll bar as well as SHIFT-mouse wheel) -- Individual highlighting of arguments, addresses, immediate values, types, etc. -- Full type signature of current function shown in an interactive header: - - Selecting elements in the header highlights them in the graph view - - Change type (`y`) and Rename (`n`) shortcuts work on elements in the header - - Reanalyze function button on left edge of the header -- Edge colors indicate whether the path is the true (green) or false (red) case of a conditional jump (a color-blind option in the preferences is useful for those with red-green color blindness) and blue for unconditional branches -- Context menu that can trigger some function-wide actions as well as some specific to the highlighted instruction (such as inverting branch logic or replacing a specific function with a NOP) - -### View Options - - - -Each of the views (Hex, Graph, Linear) have a variety of options configurable from the ☰ menu on the top right of the view pane. - -Current options include: - -- Hex - - Background highlight - - None - - Column - - Byte value - - Color highlight - - None - - ASCII and printable - - Modification - - Contrast - - Normal - - Medium - - Highlight -- Graph & Linear Views - - Expand long opcode - - Show address - - Show call parameter names (MLIL only) - - Show function address - - Show opcode bytes - - Show register set highlighting - - Show variable types - - At assignment (MLIL only) - - At top of function - - Assembly - - Low Level IL - - Show Stack Pointer Value - - Medium Level IL - - High Level IL - - Pseudo C - - Advanced IL Forms - - Lifted IL - - Show IL Flag Usage - - Low Level IL (SSA Form) - - Medium Level IL (Mapped) - - Medium Level IL (Mapped, SSA Form) - - Medium Level IL (SSA Form) - - High Level IL (SSA Form) - - -### Hex View - - - -The hexadecimal view is useful for viewing raw binary files that may or may not even be executable binaries and allows direct editing of the binary contents in place, regardless of the type of the binary. Any changes made in hex view will be reflected in all other [open views](#tiling-panes) of the same binary. The lock button on the right edge of the bottom status bar must be toggled off (🔓) to perform any direct editing in hex view -- this is to prevent unintended modification of the binary by accidental pasting or typing. - -The hex view is particularly good for transforming data in various ways via the `Copy as`, `Transform`, and `Paste from` menus. Note that like any other edits, `Transform` menu options will transform the data in-place, but unlike other means of editing the binary, the transformation dialog will work even when the lock button is toggled on (🔒). - -!!! Tip "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. - -#### Template Simplifier - -The [`analysis.types.templateSimplifier`](#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"/> -</div> - -#### 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 - - -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. +For more hotkeys, see the [User Manual](/guide/). -Linear view is most 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 +## Intermediate Languages - - -The symbols list in Binary Ninja shows the list of symbols for functions and/or data variables currently identified. As large binaries are analyzed, the list may grow during analysis. The symbols list starts with known functions and data variables such as the entry point, exports, or using other features of the binary file format and explores from there to identify other functions and data variables. - -The symbols list highlights symbols according to whether they are functions or data variables, local or exported, or imported. All of these kinds of symbols can be toggled from the ☰ menu at the top right of the Symbols pane. - -!!! Tip "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". - -### 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 - - - -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: - -1. **Function prototype.** The function’s prototype. If the prototype is too long to fit inside the window, a scroll bar will appear. -1. **Function info.** A list of conditionally-shown tags offering information about the function. Possible tags are as follows: - - **Function architecture/platform**: The function's architecture/platform (e.g. `windows-x86_64`) - - **Analysis skipped (too large)**: Analysis was skipped for this function because it was too large ([`analysis.limits.maxFunctionSize`](#analysis.limits.maxFunctionSize)) - - **Analysis timed out**: Analysis for this function was skipped because it exceeded the maximum allowed time ([`analysis.limits.maxFunctionAnalysisTime`](#analysis.limits.maxFunctionAnalysisTime)) - - **Analysis was skipped (too many updates)**: Analysis was skipped for this function because it caused too many updates ([`analysis.limits.maxFunctionUpdateCount`](#analysis.limits.maxFunctionUpdateCount)) - - **Analysis suppressed**: Analysis was suppressed for this function because analysis of auto-discovered functions was disabled ([`analysis.suppressNewAutoFunctionAnalysis`](#analysis.suppressNewAutoFunctionAnalysis)) - - **Basic analysis only**: This function only received basis analysis ([`analysis.mode`](#analysis.mode) was 'basic') - - **Intermediate analysis only**: This function only received intermediate analysis ([`analysis.mode`](#analysis.mode) was 'intermediate') - - **Unresolved stack usage**: The function has unresolved stack usage - - **GP = 0xABCD1234**: The global pointer value is 0xABCD1234 -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.** Does this function return? If not, #8 will be unavailable. -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. -1. **Register stack adjustments.** A table containing a row for each register stack (e.g. x87) in the architecture, with the ability to adjust how many registers are removed from each stack when the function returns. - - - - -<!-- These same points need to be made about Panes, but also a lot more -### Reflection View - -- View BNILs and assembly for the same file side-by-side - - - -- Settings to control the synchronization behavior - - - -- Right Click the Function Header for quick access to synchronization mode changes - - - -- Reflection currently presents in graph view only - -- When main view is linear, Mini Graph renders the Reflection View ---> - -### High Level IL - - - -Binary Ninja features a decompiler that produces High Level IL (HLIL) as output. HLIL is not intended to be a representation of the code in C, but some users prefer to have a more C-like scoping style. - -You can control the way HLIL appears in the settings. - -The different options are shown below: - - - -### Pseudo C - - - -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: - - - -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. - - - -Performing this action on both variables in the example results in the following output: - - - -### Merging and Splitting Variables - -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. - - - -To merge variables, first click on the variable that the others should be merged into. Then, select "Merge Variables..." from the context menu (the default keybind for this action is `=`). This will bring up a dialog where the variables -to be merged in can be selected. All selected variables will be merged into the target variable, inheriting the name -and type of the variable that was first clicked. - - - -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. - - - -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 - - - -The integrated script console is useful for small scripts that aren't worth writing as full plugins. - -To trigger the console, either use `<BACKTICK>`, or use the `View`/`Python Console` menu. - -!!!Tip "Note" - 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. - - - -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. - -Multi-line input is possible just by doing what you'd normally do in python. If you leave a trailing `:` at the end of a line, the box will automatically turn into a multi-line edit box, complete with a command-history. To submit that multi-line input, use `<CTRL>-<ENTER>`. You can also force multi-line input with `<SHIFT>-<ENTER>`. - -The scripting console is not a full IDE, but it has several convenience features that make it more pleasant to use: - -- `<TAB>` offers completion of variables, methods, anything in-scope -- `<CTRL>-R` allows for reverse-searching your console history -- `<UP>` and `<DOWN>` can be used to view the command-history - -The interactive python prompt also has several built-in functions and variables: - -- `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) -- `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_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) - -#### startup.py - -The python interpreter can be customized to run scripts on startup using `startup.py` in your user folder. Simply enter commands into that file, and they will be executed every time Binary Ninja starts. By default, it comes with an import helper: - - # Commands in this file will be run in the interactive python console on startup - from binaryninja import * - -From here, you can add any custom functions or objects you want to be available in the console. If you want to restore the original copy of `startup.py` at any time, simply delete the file and restart Binary Ninja. A fresh copy of the above will be generated. - -#### "Run Script..." - -The "Run Script..." option in the File Menu allows loading a python script from your filesystem and executing it -within the console. It can also be ran 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 -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 -defined within the console, but within the script, it will be set to the absolute path of the script. - -Any variables or functions defined globally within the script will be available within the console, and to future scripts. - -#### Python Debugging -See the [plugin development guide](dev/plugins.md#debugging-python). - -Note -!!! Tip "Note" - The current script console only supports Python at the moment, but it's fully extensible for other programming languages for advanced users who wish to implement their own bindings. +Binary Ninja is one of the most advanced binary analysis platforms, and it has a unique stack of related intermediate languages. If that gets you excited, you'll surely want to check out the [developer guide](/dev/bnil-overview.md) for more information. If it doesn't mean anything to you, no worries, here's a few tips to make your life easier. The default view is "High Level IL". It looks and reads almost like pseudo code. There's a few extra notations (usually just around comparisons for whether they are signed or not, or between moves of data indicating the size of the operation) but it should otherwise be very understandable. If you prefer disassembly or even [Pseudo C](/guide/#pseudo-c) as your default view, no worries, just check out the `UI`/`view.graph` and `view.linear` settings. ## Using Plugins -Plugins can be installed by one of two methods. First, 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: - -- macOS: `~/Library/Application Support/Binary Ninja/plugins/` -- Linux: `~/.binaryninja/plugins/` -- Windows: `%APPDATA%\Binary Ninja\plugins` +Plugins can be installed by one of two methods. First, they can be manually installed by copying the plugin to the appropriate [folder](guide/#user-folder), or using the [Plugin Manager](guide/plugins.md#plugin-manager). -Alternatively, plugins can be installed with the new [pluginmanager](https://api.binary.ninja/binaryninja.pluginmanager-module.html) API. +## Debugger -For more detailed information on plugins, see the [plugin guide](guide/plugins.md). +Binary Ninja includes a debugger that can debug executables on Windows, Linux, and macOS. -## PDB Plugin - -Binary Ninja supports loading PDB files through a built in PDB loader. When selected from the plugin menu it attempts to find the corresponding PDB file using the following search order: - -1. Look in the same directory as the opened file/bndb (e.g. If you have `c:\foo.exe` or `c:\foo.bndb` open the PDB plugin looks for `c:\foo.pdb`) -2. Look in the local symbol store. This is the directory specified by the settings: `local-store-relative` or `local-store-absolute`. The format of this directory is `foo.pdb\<guid>\foo.pdb`. -3. Attempt to connect and download the PDB from the list of symbol servers specified in setting `symbol-server-list`. -4. Prompt the user for the PDB. - -## Debugger Plugin - -Binary Ninja now comes with the debugger plugin that can debug executables on Windows, Linux, and macOS. - -For more detailed information on plugins, see the [debugger guide](guide/debugger.md). - -## Settings - - - -Binary Ninja provides various settings which are available via the `[CMD/CTRL] ,` hotkey. These settings allow a wide variety of customization of the user interface and functional aspects of the analysis environment. - -Several search keywords are available in the settings UI. Those include: - -- `@default` - Shows settings that are in the default scope -- `@user` - Shows only settings that the user has changed -- `@project` - Shows settings scoped to the current project -- `@resource` - Shows settings scoped to the current resource (for example if you used open-with-options and changed settings) -- `@modified` - Shows settings that are changed from their default values - -There are several scopes available for settings: - -* **User Settings** - Settings that apply globally and override the defaults. These settings are stored in `settings.json` within the [User Folder](#user-folder). -* **Project Settings** - Settings which only apply if a project is opened. These settings are stored in `.binaryninja/settings.json` within a Project Folder. Project Folders can exist anywhere except within the User Folder. These settings apply to all files contained in the Project Folder and override the default and user settings. In order to activate this feature, select the Project Settings tab and a clickable "Open Project" link will appear at the top right of the view. Clicking this will create `.binaryninja/settings.json` in the folder of the currently selected binary view. If it already exists, this link will be replaced with the path of the project folder. -* **Resource Settings** - Settings which only apply to a specific BinaryView object within a file. These settings persist in a Binary Ninja Database (.bndb) database or ephemerally in a BinaryView object if a database does not yet exist for a file. - -!!!Tip "Tip" - Both the _Project_ and _Resource_ tabs have a drop down indicator (▾) that can be clicked to select the project or resource whose settings you want to adjust. - -All settings are uniquely identified with an identifier string. Identifiers are available in the settings UI via the context menu and are useful for find settings using the search box and for [programmatically](https://api.binary.ninja/binaryninja.settings-module.html) interacting with settings. - -**Note**: In order to facilitate reproducible analysis results, when opening a file for the first time, all of the analysis settings are automatically serialized into the _Resource Setting_ scope. This prevents subsequent _User_ and _Project_ setting modifications from unintentionally changing existing analysis results. - -### All Settings - -Here's a list of all built-in settings currently available from the UI: - -|Category|Setting|Description|Type|Default|Scope|Key| -|---|---|---|---|--|---|---| -|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|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|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|External Debug Information 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|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|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|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|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|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|Max Intermediate Condition Complexity|High Level IL tuning parameter.|`number`|`1048576`|[`SettingsProjectScope`, `SettingsResourceScope`, `SettingsUserScope`]|<a id='analysis.hlil.maxIntermediateConditionComplexity'>analysis.hlil.maxIntermediateConditionComplexity</a>| -|analysis|Switch Case Node Threshold|High Level IL tuning parameter.|`number`|`4`|[`SettingsProjectScope`, `SettingsResourceScope`, `SettingsUserScope`]|<a id='analysis.hlil.switchCaseNodeThreshold'>analysis.hlil.switchCaseNodeThreshold</a>| -|analysis|Switch Case Value Count Threshold|High Level IL tuning parameter.|`number`|`6`|[`SettingsProjectScope`, `SettingsResourceScope`, `SettingsUserScope`]|<a id='analysis.hlil.switchCaseValueCountThreshold'>analysis.hlil.switchCaseValueCountThreshold</a>| -|analysis|Target Max Condition Complexity|High Level IL tuning parameter.|`number`|`16`|[`SettingsProjectScope`, `SettingsResourceScope`, `SettingsUserScope`]|<a id='analysis.hlil.targetMaxConditionComplexity'>analysis.hlil.targetMaxConditionComplexity</a>| -|analysis|Initial Analysis Hold|Enabling the analysis hold discards all future analysis updates until clearing the hold. This setting only applies to analysis in the InitialState.|`boolean`|`False`|[`SettingsProjectScope`, `SettingsResourceScope`, `SettingsUserScope`]|<a id='analysis.initialAnalysisHold'>analysis.initialAnalysisHold</a>| -|analysis|Advanced Analysis Cache Size|Controls the number of functions for which the most recent generated advanced analysis is cached. Large values may result in very high memory utilization.|`number`|`64`|[`SettingsProjectScope`, `SettingsResourceScope`, `SettingsUserScope`]|<a id='analysis.limits.cacheSize'>analysis.limits.cacheSize</a>| -|analysis|Max Function Analysis Time|Any functions that exceed this analysis time are deferred. A value of 0 disables this feature. The default value is 20 seconds. Time is specified in milliseconds.|`number`|`20000`|[`SettingsProjectScope`, `SettingsResourceScope`, `SettingsUserScope`]|<a id='analysis.limits.maxFunctionAnalysisTime'>analysis.limits.maxFunctionAnalysisTime</a>| -|analysis|Max Function Size|Any functions over this size will not be automatically analyzed. A value of 0 disables analysis of functions and suppresses the related log warning. To override see FunctionAnalysisSkipOverride. Size is specified in bytes.|`number`|`65536`|[`SettingsProjectScope`, `SettingsResourceScope`, `SettingsUserScope`]|<a id='analysis.limits.maxFunctionSize'>analysis.limits.maxFunctionSize</a>| -|analysis|Max Function Update Count|Any functions that exceed this incremental update count are deferred. A value of 0 disables this feature.|`number`|`100`|[`SettingsProjectScope`, `SettingsResourceScope`, `SettingsUserScope`]|<a id='analysis.limits.maxFunctionUpdateCount'>analysis.limits.maxFunctionUpdateCount</a>| -|analysis|Max Lookup Table Size|Limits the maximum number of entries for a lookup table.|`number`|`4095`|[`SettingsProjectScope`, `SettingsResourceScope`, `SettingsUserScope`]|<a id='analysis.limits.maxLookupTableSize'>analysis.limits.maxLookupTableSize</a>| -|analysis|Minimum String Length|The minimum length for strings created during auto-analysis|`number`|`4`|[`SettingsProjectScope`, `SettingsResourceScope`, `SettingsUserScope`]|<a id='analysis.limits.minStringLength'>analysis.limits.minStringLength</a>| -|analysis|Maximum String Search|Maximum number of strings to find before giving up.|`number`|`1048576`|[`SettingsProjectScope`, `SettingsResourceScope`, `SettingsUserScope`]|<a id='analysis.limits.stringSearch'>analysis.limits.stringSearch</a>| -|analysis|Worker Thread Count|The number of worker threads available for concurrent analysis activities.|`number`|`9`|[`SettingsProjectScope`, `SettingsResourceScope`, `SettingsUserScope`]|<a id='analysis.limits.workerThreadCount'>analysis.limits.workerThreadCount</a>| -|analysis|Autorun Linear Sweep|Automatically run linear sweep when opening a binary for analysis.|`boolean`|`True`|[`SettingsProjectScope`, `SettingsResourceScope`, `SettingsUserScope`]|<a id='analysis.linearSweep.autorun'>analysis.linearSweep.autorun</a>| -|analysis|Control Flow Graph Analysis|Enable the control flow graph analysis (Analysis Phase 3) portion of linear sweep.|`boolean`|`True`|[`SettingsProjectScope`, `SettingsResourceScope`, `SettingsUserScope`]|<a id='analysis.linearSweep.controlFlowGraph'>analysis.linearSweep.controlFlowGraph</a>| -|analysis|Detailed Linear Sweep Log Information|Linear sweep generates additional log information at the InfoLog level.|`boolean`|`False`|[`SettingsProjectScope`, `SettingsResourceScope`, `SettingsUserScope`]|<a id='analysis.linearSweep.detailedLogInfo'>analysis.linearSweep.detailedLogInfo</a>| -|analysis|Entropy Heuristics for Linear Sweep|Enable the application of entropy based heuristics to the function search space for linear sweep.|`boolean`|`True`|[`SettingsProjectScope`, `SettingsResourceScope`, `SettingsUserScope`]|<a id='analysis.linearSweep.entropyHeuristics'>analysis.linearSweep.entropyHeuristics</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|Analysis Mode|Controls the amount of analysis performed on functions.|`string`|`full`|[`SettingsProjectScope`, `SettingsResourceScope`, `SettingsUserScope`]|<a id='analysis.mode'>analysis.mode</a>| -| | | enum: Only perform control flow analysis on the binary. Cross references are valid only for direct function calls. [Disassembly Only]|`enum`|`controlFlow`| | | -| | | enum: Perform fast initial analysis of the binary. This mode does not analyze types or data flow through stack variables. [LLIL and Equivalents]|`enum`|`basic`| | | -| | | enum: Perform analysis which includes type propagation and data flow. [MLIL and Equivalents]|`enum`|`intermediate`| | | -| | | enum: Perform full analysis of the binary.|`enum`|`full`| | | -|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|Simplify Templates|Simplify common C++ templates that are expanded with default arguments at compile time (eg. `std::__cxx11::basic_string<wchar, std::char_traits<wchar>, std::allocator<wchar> >` to `std::wstring`).|`boolean`|`True`|[`SettingsProjectScope`, `SettingsResourceScope`, `SettingsUserScope`]|<a id='analysis.types.templateSimplifier'>analysis.types.templateSimplifier</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`|`CoreTypeParser`| | | -| | | |`enum`|`ClangTypeParser`| | | -|analysis|Type Printer|Specify the implementation used for formatting types into text.|`string`|`CoreTypePrinter`|[`SettingsProjectScope`, `SettingsResourceScope`, `SettingsUserScope`]|<a id='analysis.types.printerName'>analysis.types.printerName</a>| -| | | |`enum`|`CoreTypePrinter`| | | -|analysis|Unicode Blocks|Defines which unicode blocks to consider when searching for strings.|`array`|[]|[`SettingsProjectScope`, `SettingsResourceScope`, `SettingsUserScope`]|<a id='analysis.unicode.blocks'>analysis.unicode.blocks</a>| -|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|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>| -| | | enum: Sets the disassembly syntax to a simplified Intel format. (TBD) |`enum`|`BN_INTEL`| | | -| | | enum: Sets the disassembly syntax to Intel format. (Destination on the left) |`enum`|`INTEL`| | | -| | | enum: Sets the disassembly syntax to AT&T format. (Destination on the right) |`enum`|`AT&T`| | | -|corePlugins|Aarch64 Architecture|Enable the built-in Aarch64 architecture module.|`boolean`|`True`|[`SettingsUserScope`]|<a id='corePlugins.architectures.aarch64'>corePlugins.architectures.aarch64</a>| -|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|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|Debugger Plugin|Enable the built-in debugger plugin.|`boolean`|`True`|[`SettingsUserScope`]|<a id='corePlugins.debugger'>corePlugins.debugger</a>| -|corePlugins|PDB Loader|Enable the built-in PDB loader plugin.|`boolean`|`True`|[`SettingsUserScope`]|<a id='corePlugins.pdb'>corePlugins.pdb</a>| -|corePlugins|DECREE Platform|Enable the built-in DECREE platform module.|`boolean`|`True`|[`SettingsUserScope`]|<a id='corePlugins.platforms.decree'>corePlugins.platforms.decree</a>| -|corePlugins|FreeBSD Platform|Enable the built-in FreeBSD platform module.|`boolean`|`True`|[`SettingsUserScope`]|<a id='corePlugins.platforms.freebsd'>corePlugins.platforms.freebsd</a>| -|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|Triage Plugin|Enable the built-in triage plugin.|`boolean`|`True`|[`SettingsUserScope`]|<a id='corePlugins.triage'>corePlugins.triage</a>| -|files|Auto Rebase Load File|When opening a file with options, automatically rebase an image which has a default load address of zero to 4MB for 64-bit binaries, or 64KB for 32-bit binaries.|`boolean`|`False`|[`SettingsProjectScope`, `SettingsUserScope`]|<a id='files.pic.autoRebase'>files.pic.autoRebase</a>| -|files|Universal Mach-O Architecture Preference|Specify an architecture preference for automatic loading of a Mach-O file from a Universal archive. By default, the first object file in the listing is loaded.|`array`|[]|[`SettingsUserScope`]|<a id='files.universal.architecturePreference'>files.universal.architecturePreference</a>| -| | | |`enum`|`alpha`| | | -| | | |`enum`|`arm`| | | -| | | |`enum`|`arm (XScale)`| | | -| | | |`enum`|`arm64`| | | -| | | |`enum`|`arm64_32`| | | -| | | |`enum`|`arm64_32v8`| | | -| | | |`enum`|`arm64e`| | | -| | | |`enum`|`arm64v8`| | | -| | | |`enum`|`armv4t`| | | -| | | |`enum`|`armv5tej`| | | -| | | |`enum`|`armv6`| | | -| | | |`enum`|`armv6m`| | | -| | | |`enum`|`armv7`| | | -| | | |`enum`|`armv7em`| | | -| | | |`enum`|`armv7f`| | | -| | | |`enum`|`armv7k`| | | -| | | |`enum`|`armv7m`| | | -| | | |`enum`|`armv7s`| | | -| | | |`enum`|`armv8`| | | -| | | |`enum`|`hppa`| | | -| | | |`enum`|`i860`| | | -| | | |`enum`|`mc680x0`| | | -| | | |`enum`|`mc88000`| | | -| | | |`enum`|`mc98000`| | | -| | | |`enum`|`mips`| | | -| | | |`enum`|`ppc`| | | -| | | |`enum`|`ppc601`| | | -| | | |`enum`|`ppc602`| | | -| | | |`enum`|`ppc603`| | | -| | | |`enum`|`ppc603e`| | | -| | | |`enum`|`ppc603ev`| | | -| | | |`enum`|`ppc604`| | | -| | | |`enum`|`ppc604e`| | | -| | | |`enum`|`ppc620`| | | -| | | |`enum`|`ppc64`| | | -| | | |`enum`|`ppc7400`| | | -| | | |`enum`|`ppc7450`| | | -| | | |`enum`|`ppc750`| | | -| | | |`enum`|`ppc970`| | | -| | | |`enum`|`sparc`| | | -| | | |`enum`|`vax`| | | -| | | |`enum`|`x86`| | | -| | | |`enum`|`x86 (Arch1)`| | | -| | | |`enum`|`x86_64`| | | -| | | |`enum`|`x86_64 (Haswell)`| | | -|network|Download Provider|Specify the registered DownloadProvider which enables resource fetching over HTTPS.|`string`|`CoreDownloadProvider`|[`SettingsUserScope`]|<a id='network.downloadProviderName'>network.downloadProviderName</a>| -| | | |`enum`|`CoreDownloadProvider`| | | -| | | |`enum`|`PythonDownloadProvider`| | | -|network|Enable External Resources|Allow Binary Ninja to download external images and resources when displaying markdown content (e.g. plugin descriptions).|`boolean`|`True`|[`SettingsUserScope`]|<a id='network.enableExternalResources'>network.enableExternalResources</a>| -|network|Enable External URLs|Allow Binary Ninja to download and open external URLs.|`boolean`|`True`|[`SettingsUserScope`]|<a id='network.enableExternalUrls'>network.enableExternalUrls</a>| -|network|Enable Plugin Manager|Allow Binary Ninja to connect to the update server to check for new plugins and plugin updates.|`boolean`|`True`|[`SettingsUserScope`]|<a id='network.enablePluginManager'>network.enablePluginManager</a>| -|network|Enable Release Notes|Allow Binary Ninja to connect to the update server to display release notes on new tabs.|`boolean`|`True`|[`SettingsUserScope`]|<a id='network.enableReleaseNotes'>network.enableReleaseNotes</a>| -|network|Enable Update Channel List|Allow Binary Ninja to connect to the update server to determine which update channels are available.|`boolean`|`True`|[`SettingsUserScope`]|<a id='network.enableUpdateChannelList'>network.enableUpdateChannelList</a>| -|network|Enable Updates|Allow Binary Ninja to connect to the update server to check for updates.|`boolean`|`True`|[`SettingsUserScope`]|<a id='network.enableUpdates'>network.enableUpdates</a>| -|network|HTTPS Proxy|Override default HTTPS proxy settings. By default, HTTPS Proxy settings are detected and used automatically via environment variables (e.g., https_proxy). Alternatively, proxy settings are obtained from the Internet Settings section of the Windows registry, or the Mac OS X System Configuration Framework.|`string`| |[`SettingsUserScope`]|<a id='network.httpsProxy'>network.httpsProxy</a>| -|network|Websocket Provider|Specify the registered WebsocketProvider which enables communication over HTTPS.|`string`|`CoreWebsocketProvider`|[`SettingsUserScope`]|<a id='network.websocketProviderName'>network.websocketProviderName</a>| -| | | |`enum`|`CoreWebsocketProvider`| | | -|pdb|Auto Download PDBs|Automatically download pdb files from specified symbol servers.|`boolean`|`True`|[`SettingsProjectScope`, `SettingsUserScope`]|<a id='pdb.autoDownload'>pdb.autoDownload</a>| -|pdb|Absolute PDB Symbol Store Path|Absolute path specifying where the PDB symbol store exists on this machine, overrides relative path.|`string`| |[`SettingsProjectScope`, `SettingsUserScope`]|<a id='pdb.localStoreAbsolute'>pdb.localStoreAbsolute</a>| -|pdb|Relative PDB Symbol Store Path|Path *relative* to the binaryninja _user_ directory, specifying the pdb symbol store.|`string`|`symbols`|[`SettingsProjectScope`, `SettingsUserScope`]|<a id='pdb.localStoreRelative'>pdb.localStoreRelative</a>| -|pdb|Symbol Server List|List of servers to query for pdb symbols.|`array`|[`https://msdl.microsoft.com/download/symbols`]|[`SettingsProjectScope`, `SettingsUserScope`]|<a id='pdb.symbolServerList'>pdb.symbolServerList</a>| -|pluginManager|Community Plugin Manager Update Channel|Specify which community update channel the Plugin Manager should update plugins from.|`string`|`master`|[`SettingsUserScope`]|<a id='pluginManager.communityUpdateChannel'>pluginManager.communityUpdateChannel</a>| -| | | enum: The default channel. This setting should be used unless you are testing the Plugin Manager.|`enum`|`master`| | | -| | | enum: Plugin Manager test channel.|`enum`|`test`| | | -|pluginManager|Debug Plugin Manager|Enable debug functionality for the Plugin Manager.|`boolean`|`False`|[`SettingsUserScope`]|<a id='pluginManager.debug'>pluginManager.debug</a>| -|pluginManager|Official Plugin Manager Update Channel|Specify which official update channel the Plugin Manager should update plugins from.|`string`|`master`|[`SettingsUserScope`]|<a id='pluginManager.officialUpdateChannel'>pluginManager.officialUpdateChannel</a>| -| | | enum: The default channel. This setting should be used unless you are testing the Plugin Manager.|`enum`|`master`| | | -| | | enum: Plugin Manager test channel.|`enum`|`test`| | | -|pluginManager|Unofficial 3rd Party Plugin Repository Display Name|Specify display name of 3rd party plugin repository.|`string`| |[`SettingsUserScope`]|<a id='pluginManager.unofficialName'>pluginManager.unofficialName</a>| -|pluginManager|Unofficial 3rd Party Plugin Repository URL|Specify URL of 3rd party plugin|`string`| |[`SettingsUserScope`]|<a id='pluginManager.unofficialUrl'>pluginManager.unofficialUrl</a>| -|python|Python Path Override|Python interpreter binary which may be necessary to install plugin dependencies. Should be the same version as the one specified in the 'Python Interpreter' setting|`string`| |[`SettingsUserScope`]|<a id='python.binaryOverride'>python.binaryOverride</a>| -|python|Python Interpreter|Python interpreter library(dylib/dll/so.1) to load if one is not already present when plugins are loaded.|`string`| |[`SettingsUserScope`]|<a id='python.interpreter'>python.interpreter</a>| -|python|Minimum Python Log Level|Set the minimum Python log level which applies in headless operation only. The log is connected to stderr. Additionally, stderr must be associated with a terminal device.|`string`|`WarningLog`|[`SettingsUserScope`]|<a id='python.log.minLevel'>python.log.minLevel</a>| -| | | enum: Print Debug, Info, Warning, Error, and Alert messages to stderr on the terminal device.|`enum`|`DebugLog`| | | -| | | enum: Print Info, Warning, Error, and Alert messages to stderr on the terminal device.|`enum`|`InfoLog`| | | -| | | enum: Print Warning, Error, and Alert messages to stderr on the terminal device.|`enum`|`WarningLog`| | | -| | | enum: Print Error and Alert messages to stderr on the terminal device.|`enum`|`ErrorLog`| | | -| | | enum: Print Alert messages to stderr on the terminal device.|`enum`|`AlertLog`| | | -| | | enum: Disable all logging in headless operation.|`enum`|`Disabled`| | | -|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|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`| | | -| | | enum: Braces around scopes, new line.|`enum`|`bracesNewLine`| | | -|rendering|Maximum String Annotation Length|The maximum substring length that will be shown in string annotations.|`number`|`32`|[`SettingsUserScope`]|<a id='rendering.strings.maxAnnotationLength'>rendering.strings.maxAnnotationLength</a>| -|snippets|Indentation Syntax highlighting for snippets|String to use for indentation in snippets (tip: to use a tab, copy/paste a tab from another text field and paste here)|`string`|` `|[`SettingsUserScope`]|<a id='snippets.indentation'>snippets.indentation</a>| -|snippets|Syntax highlighting for snippets|Whether to syntax highlight (may be performance problems with very large snippets and the current highlighting implementation.)|`boolean`|`True`|[`SettingsUserScope`]|<a id='snippets.syntaxHighlight'>snippets.syntaxHighlight</a>| -|triage|Triage Analysis Mode|Controls the amount of analysis performed on functions when opening for triage.|`string`|`basic`|[`SettingsProjectScope`, `SettingsResourceScope`, `SettingsUserScope`]|<a id='triage.analysisMode'>triage.analysisMode</a>| -| | | enum: Only perform control flow analysis on the binary. Cross references are valid only for direct function calls.|`enum`|`controlFlow`| | | -| | | enum: Perform fast initial analysis of the binary. This mode does not analyze types or data flow through stack variables.|`enum`|`basic`| | | -| | | enum: Perform full analysis of the binary.|`enum`|`full`| | | -|triage|Triage Shows Hidden Files|Whether the Triage file picker shows hidden files.|`boolean`|`False`|[`SettingsProjectScope`, `SettingsResourceScope`, `SettingsUserScope`]|<a id='triage.hiddenFiles'>triage.hiddenFiles</a>| -|triage|Triage Linear Sweep Mode|Controls the level of linear sweep performed when opening for triage.|`string`|`partial`|[`SettingsProjectScope`, `SettingsResourceScope`, `SettingsUserScope`]|<a id='triage.linearSweep'>triage.linearSweep</a>| -| | | enum: Do not perform linear sweep of the binary.|`enum`|`none`| | | -| | | enum: Perform linear sweep on the binary, but skip the control flow graph analysis phase.|`enum`|`partial`| | | -| | | enum: Perform full linear sweep on the binary.|`enum`|`full`| | | -|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|Color Blind|Choose colors that are visible to those with red/green color blindness.|`boolean`|`False`|[`SettingsUserScope`]|<a id='ui.colorBlind'>ui.colorBlind</a>| -|ui|Developer Mode|Enable developer preferences.|`boolean`|`False`|[`SettingsUserScope`]|<a id='ui.developerMode'>ui.developerMode</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|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|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`| | | -|ui|File Contents Lock|Lock the file contents to prevent accidental edits from the UI. File modification via API and menu based patching is explicitly allowed while the lock is enabled.|`boolean`|`True`|[`SettingsUserScope`]|<a id='ui.fileContentsLock'>ui.fileContentsLock</a>| -|ui|Existing Database Detection|When opening a file in the UI, detect if a database (bndb) exists and offer to open the database.|`string`|`prompt`|[`SettingsUserScope`]|<a id='ui.files.databaseDetection'>ui.files.databaseDetection</a>| -| | | enum: Enable detection and generate prompt.|`enum`|`prompt`| | | -| | | enum: Enable detection and automatically open the file or database, if found.|`enum`|`always`| | | -| | | enum: Disable detection.|`enum`|`disable`| | | -|ui|Existing Downloaded URL View Detection|When opening a database from an external URL in the UI, detect if an unsaved database from the same URL is already open and offer to navigate in that open view.|`string`|`prompt`|[`SettingsUserScope`]|<a id='ui.files.openExistingViewFromURL'>ui.files.openExistingViewFromURL</a>| -| | | enum: Enable detection and generate prompt.|`enum`|`prompt`| | | -| | | enum: Enable detection and automatically switch to the open view, if found.|`enum`|`always`| | | -| | | enum: Disable detection.|`enum`|`disable`| | | -|ui|Auto Open with Options|Specify the file types which automatically open with the options dialog.|`array`|[`Mapped`, `Universal`]|[`SettingsUserScope`]|<a id='ui.files.openWithOptions'>ui.files.openWithOptions</a>| -| | | |`enum`|`Mapped`| | | -| | | |`enum`|`ELF`| | | -| | | |`enum`|`Mach-O`| | | -| | | |`enum`|`COFF`| | | -| | | |`enum`|`PE`| | | -| | | |`enum`|`Universal`| | | -|ui|Navigate to Main Function when First Opening a Binary.|Automatically navigate to a 'main' function when first opening a binary.|`boolean`|`True`|[`SettingsUserScope`]|<a id='ui.firstNavigate.enable'>ui.firstNavigate.enable</a>| -|ui|List of common main function names|Common 'main' function names to try to automatically navigate to when first opening a binary.|`array`|[`main`, `_main`, `WinMain`]|[`SettingsUserScope`]|<a id='ui.firstNavigate.names'>ui.firstNavigate.names</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`| | | -| | | enum: No subpixel antialiasing at High DPI.|`enum`|`hidpi`| | | -| | | 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`|`Open Sans`|[`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`|`11`|[`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`|`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`|`Source Code Pro`|[`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`|[`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|Number of history entries to store.|Controls the number of history entries to store for input dialogs.|`number`|`50`|[`SettingsUserScope`]|<a id='ui.inputHistoryCount'>ui.inputHistoryCount</a>| -|ui|Maximum UI Log Size|Set the maximum number of lines for the UI log.|`number`|`10000`|[`SettingsUserScope`]|<a id='ui.log.maxSize'>ui.log.maxSize</a>| -|ui|Minimum UI Log Level|Set the minimum log level for the UI log.|`string`|`InfoLog`|[`SettingsUserScope`]|<a id='ui.log.minLevel'>ui.log.minLevel</a>| -| | | enum: Display Debug, Info, Warning, Error, and Alert messages to log console.|`enum`|`DebugLog`| | | -| | | enum: Display Info, Warning, Error, and Alert messages to log console.|`enum`|`InfoLog`| | | -| | | enum: Display Warning, Error, and Alert messages to log console.|`enum`|`WarningLog`| | | -| | | enum: Display Error and Alert messages to log console.|`enum`|`ErrorLog`| | | -| | | enum: Display Alert messages to log console.|`enum`|`AlertLog`| | | -|ui|Manual Tooltip|Enable to prevent tooltips from showing without <ctrl> being held.|`boolean`|`False`|[`SettingsUserScope`]|<a id='ui.manualTooltip'>ui.manualTooltip</a>| -|ui|Maximum Number of Cross-reference Items|The number of cross-reference items to show in the cross-reference widget. Value 0 means no limit.|`number`|`1000`|[`SettingsUserScope`]|<a id='ui.maxXrefItems'>ui.maxXrefItems</a>| -|ui|Middle Click Navigation Action|Customize action on middle click (scroll wheel click) |`string`|`NewPane`|[`SettingsUserScope`]|<a id='ui.middleClickNavigationAction'>ui.middleClickNavigationAction</a>| -| | | 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|Shift + Middle Click Navigation Action|Customize action on shift + middle click (scroll wheel click) |`string`|`NewTab`|[`SettingsUserScope`]|<a id='ui.middleClickShiftNavigationAction'>ui.middleClickShiftNavigationAction</a>| -| | | 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|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>| -| | | enum: Left side for horizontal split, top side for vertical split.|`enum`|`topLeft`| | | -| | | enum: Right side for horizontal split, top side for vertical split.|`enum`|`topRight`| | | -| | | enum: Left side for horizontal split, bottom side for vertical split.|`enum`|`bottomLeft`| | | -| | | enum: Right side for horizontal split, bottom side for vertical split.|`enum`|`bottomRight`| | | -|ui|Default Split Direction|Default direction for splitting panes.|`string`|`horizontal`|[`SettingsUserScope`]|<a id='ui.panes.splitDirection'>ui.panes.splitDirection</a>| -| | | enum: Horizontal split (columns).|`enum`|`horizontal`| | | -| | | enum: Vertical split (rows).|`enum`|`vertical`| | | -|ui|Always Show Pane Options in Status Bar|Enable to always show options for the active pane in the status bar.|`boolean`|`False`|[`SettingsUserScope`]|<a id='ui.panes.statusBarOptions'>ui.panes.statusBarOptions</a>| -|ui|Sync Panes by Default|Sync current location between panes by default.|`boolean`|`True`|[`SettingsUserScope`]|<a id='ui.panes.sync'>ui.panes.sync</a>| -|ui|Recent Command Limit|Specify a limit for the recent command palette history.|`number`|`5`|[`SettingsUserScope`]|<a id='ui.recentCommandLimit'>ui.recentCommandLimit</a>| -|ui|Recent File Limit|Specify a limit for the recent file history in the new tab window.|`number`|`10`|[`SettingsUserScope`]|<a id='ui.recentFileLimit'>ui.recentFileLimit</a>| -|ui|Show Indentation Guides|Show indentation markers in linear high-level IL|`boolean`|`True`|[`SettingsUserScope`]|<a id='ui.renderIndentGuides'>ui.renderIndentGuides</a>| -|ui|Default Scripting Provider|Specify the registered ScriptingProvider for the default scripting console in the UI.|`string`|`Python`|[`SettingsUserScope`]|<a id='ui.scripting.defaultProvider'>ui.scripting.defaultProvider</a>| -| | | |`enum`|`Python`| | | -|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>| -| | | |`enum`|`None`| | | -| | | |`enum`|`Symbols`| | | -| | | |`enum`|`Types`| | | -| | | |`enum`|`Variables`| | | -| | | |`enum`|`Stack`| | | -| | | |`enum`|`Strings`| | | -| | | |`enum`|`Tags`| | | -|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`| | | -|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|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|Theme|Customize the appearance and style of Binary Ninja.|`string`|`Dark`|[`SettingsUserScope`]|<a id='ui.theme'>ui.theme</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>| -| | | |`enum`|`Disassembly`| | | -| | | |`enum`|`LowLevelIL`| | | -| | | |`enum`|`LiftedIL`| | | -| | | |`enum`|`LowLevelILSSAForm`| | | -| | | |`enum`|`MediumLevelIL`| | | -| | | |`enum`|`MediumLevelILSSAForm`| | | -| | | |`enum`|`MappedMediumLevelIL`| | | -| | | |`enum`|`MappedMediumLevelILSSAForm`| | | -| | | |`enum`|`HighLevelIL`| | | -| | | |`enum`|`HighLevelILSSAForm`| | | -| | | |`enum`|`PseudoC`| | | -|ui|Default IL for Graph View|Default IL for graph view on startup.|`string`|`Disassembly`|[`SettingsUserScope`]|<a id='ui.view.graph.il'>ui.view.graph.il</a>| -| | | |`enum`|`Disassembly`| | | -| | | |`enum`|`LowLevelIL`| | | -| | | |`enum`|`LiftedIL`| | | -| | | |`enum`|`LowLevelILSSAForm`| | | -| | | |`enum`|`MediumLevelIL`| | | -| | | |`enum`|`MediumLevelILSSAForm`| | | -| | | |`enum`|`MappedMediumLevelIL`| | | -| | | |`enum`|`MappedMediumLevelILSSAForm`| | | -| | | |`enum`|`HighLevelIL`| | | -| | | |`enum`|`HighLevelILSSAForm`| | | -| | | |`enum`|`PseudoC`| | | -|ui|Graph View Padding|Add extra space around graphs, proportional to the view's size.|`number`|`0.0`|[`SettingsProjectScope`, `SettingsUserScope`]|<a id='ui.view.graph.padding'>ui.view.graph.padding</a>| -|ui|Prefer Graph|Prefer graph view over linear view on startup.|`boolean`|`False`|[`SettingsUserScope`]|<a id='ui.view.graph.preferred'>ui.view.graph.preferred</a>| -|ui|Linear View IL Carousel|Specify the IL view types and order for use with the 'Cycle IL' actions in Linear view.|`array`|[`Disassembly`, `LowLevelIL`, `MediumLevelIL`, `HighLevelIL`]|[`SettingsUserScope`]|<a id='ui.view.linear.carousel'>ui.view.linear.carousel</a>| -| | | |`enum`|`Disassembly`| | | -| | | |`enum`|`LowLevelIL`| | | -| | | |`enum`|`LiftedIL`| | | -| | | |`enum`|`LowLevelILSSAForm`| | | -| | | |`enum`|`MediumLevelIL`| | | -| | | |`enum`|`MediumLevelILSSAForm`| | | -| | | |`enum`|`MappedMediumLevelIL`| | | -| | | |`enum`|`MappedMediumLevelILSSAForm`| | | -| | | |`enum`|`HighLevelIL`| | | -| | | |`enum`|`HighLevelILSSAForm`| | | -| | | |`enum`|`PseudoC`| | | -|ui|Linear View Gutter Width|Linear view gutter and tags width, in characters.|`number`|`5`|[`SettingsUserScope`]|<a id='ui.view.linear.gutterWidth'>ui.view.linear.gutterWidth</a>| -|ui|Default IL for Linear View|Default linear view type to display on startup.|`string`|`HighLevelIL`|[`SettingsUserScope`]|<a id='ui.view.linear.il'>ui.view.linear.il</a>| -| | | |`enum`|`Disassembly`| | | -| | | |`enum`|`LowLevelIL`| | | -| | | |`enum`|`LiftedIL`| | | -| | | |`enum`|`LowLevelILSSAForm`| | | -| | | |`enum`|`MediumLevelIL`| | | -| | | |`enum`|`MediumLevelILSSAForm`| | | -| | | |`enum`|`MappedMediumLevelIL`| | | -| | | |`enum`|`MappedMediumLevelILSSAForm`| | | -| | | |`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|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>| -|updates|Show All Versions|Show all versions that are available for the current update channel in the UI.|`boolean`|`False`|[`SettingsUserScope`]|<a id='updates.showAllVersions'>updates.showAllVersions</a>| -|user|Email|The email that will be shown when collaborating with other users.|`string`| |[`SettingsUserScope`]|<a id='user.email'>user.email</a>| -|user|Name|The name that will be shown when collaborating with other users.|`string`| |[`SettingsUserScope`]|<a id='user.name'>user.name</a>| -|workflows|Workflows Analysis Orchestration Framework|Enable the analysis orchestration framework. This feature is currently under active development.|`boolean`|`False`|[`SettingsProjectScope`, `SettingsResourceScope`, `SettingsUserScope`]|<a id='workflows.enable'>workflows.enable</a>| -|workflows|Workflows Example Plugins|Enable the built-in example plugins.|`boolean`|`False`|[`SettingsUserScope`]|<a id='workflows.examples'>workflows.examples</a>| -|workflows|Function Workflow|Workflow selection for function-based analysis.|`string`|`core.function.defaultAnalysis`|[`SettingsProjectScope`, `SettingsResourceScope`, `SettingsUserScope`]|<a id='workflows.functionWorkflow'>workflows.functionWorkflow</a>| -| | | |`enum`|`core.function.defaultAnalysis`| | | -|workflows|Module Workflow|Workflow selection for module-based analysis. Note: Module-based workflows incomplete.|`string`|`core.module.defaultAnalysis`|[`SettingsProjectScope`, `SettingsResourceScope`, `SettingsUserScope`]|<a id='workflows.moduleWorkflow'>workflows.moduleWorkflow</a>| -| | | |`enum`|`core.module.defaultAnalysis`| | | +For more detailed information, see the [debugger guide](/guide/debugger.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. - -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 -!!! Tip "Note" - If you have any trouble with the self-updater, you can always [request](https://binary.ninja/recover/) a fresh set of download links as long as you are under active support. - -### 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. - -<!-- ## Unicode Support - -Currently, Unicode support for Big Endian strings is very limited. Also, UTF-16 only supports Basic Latin code points. --> +While Binary Ninja automatically updates itself, by default you will only use the Stable Branch and you can check out features much faster on the development branch using the [update channel](guide/#updates) dialog. -## Getting Support +## What's next? -Vector 35 offers a number of ways to receive [support](https://binary.ninja/support/). +- Consider writing your first [plugin](/dev/) +- Watch our [Binary Ninja Basics](https://www.youtube.com/watch?v=xKBQatwshs0&list=PLCVV6Y9LmwOgqqT5obf0OmN9fp5495bLr) videos +- Read the rest of the more detailed [User Manual](/guide/)
\ No newline at end of file diff --git a/docs/guide/index.md b/docs/guide/index.md new file mode 100644 index 00000000..e52bf5e4 --- /dev/null +++ b/docs/guide/index.md @@ -0,0 +1,649 @@ +# User Manual + +Welcome to the Binary Ninja User Manual. You'll notice two menus here, on the left are links to subsections that have grown so large they are split out into their own sections. On the right is the table of contents for the user manual. Major sections on their own page include: + +- [Plugins](plugins.md) +- [Settings](settings.md) +- [Types](type.md) +- [Debugger](debugger.md) +- [Objective C](objectivec.md) +- [Troubleshooting](troubleshooting.md) + +## Directories + +Binary Ninja stores information in two primary locations. The first is the binary path (wherever Binary Ninja is installed) and the second is the user folder for user-installed content. + +### Binary Path + +Binaries are installed in the following locations by default: + +- macOS: `/Applications/Binary Ninja.app` +- Windows (global install): `C:\Program Files\Vector35\BinaryNinja` +- Windows (user install): `%LOCALAPPDATA%\Vector35\BinaryNinja` +- Linux: Wherever you extract it! (No standard location) + +???+ 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. + +### User Folder + +User folders are: + +- macOS: `~/Library/Application Support/Binary Ninja` +- Linux: `~/.binaryninja` +- Windows: `%APPDATA%\Binary Ninja` + +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 +- `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) +- `settings.json`: User settings file (see [settings](settings.md)) + +The following files and folders may be created in the user folder but are not created by default without some additional action: +- `keybindings.json`: Custom key bindings (see [key bindings](#custom-hotkeys)) +- `startup.py`: Default python commands run once the UI is loaded in the context of the scripting console +- `signatures/`: Any user-signatures can be stored in this location which is not created by default +- `pythonVER/`: Any pip dependencies from plugin manager plugins are installed to the appropriate python version subfolder such as `python310` +- `symbols/`: Store PDBs downloaded +- `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 +- `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 + + + +### QSettings Locations + +Some settings such as window locations, saved checkboxes, recent file lists, disassembly settings, dialog histories. + +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-5/qsettings.html#platform-specific-notes). + +## License + +When you first run Binary Ninja, it will prompt you for your license key. You should have received your license key via email after your purchase. If not, please contact [support](https://binary.ninja/support). + +Once the license key is installed, you can change it, back it up, or otherwise inspect it simply by looking inside the base of the user folder for `license.dat`. + +## Linux Setup + +Because Linux install locations can vary widely, we do not assume that Binary Ninja has been installed in any particular folder on Linux. Rather, you can simply run `binaryninja/scripts/linux-setup.sh` after extracting the zip and various file associations, icons, and other settings will be set up. Run it with `-h` to see the customization options. + +## Loading Files + +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`) +3. Use the `File/Open with Options` menu which allows you to customize the analysis options (`[CMD/CTRL-SHIFT] o`) +4. Open a file from the Triage picker (`File/Open for Triage`) which enables several minimal analysis options and shows a summary view first +5. Click an item in the recent files list (hold `[CMD/CTRL-SHIFT]` while clicking to use the `Open with Options` workflow) +6. Press the number key associated with an item from the recent files list (0-9, where 0 represents file 10 on the recent list, optionally holding `[CMD/CTRL-SHIFT]` to use the `Open with Options` workflow) +7. Run Binary Ninja with an optional command-line parameter +8. Open a file from a URL via the `[CMD/CTRL] l` hotkey +9. Open a file using the `binaryninja:` URL handler. For security reasons, the URL handler requires you to confirm a warning before opening a file via the URL handler. URLs additionally support deep linking using the `expr` query parameter where expression value is a valid parsable expression such as those possible in the [navigation dialog](#navigating), and fully documented in the [`parse_expression`](https://api.binary.ninja/binaryninja.binaryview-module.html?highlight=parse_expression#binaryninja.binaryview.BinaryView.parse_expression) API. Below a few examples are provided: + * URLs For referencing files on the local file system. + * `binaryninja:///bin/ls?expr=sub_2830` - open the given file and navigate to the function: `sub_2830` + * `binaryninja:///bin/ls?expr=.text` - open the given file and navigate to the start address of the `.text` section + * `binaryninja:///bin/ls?expr=.text+6b` - open the given file and navigate to the hexadecimal offset `6b` from the `.text` section. + * URLs For referencing remote file files either the URL should be prefixed with `binaryninja:` and optionally suffixed with the `expr` query parameter + * `binaryninja:file://<remote_path>?expr=[.data + 400]` - Download the remote file and navigate to the address at `.data` plus `0x400` + +## Saving Files + + + +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: + +1. "Save" - This menu is the only one bound to a hotkey by default and it is intended to be the "do what I probably want" option. + - If you have edited the contents of a file and have not yet confirmed the file name to save over, this will ask you to save the file contents and prompt for a file name (check the save dialog title text to confirm this). + - If you have edited the file contents and _have_ previously specified the file name, this option will save those changes to that file without a prompt. + - If you have not edited the contents of the file but have added any analysis information (created functinos, comments, changed names types, etc), you will be asked for the name of the `.bndb` analysis database if one does not already exist. + - If an existing analysis database does exist and is in use, the existing database will be saved without a prompt. + - Finally, if you have changed both file contents and analysis information, you'll be prompted as to which you wish to save. + +2. "Save As" - Will prompt to save the analysis database or just the file contents. + - 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. + +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. + + <!-- this image is getting floated down into the next section --> + +## Status Bar + + <!-- this image needs updating to reflect new status bar --> + +The status bar provides current information about the open file as well as some interactive controls. Summary features are listed below: + +* Update Notification - perform updates, download status, and restart notification +* Analysis progress - ongoing analysis progress of current active file +* Cursor offset or selection +* File Contents Lock - interactive control to prevent accidental changes to the underlying file + +## Analysis + +As soon as you open a file, Binary Ninja begins its auto-analysis which is fairly similar to decompiling the entire binary. + +Even while Binary Ninja is analyzing a binary, the UI should be responsive. Not only that, but because the analysis prioritizes user-requested analysis, you can start navigating a binary immediately and wherever you are viewing will be prioritized for analysis. The current progress through a binary is shown in the status bar (more details are available via `bv.analysis_info` in the Python console), but note that the total number of items left to analyze will go up as well as the binary is processed and more items are discovered that require analysis. + +Analysis proceeds through several phases summarized below: + +* Phase 1 - Initial Recursive Descent +* Phase 2 - Call Target Analysis (Part of Linear Sweep) +* Phase 3.x - Control Flow Graph Analysis (Part of Linear Sweep) + +Errors or warnings during the load of the binary are also shown in the status bar, each with an appropriate icon. The most common warnings are from incomplete lifting and can be safely ignored. If the warnings include a message like `Data flow for function at 0x41414141 did not terminate`, then please report the binary to the [bug database](https://github.com/Vector35/binaryninja-api/issues). + +### Analysis Speed + +If you wish to speed up analysis, you have several options. The first is to use the `File/Open for Triage` menu which activates the Triage file picker. By default, [Triage mode](https://binary.ninja/2019/04/01/hackathon-2019-summary.html#triage-mode-rusty) will enable a faster set of default analysis options that doesn't provide as much in-depth analysis but is significantly faster. + +Additionally, using the [open with options](#loading-files) feature allows for customization of a number of analysis options on a per-binary basis. See [all settings](settings.md#all-settings) under the `analysis` category for more details. + +## Interacting + +### 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). + +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. + +### The Sidebar + + + +Once you have a file open, the sidebar lets you quickly access the most common features and keeps them available while you work, including: +- 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 + +### Tiling Panes + + + +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. + +### Feature Map + + + +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 dark-theme: + +- <span style="background-color: rgb(128, 198, 233); color: rgb(128, 198, 233);"> </span> Blue represents code in functions +- <span style="background-color: rgb(237, 189, 129); color: rgb(237, 189, 129);"> </span> Orange represents imports and externs +- <span style="background-color: rgb(162, 217, 175); color: rgb(162, 217, 175);"> </span> Green represents ASCII strings +- <span style="background-color: rgb(222, 143, 151); color: rgb(222, 143, 151);"> </span> Red represents Unicode strings +- <span style="background-color: rgb(144, 144, 144); color: rgb(144, 144, 144);"> </span> Grey represents data variables +- <span style="background-color: rgb(0, 0, 0); color: rgb(0, 0, 0);"> </span> Black is the base color when nothing else exists there + +### Switching Views + <!-- this image needs updating to the pane header --> + +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. + +### Command Palette + + + +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. + +### Custom Hotkeys + + + +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. + +The settings themselves are saved directly in the `keybindings.json` file in your [user folder](#user-folder). + +???+ Warning "Tip" + To search in the keybindings list, just click to make sure it's focused and start typing! + +???+ Warning "Tip" + On macOS, within the `keybindings.json`, `Ctrl` refers to the Command key, while `Meta` refers to the Option key. This is a remapping performed by Qt to make cross-platform keybindings easier to define. + +### Default Hotkeys + + - `h` : Switch to hex view + - `p` : Create a function + - `[ESC]` : Navigate backward + - `[CMD] [` (macOS) : Navigate backward + - `[CMD] ]` (macOS) : Navigate forward + - `[CTRL] [` (Windows/Linux) : Navigate backward + - `[CTRL] ]` (Windows/Linux) : Navigate forward + - `[SPACE]` : Toggle between linear view and graph view + - `[F5]`, `[TAB]` : Toggle between decompilation (HLIL) and disassembly view + - `g` : Go To Address dialog + - `n` : Name a symbol + - `u` : Undefine an existing symbol (only for removing new user-defined names) + - `e` : Edit an instruction (by modifying the original binary -- currently only enabled for x86, and x64) + - `x` : Focus the cross-reference pane + - `;` : Add a comment + - `i` : Cycle between disassembly, LLIL, MLIL and HLIL + - `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 + - `1`, `2`, `4`, `8` : Change type directly to a data variable of the indicated widths + - `d` : Switch between data variables of various widths + - `r` : Change the data type to single ASCII character + - `o` : Create a pointer data type + - `[CMD-SHIFT] +` (macOS) : Graph view zoom in + - `[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 in the [type guide](type.md#direct-ui-manipulation) + +### Graph View + + + +Binary Ninja offers a graph view that groups the basic blocks of disassembly into visually distinct blocks with edges showing control flow between them. + +Features of the graph view include: + +- Ability to double click edges to quickly jump between locations +- Zoom (CTRL-mouse wheel) +- Zoom to Fit - Zooms out until the whole graph is visible (`w`) +- Zoom to Cursor - Zooms to 100% at the position of the cursor (`z`) +- Vertical Scrolling (Side scroll bar as well as mouse wheel) +- Horizontal Scrolling (Bottom scroll bar as well as SHIFT-mouse wheel) +- Individual highlighting of arguments, addresses, immediate values, types, etc. +- Full type signature of current function shown in an interactive header: + - Selecting elements in the header highlights them in the graph view + - Change type (`y`) and Rename (`n`) shortcuts work on elements in the header + - Reanalyze function button on left edge of the header +- Edge colors indicate whether the path is the true (green) or false (red) case of a conditional jump (a color-blind option in the preferences is useful for those with red-green color blindness) and blue for unconditional branches +- Context menu that can trigger some function-wide actions as well as some specific to the highlighted instruction (such as inverting branch logic or replacing a specific function with a NOP) + + +### View Options + + + +Each of the views (Hex, Graph, Linear) have a variety of options configurable from the ☰ menu on the top right of the view pane. + +Current options include: + +- Hex + - Background highlight + - None + - Column + - Byte value + - Color highlight + - None + - ASCII and printable + - Modification + - Contrast + - Normal + - Medium + - Highlight +- Graph & Linear Views + - Expand long opcode + - Show address + - Show call parameter names (MLIL only) + - Show function address + - Show opcode bytes + - Show register set highlighting + - Show variable types + - At assignment (MLIL only) + - At top of function + - Assembly + - Low Level IL + - Show Stack Pointer Value + - Medium Level IL + - High Level IL + - Pseudo C + - Advanced IL Forms + - Lifted IL + - Show IL Flag Usage + - Low Level IL (SSA Form) + - Medium Level IL (Mapped) + - Medium Level IL (Mapped, SSA Form) + - Medium Level IL (SSA Form) + - High Level IL (SSA Form) + + +### Hex View + + + +The hexadecimal view is useful for viewing raw binary files that may or may not even be executable binaries and allows direct editing of the binary contents in place, regardless of the type of the binary. Any changes made in hex view will be reflected in all other [open views](#tiling-panes) of the same binary. The lock button on the right edge of the bottom status bar must be toggled off (🔓) to perform any direct editing in hex view -- this is to prevent unintended modification of the binary by accidental pasting or typing. + +The hex view is particularly good for transforming data in various ways via the `Copy as`, `Transform`, and `Paste from` menus. Note that like any other edits, `Transform` menu options will transform the data in-place, but unlike other means of editing the binary, the transformation dialog will work even when the lock button is toggled on (🔒). + +???+ 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. + +#### Template Simplifier + +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"/> +</div> + +#### 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 + + + +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 most 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 in Binary Ninja shows the list of symbols for functions and/or data variables currently identified. As large binaries are analyzed, the list may grow during analysis. The symbols list starts with known functions and data variables such as the entry point, exports, or using other features of the binary file format and explores from there to identify other functions and data variables. + +The symbols list highlights symbols according to whether they are functions or data variables, local or exported, or imported. All of these kinds of symbols can be toggled from the ☰ menu at the top right of the Symbols pane. + +???+ 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". + +### 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 + + + +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: + +1. **Function prototype.** The function’s prototype. If the prototype is too long to fit inside the window, a scroll bar will appear. +1. **Function info.** A list of conditionally-shown tags offering information about the function. Possible tags are as follows: + - **Function architecture/platform**: The function's architecture/platform (e.g. `windows-x86_64`) + - **Analysis skipped (too large)**: Analysis was skipped for this function because it was too large ([`analysis.limits.maxFunctionSize`](settings.md#analysis.limits.maxFunctionSize)) + - **Analysis timed out**: Analysis for this function was skipped because it exceeded the maximum allowed time ([`analysis.limits.maxFunctionAnalysisTime`](settings.md#analysis.limits.maxFunctionAnalysisTime)) + - **Analysis was skipped (too many updates)**: Analysis was skipped for this function because it caused too many updates ([`analysis.limits.maxFunctionUpdateCount`](settings.md#analysis.limits.maxFunctionUpdateCount)) + - **Analysis suppressed**: Analysis was suppressed for this function because analysis of auto-discovered functions was disabled ([`analysis.suppressNewAutoFunctionAnalysis`](settings.md#analysis.suppressNewAutoFunctionAnalysis)) + - **Basic analysis only**: This function only received basis analysis ([`analysis.mode`](settings.md#analysis.mode) was 'basic') + - **Intermediate analysis only**: This function only received intermediate analysis ([`analysis.mode`](settings.md#analysis.mode) was 'intermediate') + - **Unresolved stack usage**: The function has unresolved stack usage + - **GP = 0xABCD1234**: The global pointer value is 0xABCD1234 +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.** Does this function return? If not, #8 will be unavailable. +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. +1. **Register stack adjustments.** A table containing a row for each register stack (e.g. x87) in the architecture, with the ability to adjust how many registers are removed from each stack when the function returns. + +<!-- These same points need to be made about Panes, but also a lot more +### Reflection View + +- View BNILs and assembly for the same file side-by-side + + + +- Settings to control the synchronization behavior + + + +- Right Click the Function Header for quick access to synchronization mode changes + + + +- Reflection currently presents in graph view only + +- When main view is linear, Mini Graph renders the Reflection View +--> + +### High Level IL + + + +Binary Ninja features a decompiler that produces High Level IL (HLIL) as output. HLIL is not intended to be a representation of the code in C, but some users prefer to have a more C-like scoping style. + +You can control the way HLIL appears in the settings. + +The different options are shown below: + + + +### Pseudo C + + + +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: + + + +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. + + + +Performing this action on both variables in the example results in the following output: + + + +### Script (Python) Console + + + +The integrated script console is useful for small scripts that aren't worth writing as full plugins. + +To trigger the console, either use `<BACKTICK>`, or use the `View`/`Python Console` menu. + +???+ 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. + + + +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. + +Multi-line input is possible just by doing what you'd normally do in python. If you leave a trailing `:` at the end of a line, the box will automatically turn into a multi-line edit box, complete with a command-history. To submit that multi-line input, use `<CTRL>-<ENTER>`. You can also force multi-line input with `<SHIFT>-<ENTER>`. + +The scripting console is not a full IDE, but it has several convenience features that make it more pleasant to use: + +- `<TAB>` offers completion of variables, methods, anything in-scope +- `<CTRL>-R` allows for reverse-searching your console history +- `<UP>` and `<DOWN>` can be used to view the command-history + +The interactive python prompt also has several built-in functions and variables: + +- `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_file_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) +- `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_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) + +#### startup.py + +The python interpreter can be customized to run scripts on startup using `startup.py` in your user folder. Simply enter commands into that file, and they will be executed every time Binary Ninja starts. By default, it comes with an import helper: + + # Commands in this file will be run in the interactive python console on startup + from binaryninja import * + +From here, you can add any custom functions or objects you want to be available in the console. If you want to restore the original copy of `startup.py` at any time, simply delete the file and restart Binary Ninja. A fresh copy of the above will be generated. + +#### "Run Script..." + +The "Run Script..." option in the File Menu allows loading a python script from your filesystem and executing it +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 +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 +defined within the console, but within the script, it will be set to the absolute path of the script. + +Any variables or functions defined globally within the script will be available within the console, and to future scripts. + +#### Python Debugging +See the [plugin development guide](/dev/plugins.md#debugging-python). + +Note +???+ Warning "Tip" + The current script console only supports Python at the moment, but it's fully extensible for other programming languages for advanced users who wish to implement their own bindings. + +## Using Plugins + +Plugins can be installed by one of two methods. First, 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: + +- macOS: `~/Library/Application Support/Binary Ninja/plugins/` +- Linux: `~/.binaryninja/plugins/` +- Windows: `%APPDATA%\Binary Ninja\plugins` + +Alternatively, plugins can be installed with the new [pluginmanager](https://api.binary.ninja/binaryninja.pluginmanager-module.html) API. + +For more detailed information on plugins, see the [plugin guide](plugins.md). + +## PDB Plugin + +Binary Ninja supports loading PDB files through a built in PDB loader. When selected from the plugin menu it attempts to find the corresponding PDB file using the following search order: + +1. Look in the same directory as the opened file/bndb (e.g. If you have `c:\foo.exe` or `c:\foo.bndb` open the PDB plugin looks for `c:\foo.pdb`) +2. Look in the local symbol store. This is the directory specified by the settings: `local-store-relative` or `local-store-absolute`. The format of this directory is `foo.pdb\<guid>\foo.pdb`. +3. Attempt to connect and download the PDB from the list of symbol servers specified in setting `symbol-server-list`. +4. Prompt the user for the PDB. + +## Debugger + +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). + +## 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. + +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" + If you have any trouble with the self-updater, you can always [request](https://binary.ninja/recover/) a fresh set of download links as long as you are under active support. + +### 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. + + +## Support + +To contact Vector 35 for support, we recommend the following methods: + + - [Public Slack](https://slack.binary.ninja/) + - Vector 35 offers a number of ways to receive [support](https://binary.ninja/support/). diff --git a/docs/guide/plugins.md b/docs/guide/plugins.md index d98f6011..dc804d2e 100644 --- a/docs/guide/plugins.md +++ b/docs/guide/plugins.md @@ -2,13 +2,13 @@ The most common Binary Ninja plugins are Python which we are covering here. That said, there are some C++ plugins which must be built for the appropriate native architecture and will usually include build instructions for each platform. Several [C++ examples](https://github.com/Vector35/binaryninja-api/tree/dev/examples) are included in the API repository, and the [binexport](https://github.com/google/binexport) utility (used with [bindiff](https://www.zynamics.com/bindiff.html)) is also a native plugin that must be built and installed manually. -Plugins are loaded from the user's plugin folder: +Plugins are loaded from the user's plugin folder: - macOS: `~/Library/Application Support/Binary Ninja/plugins/` - Linux: `~/.binaryninja/plugins/` - Windows: `%APPDATA%\Binary Ninja\plugins` -Note that plugins installed via the [PluginManager API](https://api.binary.ninja/binaryninja.pluginmanager-module.html) are installed in the `repositories` folder in the same path as the previous `plugin` folder listed above. You should not need to manually adjust anything in that folder, but should access them via the API instead. +Note that plugins installed via the [PluginManager API](https://api.binary.ninja/binaryninja.pluginmanager-module.html) are installed in the `repositories` folder in the same path as the previous `plugin` folder listed above. You should not need to manually adjust anything in that folder, but should access them via the API instead. ## Plugin Manager @@ -29,7 +29,7 @@ Plugins can now be installed directly via the GUI from Binary Ninja. You can lau - (Linux/Windows) `[CTRL-P]` / `Plugin Manager` / `[ENTER]` - (macOS) `[CMD-P]` / `Plugin Manager` / `[ENTER]` -Note that some plugins may show `Force Install` instead of the normal `Install` button. If that's the case, it means the plugin does not specifically advertise support for your platform or version of python. Often times the plugin will still work, but you must override a warning to confirm installation and be aware that the plugin may not be compatible. +Note that some plugins may show `Force Install` instead of the normal `Install` button. If that's the case, it means the plugin does not specifically advertise support for your platform or version of python. Often times the plugin will still work, but you must override a warning to confirm installation and be aware that the plugin may not be compatible. ### Plugin Manager Searching @@ -57,7 +57,7 @@ Note, if manually cloning the [api repository](https://github.com/Vector35/binar git submodule update --init --recursive ``` -after cloning or else the submodules will not actually be downloaded. +after cloning or else the submodules will not actually be downloaded. ### Installing via the API @@ -90,7 +90,7 @@ Binary Ninja can now automatically install pip requirements for python plugins w Because Windows and macOS ship with an embedded version of Python, if you want to install plugins inside that Python, we recommend instead installing an official [python.org](https://www.python.org/downloads/windows/) (NOTE: ensure you do not accidentally install a 32-bit build) version, or a [homebrew](https://docs.brew.sh/Homebrew-and-Python) Python 3.x build. -Then you can adjust your [python.interpreter setting](../getting-started.md#python.interpreter) to point to the appropriate install location. Note that the file being pointed to should be a `.dll` or `.dylib` though homebrew will often install libraries without any extension. For example: +Then you can adjust your [python.interpreter setting](settings.md#python.interpreter) to point to the appropriate install location. Note that the file being pointed to should be a `.dll` or `.dylib` though homebrew will often install libraries without any extension. For example: ``` $ file /usr/local/Cellar/python@3.8/3.8.5/Frameworks/Python.framework/Versions/3.8/Python @@ -105,10 +105,10 @@ Troubleshooting many Binary Ninja problems is enhanced by enabling debug logs an /Applications/Binary\ Ninja.app/Contents/macOS/binaryninja -d -l /tmp/bnlog.txt ``` -And check `/tmp/bnlog.txt` when you're done. +And check `/tmp/bnlog.txt` when you're done. Additionally, running a python plugin with an environment variable of `BN_DISABLE_USER_PLUGINS` will prevent the API from initializing user-plugins which is helpful for identifying when a plugin is causing problems. Furthermore, by setting `BN_USER_DIRECTORY` you can override your 'user' directory where all your settings and plugins are loaded. ## Writing Plugins -See the [developer documentation](../dev/api.md) for documentation on creating plugins. +See the [developer documentation](../dev/) for documentation on creating plugins. diff --git a/docs/guide/settings.md b/docs/guide/settings.md new file mode 100644 index 00000000..9071ec41 --- /dev/null +++ b/docs/guide/settings.md @@ -0,0 +1,365 @@ +# Settings + +## UI + + + +Binary Ninja provides various settings which are available via the `[CMD/CTRL] ,` hotkey. These settings allow a wide variety of customization of the user interface and functional aspects of the analysis environment. + +Several search keywords are available in the settings UI. Those include: + +- `@default` - Shows settings that are in the default scope +- `@user` - Shows only settings that the user has changed +- `@project` - Shows settings scoped to the current project +- `@resource` - Shows settings scoped to the current resource (for example if you used open-with-options and changed settings) +- `@modified` - Shows settings that are changed from their default values + +There are several scopes available for settings: + +* **User Settings** - Settings that apply globally and override the defaults. These settings are stored in `settings.json` within the [User Folder](./#user-folder). +* **Project Settings** - Settings which only apply if a project is opened. These settings are stored in `.binaryninja/settings.json` within a Project Folder. Project Folders can exist anywhere except within the User Folder. These settings apply to all files contained in the Project Folder and override the default and user settings. In order to activate this feature, select the Project Settings tab and a clickable "Open Project" link will appear at the top right of the view. Clicking this will create `.binaryninja/settings.json` in the folder of the currently selected binary view. If it already exists, this link will be replaced with the path of the project folder. +* **Resource Settings** - Settings which only apply to a specific BinaryView object within a file. These settings persist in a Binary Ninja Database (.bndb) database or ephemerally in a BinaryView object if a database does not yet exist for a file. + +???+ Warning "Tip" + Both the _Project_ and _Resource_ tabs have a drop down indicator (▾) that can be clicked to select the project or resource whose settings you want to adjust. + +All settings are uniquely identified with an identifier string. Identifiers are available in the settings UI via the context menu and are useful for find settings using the search box and for [programmatically](https://api.binary.ninja/binaryninja.settings-module.html) interacting with settings. + +**Note**: In order to facilitate reproducible analysis results, when opening a file for the first time, all of the analysis settings are automatically serialized into the _Resource Setting_ scope. This prevents subsequent _User_ and _Project_ setting modifications from unintentionally changing existing analysis results. + +## All Settings +|Category|Setting|Description|Type|Default|Scope|Key| +|---|---|---|---|---|---|---| +|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|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|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 Manged 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.extractTypesFromMangedNames'>analysis.extractTypesFromMangedNames</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|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|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|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|Switch Case Node Threshold|High Level IL tuning parameter.|`number`|`4`|[`SettingsProjectScope`, `SettingsResourceScope`, `SettingsUserScope`]|<a id='analysis.hlil.switchCaseNodeThreshold'>analysis.hlil.switchCaseNodeThreshold</a>| +|analysis|Switch Case Value Count Threshold|High Level IL tuning parameter.|`number`|`6`|[`SettingsProjectScope`, `SettingsResourceScope`, `SettingsUserScope`]|<a id='analysis.hlil.switchCaseValueCountThreshold'>analysis.hlil.switchCaseValueCountThreshold</a>| +|analysis|Target Max Condition Complexity|High Level IL tuning parameter.|`number`|`16`|[`SettingsProjectScope`, `SettingsResourceScope`, `SettingsUserScope`]|<a id='analysis.hlil.targetMaxConditionComplexity'>analysis.hlil.targetMaxConditionComplexity</a>| +|analysis|Initial Analysis Hold|Enabling the analysis hold discards all future analysis updates until clearing the hold. This setting only applies to analysis in the InitialState.|`boolean`|`False`|[`SettingsProjectScope`, `SettingsResourceScope`, `SettingsUserScope`]|<a id='analysis.initialAnalysisHold'>analysis.initialAnalysisHold</a>| +|analysis|Advanced Analysis Cache Size|Controls the number of functions for which the most recent generated advanced analysis is cached. Large values may result in very high memory utilization.|`number`|`64`|[`SettingsProjectScope`, `SettingsResourceScope`, `SettingsUserScope`]|<a id='analysis.limits.cacheSize'>analysis.limits.cacheSize</a>| +|analysis|Max Function Analysis Time|Any functions that exceed this analysis time are deferred. A value of 0 disables this feature. The default value is 20 seconds. Time is specified in milliseconds.|`number`|`20000`|[`SettingsProjectScope`, `SettingsResourceScope`, `SettingsUserScope`]|<a id='analysis.limits.maxFunctionAnalysisTime'>analysis.limits.maxFunctionAnalysisTime</a>| +|analysis|Max Function Size|Any functions over this size will not be automatically analyzed. A value of 0 disables analysis of functions and suppresses the related log warning. To override see FunctionAnalysisSkipOverride. Size is specified in bytes.|`number`|`65536`|[`SettingsProjectScope`, `SettingsResourceScope`, `SettingsUserScope`]|<a id='analysis.limits.maxFunctionSize'>analysis.limits.maxFunctionSize</a>| +|analysis|Max Function Update Count|Any functions that exceed this incremental update count are deferred. A value of 0 disables this feature.|`number`|`100`|[`SettingsProjectScope`, `SettingsResourceScope`, `SettingsUserScope`]|<a id='analysis.limits.maxFunctionUpdateCount'>analysis.limits.maxFunctionUpdateCount</a>| +|analysis|Max Lookup Table Size|Limits the maximum number of entries for a lookup table.|`number`|`4095`|[`SettingsProjectScope`, `SettingsResourceScope`, `SettingsUserScope`]|<a id='analysis.limits.maxLookupTableSize'>analysis.limits.maxLookupTableSize</a>| +|analysis|Minimum String Length|The minimum length for strings created during auto-analysis|`number`|`4`|[`SettingsProjectScope`, `SettingsResourceScope`, `SettingsUserScope`]|<a id='analysis.limits.minStringLength'>analysis.limits.minStringLength</a>| +|analysis|Maximum String Search|Maximum number of strings to find before giving up.|`number`|`1048576`|[`SettingsProjectScope`, `SettingsResourceScope`, `SettingsUserScope`]|<a id='analysis.limits.stringSearch'>analysis.limits.stringSearch</a>| +|analysis|Worker Thread Count|The number of worker threads available for concurrent analysis activities.|`number`|`9`|[`SettingsProjectScope`, `SettingsResourceScope`, `SettingsUserScope`]|<a id='analysis.limits.workerThreadCount'>analysis.limits.workerThreadCount</a>| +|analysis|Autorun Linear Sweep|Automatically run linear sweep when opening a binary for analysis.|`boolean`|`True`|[`SettingsProjectScope`, `SettingsResourceScope`, `SettingsUserScope`]|<a id='analysis.linearSweep.autorun'>analysis.linearSweep.autorun</a>| +|analysis|Control Flow Graph Analysis|Enable the control flow graph analysis (Analysis Phase 3) portion of linear sweep.|`boolean`|`True`|[`SettingsProjectScope`, `SettingsResourceScope`, `SettingsUserScope`]|<a id='analysis.linearSweep.controlFlowGraph'>analysis.linearSweep.controlFlowGraph</a>| +|analysis|Detailed Linear Sweep Log Information|Linear sweep generates additional log information at the InfoLog level.|`boolean`|`False`|[`SettingsProjectScope`, `SettingsResourceScope`, `SettingsUserScope`]|<a id='analysis.linearSweep.detailedLogInfo'>analysis.linearSweep.detailedLogInfo</a>| +|analysis|Entropy Heuristics for Linear Sweep|Enable the application of entropy based heuristics to the function search space for linear sweep.|`boolean`|`True`|[`SettingsProjectScope`, `SettingsResourceScope`, `SettingsUserScope`]|<a id='analysis.linearSweep.entropyHeuristics'>analysis.linearSweep.entropyHeuristics</a>| +|analysis|High Entropy Threshold for Linear Sweep|Regions in the binary at or above this threshold are not included in the search space for linear sweep.|`number`|`0.82`|[`SettingsProjectScope`, `SettingsResourceScope`, `SettingsUserScope`]|<a id='analysis.linearSweep.entropyThresholdHigh'>analysis.linearSweep.entropyThresholdHigh</a>| +|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|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`| | | +| | | enum: Split oversized accesses to valid fields and include accessed gaps/alignment/padding bytes|`enum`|`allOffsets`| | | +|analysis|Analysis Mode|Controls the amount of analysis performed on functions.|`string`|`full`|[`SettingsProjectScope`, `SettingsResourceScope`, `SettingsUserScope`]|<a id='analysis.mode'>analysis.mode</a>| +| | | enum: Only perform control flow analysis on the binary. Cross references are valid only for direct function calls. [Disassembly Only]|`enum`|`controlFlow`| | | +| | | enum: Perform fast initial analysis of the binary. This mode does not analyze types or data flow through stack variables. [LLIL and Equivalents]|`enum`|`basic`| | | +| | | enum: Perform analysis which includes type propagation and data flow. [MLIL and Equivalents]|`enum`|`intermediate`| | | +| | | enum: Perform full analysis of the binary.|`enum`|`full`| | | +|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|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`|`CoreTypeParser`| | | +| | | |`enum`|`ClangTypeParser`| | | +|analysis|Type Printer|Specify the implementation used for formatting types into text.|`string`|`CoreTypePrinter`|[`SettingsProjectScope`, `SettingsResourceScope`, `SettingsUserScope`]|<a id='analysis.types.printerName'>analysis.types.printerName</a>| +| | | |`enum`|`CoreTypePrinter`| | | +|analysis|Simplify Templates|Simplify common C++ templates that are expanded with default arguments at compile time (eg. `std::__cxx11::basic_string<wchar, std::char_traits<wchar>, std::allocator<wchar> >` to `std::wstring`).|`boolean`|`True`|[`SettingsProjectScope`, `SettingsResourceScope`, `SettingsUserScope`]|<a id='analysis.types.templateSimplifier'>analysis.types.templateSimplifier</a>| +|analysis|Unicode Blocks|Defines which unicode blocks to consider when searching for strings.|`array`|[]|[`SettingsProjectScope`, `SettingsResourceScope`, `SettingsUserScope`]|<a id='analysis.unicode.blocks'>analysis.unicode.blocks</a>| +|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|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>| +| | | enum: Sets the disassembly syntax to a simplified Intel format. (TBD) |`enum`|`BN_INTEL`| | | +| | | enum: Sets the disassembly syntax to Intel format. (Destination on the left) |`enum`|`INTEL`| | | +| | | enum: Sets the disassembly syntax to AT&T format. (Destination on the right) |`enum`|`AT&T`| | | +|corePlugins|Aarch64 Architecture|Enable the built-in Aarch64 architecture module.|`boolean`|`True`|[`SettingsUserScope`]|<a id='corePlugins.architectures.aarch64'>corePlugins.architectures.aarch64</a>| +|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|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|Debugger|Enable the built-in debugger plugin.|`boolean`|`True`|[`SettingsUserScope`]|<a id='corePlugins.debugger'>corePlugins.debugger</a>| +|corePlugins|IDB Import Plugin (Beta)|Enable the built-in IDB import plugin.|`boolean`|`True`|[`SettingsUserScope`]|<a id='corePlugins.idbImport'>corePlugins.idbImport</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|FreeBSD Platform|Enable the built-in FreeBSD platform module.|`boolean`|`True`|[`SettingsUserScope`]|<a id='corePlugins.platforms.freebsd'>corePlugins.platforms.freebsd</a>| +|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|Triage Plugin|Enable the built-in triage plugin.|`boolean`|`True`|[`SettingsUserScope`]|<a id='corePlugins.triage'>corePlugins.triage</a>| +|corePlugins|Objective-C|Enable the built-in Objective-C plugin.|`boolean`|`True`|[`SettingsUserScope`]|<a id='corePlugins.workflows.objc'>corePlugins.workflows.objc</a>| +|debugger|Stop At Entry Point|Stop the target at program entry point|`boolean`|`True`|[`SettingsUserScope`]|<a id='debugger.stopAtEntryPoint'>debugger.stopAtEntryPoint</a>| +|debugger|Stop At System Entry Point|Stop the target at system entry point|`boolean`|`False`|[`SettingsUserScope`]|<a id='debugger.stopAtSystemEntryPoint'>debugger.stopAtSystemEntryPoint</a>| +|files|Auto Rebase Load File|When opening a file with options, automatically rebase an image which has a default load address of zero to 4MB for 64-bit binaries, or 64KB for 32-bit binaries.|`boolean`|`False`|[`SettingsProjectScope`, `SettingsUserScope`]|<a id='files.pic.autoRebase'>files.pic.autoRebase</a>| +|files|Universal Mach-O Architecture Preference|Specify an architecture preference for automatic loading of a Mach-O file from a Universal archive. By default, the first object file in the listing is loaded.|`array`|[]|[`SettingsUserScope`]|<a id='files.universal.architecturePreference'>files.universal.architecturePreference</a>| +|network|Download Provider|Specify the registered DownloadProvider which enables resource fetching over HTTPS.|`string`|`CoreDownloadProvider`|[`SettingsUserScope`]|<a id='network.downloadProviderName'>network.downloadProviderName</a>| +| | | |`enum`|`CoreDownloadProvider`| | | +| | | |`enum`|`PythonDownloadProvider`| | | +|network|Enable External Resources|Allow Binary Ninja to download external images and resources when displaying markdown content (e.g. plugin descriptions).|`boolean`|`True`|[`SettingsUserScope`]|<a id='network.enableExternalResources'>network.enableExternalResources</a>| +|network|Enable External URLs|Allow Binary Ninja to download and open external URLs.|`boolean`|`True`|[`SettingsUserScope`]|<a id='network.enableExternalUrls'>network.enableExternalUrls</a>| +|network|Enable Plugin Manager|Allow Binary Ninja to connect to the update server to check for new plugins and plugin updates.|`boolean`|`True`|[`SettingsUserScope`]|<a id='network.enablePluginManager'>network.enablePluginManager</a>| +|network|Enable Release Notes|Allow Binary Ninja to connect to the update server to display release notes on new tabs.|`boolean`|`True`|[`SettingsUserScope`]|<a id='network.enableReleaseNotes'>network.enableReleaseNotes</a>| +|network|Enable Update Channel List|Allow Binary Ninja to connect to the update server to determine which update channels are available.|`boolean`|`True`|[`SettingsUserScope`]|<a id='network.enableUpdateChannelList'>network.enableUpdateChannelList</a>| +|network|Enable Updates|Allow Binary Ninja to connect to the update server to check for updates.|`boolean`|`True`|[`SettingsUserScope`]|<a id='network.enableUpdates'>network.enableUpdates</a>| +|network|HTTPS Proxy|Override default HTTPS proxy settings. By default, HTTPS Proxy settings are detected and used automatically via environment variables (e.g., https_proxy). Alternatively, proxy settings are obtained from the Internet Settings section of the Windows registry, or the Mac OS X System Configuration Framework.|`string`| |[`SettingsUserScope`]|<a id='network.httpsProxy'>network.httpsProxy</a>| +|network|Enable Auto Downloading PDBs|Automatically search for and download pdb files from specified symbol servers.|`boolean`|`True`|[`SettingsProjectScope`, `SettingsResourceScope`, `SettingsUserScope`]|<a id='network.pdbAutoDownload'>network.pdbAutoDownload</a>| +|network|Websocket Provider|Specify the registered WebsocketProvider which enables communication over HTTPS.|`string`|`CoreWebsocketProvider`|[`SettingsUserScope`]|<a id='network.websocketProviderName'>network.websocketProviderName</a>| +| | | |`enum`|`CoreWebsocketProvider`| | | +|pdb|Allow Unnamed Void Symbol Types|Allow creation of symbols with no name and void types, often used as static local variables. Generally, these are just noisy and not relevant.|`boolean`|`False`|[`SettingsProjectScope`, `SettingsResourceScope`, `SettingsUserScope`]|<a id='pdb.allowUnnamedVoidSymbols'>pdb.allowUnnamedVoidSymbols</a>| +|pdb|Expand RTTI Structures|Create structures for RTTI symbols with variable-sized names and arrays.|`boolean`|`True`|[`SettingsProjectScope`, `SettingsResourceScope`, `SettingsUserScope`]|<a id='pdb.expandRTTIStructures'>pdb.expandRTTIStructures</a>| +|pdb|Generate Virtual Table Structures|Create Virtual Table (VTable) structures for C++ classes found when parsing.|`boolean`|`True`|[`SettingsProjectScope`, `SettingsResourceScope`, `SettingsUserScope`]|<a id='pdb.generateVTables'>pdb.generateVTables</a>| +|pdb|Load Global Module Symbols|Load symbols in the Global module of the PDB. These symbols have generally lower quality types due to relying on the demangler.|`boolean`|`True`|[`SettingsProjectScope`, `SettingsResourceScope`, `SettingsUserScope`]|<a id='pdb.loadGlobalSymbols'>pdb.loadGlobalSymbols</a>| +|pdb|Absolute PDB Symbol Store Path|Absolute path specifying where the PDB symbol store exists on this machine, overrides relative path.|`string`| |[`SettingsProjectScope`, `SettingsResourceScope`, `SettingsUserScope`]|<a id='pdb.localStoreAbsolute'>pdb.localStoreAbsolute</a>| +|pdb|Cache Downloaded PDBs in Local Store|Store PDBs downloaded from Symbol Servers in the local Symbol Store Path.|`boolean`|`True`|[`SettingsProjectScope`, `SettingsResourceScope`, `SettingsUserScope`]|<a id='pdb.localStoreCache'>pdb.localStoreCache</a>| +|pdb|Relative PDB Symbol Store Path|Path *relative* to the binaryninja _user_ directory, specifying the pdb symbol store.|`string`|`symbols`|[`SettingsProjectScope`, `SettingsResourceScope`, `SettingsUserScope`]|<a id='pdb.localStoreRelative'>pdb.localStoreRelative</a>| +|pdb|Symbol Server List|List of servers to query for pdb symbols.|`array`|[`https://msdl.microsoft.com/download/symbols`]|[`SettingsProjectScope`, `SettingsResourceScope`, `SettingsUserScope`]|<a id='pdb.symbolServerList'>pdb.symbolServerList</a>| +|pluginManager|Community Plugin Repository|Whether the community plugin repository is enabled|`boolean`|`True`|[`SettingsUserScope`]|<a id='pluginManager.communityRepo'>pluginManager.communityRepo</a>| +|pluginManager|Community Plugin Manager Update Channel|Specify which community update channel the Plugin Manager should update plugins from.|`string`|`master`|[`SettingsUserScope`]|<a id='pluginManager.communityUpdateChannel'>pluginManager.communityUpdateChannel</a>| +| | | enum: The default channel. This setting should be used unless you are testing the Plugin Manager.|`enum`|`master`| | | +| | | enum: Plugin Manager test channel.|`enum`|`test`| | | +|pluginManager|Debug Plugin Manager|Enable debug functionality for the Plugin Manager.|`boolean`|`False`|[`SettingsUserScope`]|<a id='pluginManager.debug'>pluginManager.debug</a>| +|pluginManager|Official Plugin Repository|Whether the official plugin repository is enabled|`boolean`|`True`|[`SettingsUserScope`]|<a id='pluginManager.officialRepo'>pluginManager.officialRepo</a>| +|pluginManager|Official Plugin Manager Update Channel|Specify which official update channel the Plugin Manager should update plugins from.|`string`|`master`|[`SettingsUserScope`]|<a id='pluginManager.officialUpdateChannel'>pluginManager.officialUpdateChannel</a>| +| | | enum: The default channel. This setting should be used unless you are testing the Plugin Manager.|`enum`|`master`| | | +| | | enum: Plugin Manager test channel.|`enum`|`test`| | | +|pluginManager|Unofficial 3rd Party Plugin Repository Display Name|Specify display name of 3rd party plugin repository.|`string`| |[`SettingsUserScope`]|<a id='pluginManager.unofficialName'>pluginManager.unofficialName</a>| +|pluginManager|Unofficial 3rd Party Plugin Repository URL|Specify URL of 3rd party plugin|`string`| |[`SettingsUserScope`]|<a id='pluginManager.unofficialUrl'>pluginManager.unofficialUrl</a>| +|python|Python Path Override|Python interpreter binary which may be necessary to install plugin dependencies. Should be the same version as the one specified in the 'Python Interpreter' setting|`string`| |[`SettingsUserScope`]|<a id='python.binaryOverride'>python.binaryOverride</a>| +|python|Python Interpreter|Python interpreter library(dylib/dll/so.1) to load if one is not already present when plugins are loaded.|`string`| |[`SettingsUserScope`]|<a id='python.interpreter'>python.interpreter</a>| +|python|Minimum Python Log Level|Set the minimum Python log level which applies in headless operation only. The log is connected to stderr. Additionally, stderr must be associated with a terminal device.|`string`|`WarningLog`|[`SettingsUserScope`]|<a id='python.log.minLevel'>python.log.minLevel</a>| +| | | enum: Print Debug, Info, Warning, Error, and Alert messages to stderr on the terminal device.|`enum`|`DebugLog`| | | +| | | enum: Print Info, Warning, Error, and Alert messages to stderr on the terminal device.|`enum`|`InfoLog`| | | +| | | enum: Print Warning, Error, and Alert messages to stderr on the terminal device.|`enum`|`WarningLog`| | | +| | | enum: Print Error and Alert messages to stderr on the terminal device.|`enum`|`ErrorLog`| | | +| | | enum: Print Alert messages to stderr on the terminal device.|`enum`|`AlertLog`| | | +| | | enum: Disable all logging in headless operation.|`enum`|`Disabled`| | | +|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|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`| | | +| | | enum: Braces around scopes, new line.|`enum`|`bracesNewLine`| | | +|rendering|Tab Width|Width (in characters) of a single tab/indent in HLIL.|`number`|`4`|[`SettingsUserScope`]|<a id='rendering.hlil.tabWidth'>rendering.hlil.tabWidth</a>| +|rendering|Maximum String Annotation Length|The maximum substring length that will be shown in string annotations.|`number`|`32`|[`SettingsUserScope`]|<a id='rendering.strings.maxAnnotationLength'>rendering.strings.maxAnnotationLength</a>| +|triage|Triage Analysis Mode|Controls the amount of analysis performed on functions when opening for triage.|`string`|`basic`|[`SettingsProjectScope`, `SettingsResourceScope`, `SettingsUserScope`]|<a id='triage.analysisMode'>triage.analysisMode</a>| +| | | enum: Only perform control flow analysis on the binary. Cross references are valid only for direct function calls.|`enum`|`controlFlow`| | | +| | | enum: Perform fast initial analysis of the binary. This mode does not analyze types or data flow through stack variables.|`enum`|`basic`| | | +| | | enum: Perform full analysis of the binary.|`enum`|`full`| | | +|triage|Triage Shows Hidden Files|Whether the Triage file picker shows hidden files.|`boolean`|`False`|[`SettingsProjectScope`, `SettingsResourceScope`, `SettingsUserScope`]|<a id='triage.hiddenFiles'>triage.hiddenFiles</a>| +|triage|Triage Linear Sweep Mode|Controls the level of linear sweep performed when opening for triage.|`string`|`partial`|[`SettingsProjectScope`, `SettingsResourceScope`, `SettingsUserScope`]|<a id='triage.linearSweep'>triage.linearSweep</a>| +| | | enum: Do not perform linear sweep of the binary.|`enum`|`none`| | | +| | | enum: Perform linear sweep on the binary, but skip the control flow graph analysis phase.|`enum`|`partial`| | | +| | | enum: Perform full linear sweep on the binary.|`enum`|`full`| | | +|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|Developer Mode|Enable developer preferences.|`boolean`|`False`|[`SettingsUserScope`]|<a id='ui.developerMode'>ui.developerMode</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|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|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`| | | +|ui|File Contents Lock|Lock the file contents to prevent accidental edits from the UI. File modification via API and menu based patching is explicitly allowed while the lock is enabled.|`boolean`|`True`|[`SettingsUserScope`]|<a id='ui.fileContentsLock'>ui.fileContentsLock</a>| +|ui|Existing Database Detection|When opening a file in the UI, detect if a database exists and offer to open the database.|`string`|`prompt`|[`SettingsUserScope`]|<a id='ui.files.detection.database'>ui.files.detection.database</a>| +| | | enum: Enable detection and generate prompt.|`enum`|`prompt`| | | +| | | enum: Enable detection and automatically open the file or database, if found.|`enum`|`always`| | | +| | | enum: Disable detection.|`enum`|`disable`| | | +|ui|Existing Downloaded URL View Detection|When opening a database from an external URL in the UI, detect if an unsaved database from the same URL is already open and offer to navigate in that open view.|`string`|`prompt`|[`SettingsUserScope`]|<a id='ui.files.detection.openExistingViewFromUrl'>ui.files.detection.openExistingViewFromUrl</a>| +| | | enum: Enable detection and generate prompt.|`enum`|`prompt`| | | +| | | enum: Enable detection and automatically switch to the open view, if found.|`enum`|`always`| | | +| | | enum: Disable detection.|`enum`|`disable`| | | +|ui|Auto Open with Options|Specify the file types which automatically open using the 'Open with Options' dialog.|`array`|[`Mapped`, `Universal`]|[`SettingsUserScope`]|<a id='ui.files.detection.openWithOptions'>ui.files.detection.openWithOptions</a>| +| | | |`enum`|`Mapped`| | | +| | | |`enum`|`ELF`| | | +| | | |`enum`|`Mach-O`| | | +| | | |`enum`|`COFF`| | | +| | | |`enum`|`PE`| | | +| | | |`enum`|`Universal`| | | +|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|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`| | | +| | | enum: No subpixel antialiasing at High DPI.|`enum`|`hidpi`| | | +| | | 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`|`11`|[`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`|`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`|[`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>| +|ui|Maximum UI Log Size|Set the maximum number of lines for the UI log.|`number`|`10000`|[`SettingsUserScope`]|<a id='ui.log.maxSize'>ui.log.maxSize</a>| +|ui|Minimum UI Log Level|Set the minimum log level for the UI log.|`string`|`InfoLog`|[`SettingsUserScope`]|<a id='ui.log.minLevel'>ui.log.minLevel</a>| +| | | enum: Display Debug, Info, Warning, Error, and Alert messages to log console.|`enum`|`DebugLog`| | | +| | | enum: Display Info, Warning, Error, and Alert messages to log console.|`enum`|`InfoLog`| | | +| | | enum: Display Warning, Error, and Alert messages to log console.|`enum`|`WarningLog`| | | +| | | enum: Display Error and Alert messages to log console.|`enum`|`ErrorLog`| | | +| | | enum: Display Alert messages to log console.|`enum`|`AlertLog`| | | +|ui|Manual Tooltip|Enable to prevent tooltips from showing without <ctrl> being held.|`boolean`|`False`|[`SettingsUserScope`]|<a id='ui.manualTooltip'>ui.manualTooltip</a>| +|ui|Maximum Number of Cross-reference Items|The number of cross-reference items to show in the cross-reference widget. Value 0 means no limit.|`number`|`1000`|[`SettingsUserScope`]|<a id='ui.maxXrefItems'>ui.maxXrefItems</a>| +|ui|Middle Click Navigation Action|Customize action on middle click (scroll wheel click) |`string`|`NewPane`|[`SettingsUserScope`]|<a id='ui.middleClickNavigationAction'>ui.middleClickNavigationAction</a>| +| | | 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|Shift + Middle Click Navigation Action|Customize action on shift + middle click (scroll wheel click) |`string`|`NewTab`|[`SettingsUserScope`]|<a id='ui.middleClickShiftNavigationAction'>ui.middleClickShiftNavigationAction</a>| +| | | 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|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>| +| | | enum: Left side for horizontal split, top side for vertical split.|`enum`|`topLeft`| | | +| | | enum: Right side for horizontal split, top side for vertical split.|`enum`|`topRight`| | | +| | | enum: Left side for horizontal split, bottom side for vertical split.|`enum`|`bottomLeft`| | | +| | | enum: Right side for horizontal split, bottom side for vertical split.|`enum`|`bottomRight`| | | +|ui|Default Split Direction|Default direction for splitting panes.|`string`|`horizontal`|[`SettingsUserScope`]|<a id='ui.panes.splitDirection'>ui.panes.splitDirection</a>| +| | | enum: Horizontal split (columns).|`enum`|`horizontal`| | | +| | | enum: Vertical split (rows).|`enum`|`vertical`| | | +|ui|Always Show Pane Options in Status Bar|Enable to always show options for the active pane in the status bar.|`boolean`|`False`|[`SettingsUserScope`]|<a id='ui.panes.statusBarOptions'>ui.panes.statusBarOptions</a>| +|ui|Sync Panes by Default|Sync current location between panes by default.|`boolean`|`True`|[`SettingsUserScope`]|<a id='ui.panes.sync'>ui.panes.sync</a>| +|ui|Recent Command Limit|Specify a limit for the recent command palette history.|`number`|`5`|[`SettingsUserScope`]|<a id='ui.recentCommandLimit'>ui.recentCommandLimit</a>| +|ui|Recent File Limit|Specify a limit for the recent file history in the new tab window.|`number`|`10`|[`SettingsUserScope`]|<a id='ui.recentFileLimit'>ui.recentFileLimit</a>| +|ui|Show Indentation Guides|Show indentation markers in linear high-level IL|`boolean`|`True`|[`SettingsUserScope`]|<a id='ui.renderIndentGuides'>ui.renderIndentGuides</a>| +|ui|Default Scripting Provider|Specify the registered ScriptingProvider for the default scripting console in the UI.|`string`|`Python`|[`SettingsUserScope`]|<a id='ui.scripting.defaultProvider'>ui.scripting.defaultProvider</a>| +| | | |`enum`|`Python`| | | +| | | |`enum`|`Debugger`| | | +| | | |`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>| +| | | |`enum`|`None`| | | +| | | |`enum`|`Symbols`| | | +| | | |`enum`|`Types`| | | +| | | |`enum`|`Variables`| | | +| | | |`enum`|`Stack`| | | +| | | |`enum`|`Strings`| | | +| | | |`enum`|`Tags`| | | +| | | |`enum`|`Memory Map`| | | +| | | |`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`| | | +|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|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|Theme|Customize the appearance and style of Binary Ninja.|`string`|`Dark`|[`SettingsUserScope`]|<a id='ui.theme.name'>ui.theme.name</a>| +|ui|Random Theme on Startup|Randomize the theme on application startup.|`boolean`|`False`|[`SettingsUserScope`]|<a id='ui.theme.randomize'>ui.theme.randomize</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>| +| | | |`enum`|`Disassembly`| | | +| | | |`enum`|`LowLevelIL`| | | +| | | |`enum`|`LiftedIL`| | | +| | | |`enum`|`LowLevelILSSAForm`| | | +| | | |`enum`|`MediumLevelIL`| | | +| | | |`enum`|`MediumLevelILSSAForm`| | | +| | | |`enum`|`MappedMediumLevelIL`| | | +| | | |`enum`|`MappedMediumLevelILSSAForm`| | | +| | | |`enum`|`HighLevelIL`| | | +| | | |`enum`|`HighLevelILSSAForm`| | | +| | | |`enum`|`PseudoC`| | | +|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`| | | +| | | |`enum`|`LiftedIL`| | | +| | | |`enum`|`LowLevelILSSAForm`| | | +| | | |`enum`|`MediumLevelIL`| | | +| | | |`enum`|`MediumLevelILSSAForm`| | | +| | | |`enum`|`MappedMediumLevelIL`| | | +| | | |`enum`|`MappedMediumLevelILSSAForm`| | | +| | | |`enum`|`HighLevelIL`| | | +| | | |`enum`|`HighLevelILSSAForm`| | | +| | | |`enum`|`PseudoC`| | | +|ui|Graph View Padding|Add extra space around graphs, proportional to the view's size.|`number`|`0.0`|[`SettingsProjectScope`, `SettingsUserScope`]|<a id='ui.view.graph.padding'>ui.view.graph.padding</a>| +|ui|Prefer Graph View|Default view preference between graph and linear view. User navigation to either view implicitly sets a run-time preference, and takes precedence over the default.|`boolean`|`False`|[`SettingsUserScope`]|<a id='ui.view.graph.preferred'>ui.view.graph.preferred</a>| +|ui|Linear View IL Carousel|Specify the IL view types and order for use with the 'Cycle IL' actions in Linear view.|`array`|[`Disassembly`, `LowLevelIL`, `MediumLevelIL`, `HighLevelIL`]|[`SettingsUserScope`]|<a id='ui.view.linear.carousel'>ui.view.linear.carousel</a>| +| | | |`enum`|`Disassembly`| | | +| | | |`enum`|`LowLevelIL`| | | +| | | |`enum`|`LiftedIL`| | | +| | | |`enum`|`LowLevelILSSAForm`| | | +| | | |`enum`|`MediumLevelIL`| | | +| | | |`enum`|`MediumLevelILSSAForm`| | | +| | | |`enum`|`MappedMediumLevelIL`| | | +| | | |`enum`|`MappedMediumLevelILSSAForm`| | | +| | | |`enum`|`HighLevelIL`| | | +| | | |`enum`|`HighLevelILSSAForm`| | | +| | | |`enum`|`PseudoC`| | | +|ui|Linear View Gutter Width|Linear view gutter and tags width, in characters.|`number`|`5`|[`SettingsUserScope`]|<a id='ui.view.linear.gutterWidth'>ui.view.linear.gutterWidth</a>| +|ui|Default IL for Linear View|Default IL for linear view. Other settings (e.g. 'ui.files.restore.viewState') have precedence over the default behavior.|`string`|`HighLevelIL`|[`SettingsUserScope`]|<a id='ui.view.linear.il'>ui.view.linear.il</a>| +| | | |`enum`|`Disassembly`| | | +| | | |`enum`|`LowLevelIL`| | | +| | | |`enum`|`LiftedIL`| | | +| | | |`enum`|`LowLevelILSSAForm`| | | +| | | |`enum`|`MediumLevelIL`| | | +| | | |`enum`|`MediumLevelILSSAForm`| | | +| | | |`enum`|`MappedMediumLevelIL`| | | +| | | |`enum`|`MappedMediumLevelILSSAForm`| | | +| | | |`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|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>| +|updates|Show All Versions|Show all versions that are available for the current update channel in the UI.|`boolean`|`False`|[`SettingsUserScope`]|<a id='updates.showAllVersions'>updates.showAllVersions</a>| +|user|Email|The email that will be shown when collaborating with other users.|`string`| |[`SettingsUserScope`]|<a id='user.email'>user.email</a>| +|user|Name|The name that will be shown when collaborating with other users.|`string`| |[`SettingsUserScope`]|<a id='user.name'>user.name</a>| +|workflows|Workflows Analysis Orchestration Framework|Enable the analysis orchestration framework. This feature is currently under active development.|`boolean`|`False`|[`SettingsProjectScope`, `SettingsResourceScope`, `SettingsUserScope`]|<a id='workflows.enable'>workflows.enable</a>| +|workflows|Workflows Example Plugins|Enable the built-in example plugins.|`boolean`|`False`|[`SettingsUserScope`]|<a id='workflows.examples'>workflows.examples</a>| +|workflows|Function Workflow|Workflow selection for function-based analysis.|`string`|`core.function.defaultAnalysis`|[`SettingsProjectScope`, `SettingsResourceScope`, `SettingsUserScope`]|<a id='workflows.functionWorkflow'>workflows.functionWorkflow</a>| +| | | |`enum`|`core.function.defaultAnalysis`| | | +| | | |`enum`|`core.function.objectiveC`| | | +| | | |`enum`|`core.module.defaultAnalysis`| | | +|workflows|Module Workflow|Workflow selection for module-based analysis. Note: Module-based workflows incomplete.|`string`|`core.module.defaultAnalysis`|[`SettingsProjectScope`, `SettingsResourceScope`, `SettingsUserScope`]|<a id='workflows.moduleWorkflow'>workflows.moduleWorkflow</a>| +| | | |`enum`|`core.module.defaultAnalysis`| | | diff --git a/docs/guide/troubleshooting.md b/docs/guide/troubleshooting.md index 425fcd35..0794f934 100644 --- a/docs/guide/troubleshooting.md +++ b/docs/guide/troubleshooting.md @@ -39,16 +39,16 @@ While third party plugins are not officially supported, there are a number of tr Additionally, if you're having trouble running a plugin in headless mode (without a GUI calling directly into the core), make sure you're running the Commercial version of Binary Ninja as the Student/Non-Commercial edition does not support headless processing. -Next, if running a python plugin, make sure the python requirements are met by your existing installation. Note that on windows, the bundled python is used and python requirements should be installed either by manually copying the modules to the `plugins` [folder](/getting-started/#directories). +Next, if running a python plugin, make sure the python requirements are met by your existing installation. Note that on windows, the bundled python is used and python requirements should be installed either by manually copying the modules to the `plugins` [folder](./#directories). ## License Problems -- If experiencing problems with Windows UAC permissions during an update, the easiest fix is to completely un-install and [recover][recover] the latest installer and license. Preferences are saved outside the installation folder and are preserved, though you might want to remove your [license](/getting-started/#license). +- If experiencing problems with Windows UAC permissions during an update, the easiest fix is to completely un-install and [recover][recover] the latest installer and license. Preferences are saved outside the installation folder and are preserved, though you might want to remove your [license](./#license). - If you need to change the email address on your license, contact [support]. ## Running as Root -Binary Ninja will refuse to run as root on Linux and macOS platforms (this is partially enforced by the usage of an embedded QWebEngine which will not run as root). You can work-around this issue by either running as a regular user, or forcing BN to launch but you will need to also disable [active content](/getting-started/#updates.activeContent). If you try to use su or another similar tool, make sure that user has permission to the X11 session. +Binary Ninja will refuse to run as root on Linux and macOS platforms (this is partially enforced by the usage of an embedded QWebEngine which will not run as root). You can work-around this issue by either running as a regular user, or forcing BN to launch but you will need to also disable [active content](settings.md#updates.activeContent). If you try to use su or another similar tool, make sure that user has permission to the X11 session. ## API @@ -56,7 +56,7 @@ Binary Ninja will refuse to run as root on Linux and macOS platforms (this is pa ## Database Issues - - BNDBs may grow in size after repeated saving/loading. While a future update to Binary Ninja will implement this optimization internally, this [unofficial script] may be useful for shrinking the size of a BNDB. Please ensure you backup your database prior to trying that script as it is not an officially supported operation. + - BNDBs may grow in size after repeated saving/loading. To shrink the size of your database, use the `File` / `Save analysis database with options` menu and select one or both of the checkboxes. ## Platforms @@ -65,7 +65,7 @@ The below steps are specific to different platforms that Binary Ninja runs on. ### Windows - While Windows 7 is not officially supported (by us, or Microsoft for that matter), it's possible to have Binary Ninja work if all available windows updates are installed as a library pack update somewhere in the updates is required for us to run. -- If you install Windows without internet access and have never run windows updates to install an update, you may have an incomplete windows certificate store. You'll see errors when attempting to update about `CERTIFICATE VERIFICATION FAILED`. If that is the case, you can either use something like `certutil.exe -generateSSTFromWU roots.sst` and then manually copy over the DST and Amazon certificates into your root store, or wait until the next time you have an update from Windows Update which should automatically refresh your certificate store. +- If you install Windows without internet access and have never run windows updates to install an update, you may have an incomplete windows certificate store. You'll see errors when attempting to update about `CERTIFICATE VERIFICATION FAILED`. If that is the case, you can either use something like `certutil.exe -generateSSTFromWU roots.sst` and then manually copy over the DST and Amazon certificates into your root store, or wait until the next time you have an update from Windows Update which should automatically refresh your certificate store. #### Some Graphics Chipsets @@ -75,7 +75,7 @@ Some graphics chipsets may experience problems with [scaling](https://github.com If you're using Windows virtual machines within virtualbox or VMWare, you may have trouble with the 3d acceleration drivers. If so, disabling the 3d acceleration is the easiest way to get BN working. -You may also manually create a `settings.json` file in your [user folder](../getting-started.md#user-folder) with the contents though using the [plugin manager](plugins.md#plugin-manager) may also have problems: +You may also manually create a `settings.json` file in your [user folder](./#user-folder) with the contents though using the [plugin manager](plugins.md#plugin-manager) may also have problems: ``` js { @@ -174,7 +174,7 @@ stdenv.mkDerivation rec { url = "https://cdn.binary.ninja/installers/BinaryNinja-demo.zip"; sha256 = "1yq2kgrhrwdi7f66jm1w5sc6r49hdhqnff9b0ysr5k65w9kxhl1k"; }; - + buildPhase = ":"; installPhase = '' mkdir -p $out/bin diff --git a/docs/guide/type.md b/docs/guide/type.md index cae1769d..8beafdf6 100644 --- a/docs/guide/type.md +++ b/docs/guide/type.md @@ -82,7 +82,7 @@ This also works within data variables with structure type. For example, if the s 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. -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](../getting-started.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. +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](./#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.  @@ -442,7 +442,7 @@ current_function.parameter_vars[0].type = Type.pointer(bv.arch, Type.char()) Type Libraries are collections of type information (structs, enums, function types, etc.) stored in a file with the extension `.bntl`. -Relative to the binaryninja executable, the default type library location is `../Resources/typelib` on macOS and `./typelib` on Linux and Windows. Individual .bntl files are organized in subdirectories named for the supported architecture. Users may include their own type libraries +Relative to the binaryninja executable, the default type library location is `../Resources/typelib` on macOS and `./typelib` on Linux and Windows. Individual .bntl files are organized in subdirectories named for the supported architecture. Users may include their own type libraries The information in a type library is contained in two key-value stores: @@ -556,7 +556,7 @@ struct.append(Type.int(4), 'weight') typelib = binaryninja.typelibrary.TypeLibrary.new(arch, 'test.so.1.4') typelib.add_named_type('human', binaryninja.types.Type.structure_type(struct)) typelib.add_alternate_name('test.so.1') #don't forget this step! -typelib.add_alternate_name('test.so') +typelib.add_alternate_name('test.so') typelib.finalize() typelib.write_to_file('test.so.1.bntl') ``` @@ -679,11 +679,11 @@ TypeLibrary: failed to import type 'Point'; referenced but not present in librar This makes sense! Now go to types view and `define struct Point { int x; int y; }` and try again, success! ``` -100001000 struct rectangle_unresolved data_100001000 = +100001000 struct rectangle_unresolved data_100001000 = 100001000 { 100001000 int32_t width = 0x5f0100 100001004 int32_t height = 0x5f030005 -100001008 struct Point center = +100001008 struct Point center = 100001008 { 100001008 int32_t x = 0x655f686d 10000100c int32_t y = 0x75636578 @@ -732,7 +732,7 @@ While many signatures are [built-in](https://github.com/Vector35/binaryninja-api ### Running the signature matcher -The signature matcher runs automatically by default once analysis completes. You can turn this off in `Settings > Analysis > Autorun Function Signature Matcher` (or, [analysis.signatureMatcher.autorun](../getting-started.md#analysis.signatureMatcher.autorun) in Settings). +The signature matcher runs automatically by default once analysis completes. You can turn this off in `Settings > Analysis > Autorun Function Signature Matcher` (or, [analysis.signatureMatcher.autorun](settings.md#analysis.signatureMatcher.autorun) in Settings). You can also trigger the signature matcher to run from the menu `Tools > Run Analysis Module > Signature Matcher`. @@ -758,8 +758,8 @@ import Vector35_sigkit as sigkit Binary Ninja loads signature libraries from 2 locations: - - [$INSTALL_DIR](https://docs.binary.ninja/getting-started.html#binary-path)/signatures/$PLATFORM - - [$USER_DIR](https://docs.binary.ninja/getting-started.html#user-folder)/signatures/$PLATFORM + - [$INSTALL_DIR](https://docs.binary.ninja/guide/#binary-path)/signatures/$PLATFORM + - [$USER_DIR](https://docs.binary.ninja/guide/#user-folder)/signatures/$PLATFORM **WARNING**: Always place your signature libraries in your user directory. The install path is wiped whenever Binary Ninja auto-updates. You can locate it with `Open Plugin Folder` in the command palette and navigate "up" a directory. @@ -769,9 +769,9 @@ Inside the signatures folder, each platform has its own folder for its set of si You can edit signature libraries programmatically using the sigkit API. A very basic [example](https://github.com/Vector35/sigkit/blob/master/examples/convert_siglib.py) shows how to load and save signature libraries. Note that Binary Ninja only supports signatures in the `.sig` format; the other formats are for debugging. The easiest way to load and save signature libraries in this format are the [`sigkit.load_signature_library()`](https://github.com/Vector35/sigkit/blob/master/__init__.py) and [`sigkit.save_signature_library()`](https://github.com/Vector35/sigkit/blob/master/__init__.py) functions. -To help debug and optimize your signature libraries in a Signature Explorer GUI by using `Tools > Signature Library > Explore Signature Library`. This GUI can be opened through the sigkit API using [`sigkit.signature_explorer()`](https://github.com/Vector35/sigkit/blob/master/__init__.py) and [`sigkit.explore_signature_library()`](https://github.com/Vector35/sigkit/blob/master/sigexplorer.py). +To help debug and optimize your signature libraries in a Signature Explorer GUI by using `Tools > Signature Library > Explore Signature Library`. This GUI can be opened through the sigkit API using [`sigkit.signature_explorer()`](https://github.com/Vector35/sigkit/blob/master/__init__.py) and [`sigkit.explore_signature_library()`](https://github.com/Vector35/sigkit/blob/master/sigkit/sigexplorer.py). -For a text-based approach, you can also export your signature libraries to JSON using the Signature Explorer. Then, you can edit them in a text editor and convert them back to a .sig using the Signature Explorer afterwards. Of course, these conversions are also accessible through the API as the [`sigkit.sig_serialize_json`](https://github.com/Vector35/sigkit/blob/master/sig_serialize_json.py) module, which provides a pickle-like interface. Likewise, [`sigkit.sig_serialize_fb`](https://github.com/Vector35/sigkit/blob/master/sig_serialize_fb.py) provides serialization for the standard .sig format. +For a text-based approach, you can also export your signature libraries to JSON using the Signature Explorer. Then, you can edit them in a text editor and convert them back to a .sig using the Signature Explorer afterwards. Of course, these conversions are also accessible through the API as the [`sigkit.sig_serialize_json`](https://github.com/Vector35/sigkit/blob/master/sigkit/sig_serialize_json.py) module, which provides a pickle-like interface. Likewise, [`sigkit.sig_serialize_fb`](https://github.com/Vector35/sigkit/blob/master/sigkit/sig_serialize_fb.py) provides serialization for the standard .sig format. ## Symbols @@ -799,7 +799,7 @@ Other objects or variables may need a [symbol](https://api.binary.ninja/binaryni >>> bv.define_user_symbol(mysym) ``` -Note that `here` and `bv` are used in many of the previous examples. These shortcuts and [several others](../getting-started.md#script-python-console) are only available when running in the Binary Ninja python console and are used here for convenience. +Note that `here` and `bv` are used in many of the previous examples. These shortcuts and [several others](./#script-python-console) are only available when running in the Binary Ninja python console and are used here for convenience. Valid symbol types [include](https://api.binary.ninja/binaryninja.enums.SymbolType.html): diff --git a/docs/img/featuremap.png b/docs/img/featuremap.png Binary files differnew file mode 100644 index 00000000..226ba48e --- /dev/null +++ b/docs/img/featuremap.png diff --git a/docs/img/graphcontext.png b/docs/img/graphcontext.png Binary files differdeleted file mode 100644 index d453f5e1..00000000 --- a/docs/img/graphcontext.png +++ /dev/null diff --git a/docs/img/ilmapping.png b/docs/img/ilmapping.png Binary files differnew file mode 100644 index 00000000..d80a3ab5 --- /dev/null +++ b/docs/img/ilmapping.png diff --git a/docs/img/main.png b/docs/img/main.png Binary files differnew file mode 100644 index 00000000..688cedc3 --- /dev/null +++ b/docs/img/main.png diff --git a/docs/img/memory-map.png b/docs/img/memory-map.png Binary files differindex f29c05b2..b3f4e825 100644 --- a/docs/img/memory-map.png +++ b/docs/img/memory-map.png diff --git a/docs/img/overview.png b/docs/img/overview.png Binary files differnew file mode 100644 index 00000000..0029ade0 --- /dev/null +++ b/docs/img/overview.png diff --git a/docs/img/recent.png b/docs/img/recent.png Binary files differdeleted file mode 100644 index 13f3ebe7..00000000 --- a/docs/img/recent.png +++ /dev/null diff --git a/docs/index.md b/docs/index.md index 6bcf6fb3..d3422274 100644 --- a/docs/index.md +++ b/docs/index.md @@ -6,7 +6,8 @@ A new kind of reverse engineering platform [Binary Ninja](https://binary.ninja/) is a reverse engineering platform. It focuses on a clean and easy to use interface with a powerful multithreaded analysis built on a custom IL to quickly adapt to a variety of architectures, platforms, and compilers. -The most common starting points for documentation are: +- To quickly get started as a new user, check out our [getting started guide](getting-started.md). +- More in-depth user questions are probably answered in our [user manual](/guide/index.md). +- Anyone wanting to get started with our powerful API should check out the [developer section](/dev/index.md). Note that this section is different from our API reference for [Python](https://api.binary.ninja/), [CPP](https://api.binary.ninja/cpp/), and [Rust](https://rust.binary.ninja/binaryninja/). -- [Getting Started Guide](getting-started.md) -- [API documentation](dev/api.md) (depending on your language of choice) +Of course, if you just have some questions, you might find our [discussions](https://github.com/Vector35/binaryninja-api/discussions) forum helpful, search [search our public issue tracker](https://github.com/Vector35/binaryninja-api/issues) or join the more interactive [slack channel](https://slack.binary.ninja/). @@ -1,7 +1,7 @@ site_name: 'Binary Ninja User Documentation' site_url: 'https://docs.binary.ninja/' repo_url: 'https://binary.ninja/' -repo_name: 'github' +repo_name: 'binary.ninja' site_description: 'Documentation for the Binary Ninja reverse engineering platform' site_author: 'Vector 35 Inc' google_analytics: ['UA-72420552-3', 'docs.binary.ninja' ] @@ -9,9 +9,20 @@ use_directory_urls: False extra_css: ['docs.css', 'github.min.css', 'juxtapose.min.css'] extra_javascript: ['highlight.min.js', 'cpp.min.js', 'python.min.js', 'juxtapose.min.js'] theme: - name: readthedocs + name: material favicon: 'img/favicon.ico' highlightjs: false + palette: + scheme: binja + accent: red + features: + - navigation.tracking + - navigation.tabs + - navigation.sections + - navigation.expand + - navigation.prune + - navigation.indexes + - navigation.top shortcuts: help: 191 # ? next: 78 # n @@ -26,29 +37,41 @@ plugins: markdown_extensions: - codehilite - admonition + - pymdownx.details + - pymdownx.superfences - toc: permalink: True nav: - - Home: 'index.md' - - Getting Started Guide: 'getting-started.md' - - User Guide: + - Home: '/' + - Getting Started: 'getting-started.md' + # + #- User Manual: 'guide/' + #- Developer Guide: 'dev/' + #- About: 'about/' + - User Manual: + - 'guide/index.md' - Plugins: 'guide/plugins.md' + - Settings: 'guide/settings.md' - Types: 'guide/type.md' - Debugger: 'guide/debugger.md' - Objective-C (Beta): 'guide/objectivec.md' - Troubleshooting: 'guide/troubleshooting.md' - Developer Guide: - - API: 'dev/api.md' - - Python Plugins: 'dev/plugins.md' - - Batch / Headless Automation: 'dev/batch.md' + - 'dev/index.md' + - Important Concepts: 'dev/concepts.md' + - Cookbook: 'dev/cookbook.md' + - Writing Plugins: 'dev/plugins.md' + - Automation: 'dev/batch.md' - BNIL Guide: Overview: 'dev/bnil-overview.md' - BNIL Guide: LLIL: 'dev/bnil-llil.md' - BNIL Guide: MLIL: 'dev/bnil-mlil.md' - Flag Guide: 'dev/flags.md' + - Workflows: 'dev/workflows.md' - Creating Themes: 'dev/themes.md' - Contributing Documentation: 'dev/documentation.md' - About: + - 'about/index.md' - License: 'about/license.md' - Open Source: 'about/open-source.md' diff --git a/python/__init__.py b/python/__init__.py index 2d36c7be..6798ebe1 100644 --- a/python/__init__.py +++ b/python/__init__.py @@ -178,7 +178,7 @@ def disable_default_log() -> None: def bundled_plugin_path() -> Optional[str]: """ - ``bundled_plugin_path`` returns a string containing the current plugin path inside the `install path <https://docs.binary.ninja/getting-started.html#binary-path>`_ + ``bundled_plugin_path`` returns a string containing the current plugin path inside the `install path <https://docs.binary.ninja/guide/#binary-path>`_ :return: current bundled plugin path :rtype: str, or None on failure @@ -188,7 +188,7 @@ def bundled_plugin_path() -> Optional[str]: def user_plugin_path() -> Optional[str]: """ - ``user_plugin_path`` returns a string containing the current plugin path inside the `user directory <https://docs.binary.ninja/getting-started.html#user-folder>`_ + ``user_plugin_path`` returns a string containing the current plugin path inside the `user directory <https://docs.binary.ninja/guide/#user-folder>`_ :return: current user plugin path :rtype: str, or None on failure @@ -198,7 +198,7 @@ def user_plugin_path() -> Optional[str]: def user_directory() -> Optional[str]: """ - ``user_directory`` returns a string containing the path to the `user directory <https://docs.binary.ninja/getting-started.html#user-folder>`_ + ``user_directory`` returns a string containing the path to the `user directory <https://docs.binary.ninja/guide/#user-folder>`_ :return: current user path :rtype: str, or None on failure diff --git a/python/examples/triage/README.md b/python/examples/triage/README.md index d578bee2..99754481 100644 --- a/python/examples/triage/README.md +++ b/python/examples/triage/README.md @@ -13,7 +13,7 @@ In particular, the Triage plugin: ## Installation
-This plugin is included by default if you are running the appropriate version of Binary Ninja (you may need to switch to the development channel in your [preferences](http://docs.binary.ninja/getting-started.html#preferencesupdates). To enable, simply copy from your [install path](http://docs.binary.ninja/getting-started.html#binary-path) to your [user](http://docs.binary.ninja/getting-started.html#user-folder)/plugins folder.
+This plugin is included by default if you are running the appropriate version of Binary Ninja (you may need to switch to the development channel in your [preferences](http://docs.binary.ninja/guide/#preferencesupdates). To enable, simply copy from your [install path](http://docs.binary.ninja/guide/#binary-path) to your [user](http://docs.binary.ninja/guide/#user-folder)/plugins folder.
## Minimum Version
diff --git a/python/interaction.py b/python/interaction.py index 9fb5d9c7..a82ad46e 100644 --- a/python/interaction.py +++ b/python/interaction.py @@ -194,12 +194,16 @@ class IntegerField: class AddressField: """ - ``AddressField`` prompts the user for an address. By passing the optional view and current_address parameters + ``AddressField`` prompts the user for an address. By passing the optional view and current_address parameters \ offsets can be used instead of just an address. The result is stored as in int in self.result. .. note:: This API currently functions differently on the command-line, as the view and current_address are \ disregarded. Additionally where as in the UI the result defaults to hexadecimal on the command-line 0x must be \ specified. + + :attr str prompt: prompt to be presented to the user + :attr BinaryView view: BinaryView for the address + :attr int current_address: current address to use as a base for relative calculations """ def __init__(self, prompt, view=None, current_address=0, default=None): self._prompt = prompt @@ -260,7 +264,7 @@ class AddressField: class ChoiceField: """ - ``ChoiceField`` prompts the user to choose from the list of strings provided in ``choices``. Result is stored + ``ChoiceField`` prompts the user to choose from the list of strings provided in ``choices``. Result is stored \ in self.result as an index in to the choices array. :attr str prompt: prompt to be presented to the user |
