haruspex/

lib.rs

//!
//! haruspex - Tool to extract IDA decompiler's pseudocode
//! Copyright (c) 2024-2025 Marco Ivaldi <raptor@0xdeadbeef.info>
//!
//! > "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).
//!
//! ## 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/binarly-io/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
//! * IDA Pro 9.0.240925 - Latest compatible: v0.2.4.
//! * IDA Pro 9.0.241217 - Latest compatible: v0.3.5.
//! * IDA Pro 9.1.250226 - Latest compatible: v0.6.2.
//! * IDA Pro 9.2.250908 - Latest compatible: current version.
//!
//! *Note: check [idalib](https://github.com/binarly-io/idalib) documentation for additional information.*
//!
//! ## Changelog
//! * <https://github.com/0xdea/haruspex/blob/master/CHANGELOG.md>
//!
//! ## TODO
//! * 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>).
//!

#![doc(html_logo_url = "https://raw.githubusercontent.com/0xdea/haruspex/master/.img/logo.png")]

use std::fs;
use std::fs::File;
use std::io::{BufWriter, Write};
use std::path::Path;
use std::sync::atomic::{AtomicUsize, Ordering};

use anyhow::Context;
use idalib::IDAError;
use idalib::decompiler::HexRaysErrorCode;
use idalib::func::{Function, FunctionFlags};
use idalib::idb::IDB;
use thiserror::Error;

/// Number of decompiled functions
static COUNTER: AtomicUsize = AtomicUsize::new(0);

/// Reserved characters in filenames
#[cfg(unix)]
static RESERVED_CHARS: &[char] = &['.', '/'];
#[cfg(windows)]
static RESERVED_CHARS: &[char] = &['.', '/', '<', '>', ':', '"', '\\', '|', '?', '*'];

/// Maximum length of filenames
static MAX_FILENAME_LEN: usize = 64;

/// Haruspex error type
#[derive(Error, Debug)]
pub enum HaruspexError {
    /// Failure in decompiling the function
    #[error(transparent)]
    DecompileFailed(#[from] IDAError),
    /// Failure in writing to the output file
    #[error(transparent)]
    FileWriteFailed(#[from] std::io::Error),
}

/// Extract pseudocode of functions in the binary file at `filepath` and save it in `filepath.dec`.
///
/// ## Errors
///
/// Returns how many functions were decompiled, or a generic error in case something goes wrong.
pub fn run(filepath: &Path) -> anyhow::Result<usize> {
    // Open the target binary and run auto-analysis
    println!("[*] Analyzing binary file `{}`", filepath.display());
    let idb = IDB::open(filepath)
        .with_context(|| format!("Failed to analyze binary file `{}`", filepath.display()))?;
    println!("[+] Successfully analyzed binary file");
    println!();

    // Print binary file information
    println!("[-] Processor: {}", idb.processor().long_name());
    println!("[-] Compiler: {:?}", idb.meta().cc_id());
    println!("[-] File type: {:?}", idb.meta().filetype());
    println!();

    // Check if Hex-Rays decompiler is available
    if !idb.decompiler_available() {
        return Err(anyhow::anyhow!("Decompiler is not available"));
    }

    // Create a new output directory, returning an error if it already exists, and it's not empty
    let dirpath = filepath.with_extension("dec");
    println!("[*] Preparing output directory `{}`", dirpath.display());
    if dirpath.exists() {
        fs::remove_dir(&dirpath).map_err(|_| anyhow::anyhow!("Output directory already exists"))?;
    }
    fs::create_dir_all(&dirpath)
        .with_context(|| format!("Failed to create directory `{}`", dirpath.display()))?;
    println!("[+] Output directory is ready");

    // Extract pseudocode of functions
    println!();
    println!("[*] Extracting pseudocode of functions...");
    println!();
    for (_id, f) in idb.functions() {
        // Skip the function if it has the `thunk` attribute
        if f.flags().contains(FunctionFlags::THUNK) {
            continue;
        }

        // Decompile function and write pseudocode to the output file
        let func_name = f.name().unwrap_or_else(|| "<no name>".into());
        let output_file = format!(
            "{}@{:X}",
            func_name
                .replace(RESERVED_CHARS, "_")
                .chars()
                .take(MAX_FILENAME_LEN)
                .collect::<String>(),
            f.start_address()
        );
        let output_path = dirpath.join(output_file).with_extension("c");

        match decompile_to_file(&idb, &f, &output_path) {
            // Print the output path in case of successful function decompilation
            Ok(()) => println!("{func_name} -> `{}`", output_path.display()),

            // Return an error if Hex-Rays decompiler license is not available
            Err(HaruspexError::DecompileFailed(IDAError::HexRays(e)))
                if e.code() == HexRaysErrorCode::License =>
            {
                return Err(e.into());
            }

            // Ignore other IDA errors
            Err(HaruspexError::DecompileFailed(_)) => continue,

            // Return any other error
            Err(e) => return Err(e.into()),
        }

        COUNTER.fetch_add(1, Ordering::Relaxed);
    }

    // Remove the output directory and return an error in case no functions were decompiled
    if COUNTER.load(Ordering::Relaxed) == 0 {
        fs::remove_dir(&dirpath)
            .with_context(|| format!("Failed to remove directory `{}`", dirpath.display()))?;
        return Err(anyhow::anyhow!(
            "No functions were decompiled, check your input file"
        ));
    }

    println!();
    println!(
        "[+] Decompiled {COUNTER:?} functions into `{}`",
        dirpath.display()
    );
    println!("[+] Done processing binary file `{}`", filepath.display());
    Ok(COUNTER.load(Ordering::Relaxed))
}

/// Decompile [`Function`] `func` in [`IDB`] `idb` and save its pseudocode to the output file at `filepath`.
///
/// ## Errors
///
/// Returns the appropriate [`HaruspexError`] in case something goes wrong.
///
/// ## Examples
///
/// Basic usage:
/// ```
/// # fn main() -> anyhow::Result<()> {
/// # let base_dir = std::path::Path::new("./tests/data");
/// let input_file = base_dir.join("ls");
/// let output_file = base_dir.join("ls-main.c");
///
/// let idb = idalib::idb::IDB::open(&input_file)?;
/// let (_, func) = idb
///     .functions()
///     .find(|(_, f)| f.name().unwrap() == "main")
///     .unwrap();
///
/// haruspex::decompile_to_file(&idb, &func, &output_file)?;
/// # std::fs::remove_file(output_file)?;
/// # Ok(())
/// # }
/// ```
///
pub fn decompile_to_file(
    idb: &IDB,
    func: &Function,
    filepath: impl AsRef<Path>,
) -> Result<(), HaruspexError> {
    // Decompile function
    let decomp = idb.decompile(func)?;
    let source = decomp.pseudocode();

    // Write pseudocode to output file
    // Note: for easier testing, we could use a generic function together with `std::io::Cursor`
    let mut writer = BufWriter::new(File::create(&filepath)?);
    writer.write_all(source.as_bytes())?;
    writer.flush()?;

    Ok(())
}