Introduction

Ghidra is a highly extensible application for performing software reverse engineering. Ghidra is built upon a completely generic application framework. Application-specific capabilities are provided by small software bundles called plugins, each providing one or more features. This user's guide provides detailed information on how to use both Ghidra's generic and reverse engineering-specific capabilities.

Intended Audience

This guide is intended for anyone interested in learning how to use Ghidra to reverse engineer a software system.

Document Scope

The purpose of this document is to describe how to use Ghidra. It does NOT provide information on the software architecture or the programming API.

Disclaimer

Ghidra is configurable. At any given time, Ghidra capabilities can be added, removed, or even replaced by changing the current set of plugins. Consequently, a feature might not be available as described and the images shown in this document may not exactly match your display.

Getting Started

File System Layout

In the directory you choose, a ghidra installation directory named ghidra_<version> is created. The following directory structure will be created under the Ghidra installation directory.

docs tutorial and on-line help
Extensions installable extensions for Ghidra, Eclipse and IDA Pro
Ghidra essential files for running Ghidra
GPL GPL utility and support programs used by Ghidra
licenses licenses for non-GPL portions of Ghidra
server files required to launch and configure the Ghidra server
support files useful for debugging and configuring Ghidra

Extensions

There are a number of Ghidra plugins that are not part of the base distribution. They are either experimental, still under development, or contributed by others. These plugins may not have been tested, and therefore may be unstable and are not included in any of the default tools. However, these plugins often contain the more cutting edge features and may be worth considering. They are easily accessible and can be added by configuring a tool.

IDA Pro Export

The Ghidra distribution includes a plugin for use with IDA Pro (a commercially available disassembler). The XML plugin is used with IDA Pro to export IDA Pro databases as XML files so that they can be imported into Ghidra. This allows IDA Pro users to migrate their data to Ghidra.

To add the XML exporter plugin to your IDA installation:

To export data to Ghidra using the XML plugin, select File -> Plugins -> Dump database as XML file... from IDA's main menu.

Starting Ghidra

Launching Ghidra varies depending on the operating system.

Ghidra on Windows:

Run the ghidraRun.bat file located in the Ghidra installation directory.

One way to run this file is to use the Windows file explorer to locate the ghidra.bat file and then simply double click on the file.

Ghidra on Linux and macOS:

Run the ghidraRun shell script file located in the Ghidra installation directory.

Advanced Startup

Ghidra provides some Java startup parameters which allow for the usage of advanced features. To use a startup parameter you must open support/launch.properties and add the parameter to that file.

For example,

               VMARGS=-Dfont.size.override=18

Ghidra Overview

When Ghidra first starts, the Ghidra Project Window will appear.


Ghidra Front-End with no open project


Ghidra is a project-oriented application and, consequently, all work must be performed in the context of a project. Therefore, the first thing to do is to create a project or open an existing project. Once a project is open, Ghidra will display the folders and data that make up the project along with the user's current set of tools. Of course, newly created projects would not contain any data. Data must be imported into a Ghidra project before any work can be performed. Importing data into a Ghidra project creates programs that Ghidra tools can manipulate.


Ghidra Front-End with an open project


A Ghidra tool is a configuration of plugins that can be used to manipulate programs. When Ghidra is first installed, a default tool - the code browser tool - is created for the user and its icon is displayed in the Tool Chest area of the Ghidra Project Window.

To run a tool, click on its icon in the Tool Chest. When a tool is running, a new window will appear for that tool and the tool's icon will be displayed in the Running Tools area of the Ghidra Project Window.

Ghidra also supports the concept of workspaces. A workspace is simply a collection of running tools that are visible on the desktop. Users can have multiple workspaces, each with its own set of running tools. Running tools that are not in the current workspace are still running and consuming system resources even though they are not visible.

Error Dialogs

Errors may occur in Ghidra. An error may be anticipated, or it may be unexpected in which case it is a programming error. Each type of error is described below.

General Errors

Whenever an action or operation does not complete as desired, but is an anticipated error such as a user entering a file path that doesn't exist, Ghidra will display an Error dialog explaining the cause of the problem as shown below in the sample error dialog:

Unexpected Programming Errors

Whenever an action or operation fails in a totally unexpected way, i.e., a programming error, a dialog is displayed as shown below:

The Details >>> button expands the dialog to show the details of the java stack trace. (The stack trace is also output to the console.)