diff --git a/README.md b/README.md index 3df9775..4291f12 100644 --- a/README.md +++ b/README.md @@ -1,9 +1,9 @@ -# binja_explain_instruction +# Explain Instruction plugin for Binary Ninja This plugin adds a popup window to Binary Ninja that explains in simple English what an assembly instruction does. ![Example Screenshot](https://raw.githubusercontent.com/ehennenfent/binja_explain_instruction/master/Examples/screenshot.png) -### Read the Limitations section in detail before using this plugin, or you may find it confuses you more than it helps you. +#### It's worth reading the [Limitations section](#limitations) before using this plugin! ## Assumed Knowledge Level The descriptions are intended to be simple enough for a novice to understand. However, there is some previous knowledge assumed, notably that the reader understands the concepts of a register, an instruction, the stack, CPU flags, etc. Consider taking a look at [Beginners.re](https://beginners.re/) if you need help with the background. @@ -33,7 +33,7 @@ Copies ((the 4 bytes of memory starting at (rbp + -0x54)) + 0xa) into memory at ``` ## Limitations -There are over 600 instructions in the current x86 instruction set alone. Rather than attempt to parse them all, the explanations here are generated by reading the corresponding Binary Ninja Low-Level Intermediate Language, which operates at a higher level. Unfortunately, the LLIL does not support corresponding operations for the entire x86 instruction set. A small portion of the x86 instructions with no LLIL equivalent have been added, but nowhere near enough to cover the entire instruction set. This project will aid beginners in understanding what common instructions do, and will hopefully help with some of the "What on earth does that instruction do?" moments, but will certainly not be able to replace consulting the documentation. +There are over 600 instructions in the current x86 instruction set alone. Rather than attempt to parse them all, the explanations here are generated by reading the corresponding Binary Ninja Low-Level Intermediate Language, which operates at a higher level. Unfortunately, the LLIL does not support corresponding operations for the entire x86 instruction set. A small portion of the x86 instructions with no LLIL equivalent have been added, but nowhere near enough to cover the entire instruction set. This project will aid beginners in understanding what common instructions do, and will hopefully help with some of the "What on earth does that instruction do?" moments, but probably can't replace consulting the documentation. For most instructions, this plugin parses the Low-Level IL that you may be used to seeing in the interface (accessed via the `i` hotkey). However, for some instructions, no Low-Level IL equivalent is available. In those cases, we instead use the Lifted IL (Options > Other IL Forms > Lifted IL), which is a less complicated form of the Low-Level Intermediate Language that corresponds more closely to the assembly instructions. See the [IL Manifest](https://github.com/ehennenfent/binja_explain_instruction/blob/master/IL_MANIFEST.md) for more details. @@ -45,8 +45,6 @@ Since this project is based on the Low-Level intermediate language, it may provi The Medium Level IL functions at a significantly higher level than the Lifted IL, which means that each MLIL instruction is typically the product of several LLIL instructions. The "equivalent" MLIL for an instruction is displayed when available, as it is particularly helpful for understanding what parameters are passed to a function, but **don't assume a 1-to-1 equivalency between the MLIL and the assembly**. Use it for a helpful cross reference, or consult the MLIL view for a high-level overview of the entire program. -This plugin has only been tested on 64-bit Ubuntu 16.04. However, since it does not rely on any strictly os-dependent code, it will likely work on other platforms. - ## Contributing This plugin is designed to make it simple to add support for new LLIL instructions or additional architectures. See [CONTRIBUTING.md](https://github.com/ehennenfent/binja_explain_instruction/blob/master/CONTRIBUTING.md). If you come across any inaccuracies, feel free to file a pull request or create an issue. diff --git a/plugin.json b/plugin.json index c242bc1..76c64bf 100644 --- a/plugin.json +++ b/plugin.json @@ -1,25 +1,27 @@ { - "plugin": { - "name": "Explain Instruction", - "type": ["ui", "education"], - "api": "python3", - "description": "Displays a window that explains in simple English what an assembly instruction does", - "longdescription": "Parses the Lifted IL for an instruction and uses it to generate an English description of what an instruction does. Works best on x86 and x86_64. See: https://github.com/ehennenfent/binja_explain_instruction/blob/master/README.md", - "license": { + "pluginmetadataversion" : 2, + "name": "Explain Instruction", + "type": ["ui","helper"], + "api": ["python3"], + "description": "Displays a window that explains in simple English what an assembly instruction does", + "longdescription": "Parses the Lifted IL for an instruction and uses it to (attempt to) generate an English description of what an instruction does. See also: [README.md](https://github.com/ehennenfent/binja_explain_instruction/blob/master/README.md)", + "license": { "name": "Apache 2", "text": "https://github.com/ehennenfent/binja_explain_instruction/blob/master/LICENSE" - }, - "dependencies": { - "pip": [], - "apt": [], - "installers": [], - "other": [] - }, - "version": "1.0 alpha", - "author": "Eric Hennenfent", - "minimumBinaryNinjaVersion": { - "dev": "1.2", - "release": "1.2" - } - } + }, + "platforms" : ["Darwin", "Linux", "Windows"], + "dependencies": { + "pip": [], + "apt": [], + "installers": [], + "other": [] + }, + "installinstructions" : { + "Darwin" : "", + "Linux" : "", + "Windows" : "" + }, + "version": "0.1.0-alpha", + "author": "Eric Hennenfent", + "minimumbinaryninjaversion": 1200 }