|
| 1 | +# Patching - Interactive Binary Patching for IDA Pro |
| 2 | + |
| 3 | +<p align="center"><img alt="Patching Plugin" src="screenshots/title.png"/></p> |
| 4 | + |
| 5 | +## Overview |
| 6 | + |
| 7 | +Patching assembly code to change the behavior of an existing program is not uncommon in malware analysis, software reverse engineering, and broader domains of security research. This project extends the popular [IDA Pro](https://www.hex-rays.com/products/ida/) disassembler to create a more robust interactive binary patching workflow designed for rapid iteration. |
| 8 | + |
| 9 | +This project is currently powered by a minor [fork](https://github.com/gaasedelen/keystone) of the ubiquitous [Keystone Engine](https://github.com/keystone-engine/keystone), supporting x86/x64 and Arm/Arm64 patching with plans to enable the remaining Keystone architectures in a future release. |
| 10 | + |
| 11 | +Special thanks to [Hex-Rays](https://hex-rays.com/) for supporting the development of this plugin. |
| 12 | + |
| 13 | +## Releases |
| 14 | + |
| 15 | +* v0.1 -- Initial release |
| 16 | + |
| 17 | +# Installation |
| 18 | + |
| 19 | +This plugin requires IDA 7.6 and Python 3. It supports Windows, Linux, and macOS. |
| 20 | + |
| 21 | +## Easy Install |
| 22 | + |
| 23 | +Run the following line in the IDA console to automatically install the plugin: |
| 24 | + |
| 25 | +### Windows / Linux |
| 26 | + |
| 27 | +```python |
| 28 | +import urllib.request as r; exec(r.urlopen('https://github.com/gaasedelen/patching/raw/main/install.py').read()) |
| 29 | +``` |
| 30 | + |
| 31 | +### macOS |
| 32 | + |
| 33 | +```python |
| 34 | +import urllib.request as r; exec(r.urlopen('https://github.com/gaasedelen/patching/raw/main/install.py', cafile='/etc/ssl/cert.pem').read()) |
| 35 | +``` |
| 36 | + |
| 37 | +## Manual Install |
| 38 | + |
| 39 | +Alternatively, the plugin can be manually installed by downloading the distributable plugin package for your respective platform from the [releases](https://github.com/gaasedelen/patching/releases) page and unzipping it to your plugins folder. |
| 40 | + |
| 41 | +It is __*strongly*__ recommended you install this plugin into IDA's user plugin directory: |
| 42 | + |
| 43 | +```python |
| 44 | +import ida_diskio, os; print(os.path.join(ida_diskio.get_user_idadir(), "plugins")) |
| 45 | +``` |
| 46 | + |
| 47 | +# Usage |
| 48 | + |
| 49 | +The patching plugin will automatically load for supported architectures (x86/x64/Arm/Arm64) and inject relevant patching actions into the right click context menu of the IDA disassembly views: |
| 50 | + |
| 51 | +<p align="center"><img alt="Patching plugin right click context menu" src="screenshots/usage.gif"/></p> |
| 52 | + |
| 53 | +A complete listing of the contextual patching actions are described in the following sections. |
| 54 | + |
| 55 | +## Assemble |
| 56 | + |
| 57 | +The main patching dialog can be launched via the Assemble action in the right click context menu. It simulates a basic IDA disassembly view that can be used to edit one or several instructions in rapid succession. |
| 58 | + |
| 59 | +<p align="center"><img alt="The interactive patching dialog" src="screenshots/assemble.gif"/></p> |
| 60 | + |
| 61 | +The assembly line is an editable field that can be used to modify instructions in real-time. Pressing enter will commit (patch) the entered instruction into the database. |
| 62 | + |
| 63 | +Your current location (a.k.a your cursor) will always be highlighted in green. Instructions that will be clobbered as a result of your patch / edit will be highlighted in red prior to committing the patch. |
| 64 | + |
| 65 | +<p align="center"><img alt="Additional instructions that will be clobbered by a patch show up as red" src="screenshots/clobber.png"/></p> |
| 66 | + |
| 67 | +Finally, the `UP` and `DOWN` arrow keys can be used while still focused on the editable assembly text field to quickly move the cursor up and down the disassembly view without using the mouse. |
| 68 | + |
| 69 | +## NOP |
| 70 | + |
| 71 | +The most common patching action is to NOP out one or more instructions. For this reason, the NOP action will always be visible in the right click menu for quick access. |
| 72 | + |
| 73 | +<p align="center"><img alt="Right click NOP instruction" src="screenshots/nop.gif"/></p> |
| 74 | + |
| 75 | +Individual instructions can be NOP'ed, as well as a selected range of instructions. |
| 76 | + |
| 77 | +## Force Conditional Jump |
| 78 | + |
| 79 | +Forcing a conditional jump to always execute a 'good' path is another common patching action. The plugin will only show this action when right clicking a conditional jump instruction. |
| 80 | + |
| 81 | +<p align="center"><img alt="Forcing a conditional jump" src="screenshots/forcejump.gif"/></p> |
| 82 | + |
| 83 | +If you *never* want a conditional jump to be taken, you can just NOP it instead! |
| 84 | + |
| 85 | +## Save & Quick Apply |
| 86 | + |
| 87 | +Patches can be saved (applied) to a selected executable via the patching submenu at any time. The quick-apply action makes it even faster to save subsequent patches using the same settings. |
| 88 | + |
| 89 | +<p align="center"><img alt="Applying patches to the original executable" src="screenshots/save.gif"/></p> |
| 90 | + |
| 91 | +The plugin will also make an active effort to retain a backup (`.bak`) of the original executable which it uses to 'cleanly' apply the current set of database patches during each save. |
| 92 | + |
| 93 | +## Revert Patch |
| 94 | + |
| 95 | +Finally, if you are ever unhappy with a patch you can simply right click patched (yellow) blocks of instructions to revert them to their original value. |
| 96 | + |
| 97 | +<p align="center"><img alt="Reverting patches" src="screenshots/revert.gif"/></p> |
| 98 | + |
| 99 | +While it is 'easy' to revert bytes back to their original value, it can be 'hard' to restore analysis to its previous state. Reverting a patch may *occasionally* require additional human fixups. |
| 100 | + |
| 101 | +# Known Bugs |
| 102 | + |
| 103 | +* Further improve ARM / ARM64 / THUMB correctness |
| 104 | +* Define 'better' behavior for cpp::like::symbols(...) / IDBs (very sketchy right now) |
| 105 | +* Adding / Updating / Modifying / Showing / Warning about Relocation Entries?? |
| 106 | +* Handle renamed registers (like against dwarf annotated idb)? |
| 107 | +* A number of new instructions (circa 2017 and later) are not supported by Keystone |
| 108 | +* A few problematic instruction encodings by Keystone |
| 109 | + |
| 110 | +# Future Work |
| 111 | + |
| 112 | +Time and motivation permitting, future work may include: |
| 113 | + |
| 114 | +* Enable the remaining major architectures supported by Keystone: |
| 115 | + * PPC32 / PPC64 / MIPS32 / MIPS64 / SPARC / SystemZ |
| 116 | +* Multi instruction assembly (eg. `xor eax, eax; ret;`) |
| 117 | +* Multi line assembly (eg. shellcode / asm labels) |
| 118 | +* Interactive byte / data / string editing |
| 119 | +* Symbol hinting / auto-complete / fuzzy-matching |
| 120 | +* Syntax highlighting the editable assembly line |
| 121 | +* Better hinting of errors, syntax issues, etc |
| 122 | +* NOP / Force Jump from Hex-Rays view (sounds easy, but probably pretty hard!) |
| 123 | +* radio button toggle between 'pretty print' mode vs 'raw' mode? or display both? |
| 124 | + ``` |
| 125 | + Pretty: mov [rsp+48h+dwCreationDisposition], 3 |
| 126 | + Raw: mov [rsp+20h], 3 |
| 127 | + ``` |
| 128 | + |
| 129 | +I welcome external contributions, issues, and feature requests. Please make any pull requests to the `develop` branch of this repository if you would like them to be considered for a future release. |
| 130 | + |
| 131 | +# Authors |
| 132 | + |
| 133 | +* Markus Gaasedelen ([@gaasedelen](https://twitter.com/gaasedelen)) |
0 commit comments