🧠 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

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 installs the plugin under $IDAUSR/plugins/idavator and first installs the matching idavator wheel into IDA's Python environment. The wheel declares llvmlite, numpy, and typer, so no separate pip install is needed for an HCLI installation. IDA loads the plugin on its next launch. Requires IDA 9.0+.

For source checkouts, embedders, or manual installs, install the package with the Python interpreter IDA uses:

python -m pip install idavator

Lift (ida2llvm)

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

idavator ida2llvm -f binary -o output.ll

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:

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+).

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 the HCLI manifest version and its exact idavator==VERSION dependency before staging the manifest. 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.