KeyPatch Enhanced — IDA Pro Symbol-Aware Assembly Plugin

An enhanced fork based on Keypatch (by Nguyen Anh Quynh & Thanh Nguyen), modified by Euarno.

Core improvement: Directly use IDA symbol names in x86/x64 assembly, the plugin automatically resolves addresses and generates correct RIP-relative / rel32 encoding.

---

New Features

1. Assemble Directly Using Symbol Names

Enter instructions with symbol names directly in the Keypatch dialog, no need to manually calculate addresses and offsets:

call rc4_crypt          ; automatically calculates rel32 relative offset
jmp  main               ; same as above
lea  rcx, enc_0         ; x64: automatically generates lea rcx, [rip + disp32]
lea  rax, Format         ; same as above

2. IDA Name Auto-Correction (_ ↔ .)

IDA sometimes displays . in the database as _ (e.g., enc.0 displayed as enc_0). The plugin automatically attempts _ → . variant lookup, no need to worry about IDA's internal storage format.

3. Supported Instruction Types

Type	Example	Handling
CALL / JMP / Jcc	call func_name	Symbol → absolute address, Keystone calculates rel32
LEA (bare symbol)	lea rcx, symbol	x64: → lea rcx, [rip + disp32] x86: → lea ecx, [addr]
LEA (compound operand)	lea rcx, [rbp+0x120+Str]	Only replaces symbol with address value, preserves expression structure
MOV offset	mov rax, offset symbol	x64: converts to lea rax, [rip + disp32] uses mov rax, imm64 if out of range
Memory access [symbol]	mov rax, qword ptr [symbol]	[symbol] → [0xADDR], Keystone auto-encodes
Immediate symbol	push symbol	Symbol → 0xADDR

4. Enhanced Error Messages

When assembly fails, the output window displays:

Keypatch: Keystone error: Invalid operand (KS_ERR_ASM_INVALIDOPERAND)
Keypatch:   input asm  : lea rcx, [rip + 0x176E3]
Keypatch:   fixed asm  : LEA RCX, [RIP + 0x176E3]
Keypatch:   address    : 0x140001966

---

Installation

Prerequisites

• IDA Pro 7.0+
• Keystone Engine Python bindings

pip install keystone-engine

Installing the Plugin

Copy keypatch.py to IDA's plugins directory:

System	Path
Windows	%APPDATA%\Hex-Rays\IDA Pro\plugins\ or <IDA installation directory>\plugins\
macOS	~/.idapro/plugins/ or <IDA installation directory>/plugins/
Linux	~/.idapro/plugins/ or <IDA installation directory>/plugins/

Restart IDA to complete.

---

Usage

Opening the Patcher

• Menu: Edit → Keypatch → Patcher
• Shortcut: Ctrl + Alt + K
• Right-click menu: Keypatch → Patcher

Basic Workflow

1. In the IDA disassembly window, position the cursor at the target address
2. Press Ctrl + Alt + K to open the Patcher
3. Enter the instruction in the Assembly field (IDA symbol names can be used)
4. Check the Encoding field to confirm the encoding is correct
5. Click Patch to apply the modification

Example: Hook a Function Call

Suppose you want to patch a jump to rc4_crypt at 0x140001966:

Assembly: call rc4_crypt

The plugin automatically resolves the address of rc4_crypt, calculates the rel32 offset, and generates the correct E8 xx xx xx xx encoding.

Example: Load a Data Address

Assembly: lea rcx, enc_0

The plugin automatically:

1. Resolves enc_0 (internal name may be enc.0) → address 0x140013050
2. Calculates RIP-relative offset disp32 = 0x140013050 - (0x140001966 + 7)
3. Generates lea rcx, [rip + 0x176E3]
4. Passes to Keystone for encoding into machine code

Fill Range

1. Select an address range in the disassembly window
2. Press Ctrl + Alt + K to open Fill Range
3. Enter the instruction (e.g., nop), automatically fills the entire range

Undo

• Menu: Edit → Keypatch → Undo last patching

---

Notes

• RIP-relative range limit: The RIP-relative addressing range for lea and [symbol] is ±2GB. If the symbol is out of range, the plugin will report an error.
• x64 immediate limit: For push symbol on x64, the symbol address must be ≤ 0x7FFFFFFF (imm32 sign extension), otherwise a warning will appear. It is recommended to use lea reg, symbol + push reg instead.
• Semicolon multi-statement: Multi-statement symbol resolution in the form lea rcx, sym; call func is not currently supported. Please patch one instruction at a time.

---

Original Project

• Original Authors: Nguyen Anh Quynh (@aquynh) & Thanh Nguyen
• Original Project: keystone-engine/keypatch
• Original License: GPL v2
• Project Homepage: http://keystone-engine.org/keypatch
• Keystone Engine: http://www.keystone-engine.org

Modifier

• Euarno — IDA symbol auto-resolution feature, _ ↔ . name correction, x64 RIP-relative encoding support, enhanced error output

---

License

This modified version is released under the MIT License. See the LICENSE file for details.

The original Keypatch code copyright belongs to the original authors, released under GPL v2.