diff --git a/docs/dev/annotation.md b/docs/dev/annotation.md index 24ff6de01b..98f065e952 100644 --- a/docs/dev/annotation.md +++ b/docs/dev/annotation.md @@ -51,7 +51,7 @@ The tags API has been reworked in 3.4 to be easier to use and understand. ### TagTypes -A [TagType](https://api.binary.ninja/binaryninja.binaryview-module.html#binaryninja.binaryview.TagType) is the object that represents the "type" of tag something is. By default, a binary view starts off with several tag types, include "Bugs," "Crashes," "Important," and so on. +A [TagType](https://api.binary.ninja/binaryninja.binaryview-module.html#binaryninja.binaryview.TagType) is the object that represents the "type" of tag something is. By default, a binary view starts off with several tag types, including "Bugs," "Crashes," "Important," and so on. Before you can create a tag of a type that's not already in the BinaryView, you need to create the tag type. @@ -481,7 +481,7 @@ current_function.parameter_vars[0].type = Type.pointer(bv.arch, Type.char()) >>> bv.get_data_var_at(here).type = Type.char() ``` -#### Applying a type where non exists yet +#### Applying a type where none exists yet In some instances you may need to first create a `DataVariable` before you can set the type at a given location: diff --git a/docs/dev/batch.md b/docs/dev/batch.md index 6377210597..f983a72623 100644 --- a/docs/dev/batch.md +++ b/docs/dev/batch.md @@ -130,7 +130,7 @@ If using a floating license, you can use the [example code](https://api.binary.n ### In-Memory License -For many applications it might be helpful to avoid having a license file on disk. Whether because the environment will be used to analyze malware, or because a docker image might be saved somewhere that the license file needs to be kept secret. (Note: this does not obfuscate the serial number as it can be extracted from memory or even via the API -- an informed attacker can still leak it and network isolation is recommended for analzying malicious applications) +For many applications it might be helpful to avoid having a license file on disk. Whether because the environment will be used to analyze malware, or because a docker image might be saved somewhere that the license file needs to be kept secret. (Note: this does not obfuscate the serial number as it can be extracted from memory or even via the API -- an informed attacker can still leak it and network isolation is recommended for analyzing malicious applications) To use this API, copy the contents of your license file into a string and pass it as an argument to [`core_set_license`](https://api.binary.ninja/#binaryninja.core_set_license) diff --git a/docs/dev/bnil-overview.md b/docs/dev/bnil-overview.md index 3903519f7d..df0447ea9f 100644 --- a/docs/dev/bnil-overview.md +++ b/docs/dev/bnil-overview.md @@ -97,7 +97,7 @@ It represents the lower 32-bits of variable `rax_2`, sign-extended into a 64-bit ## Using the API with ILs -When you want to use the API to access BNIL instructions, here are a few tips that will help you with the task. First, if you want to learn what properties different instructions have, instead of manually using `dir()` or looking in the documentation ([1](https://docs.binary.ninja/dev/bnil-llil.html#the-instructions), [2](https://docs.binary.ninja/dev/bnil-mlil.html#the-instruction-set)) lists is to use the [BNIL Graph](https://github.com/Vector35/community-plugins#:~:text=BNIL%20Instruction%20Graph) plugin. Another very useful plugin is the [IL Hierarch](https://github.com/Vector35/community-plugins#:~:text=into%20Binary%20Ninja.-,ilhierarchy,-Fabian%20Freyer) plugin. This plugin is extremely useful for showing the _structure_ of IL instructions relative to one another. You can use several APIs ([1](https://api.binary.ninja/binaryninja.lowlevelil-module.html#binaryninja.lowlevelil.LowLevelILInstruction.show_llil_hierarchy), [2](https://api.binary.ninja/binaryninja.mediumlevelil-module.html#binaryninja.mediumlevelil.MediumLevelILInstruction.show_mlil_hierarchy), [3](https://api.binary.ninja/binaryninja.highlevelil-module.html#binaryninja.highlevelil.HighLevelILInstruction.show_hlil_hierarchy)) to see this overall structure, but the IL Hierarchy plugin lets you select a single IL instruction and see visually which categories of IL instructions it is in. +When you want to use the API to access BNIL instructions, here are a few tips that will help you with the task. First, if you want to learn what properties different instructions have, instead of manually using `dir()` or looking in the documentation ([1](https://docs.binary.ninja/dev/bnil-llil.html#the-instructions), [2](https://docs.binary.ninja/dev/bnil-mlil.html#the-instruction-set)) lists is to use the [BNIL Graph](https://github.com/Vector35/community-plugins#:~:text=BNIL%20Instruction%20Graph) plugin. Another very useful plugin is the [IL Hierarchy](https://github.com/Vector35/community-plugins#:~:text=into%20Binary%20Ninja.-,ilhierarchy,-Fabian%20Freyer) plugin. This plugin is extremely useful for showing the _structure_ of IL instructions relative to one another. You can use several APIs ([1](https://api.binary.ninja/binaryninja.lowlevelil-module.html#binaryninja.lowlevelil.LowLevelILInstruction.show_llil_hierarchy), [2](https://api.binary.ninja/binaryninja.mediumlevelil-module.html#binaryninja.mediumlevelil.MediumLevelILInstruction.show_mlil_hierarchy), [3](https://api.binary.ninja/binaryninja.highlevelil-module.html#binaryninja.highlevelil.HighLevelILInstruction.show_hlil_hierarchy)) to see this overall structure, but the IL Hierarchy plugin lets you select a single IL instruction and see visually which categories of IL instructions it is in. ![LLIL Hierarchy](../img/llil-hierarchy.png) diff --git a/docs/dev/concepts.md b/docs/dev/concepts.md index 8e70dba72c..14756160ab 100644 --- a/docs/dev/concepts.md +++ b/docs/dev/concepts.md @@ -147,13 +147,13 @@ Generally speaking, scripts should operate on ILs. The available information far ### 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! +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 expressions 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! ### Static Single Assignment Basics Our [BNIL Overview](bnil-overview.md) mentions Static Single Assignment (SSA) without explaining what it is. You can of course always check out [Wikipedia](https://en.wikipedia.org/wiki/Static_single-assignment_form), but here's a quick summary of what it is, why we expose multiple SSA forms of our ILs and how you can use it to improve your plugin writing with BNIL. -At it's simplest, SSA forms of an Intermediate Language or Intermediate Representation are those in which variables are read only. They can be set when created, but not modified. Instead of modifying them, when you make a change, a new "version" of the variable is created denoting that the value has changed in some way. While this certainly makes the form less readable to humans, this means it's actually really easy to walk back and see how a variable has been modified by simply looking at the definition site for a given variable or all possible versions before it. Any time the variable is modified, a new version of that variable will be created (you'll see `#` followed by a number indicating that this is a new version). +At its simplest, SSA forms of an Intermediate Language or Intermediate Representation are those in which variables are read only. They can be set when created, but not modified. Instead of modifying them, when you make a change, a new "version" of the variable is created denoting that the value has changed in some way. While this certainly makes the form less readable to humans, this means it's actually really easy to walk back and see how a variable has been modified by simply looking at the definition site for a given variable or all possible versions before it. Any time the variable is modified, a new version of that variable will be created (you'll see `#` followed by a number indicating that this is a new version). But what if the code takes multiple paths and could have different values depending on the path that was taken? SSA forms use a `Φ` (pronounced either as "fee" or "fi" like "fly" depending on which mathematician or Greek speaker you ask!) function to solve this ambiguity. All a `Φ` function does is aggregate different versions of a variable when entering a basic block with multiple paths. So a basic block with two incoming edges where `eax` is modified might have something like: `eax#3 = Φ(eax#1, eax#2)` denoting that the new version of the variable could have come from either of those sources. diff --git a/docs/dev/cookbook.md b/docs/dev/cookbook.md index e4740a1e3a..f9aee0051d 100644 --- a/docs/dev/cookbook.md +++ b/docs/dev/cookbook.md @@ -195,7 +195,7 @@ As defined by having the highest sum of incoming and outgoing calls. Adjust acco ```python max(bv.functions, key=lambda x: len(x.callers + x.callees)) ``` -j + ### Accessing cross references This recipe is useful for iterating over all of the HLIL cross-references of a given interesting function: diff --git a/docs/dev/documentation.md b/docs/dev/documentation.md index bc0a445ed8..741298844d 100644 --- a/docs/dev/documentation.md +++ b/docs/dev/documentation.md @@ -23,7 +23,7 @@ To contribute to the Binary Ninja documentation, first sign the [contribution li echo API documentation available in build/html ## Changing -Changing documentation for the API itself is fairly straight forward. Use [doxygen style comment blocks](https://www.doxygen.nl/manual/docblocks.html) in C++ and C, and [restructured text blocks](https://sphinx-tutorial.readthedocs.io/step-1/) 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. +Changing documentation for the API itself is fairly straightforward. Use [doxygen style comment blocks](https://www.doxygen.nl/manual/docblocks.html) in C++ and C, and [restructured text blocks](https://sphinx-tutorial.readthedocs.io/step-1/) 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. ???+ Info "Tip" When updating user documentation, the `properdocs serve` feature is particularly helpful. diff --git a/docs/getting-started.md b/docs/getting-started.md index 6e0c8601b2..77fcc774ac 100644 --- a/docs/getting-started.md +++ b/docs/getting-started.md @@ -10,7 +10,7 @@ The download links you receive after purchasing expire after 72 hours but as lon ### Linux -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 Binary Ninja. Next, for paid versions, run `./binaryninja/scripts/linux-setup.sh`. This sets up file associations, icons, and adds Binary Ninja's Python library to your Python path. Adding the library to your path is most helpful for headless functionality in the Commercial and Ultimate editions, but even on the Non-Commercial edition it can help your IDE find the api sources to make plugin development easier. Run the script with `-h` to see customization options. +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 Binary Ninja. Next, for paid versions, run `./binaryninja/scripts/linux-setup.sh`. This sets up file associations, icons, and adds Binary Ninja's Python library to your Python path. Adding the library to your path is most helpful for headless functionality in the Commercial and Ultimate editions, but even on the Non-Commercial edition it can help your IDE find the API sources to make plugin development easier. Run the script with `-h` to see customization options. ### macOS diff --git a/docs/guide/index.md b/docs/guide/index.md index ad5549081d..5f52d28b9a 100644 --- a/docs/guide/index.md +++ b/docs/guide/index.md @@ -1,6 +1,6 @@ # User Guide -Welcome to the Binary Ninja User Guide. You'll notice two menus here. On the right is the table of contents for this main page of the user manual. On the left are links to larger topics that have their own pages, including: +Welcome to the Binary Ninja User Guide! You'll notice two menus here. On the right is the table of contents for this main page of the user manual. On the left are links to larger topics that have their own pages, including: ## Directories @@ -232,7 +232,7 @@ Recent files can be opened on double click. They can also be navigated using the The Recent files list can be cleared via using the Command Palette (`[CTRL] + P`) action `Clear All Recent Files`. -Hotkeys (macOS: `[CMD] + 0` - `[CMD] + 9`, Windows/Linux: `[CTRL] + 0` - `[CTRL + 9]`) can also be used to quickly open a file. The hotkey for a given entry will be shown on the right. +Hotkeys (macOS: `[CMD] + 0` - `[CMD] + 9`, Windows/Linux: `[CTRL] + 0` - `[CTRL] + 9`) can also be used to quickly open a file. The hotkey for a given entry will be shown on the right. ### Plugins @@ -312,9 +312,9 @@ Switching views happens multiple ways. In some instances, it is automatic, such ![the sidebar ><](../img/sidebars.png "The Sidebar"){ width = "800" } -Once you have a file open, the sidebar lets you quickly access the most common features as sidebar panels and keeps them available while you work. These panels can be moved both upper left (1) and upper right (2) as well as to the bottom left (3), bottom right (4), and along the bottom left (5) and bottom right (5) in the middle. +Once you have a file open, the sidebar lets you quickly access the most common features as sidebar panels and keeps them available while you work. These panels can be moved to the upper-left (1), upper-right (2), lower-left (3), lower-right (4), bottom-left (5), and bottom-right (6) panel regions. - - 1-2: This section is where the majority of the primarily vertical panels reside. You can only have on larger item here at a time visible. The default behavior is for a click on another panel icon to hide the previous panel. However, this default can be overridden by using `[SHIFT]` click. If overridden, both the old panel and the new panel will be visible. + - 1-2: This section is where the majority of the primarily vertical panels reside. You can only have one larger item here at a time visible. The default behavior is for a click on another panel icon to hide the previous panel. However, this default can be overridden by using `[SHIFT]` click. If overridden, both the old panel and the new panel will be visible. - 3-4: This section is primarily for smaller panels where you may wish to toggle multiple on or off. Clicking a panel here will toggle its visibility without impacting other panels. Note that despite 4 not having any items in it by default, when you drag a panel icon to this region, you'll see the separator that separates 1/2 from 3/4 appear. - 5-6: Primarily for horizontal content, the bottom-most panel icon regions behave much like sections 1-2 except they are applied to two regions in the bottom of the window. Clicking a different icon in this region will switch to that panel, or hide that panel entirely if it is already selected. @@ -343,7 +343,7 @@ The Symbol List shows the following columns by default: Additionally, the following columns are hidden by default and can be enabled by right-clicking the header: -- `Total Bytes`: tn the case of functions, the sum of size of basic blocks +- `Total Bytes`: in the case of functions, the sum of size of basic blocks These columns can be re-arranged, hidden, and used for sorting. @@ -536,7 +536,7 @@ The search types are available from a drop-down next to the text input field and - Advanced Binary Search: A new search type using the [bv.search](https://api.binary.ninja/binaryninja.binaryview-module.html#binaryninja.binaryview.BinaryView.search) syntax (supporting regular expressions and wildcard hex strings) - Escaped: Escaped strings such as `OneString\x09\Tabsx09Another` - - Hex: All values much be valid hex characters such as `ebfffc390` and the bytes will only be searched for in this particular order + - Hex: All values must be valid hex characters such as `ebfffc390` and the bytes will only be searched for in this particular order - Raw: A simple string search that matches the exact string as specified - Text: Searches the decompilation or whatever view is currently selected for disassembly, BNIL, or Pseudo C - Constant: Useful for searching for a constant where the byte ordering is handled for you, such as `0x01020304` @@ -751,7 +751,7 @@ it into your clipboard. This section appears only in `BinaryView`s and the exact information depends on the view itself. PE headers are the most detailed and include such items as checksums, characteristics, and compiler strings. Addresses that -existing in the virtual memory space of the file can be clicked to navigate to that location. +exist in the virtual memory space of the file can be clicked to navigate to that location. ### 4. Base Address Detection (BASE) @@ -855,7 +855,7 @@ This section contains a list of conditionally-shown tags offering information ab - **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') + - **Basic analysis only**: This function only received basic 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 @@ -882,20 +882,24 @@ Pure functions are assumed to have no side effects and may be inlined if their r ### 8. Inline During Analysis -When Inline During Analysis is checked, it causes the function to be [inlined](https://api.binary.ninja/binaryninja.function-module.html#binaryninja.function.Function.inline_during_analysis) during analysis. +When Inline During Analysis is checked, it causes the function to be [inlined](https://api.binary.ninja/binaryninja.function-module.html#binaryninja.function.Function.inline_during_analysis) during analysis. The three options control whether instruction addresses are preserved per function or per call site. -### 9. Clobbered Registers +### 9. Signature Table -This section contains the list of registers that this function clobbers; individual registers can be checked or unchecked. +This section contains the function's return value and parameters as an editable table with columns for index, type, name, source, and location. -### 10. Return Registers +### 10. Clobbered Registers -Return registers shows the list of registers that this function returns data in; individual registers can be checked or unchecked. +This section contains the list of registers that this function clobbers; individual registers can be checked or unchecked. ### 11. Register Stack Adjustments This element is 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. +### 12. Function Workflow + +This dropdown selects the [function-level workflow](https://docs.binary.ninja/dev/workflows.html#workflow) which is used to analyze this function. + ## High Level IL ![HLIL Scoping Options >](../img/hlil-scope.png "HLIL Scoping Options"){ width="400" } @@ -1055,7 +1059,7 @@ The interactive python prompt also has several built-in "magic" functions and va - `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 +- `current_raw_offset`: the file offset that corresponds to 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) diff --git a/docs/guide/types/attributes.md b/docs/guide/types/attributes.md index c2f01992fb..34aa122159 100644 --- a/docs/guide/types/attributes.md +++ b/docs/guide/types/attributes.md @@ -72,7 +72,7 @@ struct Foo }; ``` -## Structures with Base Classes and Inheritence +## Structures with Base Classes and Inheritance See [Working with C++ Types and Virtual Function Tables](cpp.md). diff --git a/docs/guide/types/index.md b/docs/guide/types/index.md index 375533af8b..ce4328fe25 100644 --- a/docs/guide/types/index.md +++ b/docs/guide/types/index.md @@ -1,6 +1,6 @@ # Working with Types, Structures, and Symbols -There's so many things to learn about working with Types in Binary Ninja that we've organized it into several sections! +There are so many things to learn about working with Types in Binary Ninja that we've organized it into several sections! - [Basic Type Editing](basictypes.md): Brief overview of the basics - [Working with Types](type.md): Interacting with types in disassembly and decompilation diff --git a/docs/img/efp-dialog-diagram.png b/docs/img/efp-dialog-diagram.png index ebd8a96b36..cd7a5e3d34 100644 Binary files a/docs/img/efp-dialog-diagram.png and b/docs/img/efp-dialog-diagram.png differ