GhidraDev provides support for developing and debugging Ghidra scripts and modules in Eclipse.
The information provided in this document is effective as of GhidraDev 5.0.0 and is subject to change with future releases.
- Change History
- Minimum Requirements
- Optional Requirements
- Installing
- GhidraDev Features
- Launching and Debugging Ghidra
- PyDev Support
- Upgrading
- Uninstalling
- Frequently Asked Questions
- Additional Resources
- Building
5.0.0:
- Added support for PyGhidra.
4.0.1:
- New Ghidra module projects now contain a default
README.md
file. - Fixed a bug that prevented an imported module source project from being discovered by Ghidra when launched with the project's run/debug configuration.
4.0.0:
- GhidraDev has been upgraded to be compatible with Ghidra 11.2 and later. It is not backwards compatible with versions of Ghidra prior to 11.2. Older versions of GhidraDev will report an error when trying to link against Ghidra 11.2 or later.
- GhidraDev now requires Eclipse 2023-12 4.30 or later.
- GhidraDev now requires JDK 21.
- Fixed an issue that could result in a
GhidraHelpService
exception when launching Ghidra. GhidraDev now properly enforces that Ghidra is only launched withUtility.jar
on the initial classpath.
3.1.0:
- GhidraDev has been upgraded to be compatible with Ghidra 11.1 and later. Older versions of GhidraDev will report an error when trying to link against Ghidra 11.1 or later.
- GhidraDev now supports importing a Ghidra module source directory. This will work best with Ghidra module projects created from Ghidra 11.1 or later.
- GhidraDev will now fail to launch Ghidra if a top-level
build
directory is detected. Presence of this intermediate build artifact can cause Ghidra to have runtime/debugging issues.
3.0.2:
- GhidraDev no longer throws an IOException when performing a
Link Ghidra
action on a Ghidra project whose original Ghidra installation moved. - GhidraDev now prevents unsupported versions of PyDev from being used.
3.0.1:
- Exporting a Ghidra Module Extension produces an intermediate
build
directory within the project. Thisbuild
directory now gets automatically cleaned up to avoid Ghidra runtime/debugging issues. - GhidraDev now prevents unsupported Ghidra source repositories from being added as a Ghidra installations.
3.0.0:
- GhidraDev now requires Eclipse 2021-12 4.22 or later.
- GhidraDev now requires JDK 17.
- Fixed an issue that could cause old extensions to incorrectly remain on the Ghidra project
classpath after performing a
Link Ghidra
.
2.1.5:
- Eclipse Python breakpoints now work when Eclipse installs PyDev in .p2 bundle pool directory.
2.1.4:
- Fixed exception that occurred when performing a
Link Ghidra
on projects that use a Gradle classpath container.
2.1.3:
- Fixed a bug that prevented Ghidra projects from recognizing extensions installed in the user's
~/.ghidra/.ghidra_<version>/Extensions
directory.
2.1.2:
- Fixed exception that occurred when creating a new Ghidra scripting project if a
~/ghidra_scripts
directory does not exist.
2.1.1:
- Python debugging now works when PyDev is installed via the Eclipse
dropins
directory. - Fixed a bug in the check that prevents Ghidra projects from being created within the Ghidra installation directory.
2.1.0:
- Added support for Ghidra 9.1. GhidraDev 2.1.0 will be unable to create new Eclipse projects for versions of Ghidra earlier than 9.1.
- Prevented Ghidra projects from being created inside of a Ghidra installation directory.
- Added an
Environments
tab to the Ghidra run configuration for setting environment variables when launching Ghidra.
2.0.1:
- Fixed exception that occurred when performing certain actions on a Ghidra project that was imported from a previously exported Archive File.
2.0.0:
- Improved Ghidra module project starting templates for Analyzer and Plugin and added new templates for Loader, Exporter, and FileSystem.
- When creating a new Ghidra project, there is now an option to automatically create a Ghidra run configuration for the project with a customizable amount of maximum Java heap space.
- When creating a new Ghidra project, the project root directory now defaults to the workspace directory if a project root directory has never been set.
- When creating a new Ghidra project, the add button in the Python Support wizard page now automatically adds the Jython interpreter found in the Ghidra installation directory to PyDev if PyDev does have any Jython interpreters configured.
- A Ghidra project's dependencies that are also projects are now passed along to a launched Ghidra so Ghidra can discover those projects as potential modules.
- The GhidraDev popup menu is now visible from within the Project Explorer (it was previously only visible in the Package Explorer).
- A new page has been added to the Export Ghidra Module Extension wizard that allows the user to point to a specific Gradle installation.
1.0.2:
- Fixed exception that occurred when performing a
Link Ghidra
on projects that specify other projects on their build paths.
1.0.1:
- Initial Release.
- Eclipse 2023-12 4.30 or later
- Ghidra 11.2 or later
- PyDev 9.3.0 or later (more info)
- Gradle - required version(s) specified by linked Ghidra release (more info)
GhidraDev can be installed either manually into Eclipse or automatically by Ghidra, depending on your uses cases. The following sections outline the different procedures.
GhidraDev can be installed into an existing installation of Eclipse the same way most Eclipse plugins are installed. From Eclipse:
- Click
Help -> Install New Software...
- Click
Add...
- Click
Archive...
- Select GhidraDev zip file from
<GhidraInstallDir>/Extensions/Eclipse/GhidraDev/
- Click
OK
(name field can be blank) - Check
Ghidra
category (orGhidraDev
entry) - Click
Next
- Click
Next
- Accept the terms of the license agreement
- Click
Finish
- Check
Unsigned
table entry - Click
Trust Selected
- Click
Restart Now
If you have an Internet connection, the latest GhidraDev can be installed by adding the official update site to an existing installation of Eclipse. This has the benefit of early access to new GhidraDev versions before the next version of Ghidra is released, and automatic updates (if you have updates enabled in Eclipse). From Eclipse:
- Click
Help -> Install New Software...
- Work with:
https://github.com/NationalSecurityAgency/ghidra-data/raw/main/Eclipse/GhidraDev/latest
- Press
Enter
- Check
Ghidra
category (orGhidraDev
entry) - Click
Next
- Click
Next
- Accept the terms of the license agreement
- Click
Finish
- Check
Unsigned
table entry - Click
Trust Selected
- Click
Restart Now
Ghidra has the ability to launch an externally linked Eclipse when certain actions are performed,
such as choosing to edit a Ghidra script by clicking the Eclipse icon in the Ghidra Script Manager.
Ghidra requires knowledge of where Eclipse is installed before it can launch it, and will prompt the
user to enter this information if it has not been defined. Before Ghidra attempts to launch
Eclipse, it will attempt to install GhidraDev into Eclipse's dropins
directory if GhidraDev
is not already installed.
GhidraDev provides a variety of features for creating and interacting with Ghidra-related projects in Eclipse. GhidraDev supports creating both Ghidra script and Ghidra module projects. Ghidra scripts are typically designed as a single Java source file that is compiled by Ghidra at runtime and run through Ghidra's Script Manager or passed to the Headless Analyzer on the command line for execution. Ghidra modules are intended to represent larger, more complex features such as Analyzers or Plugins. When Ghidra modules are ready for production, they can be exported and installed into Ghidra as an "extension".
Opens a wizard that creates a new Ghidra script with the provided metadata in the specified location. Ghidra scripts can be created in both Ghidra script and Ghidra module projects.
Opens a wizard that creates a new Ghidra scripting project that is linked
against a specified Ghidra installation. The project can be set up to develop scripts in both the
user's home ghidra_scripts
directory, as well as any scripts found in the Ghidra installation.
Opens a wizard that creates a new Ghidra module project that is linked against a specified Ghidra installation. The project can be initialized with optional template source files that provide a good starting point for implementing advanced Ghidra features such as Analyzers, Plugins, Loaders, etc.
Opens a wizard that imports a Ghidra module source directory as a new Ghidra module project.
Opens a wizard that exports a Ghidra module project as a Ghidra extension to the project's dist
folder. The exported extension archive file can be distributed to other users and imported via
Ghidra's front-end GUI. The export process requires Gradle, which is configured in the wizard. Note
that the Gradle version to use is specified in the linked Ghidra release's
<GhidraInstallDir>/Ghidra/application.properties
file.
Links a Ghidra installation to an existing Java project, which enables Ghidra script/module development for the project. If a Ghidra installation is already linked to the project when this operation is performed, the project will be relinked to the specified Ghidra installation, which can be used to build the project for a different version of Ghidra, discover new Ghidra extensions that were later added to a Ghidra installation, or repair a corrupted project.
- Ghidra Installations: Add or remove Ghidra installations. Certain features such as creating Ghidra script/module projects require linking against a valid installation of Ghidra.
- Script Editor: The port used by Ghidra to open a script in Eclipse. Must match the
corresponding port in Ghidra's
Eclipse Integration
tool options. Disable this preference to prevent GhidraDev from listening on a port for this feature. - Symbol Lookup: The project name and port used by Ghidra to perform symbol lookup in
Eclipse. Must match the corresponding port in Ghidra's
Eclipse Integration
tool options. Disable this preference to prevent GhidraDev from listening on a port for this feature. Symbol lookup requires the Eclipse CDT plugin to be installed (see optional requirements for supported versions).
Most GhidraDev features can also be accessed by right-clicking on appropriate project elements in
Eclipse's Project/Package Explorer. For example, the Link Ghidra feature can be
accessed by right-clicking on an existing Java project, and then clicking
Ghidra -> Link Ghidra...
.
GhidraDev introduces two new run configurations to Eclipse which are capable of launching the installation of Ghidra that an Eclipse Ghidra project is linked to:
- Ghidra: Launches the Ghidra GUI.
- Ghidra Headless: Launches Ghidra in headless mode. By default, this run configuration will not
have any program arguments associated with it, which are required to tell headless Ghidra what
project to open, what scripts to run, etc. Newly created
Ghidra Headless
run configurations will have to be modified with the desired headless program arguments. For more information on headless command line arguments, see<GhidraInstallDir>/support/analyzeHeadlessREADME.html
.
There are two ways to create Ghidra run configurations:
- Click
Run -> Run Configurations...
- Right-click on
Ghidra
(orGhidra Headless
), and clickNew
- In the
Main
tab, clickBrowse...
and select the Ghidra project to launch - Optionally rename the new run configuration by editing the
Name
field at the top
Alternatively, you can right-click on any Ghidra project in the Eclipse package explorer, and then
click Run As -> Ghidra
.
To debug Ghidra, click Debug As -> Ghidra
. GhidraDev will automatically switch Eclipse to the
debug perspective.
NOTE: Ghidra can only be launched/debugged from an existing Eclipse Ghidra project. Launching Ghidra from Eclipse independent of a project is not supported.
GhidraDev is able to integrate with PyDev to conveniently configure Python support into Ghidra script and module projects. GhidraDev supports both Jython and PyGhidra Python implementations.
NOTE: PyDev discontinued Jython 2 support in version 10.0.0. If you want to use GhidraDev with Jython, you must use PyDev 9.3.0. The latest vesions of PyDev support PyGhidra.
From Eclipse:
- Download PyDev (see optional requirements for supported versions)
- Unzip PyDev
- Click
Help -> Install New Software...
- Click
Add...
- Click
Local...
- Select unzipped PyDev directory
- Click
OK
(name field can be blank) - Uncheck
Group items by category
(if applicable) - Check
PyDev for Eclipse
- Click
Next
- Click
Next
- Accept the terms of the license agreement
- Click
Finish
- Click
Restart Now
GhidraDev can add Python support to a Ghidra project when:
- Creating a new Ghidra module project
- Creating a new Ghidra script project
- Linking a Ghidra installation to an existing Java project
In order for GhidraDev to add in Python support, PyDev must have a PyGhidra or Jython interpreter
configured. GhidraDev will present a list of detected PyGhidra/Jython interpreters that it found in
PyDev's preferences. If no interpreters were found, one can be added from GhidraDev by clicking
the +
icons.
When the Jython +
icon is clicked, GhidraDev will attempt to find the Jython interpreter bundled
with the selected Ghidra installation and automatically configure PyDev to use it. If for some
reason GhidraDev was unable to find a Jython interpreter in the Ghidra installation, one will have
to be added manually in the PyDev preferences.
When the PyGhidra +
icon is clicked, GhidraDev will attempt to find the PyGhidra interpreter
that was last used to launch PyGhidra. If it cannot find it, you will have to launch PyGhidra
and try again.
GhidraDev is upgraded differently depending on how it was installed. If GhidraDev was manually installed in Eclipse, it can be upgraded the same was it was installed.
If GhidraDev was automatically installed through Ghidra,
it can be upgraded by simply removing the GhidraDev file from Eclipse's dropins
directory before
following one of the two techniques described in the Installing section.
GhidraDev is uninstalled differently depending on how it was installed. If GhidraDev was manually installed in Eclipse, it can be uninstalled as follows from Eclipse:
- Click
Help -> About Eclipse
- For macOS:
Eclipse -> About Eclipse
- For macOS:
- Click
Installation Details
- Select
GhidraDev
- Click
Uninstall...
- Select
GhidraDev
- Click
Finish
- Click
Restart Now
If GhidraDev was automatically installed through Ghidra,
it can be uninstalled by simply removing the GhidraDev file from Eclipse's dropins
directory and
restarting Eclipse. The dropins
directory can be found at the top level of Eclipse's
installation directory.
- I've created a Ghidra script project. Where should I create my new scripts?
- The best place to create your scripts in is your home
~/ghidra_scripts
directory because Ghidra will automatically find them there without any additional configuration. By default, your Ghidra script project will have a folder namedHome scripts
which is linked to your home~/ghidra_scripts
directory. Either right-click on this folder in Eclipse and doGhidraDev -> New -> GhidraScript...
or from the menu bar doGhidraDev -> New -> GhidraScript...
and populate theScript folder
box with your project'sHome scripts
folder.
- The best place to create your scripts in is your home
- How do I launch Ghidra in headless mode from Eclipse?
- GhidraDev provides custom run configurations to launch Ghidra installations both in GUI mode and headlessly. See the Launching section for information on how to launch Ghidra from Eclipse.
- Why doesn't my Ghidra module project know about the Ghidra extension I installed into my Ghidra
installation?
- You most likely installed the Ghidra extension after the Ghidra installation was linked to your Ghidra module project, which automatically happens when the project is created. Simply relink your Ghidra installation to the project, and your project will pick up any newly discovered Ghidra extensions.
For more information on the GhidraDev plugin and developing for Ghidra in an Eclipse environment,
please see the Ghidra Scripting slide deck
at <GhidraInstallDir>/docs/GhidraClass/Intermediate/Scripting.html
.
GhidraDev is currently built from Eclipse and distributed with Ghidra manually. Ideally we will use Gradle one day, but we aren't there yet. We do rely on Gradle to generate the Eclipse project and build GhidraDev's dependencies though.
NOTE: Only "Eclipse for RCP and RAP Developers" has the ability to do the below instructions. The following instructions assume that you are using this version of Eclipse.
- Run
gradle prepGhidraDev eclipse -PeclipsePDE
- From Eclipse,
File -> Import -> General -> Existing Projects into Workspace
- From the ghidra repo, import
Eclipse GhidraDevFeature
andEclipse GhidraDevPlugin
- Open
plugin.xml
in the GhidraDevPlugin project - In the
Overview
tab, update theVersion
field tox.y.z.qualifier
and save - Open
feature.xml
in theGhidraDevFeature
project - In the
Overview
tab, update theVersion
field tox.y.z.qualifier
and save - Open
category.xml
in theGhidraDevFeature
project - Highlight
ghidra.ghidradev (x.y.z.qualifier)
, and clickRemove
- Highlight
ghidra.ghidradev
and clickAdd Feature
- Select
ghidra.ghidradev (x.y.z.qualifer)
, clickOK
, and save - Update the Change History section if necessary
- Do a
gradle prepDev
to ensure GhidraDev's dependencies are up-to-date File -> Export -> Plug-in Development -> Deployable features
- Check
ghidra.ghidradev (x.y.z.qualifier)
- Select
Archive file
and choose a directory to save it to. Name itGhidraDev-x.y.z.zip
. - In the
Options
tab make sure things look like this:- Export source: UNCHECKED
- Package as individual JAR archives: CHECKED
- Generate p2 repository: CHECKED
- Categorize repository: CHECKED + Browse to category.xml file in the GhidraDevFeature project
- Qualifier replacement: CHECKED + clear field so default is used
- Save as Ant script: UNCHECKED
- Allow for binary cycles in target platform: CHECKED
- Use class files compiled in the workspace: UNCHECKED
- Finish