IDA Mask Plugin

A professional IDA Pro plugin for binary pattern analysis and generation, featuring ARM64 assembly-to-pattern conversion capabilities.

Features

Search by Pattern:Mask

Search through loaded binaries using byte patterns with bit-level mask support. Searches can target the whole binary, a specific segment, or an address range

IDA's native find_bytes/bin_search mask is byte-granular (a non-zero mask byte forces a full-byte compare), so it cannot honor sub-byte fields such as an ARM64 register (5 bits). The plugin therefore uses IDA's native engine as a fast pre-filter over the fully-constrained (0xFF) bytes and then verifies each candidate against the full bit-level mask, falling back to a pure bit-level scan when a pattern has no fully-constrained byte.

Create Pattern:Mask

Generate precise byte patterns and masks from ARM64 assembly templates, powered by the arm64-mask-gen engine.

Scriptable / MCP API

All functionality is exposed as plain functions that return values (no GUI), so it can be driven from the IDA scripting console or an MCP bridge. The GUI and the scriptable API share the same functions in a single module.

📦 Installation

Step 1: Install the Plugin

Copy the plugin (a single self-contained file) to your IDA Pro plugins directory:

cp ida_mask_plugin.py ~/.idapro/plugins/

Step 2: Install Dependencies

Install the required Python packages using the provided requirements file:

pip install -r requirements.txt

Or install individually:

pip install arm64-mask-gen-py capstone

Note: For IDA Pro's embedded Python, you may need to use the specific Python interpreter that IDA uses.

🚀 Usage

Accessing the Plugin

1. Launch IDA Pro and load your target binary
2. Navigate to Edit → Plugins → IDA Mask Plugin
3. Select your desired operation

Pattern Search

A single dialog asks for the pattern:mask and the search scope:

• Pattern:mask: e.g. 1f2003d5:1ffcffff (exact bytes, or partial/bit-level mask)
• Scope (radio): Whole binary, Specific segment (name; substring ok), or Address range (hex start/end)

The scope defaults to Specific segment, pre-filled with the segment at the current address.

Pattern Generation

Input ARM64 assembly templates to generate corresponding patterns:

Example:

Template : MOV X3, #?
Pattern  : 030080d2
Mask     : 1f00e0ff
COMBINED : 030080d2:1f00e0ff

Scriptable / MCP API

Import the plugin module and call its functions directly (e.g. from the IDA Python console or an MCP py_eval):

import ida_mask_plugin as M

# Generate a pattern:mask from one or more ARM64 instruction templates.
# Wildcard the variable operands: x?/w? = any reg, #? = any imm, bl #? = any target.
pm = M.gen_mask(["mov x?, #?", "bl #?"])        # -> "....:...."

# Instructions Keystone can't assemble (e.g. pacibsp): use the raw bytes.
pm2 = M.exact("7f2303d5")                         # -> "7f2303d5:ffffffff"

# Search, restricted by scope (the key new capability):
M.masked_search(pm)                               # whole binary  -> [ea, ...]
M.masked_search(pm, scope="__TEXT_EXEC")          # by segment name (exact/substring)
M.masked_search(pm, scope=(0xFFFFFFF007004000, 0xFFFFFFF007010000))  # address range
M.masked_search(pm, scope=["__text", (lo, hi)])   # a list of names and/or ranges
M.masked_search(pm, step=4)                        # ARM64-aligned hits only

# Rich results (segment / function / bytes / disasm per hit):
M.search(pm, scope="__TEXT_EXEC")                 # -> [ {ea, segment, function, ...} ]

# Discover scopes, or describe a single address:
M.list_segments()                                 # -> [ {name, start, end, size, perm} ]
M.describe(0xFFFFFFF007004000)

scope accepts: None (whole binary), a segment name (exact or substring match), an (start, end) address range, or a list mixing names and ranges. Masking is bit-level, so partial masks (e.g. an instruction's register field) are honored.

A test suite lives in test_ida_mask_plugin.py. Because the plugin imports IDA modules, run it inside IDA (File > Script file..., or an MCP py_eval that execs it against the open database).

Requirements

• IDA Pro 9.0+ (tested)
• Python 3.7+ (bundled with IDA Pro)
• Dependencies (auto-installed via requirements.txt):
  • arm64-mask-gen-py: ARM64 pattern generation engine
  • capstone: Disassembly framework

Advanced Configuration

Custom Python Environment

If IDA Pro uses a different Python interpreter, install dependencies directly:

/path/to/ida/python -m pip install arm64-mask-gen-py capstone

Building from Source

For development or custom builds, use the PyO3 wrapper:

git clone https://github.com/xliee/arm64-mask-gen-py
cd arm64-mask-gen-py
maturin develop --release

Related Projects

• Core Library: arm64-mask-gen - Rust-based pattern generation engine
• Python Wrapper: arm64-mask-gen-py - PyO3 bindings
• PyPI Package: arm64-mask-gen-py - Published Python wheel

📝 License

Licensed under the MIT License. See LICENSE for details.