idavator 0.1.0

IDAvator is a bi-directional bridge between IDA Pro's Hex-Rays microcode and LLVM IR. It lets you lift decompiler microcode into LLVM for analysis, optimization, or deobfuscation. Then, drop it back into IDA, patched and ready for further exploration.

🧠 IDAvator - Ride the elevator to lift between microcode and machine.

About | QuickStart | Acknowledgements |

About

IDAvator is a bi-directional bridge between IDA Pro’s Hex-Rays microcode and LLVM IR. It lets you lift decompiler microcode into LLVM for analysis, optimization, or deobfuscation. Then, drop it back into IDA, patched and ready for further exploration.

Features

Action	Command	Description
Lift	idavator ida2llvm	Headless: microcode (mba_t) → LLVM IR via idalib.
Drop	IDA plugin (GUI)	Edit → IDAvator → Apply LLVM IR... (microcode drop; patch/export WIP).
Lift (interactive)	IDA plugin (GUI)	Edit → IDAvator → Lifting Viewer (Ctrl+Alt+L).
Optimize	Use opt or any LLVM pass pipeline	Apply LLVM analyses or transformations (e.g., constant propagation, CFG cleanup).
Deobfuscate	Combine with IDAvator’s switch-flattening or simplification passes	Simplify complex control flow graphs.
Patch / Rebuild	Patch directly in IDA or export .o / .bin	Choose live patching or external reconstruction.

---

Architecture

  +-----------+           +------------------+           +-------------+
  |  IDA Pro  |  ida2llvm |     LLVM IR      | llvm2ida  |  Patched IDA|
  | (microcode) +---------> (optimize, deobf) +----------> (clean code) |
  +-----------+           +------------------+           +-------------+
         ^                        |
         |        idavator        |
         +------------------------+

QuickStart

Install

pip install -e .

Requires Python >= 3.10, IDA Pro 9+ with idalib, and dependencies from pyproject.toml (llvmlite, numpy, typer).

Install with hcli

hcli is Hex-Rays' command-line tool; it installs IDAvator from the IDA Plugin Repository. Install hcli once:

curl -LsSf https://hcli.docs.hex-rays.com/install | sh        # macOS/Linux
iwr -useb https://hcli.docs.hex-rays.com/install.ps1 | iex    # Windows (PowerShell)

Then authenticate (see the hcli docs) and install the plugin:

hcli plugin search idavator
hcli plugin install idavator

hcli downloads the plugin into $IDAUSR/plugins (~/.idapro/plugins on macOS/Linux), where IDA loads it on the next launch. Requires IDA 9.0+.

Because IDAvator is a multi-module package with third-party dependencies (llvmlite, numpy, typer) that hcli does not install, also install the package into IDA's Python so those imports resolve:

pip install idavator

Lift (ida2llvm)

Lift a binary to LLVM IR (headless via idalib):

idavator ida2llvm -f binary -o output.ll

Option	Description
-f, --file	Input binary to analyze
-o, --output	Output LLVM IR path (.ll)
--target	Target triple: host (default) or ida
--ir-pass, --ir-passes	Comma-separated post-lift IR pass pipeline
--annotate-concurrency	Compatibility alias for --ir-pass concurrency
--log-type	Log destination: file (default) or console (stderr)
--log-file	Log file path when --log-type=file (default: idavator.log)
-v, --verbose	Enable DEBUG logging

idavator ida2llvm -f binary -o output.ll --log-type console -v

Logging is configured before the lift module loads, so early messages use the chosen destination.

Run post-lift IR passes while writing the output:

idavator ida2llvm -f binary -o output.ll --ir-pass concurrency,verify

Available passes:

Pass	Description
concurrency	Appends metadata for recognized TLS helper calls, syscalls, and futex syscalls
verify	Parses and verifies the final LLVM IR with llvmlite

For older scripts, --annotate-concurrency is still accepted and enables the concurrency pass.

Regression baselines (pytest)

Metric baselines live under tests/artifacts/ and compare lift/pass output without requiring full IR text diffs. Refresh them after intentional improvements:

pip install -e ".[dev]"
pytest --baseline-update
pytest

IDA-backed lift checks run only when idalib is available:

pytest -m ida

IDA plugin (GUI)

Install the package into IDA’s Python (pip install -e . from this repo), then load the plugin via ida-plugin.json (IDA 9+).

Menu	Hotkey	Purpose
Edit → IDAvator → Lifting Viewer	Ctrl+Alt+L	Interactive lift: add functions, declare-only toggle, preview IR, save .ll
Edit → IDAvator → Apply LLVM IR...		Drop optimized .ll back into the open database (microcode)

Headless batch lift remains CLI-only (idavator ida2llvm). Drop is not on the CLI.

Workflow:

1. Lift in IDA (viewer) or headless (idavator ida2llvm -f binary -o output.ll).
2. Optimize LLVM offline (opt, custom passes).
3. Edit → IDAvator → Apply LLVM IR... on the same database.

pip install -e .
python -m idavator ida2llvm -f binary -o output.ll

Requirements

• Python >= 3.10, llvmlite, and IDA Pro 9+ with idalib

Contributing

The version lives in one place: __version__ in src/idavator/__init__.py (pyproject.toml derives the package version from it). The IDA Plugin Repository and hcli read the version out of ida-plugin.json, so the two must agree. To keep them in step automatically, enable the repo's git hook once per clone:

git config core.hooksPath .githooks

The pre-commit hook (.githooks/pre-commit) runs tools/sync_plugin_version.py, which copies __version__ into ida-plugin.json and stages it, so the manifest can never drift behind a version bump. The test suite runs the same check (tests/test_plugin_manifest.py) as a CI backstop.

Acknowledgements

• sandspeare's ida2llvm continuation - Thank you for such a great tool!
• loyaltypollution's original ida2llvm: The codebase sandspeare built on, fixing most of the bugs (float, unsupport inst, unsupport typecast and structure) and transforming it from an experimental toy to a stable tool.