oneiromancer

"A large fraction of the flaws in software development are due to programmers not fully understanding all the possible states their code may execute in." -- John Carmack

"Can it run Doom?" -- https://canitrundoom.org/

Oneiromancer is a reverse engineering assistant that uses a locally running LLM that has been fine-tuned for Hex-Rays pseudo-code, to aid with code analysis. It can analyze a function or a smaller code snippet, returning a high-level description of what the code does, a recommended name for the function, and variable renaming suggestions, based on the results of the analysis.

Features

• Support for the fine-tuned LLM aidapal based on mistral-7b-instruct.
• Easy integration with the pseudo-code extractor haruspex and popular IDEs.
• Code description, recommended function name, and variable renaming suggestions are printed to the terminal.
• Improved pseudo-code of each analyzed function is saved in a separated file for easy inspection.
• External crates can invoke analyze_code or analyze_file to analyze pseudo-code and then process analysis results.

Blog post

• https://security.humanativaspa.it/aiding-reverse-engineering-with-rust-and-a-local-llm (coming soon)

See also

• https://www.atredis.com/blog/2024/6/3/how-to-train-your-large-language-model
• https://huggingface.co/AverageBusinessUser/aidapal
• https://github.com/atredispartners/aidapal
• https://plugins.hex-rays.com/aidapal

Installing

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

$ cargo install oneiromancer

To install as a library, run the following command in your project directory:

$ cargo add oneiromancer

Compiling

Alternatively, you can build from source:

$ git clone https://github.com/0xdea/oneiromancer
$ cd oneiromancer
$ cargo build --release

Configuration

1. Download and install ollama.
2. Download the fine-tuned weights and Ollama modelfile from huggingface:

   $ wget https://huggingface.co/AverageBusinessUser/aidapal/resolve/main/aidapal-8k.Q4_K_M.gguf
   $ wget https://huggingface.co/AverageBusinessUser/aidapal/resolve/main/aidapal.modelfile
   

3. Configure Ollama by running the following commands within the directory in which you downloaded the files:

   $ ollama create aidapal -f aidapal.modelfile
   $ ollama list
   

Usage

1. Run oneiromancer as follows:

   $ export OLLAMA_BASEURL=custom_baseurl # if not set, the default will be used
   $ export OLLAMA_MODEL=custom_model # if not set, the default will be used
   $ oneiromancer <source_file>.c
   

2. Find the extracted pseudo-code of each decompiled function in source_file.out.c:

   $ vim <source_file>.out.c
   $ code <source_file>.out.c
   

Note: for best results, you shouldn't submit for analysis to the LLM more than one function at a time.

Tested on

• Apple macOS Sequoia 15.2 with ollama 0.5.11
• Ubuntu Linux 24.04.2 LTS with ollama 0.5.11
• Microsoft Windows 11 23H2 with ollama 0.5.11

Changelog

• CHANGELOG.md

Credits

• Chris (@AverageBusinessUser) at Atredis Partners for his fine-tuned LLM aidapal <3

TODO

• Improve output file handling with versioning and/or an output directory.
• Implement other features of the IDAPython aidapal IDA Pro plugin (e.g., context).
• Integrate with haruspex and idalib.
• Implement a "minority report" protocol (i.e., make three queries and select the best responses).
• Investigate other use cases for the aidapal LLM and implement a modular architecture to plug in custom LLMs.