haruspex

"Hacking is the discipline of questioning all your assumptions all of the time."

-- Dave Aitel

Haruspex is a blazing-fast IDA headless plugin that extracts pseudocode generated by IDA's decompiler in a format that should be suitable to be imported into an IDE, or parsed by static analysis tools such as Semgrep, weggli, or oneiromancer.

• Blazing-fast, headless user experience courtesy of IDA 9.x and idalib-rs Rust bindings.
• Support for binary targets for any architecture implemented by IDA's Hex-Rays decompiler.
• Pseudocode of each function is stored in a separated file in the output directory for easy inspection.
• Global and per-function type definitions are extracted to header files alongside the pseudocode.
• External crates can invoke [decompile_to_file] to decompile a function and save its pseudocode and type definitions to disk, telling apart functions that can't be decompiled from errors that affect all functions, such as an unavailable decompiler or license.

• https://hex-rays.com/blog/streamlining-vulnerability-research-idalib-rust-bindings
• https://hnsecurity.it/blog/streamlining-vulnerability-research-with-ida-pro-and-rust

• https://github.com/0xdea/ghidra-scripts/blob/main/Haruspex.java
• https://github.com/0xdea/semgrep-rules
• https://github.com/0xdea/weggli-patterns
• https://docs.hex-rays.com/release-notes/9_0#headless-processing-with-idalib
• https://github.com/idalib-rs/idalib
• https://github.com/xorpse/parascope
• https://hnsecurity.it/blog/automating-binary-vulnerability-discovery-with-ghidra-and-semgrep

The easiest way to get the latest release is via crates.io:

1. Download, install, and configure IDA (see https://hex-rays.com/ida-pro).
2. Install LLVM/Clang (see https://rust-lang.github.io/rust-bindgen/requirements.html).
3. On Linux/macOS, install as follows:

   export IDADIR=/path/to/ida # if not set, the build script will check common locations
   cargo install haruspex --locked

   On Windows, instead, use the following commands:

   $env:LIBCLANG_PATH="\path\to\clang+llvm\bin"
   $env:PATH="\path\to\ida;$env:PATH"
   $env:IDADIR="\path\to\ida" # if not set, the build script will check common locations
   cargo install haruspex --locked

Alternatively, you can build from source:

1. Download, install, and configure IDA (see https://hex-rays.com/ida-pro).
2. Install LLVM/Clang (see https://rust-lang.github.io/rust-bindgen/requirements.html).
3. On Linux/macOS, compile as follows:

   git clone --depth 1 https://github.com/0xdea/haruspex
   cd haruspex
   export IDADIR=/path/to/ida # if not set, the build script will check common locations
   cargo build --release --locked

   On Windows, instead, use the following commands:

   git clone --depth 1 https://github.com/0xdea/haruspex
   cd haruspex
   $env:LIBCLANG_PATH="\path\to\clang+llvm\bin"
   $env:PATH="\path\to\ida;$env:PATH"
   $env:IDADIR="\path\to\ida" # if not set, the build script will check common locations
   cargo build --release --locked

1. Make sure IDA is properly configured with a valid license.
2. Make sure the IDADIR environment variable is set if your IDA installation is in a non-standard location.
3. Run as follows:

   haruspex <binary_file>

4. Find the extracted pseudocode and type definitions in the output directory next to <binary_file>, named after it with its extension, if any, replaced by .dec (e.g., foo.exe and foo both produce foo.dec, so binaries that differ only in their extension share the same output directory):

   vim foo.dec
   code foo.dec

Only the latest IDA release is officially supported, but older versions may work as well. The following table summarizes the latest compatible release for each IDA version:

This project's development has been supported by the following organizations:

• HN Security
• Hex-Rays via their Contributor Program

• CHANGELOG.md

• Add a Semgrep CI regression test to make sure the percentage of parsed lines doesn't decrease.
• Use the .cpp extension instead of .c to output pseudocode (see this issue)?
• Implement serialized output to facilitate automated parsing and analysis.
• Integrate with Semgrep scanning (see https://github.com/0xdea/semgrep-rules).
• Integrate with weggli scanning (see https://github.com/0xdea/weggli-patterns).
• Improve decompiler output in the style of HexRaysPyTools and abyss.
• Implement parallel analysis (see https://github.com/fugue-re/fugue-mptp).