XRefer: The Binary Navigator

XRefer is a Python-based plugin for the IDA Pro disassembler, a tool used for analyzing software. The plugin provides a custom navigation interface within IDA. It examines execution paths from entry points, breaks down the binary into clusters of related functions, and highlights downstream behaviors and artifacts for quicker insights. XRefer can incorporate external data (e.g., API traces, capa results, user-defined xrefs) and provides path graphs for richer context. It integrates with Google's Gemini model to produce natural language descriptions of code relationships and behaviors. Additionally, XRefer can provide cluster based labels for functions, aiming to accelerate the manual static analysis process.

More can be read about XRefer in the accompanying blog post.

Installation

1. Clone the Repository:

   git clone https://github.com/mandiant/xrefer.git
   

2. Install the Plugin:

• Inside the cloned repository, a plugins directory contains the plugin code.
• Copy the contents of plugins/ into your IDA Pro plugins directory:

  cp -r xrefer/plugins/* /path/to/IDA/plugins/
  

3. Install Dependencies:
   From the main directory of the cloned repository:

   pip install -r requirements-ida.txt
   

   Note: The asciinet dependency requires Java to be installed. OpenJDK or any JRE should work. Ensure java is accessible on your system's PATH.

Usage

After installation, restart IDA. You will find XRefer's menu entries under Edit -> XRefer. Some options will also be available under the right click context menu.

• Configuration:
  Go to Edit -> XRefer -> Configure to adjust LLM settings, paths, exclusions and other settings.

• Starting Analysis:
  Run analysis either from the default entry point Edit -> XRefer -> Run Analysis -> Default Entrypoint or specify a custom entry point Edit -> XRefer -> Run Analysis -> Custom Entrypoint in the case of a DLL/library for example.

• External Data & Exclusions:
  XRefer can ingest external data sources, including API trace files from dynamic analysis sandboxes VMRay and Cape. It can also ingest capa analysis outputs, and user-defined indirect xrefs for enhanced path resolution. These inputs help enrich the analysis with additional context. Manage default paths for these resources from the configuration dialog and fine-tune their usage by enabling or disabling exclusions, as well as adding or removing exclusion entries to focus on the most relevant artifacts.

For more in-depth instructions and usage scenarios, please refer to the Usage Documentation.

Contributing

Contributions, bug reports, and feature requests are welcome. Please open an issue or submit a pull request with a clear description of the proposed changes.

Important Privacy Notice

XRefer's LLM-based features, when enabled, send portions of analyzed data (e.g., APIs, strings, library references, and function relationships) to external servers, such as Google's Gemini API or other configured LLM endpoints. These external services process the information to generate natural language descriptions and insights. If you are analyzing sensitive binaries or prefer not to share data outside your local environment, you can disable all LLM features in the settings, preventing any external communication. Please consult Google Gemini's Terms of Service before use.

CLI Installation

1. Clone the repository and enter it:

   git clone https://github.com/mandiant/xrefer && cd xrefer

2. Install the package (creates .venv and syncs dependencies): If you have not yet installed uv, check out the installation instructions. After installing uv, run:

   uv sync

3. Add any required reverse-engineering backends (IDA Pro, Binary Ninja, Ghidra).
   Reference: IDA, Binary Ninja, Ghidra. e.g. for IDA:

   # set `IDADIR`
   uv sync --group ida

   for ghidra:

   # set `GHIDRA_INSTALL_DIR`
   uv sync --group ghidra

   if you want multiple backends, add them all.

   uv sync --group ida --group ghidra
   

4. Run analyses from the packaged CLI:

   uv run xrefer --backend ghidra /path/to/binary

   For reference on CLI options, run:

    ❯ uv run xrefer --help
    usage: xrefer [-h] --backend {ida,binaryninja,ghidra} [--save] [--auto-analysis] [--mode {light,full}]
                  [--report-data-mode {html,json,none}] [--force] [--entry-point ENTRY_POINT] [-L LOGFILE]
                  file
   
    Unified XRefer CLI for multiple backends
   
    positional arguments:
      file                  Path to the file to analyze
   
    options:
      -h, --help            show this help message and exit
      --backend {ida,binaryninja,ghidra}
                            Analysis backend to use (available: ida, binaryninja, ghidra)
      --save                Save changes to database/project
      --auto-analysis       Run auto analysis (default: True)
      --mode {light,full}   Select analyzer mode (default: full)
      --report-data-mode {html,json,none}
                            Report output format: html (standalone), json (data only), or none
      --force               Remove previous artifacts and re-analyze
      --entry-point ENTRY_POINT
                            Override entry point address (decimal or hex like 0x401000)
      -L, --logfile LOGFILE
                            Output log file path

Development

1. Setup a development environment:

   uv sync --group dev

2. Clone the test-samples

   git submodule update --init --recursive