haruspex 0.9.0

Vulnerability research assistant that extracts pseudocode from IDA Hex-Rays decompiler.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129

# haruspex

[![](https://img.shields.io/github/stars/0xdea/haruspex.svg?style=flat&color=yellow)](https://github.com/0xdea/haruspex)
[![](https://img.shields.io/crates/v/haruspex?style=flat&color=green)](https://crates.io/crates/haruspex)
[![](https://img.shields.io/crates/d/haruspex?style=flat&color=red)](https://crates.io/crates/haruspex)
[![](https://img.shields.io/badge/ida-9.3-violet)](https://hex-rays.com/ida-pro)
[![](https://img.shields.io/badge/twitter-%400xdea-blue.svg)](https://twitter.com/0xdea)
[![](https://img.shields.io/badge/mastodon-%40raptor-purple.svg)](https://infosec.exchange/@raptor)
[![build](https://github.com/0xdea/haruspex/actions/workflows/build.yml/badge.svg)](https://github.com/0xdea/haruspex/actions/workflows/build.yml)
[![doc](https://github.com/0xdea/haruspex/actions/workflows/doc.yml/badge.svg)](https://github.com/0xdea/haruspex/actions/workflows/doc.yml)

> "Hacking is the discipline of questioning all your assumptions all of the time."
>
> -- Dave Aitel

Haruspex is a blazing fast IDA Pro headless plugin that extracts pseudocode generated by IDA Pro's
decompiler in a format that should be suitable to be imported into an IDE, or parsed by static
analysis tools such as [Semgrep](https://semgrep.dev/), [weggli](https://github.com/weggli-rs/weggli),
or [oneiromancer](https://crates.io/crates/oneiromancer).

![](https://raw.githubusercontent.com/0xdea/haruspex/master/.img/screen01.png)

## Features

- Blazing fast, headless user experience courtesy of IDA Pro 9.x and Binarly's idalib Rust bindings.
- Support for binary targets for any architecture implemented by IDA Pro's Hex-Rays decompiler.
- Pseudocode of each function is stored in a separated file in the output directory for easy inspection.
- External crates can invoke [`decompile_to_file`] to decompile a function and save its pseudocode to disk.

## Blog posts

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

## See also

- <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>

## Installing

The easiest way to get the latest release is via [crates.io](https://crates.io/crates/haruspex):

1. Download, install, and configure IDA Pro (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:
   ```sh
   export IDADIR=/path/to/ida # if not set, the build script will check common locations
   cargo install haruspex
   ```
   On Windows, instead, use the following commands:
   ```powershell
   $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
   ```

## Compiling

Alternatively, you can build from [source](https://github.com/0xdea/haruspex):

1. Download, install, and configure IDA Pro (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:
   ```sh
   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
   ```
   On Windows, instead, use the following commands:
   ```powershell
   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
   ```

## Usage

1. Make sure IDA Pro is properly configured with a valid license.
2. Run as follows:
   ```sh
   haruspex <binary_file>
   ```
3. Find the extracted pseudocode of each decompiled function in the `binary_file.dec` directory:
   ```sh
   vim <binary_file>.dec
   code <binary_file>.dec
   ```

## Compatibility

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

| IDA Pro version | Latest compatible release |
| --------------- | ------------------------- |
| v9.0.240925     | v0.2.4                    |
| v9.0.241217     | v0.3.5                    |
| v9.1.250226     | v0.6.2                    |
| v9.2.250908     | v0.7.5                    |
| v9.3.260213     | v0.8.1                    |
| v9.3.260327     | current release           |

> [!NOTE]
> Check the [idalib](https://github.com/idalib-rs/idalib) documentation for additional information.

## Changelog

- [CHANGELOG.md](https://github.com/0xdea/haruspex/blob/master/CHANGELOG.md)

## TODO

- Use the `.cpp` extension instead of `.c` to output pseudocode (see
  this [issue](https://github.com/0xdea/semgrep-rules/issues/12))?
- 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](https://github.com/igogo-x86/HexRaysPyTools)
  and [abyss](https://github.com/patois/abyss).
- Implement parallel analysis (see <https://github.com/fugue-re/fugue-mptp>).