Skip to content

Commit

Permalink
Update plugin.json and README for public (re)release
Browse files Browse the repository at this point in the history
  • Loading branch information
Eric Hennenfent committed Jul 10, 2020
1 parent e261756 commit 20d639c
Show file tree
Hide file tree
Showing 2 changed files with 26 additions and 26 deletions.
8 changes: 3 additions & 5 deletions README.md
Original file line number Diff line number Diff line change
@@ -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.
Expand Down Expand Up @@ -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.

Expand All @@ -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.

Expand Down
44 changes: 23 additions & 21 deletions plugin.json
Original file line number Diff line number Diff line change
@@ -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
}

0 comments on commit 20d639c

Please sign in to comment.