From 6ac3ea169e980b86c45c017892ef8a76fe5fb95d Mon Sep 17 00:00:00 2001 From: Jordan Wiens Date: Tue, 14 Feb 2017 13:39:02 -0500 Subject: add libgit2 to licensing info --- docs/about/open-source.md | 3 +++ 1 file changed, 3 insertions(+) (limited to 'docs') diff --git a/docs/about/open-source.md b/docs/about/open-source.md index f884b0b7..60b90635 100644 --- a/docs/about/open-source.md +++ b/docs/about/open-source.md @@ -27,6 +27,7 @@ The previous tools are used in the generation of our documentation, but are not - [discount] ([discount license] - BSD) - [sqlite] ([sqlite license] - public domain) - [llvm] ([llvm license] - BSD-style) + - [libgit2] ([libgit2 license] - GPLv2 with linking exception) * Other - [yasm] ([yasm license] - 2-clause BSD) @@ -72,6 +73,8 @@ Please note that we offer no support for running Binary Ninja with modified Qt l [sqlite license]: https://www.sqlite.org/copyright.html [llvm]: http://llvm.org/releases/3.8.1/ [llvm license]: http://llvm.org/releases/3.8.1/LICENSE.TXT +[libgit2]: https://libgit2.github.com/ +[libgit2 license]: https://github.com/libgit2/libgit2/blob/master/COPYING [yasm]: http://yasm.tortall.net/ [yasm license]: https://github.com/yasm/yasm/blob/master/BSD.txt [zlib]: http://www.zlib.net/ -- cgit v1.3.1 From 431dad36edd8c55a0c32759c7b939a5d017d5c46 Mon Sep 17 00:00:00 2001 From: Jordan Wiens Date: Fri, 17 Feb 2017 15:25:26 -0500 Subject: update aur link --- docs/guide/troubleshooting.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/guide/troubleshooting.md b/docs/guide/troubleshooting.md index af91f6f1..423a325c 100644 --- a/docs/guide/troubleshooting.md +++ b/docs/guide/troubleshooting.md @@ -42,7 +42,7 @@ QT_PLUGIN_PATH=./qt ./binaryninja - If the GUI launches but the license file is not valid when launched from the command-line, check that you're using the right version of Python. Only a 64-bit Python 2.7 is supported at this time. Additionally, the [personal][purchase] edition does not support headless operation. [known issues]: https://github.com/Vector35/binaryninja-api/issues?q=is%3Aissue -[libcurl-compat]: https://aur.archlinux.org/packages/libcurl-compat/ +[libcurl-compat]: https://www.archlinux.org/packages/community/x86_64/libcurl-compat/ [archrepo]: https://wiki.archlinux.org/index.php/Official_repositories [recover]: https://binary.ninja/recover.html [support]: https://binary.ninja/support.html -- cgit v1.3.1 From 27f1271083efb09efc6405f91be893ab38dad9a0 Mon Sep 17 00:00:00 2001 From: Jordan Wiens Date: Fri, 3 Mar 2017 18:10:53 -0500 Subject: add more linux troubleshooting --- docs/guide/troubleshooting.md | 12 ++++++++++-- 1 file changed, 10 insertions(+), 2 deletions(-) (limited to 'docs') diff --git a/docs/guide/troubleshooting.md b/docs/guide/troubleshooting.md index 423a325c..560b0f1f 100644 --- a/docs/guide/troubleshooting.md +++ b/docs/guide/troubleshooting.md @@ -22,10 +22,18 @@ Running Binary Ninja with debug logging will make your bug report more useful. Given the diversity of Linux distributions, some work-arounds are required to run Binary Ninja on platforms that are not [officially supported][faq]. +### Headless Ubuntu + +If you're having trouble getting Binary Ninja installed in a headless server install where you want to be able to X-Forward the GUI on a remote machine, the following should meet requiremetns (for at least 14.04 LTS): + +``` +apt-get install libgl1-mesa-glx libfontconfig1 libxrender1 libegl1-mesa libxi6 libnspr4 libsm6 +``` + ### Arch Linux - - Install python2 from the [official repositories][archrepo] - - Install the [libcurl-compat] library from AUR, and run Binary Ninja via `LD_PRELOAD=libcurl.so.3 ~/binaryninja/binaryninja` + - Install python2 from the [official repositories][archrepo] (`sudo pacman -S python2`) and create a sym link: `sudo ln -s /usr/lib/libpython2.7.so.1.0 /usr/lib/libpython2.7.so.1` + - Install the [libcurl-compat] library with `sudo pacman -S libcurl-compat`, and run Binary Ninja via `LD_PRELOAD=libcurl.so.3 ~/binaryninja/binaryninja` ### KDE -- cgit v1.3.1 From 10ac7c6fc5963dddda9b463a53f2757f1a3f9b18 Mon Sep 17 00:00:00 2001 From: Jordan Wiens Date: Mon, 17 Apr 2017 19:09:00 -0400 Subject: add LLIL dev tutorial --- docs/dev/bnil-llil.md | 272 ++++++++++++++++++++++++++++++++++++++++++++ docs/files/chal1 | Bin 0 -> 13144 bytes docs/images/BNIL.png | Bin 0 -> 297068 bytes docs/images/llil_option.png | Bin 0 -> 29139 bytes 4 files changed, 272 insertions(+) create mode 100644 docs/dev/bnil-llil.md create mode 100755 docs/files/chal1 create mode 100644 docs/images/BNIL.png create mode 100644 docs/images/llil_option.png (limited to 'docs') diff --git a/docs/dev/bnil-llil.md b/docs/dev/bnil-llil.md new file mode 100644 index 00000000..dac89765 --- /dev/null +++ b/docs/dev/bnil-llil.md @@ -0,0 +1,272 @@ +# Binary Ninja Intermediate Language Series, Part 1: Low Level IL + +The Binary Ninja Intermediate Language (BNIL) is a semantic representation of the assembly language instructions for a native architecture in Binary Ninja. BNIL is actually a family of intermediate languages that work together to provide functionality at different abstraction layers. This developer guide is intended to cover the design and structure of the different ILs with the goal of helping clarify which APIs are best for answering which types of questions or changing which types of data. + +In later guides, we'll look at other ILs. This one is just focused on the Low Level Intermediate Language (LLIL), the second stage intermediate language in BNIL. + +![BNIL-LLIL Selected](/images/BNIL.png) + +The Lifted IL is very similar to the LLIL and is primarily of interest for Architecture plugin authors. If you're writing an analysis plugin, you'll always want to be working at LLIL or higher. During each stage of the lifting process a number of transformations take place, and each layer of IL can have different instructions. Because of this, you can not rely on an instruction from one layer existing in another. + +## Introduction by example + +Since doing is the easiest way to learn lets start with a simple example binary and step through analyzing it using the python console. + +![Low Level IL Option >](/images/llil_option.png) + + - Download [chal1](../files/chal1) and open it with Binary Ninja + - Next, bring up the `Low Level IL` view by clicking in the options pane at the bottom of the screen + (or alternatively, use the `i` key) + - Finally, bring up the python console using: `~` + +Next, enter the following in the console: + +``` +>>> for block in current_function.low_level_il: +... for instr in block: +... print instr.address, instr.instr_index, instr +... +4196422 0 push(rbp) +4196423 1 rbp = rsp {var_8} +4196426 2 rsp = rsp - 0x110 +4196433 3 rax = rbp - 0xc0 {var_c8} +... +``` + +This will print out all the LLIL instructions in the current function. How does this code work? + +First we use the global magic variable `current_function` which gives us the python object [`function.Function`](http://api.binary.ninja/function.Function.html) for whatever function is currently selected in the UI. The variable is only usable from the python console, and shouldn't be used for headless plugins. In a script you can either use the function that was passed in if you [registered your plugin](https://api.binary.ninja/binaryninja.plugin-module.html#binaryninja.plugin.PluginCommand.register_for_function) to handle functions, or you can compute the function based on [a specific address](https://api.binary.ninja/binaryninja.binaryview-module.html?highlight=get_functions_at#binaryninja.binaryview.BinaryView.get_functions_at). + +Next we get the [`lowlevelil.LowLevelILFunction`](http://api.binary.ninja/binaryninja.lowlevelil.LowLevelILFunction.html) from the `Function` class: `current_function.low_level_il`. Iterating over the `LowLevelILFunction` class provides access to the [`lowlevelil.LowLevelILBasicBlock`](http://api.binary.ninja/binaryninja.lowlevelil.LowLevelILBasicBlock.html) classes for this function. Inside the loop we can now iterate over the `LowLevelILBasicBlock` class which provides access to the individual [`lowlevelil.LowLevelILInstruction`](http://api.binary.ninja/binaryninja.lowlevelil.LowLevelILInstruction.html) classes. + +Finally, we can print out the attributes of the instruction. We first print out `address` which is the address of the corresponding assembly language instruction. Next, we print the `instr_index`, this you can think of as the address of the IL instruction. Since translating assembly language is a many-to-many relationship we may see multiple IL instructions needed to represent a single assembly language instruction, and thus each IL instruction needs to have its own index separate from its address. Finally, we print out the instruction text. + +In python, iterating over a class is a distinct operation from subscripting. This separation is used in the `LowLevelILFunction` class. If you iterate over a `LowLevelILFunction` you get a list of `LowLevelILBasicBlocks`, however if you subscript a `LowLevelILFunction` you actually get the `LowLevelILInstruction` whose `instr_index` corresponds to the subscript: + +``` +>>> list(current_function.low_level_il) +[, , , + , , ] +>>> type(current_function.low_level_il[0]) + +>>> current_function.low_level_il[0] + +``` + +## Low Level IL Instructions +Now that we've established how to access LLIL Functions, Blocks, and Instructions, lets focus in on the instructions themselves. LLIL instructions are infinite length and structured as an expression tree. An expression tree means that instruction operands can be composed of operation. Thus we can have an IL instruction like this: + +``` +eax = eax + ecx * 4 +``` + +The tree for such an instruction would look like: + +``` + = + / \ +eax + + / \ + eax * + / \ + ecx 4 +``` +There are quite a few reasons that we chose to use expression trees that we won't go into in detail here, but suffice it to say lifting to this form and reading this form are both much easier than other forms. + +Now lets get back to the examples. First let's pick an instruction to work with: + +``` +>>> instr = current_function.low_level_il[2] +>>> instr + +``` + +For the above instruction, we have a few operations we can perform: + +* **address** - returns the virtual address + +``` +>>> hex(instr.address) +'0x40084aL' +``` +* **dest** - returns the destination operand + +``` +>>> instr.dest +'rsp' +``` +* **function** - returns the containing function + +``` +>>> instr.function + +``` +* **instr_index** - returns the LLIL index + +``` +>>> instr.instr_index +2 +``` +* **operands** - returns a list of all operands. + +``` +>>> instr.operands +['rsp', ] +``` +* **operation** - returns the enumeration value of the current operation + +``` +>>> instr.operation + +``` +* **src** - returns the source operand + +``` +>>> instr.src + +``` +* **dest** - returns the destination operand + +``` +>>> instr.dest +'rsp' +``` + +* **size** - returns the size of the operation in bytes (in this case we have an 8 byte assigment) + +``` +>>> instr.size +8L +``` + +Now with some knowledge of the `LowLevelIL` class lets try to do something with it. Lets say our goal is to find all the times the register `rdx` is written to in the current function. This code is straight forward: + +``` +>>> for block in current_function.low_level_il: +... for instr in block: +... if instr.operation == LowLevelILOperation.LLIL_SET_REG and instr.dest == 'rdx': +... print instr.address, instr.instr_index, instr +... +4196490 14 rdx = [rax].q +4196500 16 rdx = [rax + 8].q +4196511 18 rdx = [rax + 0x10].q +4196522 20 rdx = [rax + 0x18].q +4196533 22 rdx = [rax + 0x20].q +4196544 24 rdx = [rax + 0x28].q +4196798 77 rdx = [0x602090].q +``` + +## The Instructions + +Going into gross detail on all the instructions is out of scope of the this article, but we'll go over the different instructions types and speak generally about how they are used. + + +### Registers, Constants & Flags + +When parsing an instruction tree the terminals are registers, constants and flags. This provide the basis from which all instructions are built. + +* **`LLIL_REG`** - A register, terminal +* **`LLIL_CONST`** - A constant integer value, terminal +* **`LLIL_SET_REG`** - Sets a register to the results of the of the IL operation in `src` attribute. +* **`LLIL_SET_REG_SPLIT`** - Uses a pair of registers as one double sized register, setting both registers at once. +* **`LLIL_SET_FLAG`** - Sets the specified flag to the IL operation in `src` attribute. + +### Memory Load & Store + +Reading and writing memory is accomplished through the following instructions. + +* **`LLIL_LOAD`** - Load a value from memory. +* **`LLIL_STORE`** - Store a value to memory. +* **`LLIL_PUSH`** - Store value to stack adjusting stack pointer by sizeof(value) after the store. +* **`LLIL_POP`** - Load value from stack adjusting stack pointer by sizeof(value) after the store. + + +### Control Flow & Conditionals + +Control flow transfering instructions and comparison instructions are straight forward enough, but one instruction that deserves more attention is the `if` instruction. To understand the `if` instruction we need to first understand the concept of labels. + +Labels function much like they do in C code. They can be put anywhere in the emitted IL and serve as a destination for the `if` and `goto` instructions. Labels are required because one assembly language instruction can translate to multiple IL instructions, and you need to be able to branch to any of the emitted IL instructions. Lets consider the following x86 instruction `cmove` (Conditional move if equal flag is set): + +``` +test eax, eax +cmove eax, ebx +``` + +To translate this instruction to IL we have to first create true and false labels. Then we emit the `if` instruction, passing it the proper conditional and labels. Next we emit the true label, then we emit the set register instruction and a goto false label instruction. This results in the following output: + +``` +0 @ 00000002 if (eax == 0) then 1 else 3 +1 @ 00000002 eax = ebx +2 @ 00000002 goto 3 +``` + +As you can see from the above code labels are really just used internaly and aren't explicitly marked. In addition to `if` and `goto`, the `jump_to` IL instruction is the only other instruction that operates on labels. The rest of the IL control flow instructions operate on addresses rather than labels, much like actual assembly language instructions. Note that an architecture plugin author should not be emitting `jump_to` IL instructions as those are generated by the analysis automatically. + +* **`LLIL_JUMP`** - Branch execution to the result of the IL operation. +* **`LLIL_JUMP_TO`** - Jump table construct, contains an expression and list of possible targets. +* **`LLIL_CALL`** - Branch execution to the result of the IL operation. +* **`LLIL_RET`** - Return execution to the caller. +* **`LLIL_NORET`** - Instruction emitted automatically after syscall or call instruction which cause the program to terminate. +* **`LLIL_IF`** - If provides conditional execution. If cond is true execution branches to the true label and false label otherwise. +* **`LLIL_GOTO`** - Goto is used to branch to an IL label, this is different than jump since jump can only jump to addresses. +* **`LLIL_FLAG_COND`** - Returns the flag condition expression for the specified flag condition. +* **`LLIL_CMP_E`** - equality +* **`LLIL_CMP_NE`** - not equal +* **`LLIL_CMP_SLT`** - signed less than +* **`LLIL_CMP_ULT`** - unsigned less than +* **`LLIL_CMP_SLE`** - signed less than or equal +* **`LLIL_CMP_ULE`** - unsigned less than or equal +* **`LLIL_CMP_SGE`** - signed greater than or equal +* **`LLIL_CMP_UGE`** - unsigned greater than or equal +* **`LLIL_CMP_SGT`** - signed greater than +* **`LLIL_CMP_UGT`** - unsigned greater than + + +### The Arithmatic & Logical Instructions + +LLIL implements the most common arithmetic as well as a host of more complicated instruction which make translating from assembly much easier. Most arithmetic and logical instruction contain `left` and `right` attributes which can themselves be other IL instructions. + +The double precision instruction multiply, divide, modulus instructions are particularly helpful for instruction sets like x86 whose output/input can be double the size of the input/output. + +* **`LLIL_ADD`** - Add +* **`LLIL_ADC`** - Add with carry +* **`LLIL_SUB`** - Subtract +* **`LLIL_SBB`** - Subtract with borrow +* **`LLIL_AND`** - Bitwise and +* **`LLIL_OR`** - Bitwise or +* **`LLIL_XOR`** - Exclusive or +* **`LLIL_LSL`** - Logical shift left +* **`LLIL_LSR`** - Logical shift right +* **`LLIL_ASR`** - Arithmetic shift right +* **`LLIL_ROL`** - Rotate left +* **`LLIL_RLC`** - Rotate left with carry +* **`LLIL_ROR`** - Rotate right +* **`LLIL_RRC`** - Rotate right with carry +* **`LLIL_MUL`** - Multiply single precision +* **`LLIL_MULU_DP`** - Unsigned multiply double precision +* **`LLIL_MULS_DP`** - Signed multiply double precision +* **`LLIL_DIVU`** - Unsigned divide single precision +* **`LLIL_DIVU_DP`** - Unsigned divide double precision +* **`LLIL_DIVS`** - Signed divide single precision +* **`LLIL_DIVS_DP`** - Signed divide double precision +* **`LLIL_MODU`** - Unsigned modulus single precision +* **`LLIL_MODU_DP`** - Unsigned modulus double precision +* **`LLIL_MODS`** - Signed modulus single precision +* **`LLIL_MODS_DP`** - Signed modulus double precision +* **`LLIL_NEG`** - Sign negation +* **`LLIL_NOT`** - Bitwise complement + +### Special instructions + +The rest of the instructions are pretty much self explanitory to anyone with familiarity with assembly languages. + +* **`LLIL_NOP`** - No operation +* **`LLIL_SX`** - Sign extend +* **`LLIL_ZX`** - Zero extend +* **`LLIL_SYSCALL`** - System call instruction +* **`LLIL_BP`** - Breakpoint instruction +* **`LLIL_TRAP`** - Trap instruction +* **`LLIL_UNDEF`** - Undefined instruction +* **`LLIL_UNIMPL`** - Unimplemented instruction +* **`LLIL_UNIMPL_MEM`** - Unimplemented memory access instruction + diff --git a/docs/files/chal1 b/docs/files/chal1 new file mode 100755 index 00000000..faacef0d Binary files /dev/null and b/docs/files/chal1 differ diff --git a/docs/images/BNIL.png b/docs/images/BNIL.png new file mode 100644 index 00000000..37fc9997 Binary files /dev/null and b/docs/images/BNIL.png differ diff --git a/docs/images/llil_option.png b/docs/images/llil_option.png new file mode 100644 index 00000000..ee42c3b9 Binary files /dev/null and b/docs/images/llil_option.png differ -- cgit v1.3.1 From 303a1501096ef09cace965f7bf7a95f8e32454cc Mon Sep 17 00:00:00 2001 From: Jordan Wiens Date: Mon, 17 Apr 2017 19:09:20 -0400 Subject: update css to support different image alignment --- docs/docs.css | 25 ++++++++++++++++++++----- docs/getting-started.md | 18 +++++++++--------- mkdocs.yml | 1 + 3 files changed, 30 insertions(+), 14 deletions(-) (limited to 'docs') diff --git a/docs/docs.css b/docs/docs.css index 95a04efe..5006119f 100644 --- a/docs/docs.css +++ b/docs/docs.css @@ -2,12 +2,27 @@ code { color: #000; } -img { - display: inline-block; - float: right; -} - .admonition { background: rgb(128, 198, 223); color: #333; } + +img[alt$=">"] { + float:right; + display: inline-block; + padding-left: 10px; +} + +img[alt$="<"] { + float:left; + display: inline-block; + padding-right: 10px; +} + +img[alt$="><"] { + display: block; + max-width: 100%; + height: auto; + margin: auto; + float: none!important; +} diff --git a/docs/getting-started.md b/docs/getting-started.md index b7d01115..dbc99ae3 100644 --- a/docs/getting-started.md +++ b/docs/getting-started.md @@ -2,7 +2,7 @@ Welcome to Binary Ninja. This introduction document is meant to quickly guide you over some of the most common uses of Binary Ninja. -![license popup](/images/license-popup.png "License Popup") +![license popup >](/images/license-popup.png "License Popup") ## License @@ -30,7 +30,7 @@ You can load files in many ways: ## Analysis -![auto analysis](/images/analysis.png "Auto Analysis") +![auto analysis ><](/images/analysis.png "Auto Analysis") As soon as you open a file, Binary Ninja begins its auto-analysis. @@ -79,7 +79,7 @@ Switching views happens multiple ways. In some instances, it's automatic (clicki The default view in Binary Ninja when opening a binary is a graph view that groups the basic blocks of disassembly into visually distinct blocks with edges showing control flow between them. -![graph view context](/images/graphcontext.png "Graph View Contet Menu") +![graph view context >](/images/graphcontext.png "Graph View Contet Menu") Features of the graph view include: @@ -93,7 +93,7 @@ Features of the graph view include: ### View Options -![options](/images/options.png "options") +![options ><](/images/options.png "options") Each of the views (Hex, Graph, Linear) have a variety of options configurable in the bottom-right of the UI. @@ -126,7 +126,7 @@ Current options include: ### Hex View -![hex](/images/hex.png "hex view") +![hex >](/images/hex.png "hex view") The hexadecimal view is useful for view raw binary files that may or may not even be executable binaries. The hex view is particularly good for transforming data in various ways via the `Copy as`, `Transform`, and `Paste from` menus. Note that `Transform` menu options will transform the data in-place, and that these options will only work when the Hex View is in the `Raw` mode as opposd to any of the binary views (such as "ELF", "Mach-O", or "PE"). @@ -134,7 +134,7 @@ Note that any changes made in the Hex view will take effect immediately in any o ### Xrefs View -![xrefs](/images/xrefs.png "xrefs") +![xrefs >](/images/xrefs.png "xrefs") The xrefs view in the lower-left shows all cross-references to a given location or reference. Note that the cross-references pane will change depending on whether an entire line is selected (all cross-references to that address are shown), or whether a specific token within the line is selected. @@ -151,7 +151,7 @@ Linear view is most commonly used for identifying and adding type information fo ### Function List -![function list](/images/functionlist.png "Function List") +![function list >](/images/functionlist.png "Function List") The function list in Binary Ninja shows the list of functions currently identified. As large binaries are analyzed, the list may grow during analysis. The function list starts with known functions such as the entry point, exports, or using other features of the binary file format and explores from there to identify other functions. @@ -162,7 +162,7 @@ The function list also highlights imports, and functions identified with symbols ### Script (Python) Console -![console](/images/console.png "Console") +![console >](/images/console.png "Console") The integrated script console is useful for small scripts that aren't worth writing as full plugins. @@ -188,7 +188,7 @@ Note ## Preferences/Updates -![preferences](/images/preferences.png "Preferences") +![preferences >](/images/preferences.png "Preferences") Binary Ninja automatically updates itself by default. This functionality can be disabled in the preferences by turning off the `Update to latest version automatically` option. Updates are silently downloaded in the background and when complete an option to restart is displayed in the status bar. Whenever Binary Ninja restarts next, it will replace itself with the new version as it launches. diff --git a/mkdocs.yml b/mkdocs.yml index 1040aa75..ba081219 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -31,6 +31,7 @@ pages: - Troubleshooting: 'guide/troubleshooting.md' - Developer Guide: - Contributing Documentation: 'dev/documentation.md' + - BNIL Guide, LLIL: 'dev/bnil-llil.md' #- Plugin Design: 'dev/plugins.md' #- API: 'dev/api.md' - About: -- cgit v1.3.1 From 57816e7d25fa37757dfa823feba1f5cb7a233625 Mon Sep 17 00:00:00 2001 From: Jordan Wiens Date: Mon, 17 Apr 2017 19:54:01 -0400 Subject: update intro, fix typo, more explanation on ways to iterate over functions --- docs/dev/bnil-llil.md | 9 ++++----- 1 file changed, 4 insertions(+), 5 deletions(-) (limited to 'docs') diff --git a/docs/dev/bnil-llil.md b/docs/dev/bnil-llil.md index dac89765..7748d140 100644 --- a/docs/dev/bnil-llil.md +++ b/docs/dev/bnil-llil.md @@ -1,8 +1,6 @@ # Binary Ninja Intermediate Language Series, Part 1: Low Level IL -The Binary Ninja Intermediate Language (BNIL) is a semantic representation of the assembly language instructions for a native architecture in Binary Ninja. BNIL is actually a family of intermediate languages that work together to provide functionality at different abstraction layers. This developer guide is intended to cover the design and structure of the different ILs with the goal of helping clarify which APIs are best for answering which types of questions or changing which types of data. - -In later guides, we'll look at other ILs. This one is just focused on the Low Level Intermediate Language (LLIL), the second stage intermediate language in BNIL. +The Binary Ninja Intermediate Language (BNIL) is a semantic representation of the assembly language instructions for a native architecture in Binary Ninja. BNIL is actually a family of intermediate languages that work together to provide functionality at different abstraction layers. This developer guide is intended to cover some of the mechanics of the LLIL to distinguish it from the other ILs in the BNIL family. ![BNIL-LLIL Selected](/images/BNIL.png) @@ -17,6 +15,7 @@ Since doing is the easiest way to learn lets start with a simple example binary - Download [chal1](../files/chal1) and open it with Binary Ninja - Next, bring up the `Low Level IL` view by clicking in the options pane at the bottom of the screen (or alternatively, use the `i` key) + - Navigate to main (`g`, then "main", or double-click it in the function list) - Finally, bring up the python console using: `~` Next, enter the following in the console: @@ -35,7 +34,7 @@ Next, enter the following in the console: This will print out all the LLIL instructions in the current function. How does this code work? -First we use the global magic variable `current_function` which gives us the python object [`function.Function`](http://api.binary.ninja/function.Function.html) for whatever function is currently selected in the UI. The variable is only usable from the python console, and shouldn't be used for headless plugins. In a script you can either use the function that was passed in if you [registered your plugin](https://api.binary.ninja/binaryninja.plugin-module.html#binaryninja.plugin.PluginCommand.register_for_function) to handle functions, or you can compute the function based on [a specific address](https://api.binary.ninja/binaryninja.binaryview-module.html?highlight=get_functions_at#binaryninja.binaryview.BinaryView.get_functions_at). +First we use the global magic variable `current_function` which gives us the python object [`function.Function`](http://api.binary.ninja/function.Function.html) for whatever function is currently selected in the UI. The variable is only usable from the python console, and shouldn't be used for headless plugins. In a script you can either use the function that was passed in if you [registered your plugin](https://api.binary.ninja/binaryninja.plugin-module.html#binaryninja.plugin.PluginCommand.register_for_function) to handle functions, or you can compute the function based on [a specific address](https://api.binary.ninja/binaryninja.binaryview-module.html?highlight=get_functions_at#binaryninja.binaryview.BinaryView.get_functions_at), or maybe even just iterate over all the functions in a BinaryView (`for func in bv.functions:`). Next we get the [`lowlevelil.LowLevelILFunction`](http://api.binary.ninja/binaryninja.lowlevelil.LowLevelILFunction.html) from the `Function` class: `current_function.low_level_il`. Iterating over the `LowLevelILFunction` class provides access to the [`lowlevelil.LowLevelILBasicBlock`](http://api.binary.ninja/binaryninja.lowlevelil.LowLevelILBasicBlock.html) classes for this function. Inside the loop we can now iterate over the `LowLevelILBasicBlock` class which provides access to the individual [`lowlevelil.LowLevelILInstruction`](http://api.binary.ninja/binaryninja.lowlevelil.LowLevelILInstruction.html) classes. @@ -222,7 +221,7 @@ As you can see from the above code labels are really just used internaly and are * **`LLIL_CMP_UGT`** - unsigned greater than -### The Arithmatic & Logical Instructions +### The Arithmetic & Logical Instructions LLIL implements the most common arithmetic as well as a host of more complicated instruction which make translating from assembly much easier. Most arithmetic and logical instruction contain `left` and `right` attributes which can themselves be other IL instructions. -- cgit v1.3.1 From 93020159006b68c5e0e5b1eafeef11d1df72da1a Mon Sep 17 00:00:00 2001 From: Jordan Wiens Date: Tue, 18 Apr 2017 15:37:25 -0400 Subject: fix transparency on code blocks --- docs/docs.css | 4 ++++ 1 file changed, 4 insertions(+) (limited to 'docs') diff --git a/docs/docs.css b/docs/docs.css index 5006119f..e06fa460 100644 --- a/docs/docs.css +++ b/docs/docs.css @@ -26,3 +26,7 @@ img[alt$="><"] { margin: auto; float: none!important; } + +.article pre code { + background: rgba(0, 0, 0, 0); +} -- cgit v1.3.1 From d52a25252a96963ab4d48a9df9138b4329cb45bc Mon Sep 17 00:00:00 2001 From: lucasduffey Date: Wed, 26 Apr 2017 10:43:19 -0700 Subject: skip the support redirect --- docs/getting-started.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/getting-started.md b/docs/getting-started.md index dbc99ae3..737a1d05 100644 --- a/docs/getting-started.md +++ b/docs/getting-started.md @@ -200,4 +200,4 @@ Most preferences are fairly intuitive. There is no advanced preference system at Vector 35 offers a number of ways to get Binary Ninja [support]. -[support]: https://binary.ninja/support.html +[support]: https://binary.ninja/support/ -- cgit v1.3.1 From 3501dd765d8ad917fb60b72f2e6983ed76eb31bc Mon Sep 17 00:00:00 2001 From: Jordan Wiens Date: Tue, 23 May 2017 20:48:42 -0400 Subject: basic plugin usage --- docs/getting-started.md | 14 ++++++++++++++ docs/guide/troubleshooting.md | 6 +++++- 2 files changed, 19 insertions(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/getting-started.md b/docs/getting-started.md index dbc99ae3..53aba268 100644 --- a/docs/getting-started.md +++ b/docs/getting-started.md @@ -14,6 +14,10 @@ Once the license key is installed, you can change it, back it up, or otherwise i - Linux: `~/.binaryninja` - Windows: `%APPDATA%\Binary Ninja` +## Linux Setup + +Because linux install locations can vary widely, we do not assume a 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: @@ -186,6 +190,16 @@ 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 with 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: + +- OS X: `~/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. + ## Preferences/Updates ![preferences >](/images/preferences.png "Preferences") diff --git a/docs/guide/troubleshooting.md b/docs/guide/troubleshooting.md index 560b0f1f..efd9fab9 100644 --- a/docs/guide/troubleshooting.md +++ b/docs/guide/troubleshooting.md @@ -3,7 +3,7 @@ ## Basics - Have you searched [known issues]? - - Is your computer powered on? + - Have you tried rebooting? (Kidding!) - Did you read all the items on this page? - Then you should contact [support]! @@ -13,6 +13,10 @@ Running Binary Ninja with debug logging will make your bug report more useful. ./binaryninja --debug --stderr-log ``` +## Plugin Troubleshooting + +While third party plugins are not officially supported, there are a number of troubleshooting tips that can help identify the cause. The most importat is to enable debug logging as suggested in the previous section. This will often highlight problems with python paths or any other issues that prevent plugins from running. + ## 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/index.html#license). -- cgit v1.3.1