DOCSEARCHbyAlgolia
Submit Docs

Ghidrathon Documentation

repository·main·Indexed 20 days ago

https://github.com/mandiant/ghidrathon

A Ghidra extension that enables modern Python 3 scripting within the Ghidra environment, replacing the legacy Jython-based Python 2.7 implementation. It utilizes the Jep library to allow the use of Python 3 analysis tools such as angr, unicorn, and capa directly inside Ghidra's UI and headless mode.

Tokens
1.2K
Snippets
3
Records
9
Agent score
24%

What's inside Ghidrathon

  1. How Ghidrathon works with Python and Jep

    main

    Ghidrathon uses the Jep library to link your local Python installation to the JVM via the Java Native Interface (JNI).

    This architecture allows:

    • Your local Python interpreter to run inside Ghidra.
    • Full access to all your installed Python packages (e.g., unicorn, angr, capa).
    • Tight integration with the Ghidra scripting API.
    • Use of Python virtual environments to isolate dependencies.

  2. Write Ghidra Python 3 scripts

    main

    Ghidrathon provides a scripting experience similar to Java/Jython, but with one key syntax difference for accessing Ghidra state variables:

    • State Variables: Variables like currentProgram are exposed as function calls rather than direct attribute access. You must call them as currentProgram() to ensure the correct state is provided.
    • API Methods: Methods from FlatProgramAPI (e.g., findBytes) are available in the Python builtins scope.
    • Scope: All imported Python modules have access to these Ghidra-specific variables and methods.

  4. Switch Python Interpreters or Virtual Environments

    main

    Ghidrathon uses your local Python installation. To switch to a different Python interpreter or use a specific Python virtual environment:

    1. Activate your new environment or use the path to the new interpreter.
    2. Re-run the configuration step: python ghidrathon_configure.py <absolute_path_to_ghidra_install_dir>.

    This allows you to isolate packages and manage different Python versions for different Ghidra sessions.

  5. Integrate Python 3 scripts with Ghidra Script Manager

    main

    Ghidrathon integrates with the standard Ghidra Script Manager:

    • Create: Click Create New Script and select Python 3.
    • Execute: Use Run Script or Run Editor's Script. Output is sent to the Ghidra Console window.

  6. Build Ghidrathon from source

    main

    To build Ghidrathon, you must first provide a supported Jep JAR release in the lib directory of the source code. Then, run the Gradle build command from the root of the Ghidrathon source directory, specifying the path to your Ghidra installation.

    The resulting extension will be located in the dist directory of the source root.

    # 1. Download Jep JAR to <ghidrathon_source_dir>/lib
# 2. Run gradle from <ghidrathon_source_dir>
$ gradle -PGHIDRA_INSTALL_DIR=<absolute_path_to_Ghidra_install_dir>

  7. Install Ghidrathon

    main

    To install Ghidrathon, follow these steps to configure your Python environment and integrate the extension into Ghidra:

    1. Download and Unzip: Get the latest Ghidrathon release from GitHub.
    2. Configure Python: Run the configuration scripts using the Python interpreter you want Ghidrathon to use.
      • Install dependencies: python -m pip install -r requirements.txt
      • Configure Ghidra path: python ghidrathon_configure.py <absolute_path_to_ghidra_install_dir>
      • Note: You may need to set JAVA_HOME to the absolute path of the JDK used by your Ghidra installation.
      • Note: To change where the ghidrathon.save file is written, set the GHIDRATHON_SAVE_PATH environment variable before running the configuration script.
    3. Install Extension:
      • Via Ghidra UI: Go to File > Install Extensions..., click the + button, and select the Ghidrathon .zip file. Select Install Anyway if a version mismatch warning appears.
      • Manual: Extract the .zip directly to <ghidra_install_dir>/Ghidra/Extensions.
    $ python -m pip install -r requirements.txt
$ python ghidrathon_configure.py /path/to/ghidra

# To customize the save path:
$ export GHIDRATHON_SAVE_PATH="/path/to/custom/dir"
$ python ghidrathon_configure.py /path/to/ghidra

  8. Run Python 3 scripts in Ghidra Headless Mode

    main

    You can execute Python 3 scripts via the analyzeHeadless utility. Use the -postScript flag to specify your Python 3 script.

    Example invocation:

    $ analyzeHeadless <path_to_ghidra_support> <project_name> -process <binary_name> -postScript <your_script.py>
    $ analyzeHeadless C:\Users\wampus example -process example.o -postScript ghidrathon_example.py

  9. Requirements for Ghidrathon

    main

    Ensure your environment meets the following minimum versions before installation:

    ToolVersionSource
    Ghidrathon>= 4.0.0GitHub Releases
    Python>= 3.8.0python.org
    Jep== 4.2.0pypi.org
    Ghidra>= 10.3.2Ghidra Releases
    Java>= 17.0.0adoptium.net