mirror of
https://github.com/NationalSecurityAgency/ghidra.git
synced 2024-11-21 19:42:14 +00:00
Merge branch 'GP-0_ryanmkurtz_InstallationGuide'
This commit is contained in:
Ryan Kurtz
commit
aff12cd6e0
@ -1,497 +0,0 @@
|
|||||||
<!DOCTYPE html>
|
|
||||||
<html>
|
|
||||||
<head>
|
|
||||||
<title>GhidraDev README</title>
|
|
||||||
<style name="text/css">
|
|
||||||
li { font-family:times new roman; font-size:14pt; font-family:times new roman; font-size:14pt; margin-bottom: 12px; }
|
|
||||||
h1 { color:#000080; font-family:times new roman; font-size:36pt; font-style:italic; font-weight:bold; text-align:center; }
|
|
||||||
h2 { padding-top:30px; color:#984c4c; font-family:times new roman; font-size:18pt; font-weight:bold; }
|
|
||||||
p { font-family:times new roman; font-size:14pt; }
|
|
||||||
td { font-family:times new roman; font-size:14pt; padding-left:10px; padding-right:10px; }
|
|
||||||
th { font-family:times new roman; font-size:14pt; font-weight:bold; padding-left:10px; padding-right:10px; }
|
|
||||||
code { color:black; font-family:courier new font-size: 14pt; }
|
|
||||||
span.code { font-family:courier new font-size: 14pt; color:#000000; }
|
|
||||||
</style>
|
|
||||||
</head>
|
|
||||||
|
|
||||||
<body>
|
|
||||||
|
|
||||||
<h1>GhidraDev README</h1>
|
|
||||||
<p>GhidraDev provides support for developing and debugging Ghidra scripts and modules in Eclipse.
|
|
||||||
</p>
|
|
||||||
<p>The information provided in this document is effective as of GhidraDev 4.0.0 and is subject to
|
|
||||||
change with future releases.</p>
|
|
||||||
|
|
||||||
<ul>
|
|
||||||
<li><a href="#ChangeHistory">Change History</a></li>
|
|
||||||
<li><a href="#MinimumRequirements">Minimum Requirements</a></li>
|
|
||||||
<li><a href="#OptionalRequirements">Optional Requirements</a></li>
|
|
||||||
<li><a href="#Install">Installing</a></li>
|
|
||||||
<ul>
|
|
||||||
<li><a href="#ManualInstall">Manual Installation in Eclipse</a></li>
|
|
||||||
<li><a href="#AutoInstall">Automatic Installation through Ghidra</a></li>
|
|
||||||
</ul>
|
|
||||||
<li><a href="#Features">GhidraDev Features</a></li>
|
|
||||||
<ul>
|
|
||||||
<li><a href="#NewGhidraScript">New Ghidra Script</a></li>
|
|
||||||
<li><a href="#NewGhidraScriptProject">New Ghidra Script Project</a></li>
|
|
||||||
<li><a href="#NewGhidraModuleProject">New Ghidra Module Project</a></li>
|
|
||||||
<li><a href="#ImportGhidraModuleSource">Import Ghidra Module Source</a></li>
|
|
||||||
<li><a href="#ExportGhidraModuleExtension">Export Ghidra Module Extension</a></li>
|
|
||||||
<li><a href="#Preferences">Preferences</a></li>
|
|
||||||
<li><a href="#LinkGhidra">Link Ghidra</a></li>
|
|
||||||
</ul>
|
|
||||||
<li><a href="#Launching">Launching and Debugging Ghidra</a></li>
|
|
||||||
<li><a href="#PyDevSupport">PyDev Support</a></li>
|
|
||||||
<ul>
|
|
||||||
<li><a href="#PyDevInstall">Installing PyDev</a></li>
|
|
||||||
<li><a href="#PyDevConfigure">Configuring PyDev</a></li>
|
|
||||||
</ul>
|
|
||||||
<li><a href="#Upgrade">Upgrading</a></li>
|
|
||||||
<li><a href="#Uninstall">Uninstalling</a></li>
|
|
||||||
<li><a href="#FAQ">Frequently Asked Questions</a></li>
|
|
||||||
<li><a href="#AdditionalResources">Additional Resources</a></li>
|
|
||||||
</ul>
|
|
||||||
|
|
||||||
<h2><a name="ChangeHistory"></a>Change History</h2>
|
|
||||||
<p><u><b>4.0.0</b>:</u>
|
|
||||||
<ul>
|
|
||||||
<li>
|
|
||||||
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.
|
|
||||||
</li>
|
|
||||||
<li>
|
|
||||||
GhidraDev now requires Eclipse 2023-12 4.30 or later.
|
|
||||||
</li>
|
|
||||||
<li>
|
|
||||||
GhidraDev now requires JDK 21.
|
|
||||||
</li>
|
|
||||||
<li>
|
|
||||||
Fixed an issue that could result in a <i>GhidraHelpService</i> exception when launching
|
|
||||||
Ghidra. GhidraDev now properly enforces that Ghidra is only launched with <i>Utility.jar</i> on
|
|
||||||
the initial classpath.
|
|
||||||
</li>
|
|
||||||
</ul>
|
|
||||||
<p><u><b>3.1.0</b>:</u>
|
|
||||||
<ul>
|
|
||||||
<li>
|
|
||||||
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.
|
|
||||||
</li>
|
|
||||||
<li>
|
|
||||||
GhidraDev now supports importing a Ghidra module source directory. This will work best
|
|
||||||
with Ghidra module projects created from Ghidra 11.1 or later.
|
|
||||||
</li>
|
|
||||||
<li>
|
|
||||||
GhidraDev will now fail to launch Ghidra if a top-level <i>build</i> directory is detected.
|
|
||||||
Presence of this intermediate build artifact can cause Ghidra to have runtime/debugging issues.
|
|
||||||
</li>
|
|
||||||
</ul>
|
|
||||||
<p><u><b>3.0.2</b>:</u>
|
|
||||||
<ul>
|
|
||||||
<li>
|
|
||||||
GhidraDev no longer throws an IOException when performing a "Link Ghidra" action on a Ghidra
|
|
||||||
project whose original Ghidra installation moved.
|
|
||||||
</li>
|
|
||||||
<li>
|
|
||||||
GhidraDev now prevents unsupported versions of PyDev from being used.
|
|
||||||
</li>
|
|
||||||
</ul>
|
|
||||||
<p><u><b>3.0.1</b>:</u>
|
|
||||||
<ul>
|
|
||||||
<li>
|
|
||||||
Exporting a Ghidra Module Extension produces an intermediate <i>build</i> directory within the
|
|
||||||
project. This <i>build</i> directory now gets automatically cleaned up to avoid Ghidra
|
|
||||||
runtime/debugging issues.
|
|
||||||
</li>
|
|
||||||
<li>
|
|
||||||
GhidraDev now prevents unsupported Ghidra source repositories from being added as a Ghidra
|
|
||||||
installations.
|
|
||||||
</li>
|
|
||||||
</ul>
|
|
||||||
<p><u><b>3.0.0</b>:</u>
|
|
||||||
<ul>
|
|
||||||
<li>
|
|
||||||
GhidraDev now requires Eclipse 2021-12 4.22 or later.
|
|
||||||
</li>
|
|
||||||
<li>
|
|
||||||
GhidraDev now requires JDK 17.
|
|
||||||
</li>
|
|
||||||
<li>
|
|
||||||
Fixed an issue that could cause old extensions to incorrectly remain on the Ghidra project
|
|
||||||
classpath after performing a "Link Ghidra."
|
|
||||||
</li>
|
|
||||||
</ul>
|
|
||||||
<p><u><b>2.1.5</b>:</u> Eclipse Python breakpoints now work when Eclipse installs PyDev in .p2
|
|
||||||
bundle pool directory.</p>
|
|
||||||
<p><u><b>2.1.4</b>:</u> Fixed exception that occurred when performing a "Link Ghidra" on projects
|
|
||||||
that use a Gradle classpath container.</p>
|
|
||||||
<p><u><b>2.1.3</b>:</u> Fixed a bug that prevented Ghidra projects from recognizing extensions
|
|
||||||
installed in the user's <i>~/.ghidra/.ghidra_<version>/Extensions</i> directory.</p>
|
|
||||||
<p><u><b>2.1.2</b>:</u> Fixed exception that occurred when creating a new Ghidra scripting project
|
|
||||||
if a <i>~/ghidra_scripts</i> directory does not exist.</p>
|
|
||||||
<p><u><b>2.1.1</b>:</u>
|
|
||||||
<ul>
|
|
||||||
<li>
|
|
||||||
Python debugging now works when PyDev is installed via the Eclipse "dropins" directory.
|
|
||||||
</li>
|
|
||||||
<li>
|
|
||||||
Fixed a bug in the check that prevents Ghidra projects from being created within the Ghidra
|
|
||||||
installation directory.
|
|
||||||
</li>
|
|
||||||
</ul>
|
|
||||||
<p><u><b>2.1.0</b>:</u>
|
|
||||||
<ul>
|
|
||||||
<li>
|
|
||||||
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.
|
|
||||||
</li>
|
|
||||||
<li>
|
|
||||||
Prevented Ghidra projects from being created inside of a Ghidra installation directory.
|
|
||||||
</li>
|
|
||||||
<li>
|
|
||||||
Added an <i>Environments</i> tab to the Ghidra run configuration for setting environment
|
|
||||||
variables when launching Ghidra.
|
|
||||||
</li>
|
|
||||||
</ul>
|
|
||||||
<p><u><b>2.0.1</b>:</u> Fixed exception that occurred when performing certain actions on a Ghidra
|
|
||||||
project that was imported from a previously exported Archive File.</p>
|
|
||||||
<p><u><b>2.0.0</b>:</u>
|
|
||||||
<ul>
|
|
||||||
<li>
|
|
||||||
Improved Ghidra module project starting templates for Analyzer and Plugin and added new
|
|
||||||
templates for Loader, Exporter, and FileSystem.
|
|
||||||
</li>
|
|
||||||
<li>
|
|
||||||
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.
|
|
||||||
</li>
|
|
||||||
<li>
|
|
||||||
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.
|
|
||||||
</li>
|
|
||||||
<li>
|
|
||||||
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.
|
|
||||||
</li>
|
|
||||||
<li>
|
|
||||||
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.
|
|
||||||
</li>
|
|
||||||
<li>
|
|
||||||
The GhidraDev popup menu is now visible from within the Project Explorer (it was previously only
|
|
||||||
visible in the Package Explorer).
|
|
||||||
</li>
|
|
||||||
<li>
|
|
||||||
A new page has been added to the Export Ghidra Module Extension wizard that allows the user to
|
|
||||||
point to a specific Gradle installation.
|
|
||||||
</li>
|
|
||||||
</ul>
|
|
||||||
<p><u><b>1.0.2</b>:</u> Fixed exception that occurred when performing a "Link Ghidra" on projects
|
|
||||||
that specify other projects on their build paths.</p>
|
|
||||||
<p><u><b>1.0.1</b>:</u> Initial Release.</p>
|
|
||||||
|
|
||||||
<h2><a name="MinimumRequirements"></a>Minimum Requirements</h2>
|
|
||||||
<ul>
|
|
||||||
<li>Eclipse 2023-12 4.30 or later</li>
|
|
||||||
<li>Ghidra 11.2 or later</li>
|
|
||||||
</ul>
|
|
||||||
<p>(<a href="#top">Back to Top</a>)</p>
|
|
||||||
|
|
||||||
<h2><a name="OptionalRequirements"></a>Optional Requirements</h2>
|
|
||||||
<ul>
|
|
||||||
<li>PyDev 6.3.1 - 9.3.0 (<a href="#PyDevSupport">more info</a>)</li>
|
|
||||||
<li>CDT 8.6.0 or later</li>
|
|
||||||
<li>
|
|
||||||
Gradle - required version(s) specified by linked Ghidra release
|
|
||||||
(<a href="#ExportGhidraModuleExtension">more info</a>)
|
|
||||||
</li>
|
|
||||||
</ul>
|
|
||||||
<p>(<a href="#top">Back to Top</a>)</p>
|
|
||||||
|
|
||||||
<h2><a name="Install"></a>Installing GhidraDev</h2>
|
|
||||||
<p>GhidraDev can be installed either manually into Eclipse or automatically by Ghidra, depending on
|
|
||||||
your uses cases. The following two sections outline both procedures.</p>
|
|
||||||
<h3><a name="ManualInstall"></a>Manual Installation in Eclipse</h3>
|
|
||||||
<p>GhidraDev can be installed into an existing installation of Eclipse the same way most Eclipse
|
|
||||||
plugins are installed. From Eclipse:</p>
|
|
||||||
<ol>
|
|
||||||
<li>Click <b>Help → Install New Software...</b></li>
|
|
||||||
<li>Click <b>Add...</b></li>
|
|
||||||
<li>Click <b>Archive...</b></li>
|
|
||||||
<li>
|
|
||||||
Select GhidraDev zip file from <i><GhidraInstallDir></i>/Extensions/Eclipse/GhidraDev/
|
|
||||||
</li>
|
|
||||||
<li>Click <b>OK</b> (name field can be blank)</li>
|
|
||||||
<li>Check <b>Ghidra</b> category (or <b>GhidraDev</b> entry)</li>
|
|
||||||
<li>Click <b>Next</b></li>
|
|
||||||
<li>Click <b>Next</b></li>
|
|
||||||
<li>Accept the terms of the license agreement</li>
|
|
||||||
<li>Click <b>Finish</b></li>
|
|
||||||
<li>Check <b>Unsigned</b> table entry</li>
|
|
||||||
<li>Click <b>Trust Selected</b></li>
|
|
||||||
<li>Click <b>Restart Now</b></li>
|
|
||||||
</ol>
|
|
||||||
<h3><a name="AutoInstall"></a>Automatic Installation through Ghidra</h3>
|
|
||||||
<p>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 <i>dropins</i> directory if GhidraDev
|
|
||||||
is not already installed.</p>
|
|
||||||
<p>(<a href="#top">Back to Top</a>)</p>
|
|
||||||
|
|
||||||
<h2><a name="Features"></a>Features</h2>
|
|
||||||
<p>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".</p>
|
|
||||||
<ul>
|
|
||||||
<li>New</li>
|
|
||||||
<ul>
|
|
||||||
<li>
|
|
||||||
<a name="NewGhidraScript"></a><b>Ghidra Script:</b> 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.
|
|
||||||
</li>
|
|
||||||
<li>
|
|
||||||
<a name="NewGhidraScriptProject"></a><b>Ghidra Script Project:</b> 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 <i>ghidra_scripts</i>
|
|
||||||
directory, as well as any scripts found in the Ghidra installation.
|
|
||||||
</li>
|
|
||||||
<li>
|
|
||||||
<a name="NewGhidraModuleProject"></a><b>Ghidra Module Project:</b> 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.
|
|
||||||
</li>
|
|
||||||
</ul>
|
|
||||||
<li>Import</li>
|
|
||||||
<ul>
|
|
||||||
<li>
|
|
||||||
<a name="ImportGhidraModuleSource"></a><b>Ghidra Module Source:</b> Opens a wizard that
|
|
||||||
imports a Ghidra module source directory as a new Ghidra module project.
|
|
||||||
</li>
|
|
||||||
</ul>
|
|
||||||
<li>Export</li>
|
|
||||||
<ul>
|
|
||||||
<li>
|
|
||||||
<a name="ExportGhidraModuleExtension"></a><b>Ghidra Module Extension:</b> Opens a wizard that
|
|
||||||
exports a Ghidra module project as a Ghidra extension to the project's <i>dist</i> 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 by the linked Ghidra release.
|
|
||||||
</li>
|
|
||||||
</ul>
|
|
||||||
<li><a name="Preferences"></a>Preferences</li>
|
|
||||||
<ul>
|
|
||||||
<li>
|
|
||||||
<b>Ghidra Installations:</b> Add or remove Ghidra installations. Certain features such as
|
|
||||||
creating Ghidra script/module projects require linking against a valid installation of Ghidra.
|
|
||||||
</li>
|
|
||||||
<li>
|
|
||||||
<b>Script Editor:</b> The port used by Ghidra to open a script in Eclipse. Must match the
|
|
||||||
corresponding port in Ghidra's <i>Eclipse Integration</i> tool options. Disable this
|
|
||||||
preference to prevent GhidraDev from listening on a port for this feature.
|
|
||||||
</li>
|
|
||||||
<li>
|
|
||||||
<b>Symbol Lookup:</b> The project name and port used by Ghidra to perform symbol lookup in
|
|
||||||
Eclipse. Must match the corresponding port in Ghidra's <i>Eclipse Integration</i> 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 <a href="#OptionalRequirements">optional requirements</a> for supported versions).
|
|
||||||
</li>
|
|
||||||
</ul>
|
|
||||||
<li>
|
|
||||||
<a name="LinkGhidra"></a><b>Link Ghidra:</b> 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.
|
|
||||||
</li>
|
|
||||||
</ul>
|
|
||||||
<p>Most GhidraDev features can also be accessed by right-clicking on appropriate project elements in
|
|
||||||
Eclipse's Project/Package Explorer. For example, the <a href="#LinkGhidra">Link Ghidra</a> feature
|
|
||||||
can be accessed by right-clicking on an existing Java project, and then clicking <b>Ghidra →
|
|
||||||
Link Ghidra...</b>
|
|
||||||
</p>
|
|
||||||
<p>(<a href="#top">Back to Top</a>)</p>
|
|
||||||
|
|
||||||
<h2><a name="Launching"></a>Launching and Debugging Ghidra</h2>
|
|
||||||
<p>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:</p>
|
|
||||||
<ul>
|
|
||||||
<li>
|
|
||||||
<b>Ghidra:</b> Launches the Ghidra GUI.
|
|
||||||
</li>
|
|
||||||
<li>
|
|
||||||
<b>Ghidra Headless:</b> 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 <i>Ghidra Headless</i>
|
|
||||||
run configurations will have to be modified with the desired headless program arguments. For
|
|
||||||
more information on headless command line arguments, see
|
|
||||||
<i><GhidraInstallDir></i>/support/analyzeHeadlessREADME.html.
|
|
||||||
</li>
|
|
||||||
</ul>
|
|
||||||
<p>There are two ways to create Ghidra run configurations:</p>
|
|
||||||
<ol>
|
|
||||||
<li>Click <b>Run → Run Configurations...</b></li>
|
|
||||||
<li>Right-click on <i>Ghidra</i> (or <i>Ghidra Headless</i>), and click <b>New</b></li>
|
|
||||||
<li>In the <i>Main</i> tab, click <b>Browse...</b> and select the Ghidra project to launch</li>
|
|
||||||
<li>Optionally rename the new run configuration by editing the <i>Name</i> field at the top
|
|
||||||
</ol>
|
|
||||||
<p>Alternatively, you can right-click on any Ghidra project in the Eclipse package explorer, and
|
|
||||||
then click <b>Run As → Ghidra</b>.</p>
|
|
||||||
<p>To debug Ghidra, click <b>Debug As → Ghidra</b>. GhidraDev will automatically switch
|
|
||||||
Eclipse to the debug perspective.</p>
|
|
||||||
<p><b>NOTE:</b> Ghidra can only be launched/debugged from an existing Eclipse Ghidra project.
|
|
||||||
Launching Ghidra from Eclipse independent of a project is not supported.</p>
|
|
||||||
<p>(<a href="#top">Back to Top</a>)</p>
|
|
||||||
|
|
||||||
<h2><a name="PyDevSupport"></a>PyDev Support</h2>
|
|
||||||
<p>GhidraDev is able to integrate with PyDev to conveniently configure Python support into Ghidra
|
|
||||||
script and module projects.</p>
|
|
||||||
<h3><a name="PyDevInstall"></a>Installing PyDev</h3>
|
|
||||||
<p>From Eclipse:</p>
|
|
||||||
<ol>
|
|
||||||
<li>
|
|
||||||
Download PyDev (see <a href="#OptionalRequirements">optional requirements</a> for supported
|
|
||||||
versions)
|
|
||||||
</li>
|
|
||||||
<li>Unzip PyDev</li>
|
|
||||||
<li>Click <b>Help → Install New Software...</b></li>
|
|
||||||
<li>Click <b>Add...</b></li>
|
|
||||||
<li>Click <b>Local...</b></li>
|
|
||||||
<li>Select unzipped PyDev directory</li>
|
|
||||||
<li>Click <b>OK</b> (name field can be blank)</li>
|
|
||||||
<li>Uncheck <b>Group items by category</b> (if applicable)</li>
|
|
||||||
<li>Check <b>PyDev for Eclipse</b></li>
|
|
||||||
<li>Click <b>Next</b></li>
|
|
||||||
<li>Click <b>Next</b></li>
|
|
||||||
<li>Accept the terms of the license agreement</li>
|
|
||||||
<li>Click <b>Finish</b></li>
|
|
||||||
<li>Click <b>Restart Now</b></li>
|
|
||||||
</ol>
|
|
||||||
<h3><a name="PyDevConfigure"></a>Configuring PyDev</h3>
|
|
||||||
<p>GhidraDev can add Python support to a Ghidra project when:
|
|
||||||
<ul>
|
|
||||||
<li>Creating a new Ghidra module project</li>
|
|
||||||
<li>Creating a new Ghidra script project</li>
|
|
||||||
<li>Linking a Ghidra installation to an existing Java project</li>
|
|
||||||
</ul>
|
|
||||||
<p>In order for GhidraDev to add in Python support, PyDev must have a Jython interpreter configured.
|
|
||||||
GhidraDev will present a list of detected Jython interpreters that it found in PyDev's preferences.
|
|
||||||
If no Jython interpreters were found, one can be added from GhidraDev by clicking the <b>+</b> icon.
|
|
||||||
When the <b>+</b> 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.</p>
|
|
||||||
<p>(<a href="#top">Back to Top</a>)</p>
|
|
||||||
|
|
||||||
<h2><a name="Upgrade"></a>Upgrading</h2>
|
|
||||||
<p>GhidraDev is upgraded differently depending on how it was installed. If GhidraDev was
|
|
||||||
<a href="#ManualInstall">manually installed in Eclipse</a>, it can be upgraded the same was it was
|
|
||||||
<a href="#ManualInstall">installed</a>.</p>
|
|
||||||
<p>If GhidraDev was <a href="#AutoInstall">automatically installed through Ghidra</a>, it can be
|
|
||||||
upgraded by simply removing the GhidraDev file from Eclipse's <i>dropins</i> directory before
|
|
||||||
following one of the two techniques described in the <a href="#Install">Installing GhidraDev</a>
|
|
||||||
section.</p>
|
|
||||||
<p>(<a href="#top">Back to Top</a>)</p>
|
|
||||||
|
|
||||||
<h2><a name="Uninstall"></a>Uninstalling</h2>
|
|
||||||
<p>GhidraDev is uninstalled differently depending on how it was installed. If GhidraDev was
|
|
||||||
<a href="#ManualInstall">manually installed in Eclipse</a>, it can be uninstalled as follows from
|
|
||||||
Eclipse:</p>
|
|
||||||
<ol>
|
|
||||||
<li>Click <b>Help → About Eclipse</b></li>
|
|
||||||
<ul>
|
|
||||||
<li><i>For macOS:</i> <b>Eclipse → About Eclipse</b></li>
|
|
||||||
</ul>
|
|
||||||
<li>Click <b>Installation Details</b></li>
|
|
||||||
<li>Select GhidraDev</li>
|
|
||||||
<li>Click <b>Uninstall...</b></li>
|
|
||||||
<li>Select GhidraDev</li>
|
|
||||||
<li>Click <b>Finish</b></li>
|
|
||||||
<li>Click <b>Restart Now</b></li>
|
|
||||||
</ol>
|
|
||||||
<p>If GhidraDev was <a href="#AutoInstall">automatically installed through Ghidra</a>, it can be
|
|
||||||
uninstalled by simply removing the GhidraDev file from Eclipse's <i>dropins</i> directory and
|
|
||||||
restarting Eclipse. The <i>dropins</i> directory can be found at the top level of Eclipse's
|
|
||||||
installation directory.</p>
|
|
||||||
<p>(<a href="#top">Back to Top</a>)</p>
|
|
||||||
|
|
||||||
<h2><a name="FAQ"></a>Frequently Asked Questions</h2>
|
|
||||||
<ul>
|
|
||||||
<li>
|
|
||||||
<b><i>I've created a Ghidra script project. Where should I create my new scripts?</i></b>
|
|
||||||
<ul>
|
|
||||||
<li>
|
|
||||||
<p>The best place to create your scripts in is your home <i>~/ghidra_scripts</i> directory
|
|
||||||
because Ghidra will automatically find them there without any additional configuration. By
|
|
||||||
default, your Ghidra script project will have a folder named <b>Home scripts</b> which is
|
|
||||||
linked to your home <i>~/ghidra_scripts</i> directory. Either right-click on this folder in
|
|
||||||
Eclipse and do <b>GhidraDev → New → GhidraScript...</b> or from the menu bar do
|
|
||||||
<b>GhidraDev → New → GhidraScript...</b> and populate the <i>Script folder</i>
|
|
||||||
box with your project's <b>Home scripts</b> folder.</p>
|
|
||||||
</li>
|
|
||||||
</ul>
|
|
||||||
</li>
|
|
||||||
<li>
|
|
||||||
<b><i>How do I launch Ghidra in headless mode from Eclipse?</i></b>
|
|
||||||
<ul>
|
|
||||||
<li>
|
|
||||||
<p>GhidraDev provides custom run configurations to launch Ghidra installations both in GUI
|
|
||||||
mode and headlessly. See the <a href="#Launching">Launching</a> section for information on
|
|
||||||
how to launch Ghidra from Eclipse.</p>
|
|
||||||
</li>
|
|
||||||
</ul>
|
|
||||||
</li>
|
|
||||||
<li>
|
|
||||||
<b><i>Why doesn't my Ghidra module project know about the Ghidra extension I installed into my
|
|
||||||
Ghidra installation?</i></b>
|
|
||||||
<ul>
|
|
||||||
<li>
|
|
||||||
<p>You most likely installed the Ghidra extension after the Ghidra installation was linked
|
|
||||||
to your Ghida module project, which automatically happens when the project is created.
|
|
||||||
Simply <a href="#LinkGhidra">relink</a> your Ghidra installation to the project, and your
|
|
||||||
project will pick up any newly discovered Ghidra extensions.</p>
|
|
||||||
</li>
|
|
||||||
</ul>
|
|
||||||
</li>
|
|
||||||
<li>
|
|
||||||
<b><i>Why doesn't GhidraDev support PyDev 10.0 or later?</i></b>
|
|
||||||
<ul>
|
|
||||||
<li>
|
|
||||||
<p>PyDev dropped support for Python 2 in their 10.0 release. Ghidra currently does not
|
|
||||||
support Python 3.</p>
|
|
||||||
</li>
|
|
||||||
</ul>
|
|
||||||
</li>
|
|
||||||
</ul>
|
|
||||||
<p>(<a href="#top">Back to Top</a>)</p>
|
|
||||||
|
|
||||||
<h2><a name="AdditionalResources"></a>Additional Resources</h2>
|
|
||||||
<p>For more information on the GhidraDev plugin and developing for Ghidra in an Eclipse environment,
|
|
||||||
please see:
|
|
||||||
<ul>
|
|
||||||
<li>
|
|
||||||
<b>Ghidra Scripting slide deck:</b>
|
|
||||||
<i><GhidraInstallDir></i>/docs/GhidraClass/Intermediate/Scripting.html</li>
|
|
||||||
</li>
|
|
||||||
</ul>
|
|
||||||
<p>(<a href="#top">Back to Top</a>)</p>
|
|
||||||
|
|
||||||
<!-- Some padding -->
|
|
||||||
<br>
|
|
||||||
<br>
|
|
||||||
<br>
|
|
||||||
|
|
||||||
</body>
|
|
||||||
</html>
|
|
||||||
@ -54,7 +54,7 @@ __3.0.2:__
|
|||||||
* GhidraDev now prevents unsupported versions of PyDev from being used.
|
* GhidraDev now prevents unsupported versions of PyDev from being used.
|
||||||
|
|
||||||
__3.0.1:__
|
__3.0.1:__
|
||||||
* Exporting a Ghidra Module Extension produces an intermediate `build<` directory within the
|
* Exporting a Ghidra Module Extension produces an intermediate `build` directory within the
|
||||||
project. This `build` directory now gets automatically cleaned up to avoid Ghidra
|
project. This `build` directory now gets automatically cleaned up to avoid Ghidra
|
||||||
runtime/debugging issues.
|
runtime/debugging issues.
|
||||||
* GhidraDev now prevents unsupported Ghidra source repositories from being added as a Ghidra
|
* GhidraDev now prevents unsupported Ghidra source repositories from being added as a Ghidra
|
||||||
|
|||||||
@ -5,7 +5,6 @@ GhidraDevFeature/category.xml||GHIDRA||||END|
|
|||||||
GhidraDevFeature/feature.xml||GHIDRA||||END|
|
GhidraDevFeature/feature.xml||GHIDRA||||END|
|
||||||
GhidraDevPlugin/.launch/GhidraDev.launch||GHIDRA||||END|
|
GhidraDevPlugin/.launch/GhidraDev.launch||GHIDRA||||END|
|
||||||
GhidraDevPlugin/GhidraDev.target||GHIDRA||||END|
|
GhidraDevPlugin/GhidraDev.target||GHIDRA||||END|
|
||||||
GhidraDevPlugin/GhidraDev_README.html||GHIDRA||||END|
|
|
||||||
GhidraDevPlugin/META-INF/MANIFEST.MF||GHIDRA||||END|
|
GhidraDevPlugin/META-INF/MANIFEST.MF||GHIDRA||||END|
|
||||||
GhidraDevPlugin/README.md||GHIDRA||||END|
|
GhidraDevPlugin/README.md||GHIDRA||||END|
|
||||||
GhidraDevPlugin/build.properties||GHIDRA||||END|
|
GhidraDevPlugin/build.properties||GHIDRA||||END|
|
||||||
|
|||||||
@ -1,733 +0,0 @@
|
|||||||
<!DOCTYPE html>
|
|
||||||
<html>
|
|
||||||
<head>
|
|
||||||
<title>Ghidra Installation Guide</title>
|
|
||||||
<style name="text/css">
|
|
||||||
li { font-family:times new roman; font-size:14pt; margin-bottom: 6px; }
|
|
||||||
h1 { color:#000080; font-family:times new roman; font-size:36pt; font-style:italic; font-weight:bold; text-align:center; }
|
|
||||||
h2 { padding-top:30px; color:#984c4c; font-family:times new roman; font-size:18pt; font-weight:bold; }
|
|
||||||
h2 { color:#984c4c; font-family:times new roman; font-size:18pt; font-weight:bold; color:#984c4c; }
|
|
||||||
h3 { color:#0000ff; font-family:times new roman; font-size:14pt; font-weight:bold; color:#0000ff; }
|
|
||||||
p { font-family:times new roman; font-size:14pt; }
|
|
||||||
td { font-family:times new roman; font-size:14pt; padding-left:10px; padding-right:10px; vertical-align: top; }
|
|
||||||
th { font-family:times new roman; font-size:14pt; font-weight:bold; padding-left:10px; padding-right:10px; }
|
|
||||||
pre { font-size:12pt }
|
|
||||||
</style>
|
|
||||||
</head>
|
|
||||||
|
|
||||||
<body>
|
|
||||||
|
|
||||||
<h1>Ghidra Installation Guide</h1>
|
|
||||||
<p>
|
|
||||||
The installation information provided is effective as of Ghidra 11.2 and is subject to change with
|
|
||||||
future releases.
|
|
||||||
</p>
|
|
||||||
|
|
||||||
<ul>
|
|
||||||
<li><a href="#Platforms">Platforms Supported</a></li>
|
|
||||||
<li><a href="#Requirements">Minimum Requirements</a></li>
|
|
||||||
<li><a href="#Install">Installing Ghidra</a></li>
|
|
||||||
<ul>
|
|
||||||
<li><a href="#InstallationNotes">Installation Notes</a></li>
|
|
||||||
<li><a href="#JavaNotes">Java Notes</a></li>
|
|
||||||
</ul>
|
|
||||||
<li><a href="#Layout">Ghidra Installation Directory Layout</a></li>
|
|
||||||
<li><a href="#Build">Building Native Components</a></li>
|
|
||||||
<li><a href="#DebuggerPython">Installing the Debuggers' Python Dependencies</a></li>
|
|
||||||
<li><a href="#Run">Running Ghidra</a></li>
|
|
||||||
<ul>
|
|
||||||
<li><a href="#RunGUI">GUI Mode</a></li>
|
|
||||||
<li><a href="#RunServer">Ghidra Server</a></li>
|
|
||||||
<li><a href="#RunHeadless">Headless (Batch) Mode</a></li>
|
|
||||||
<li><a href="#RunJar">Single Jar Mode</a></li>
|
|
||||||
<li><a href="#RunPyGhidra">PyGhidra</a></li>
|
|
||||||
</ul>
|
|
||||||
<li><a href="#Extensions">Extensions</a></li>
|
|
||||||
<ul>
|
|
||||||
<li><a href="#GhidraExtensionNotes">Ghidra Extension Notes</a></li>
|
|
||||||
</ul>
|
|
||||||
<li><a href="#Development">Ghidra Development</a></li>
|
|
||||||
<li><a href="#Upgrading">Upgrade Instructions</a></li>
|
|
||||||
<ul>
|
|
||||||
<li><a href="#GeneralUpgrade">General Upgrade Instructions</a></li>
|
|
||||||
<li><a href="#ServerUpgrade">Server Upgrade Instructions</a></li>
|
|
||||||
</ul>
|
|
||||||
<li><a href="#Troubleshooting">Troubleshooting & Help</a></li>
|
|
||||||
<ul>
|
|
||||||
<li><a href="#LaunchIssues">Launching Ghidra</a></li>
|
|
||||||
<li><a href="#GhidraHelp">Using Ghidra</a></li>
|
|
||||||
</ul>
|
|
||||||
<li><a href="#KnownIssues">Known Issues</a></li>
|
|
||||||
<ul>
|
|
||||||
<li><a href="#CommonIssues">All Platforms</a></li>
|
|
||||||
<li><a href="#WindowsIssues">Windows</a></li>
|
|
||||||
<li><a href="#LinuxIssues">Linux</a></li>
|
|
||||||
<li><a href="#MacOSIssues">macOS (OS X)</a></li>
|
|
||||||
</ul>
|
|
||||||
</ul>
|
|
||||||
|
|
||||||
|
|
||||||
<h2><a name="Platforms"></a>Platforms Supported</h2>
|
|
||||||
<ul>
|
|
||||||
<li>Windows 10 or later (64-bit)</li>
|
|
||||||
<li>Linux (64-bit)</li>
|
|
||||||
<li>macOS 10.13 or later</li>
|
|
||||||
</ul>
|
|
||||||
<blockquote><p><b>NOTE: </b>All 32-bit OS installations are now deprecated. Please contact the
|
|
||||||
Ghidra team if you have a specific need.</p></blockquote>
|
|
||||||
|
|
||||||
<h2><a name="Requirements"></a>Minimum Requirements</h2>
|
|
||||||
<h3>Hardware</h3>
|
|
||||||
<ul>
|
|
||||||
<li>4 GB RAM</li>
|
|
||||||
<li>1 GB storage (for installed Ghidra binaries)</li>
|
|
||||||
<li>Dual monitors strongly suggested</li>
|
|
||||||
</ul>
|
|
||||||
<h3>Software</h3>
|
|
||||||
<ul>
|
|
||||||
<li>Java 21 64-bit Runtime and Development Kit (JDK) (see <a href="#JavaNotes">Java Notes</a>)</li>
|
|
||||||
<ul>
|
|
||||||
<li>Free long term support (LTS) versions of JDK 21 are provided by:</li>
|
|
||||||
<ul>
|
|
||||||
<li>
|
|
||||||
<a href="https://adoptium.net/temurin/releases">
|
|
||||||
Adoptium Temurin</a>
|
|
||||||
</li>
|
|
||||||
<li>
|
|
||||||
<a href="https://docs.aws.amazon.com/corretto/latest/corretto-21-ug/downloads-list.html">
|
|
||||||
Amazon Corretto</a>
|
|
||||||
</li>
|
|
||||||
</ul>
|
|
||||||
</ul>
|
|
||||||
<li>Python3 (3.9 to 3.12)</li>
|
|
||||||
<ul>
|
|
||||||
<li>Python 3.7 to 3.12 for <a href="#DebuggerPython">Debugger support</a></li>
|
|
||||||
<li>Python 3.9 to 3.12 for <a href="#RunPyGhidra">PyGhidra support</a></li>
|
|
||||||
<li>This is available from <a href="https://python.org">Python.org</a> or most operating system's
|
|
||||||
app stores or software repositories. For Linux it is recommended that the system's package
|
|
||||||
repository be used to install a suitable version of Python.</li>
|
|
||||||
</ul>
|
|
||||||
</ul>
|
|
||||||
<p>(<a href="#top">Back to Top</a>)</p>
|
|
||||||
|
|
||||||
<h3>
|
|
||||||
|
|
||||||
<h2><a name="Install"></a>Installing Ghidra</h2>
|
|
||||||
<p>To install Ghidra, simply extract the Ghidra distribution file to the desired filesystem
|
|
||||||
destination using any unzip program (built-in OS utilities, 7-Zip, WinZip, WinRAR, etc)</p>
|
|
||||||
|
|
||||||
<h3><a name="InstallationNotes"></a>Installation Notes</h3>
|
|
||||||
<ul>
|
|
||||||
<li>
|
|
||||||
Ghidra does not use a traditional installer program. Instead, the Ghidra distribution file is
|
|
||||||
simply extracted in-place on the filesystem. This approach has advantages and disadvantages.
|
|
||||||
On the up side, administrative privilege is not required to install Ghidra for personal use.
|
|
||||||
Also, because installing Ghidra does not update any OS configurations such as the registry on
|
|
||||||
Windows, removing Ghidra is as simple as deleting the Ghidra installation directory. On the
|
|
||||||
down side, Ghidra will not automatically create a shortcut on the desktop or appear in
|
|
||||||
application start menus.
|
|
||||||
</li>
|
|
||||||
<li>
|
|
||||||
When launching Ghidra for the first time on macOS, the macOS Gatekeeper feature may attempt
|
|
||||||
to quarantine the pre-built unsigned Ghidra native components. Two techniques can be used to
|
|
||||||
prevent this from happening:
|
|
||||||
<ul>
|
|
||||||
<li>
|
|
||||||
Prior to extracting the Ghidra distribution file, running
|
|
||||||
<i>xattr -d com.apple.quarantine ghidra_<version>_<date>.zip</i>
|
|
||||||
from a terminal.
|
|
||||||
</li>
|
|
||||||
<li>
|
|
||||||
Prior to first launch, following the instructions in the
|
|
||||||
<a href="#Build">Building Native Components</a> section.
|
|
||||||
</li>
|
|
||||||
</ul>
|
|
||||||
</li>
|
|
||||||
<li>
|
|
||||||
Administrative privilege may be required to extract Ghidra to certain filesystem destinations
|
|
||||||
(such as C:\), as well as install the Ghidra Server as a service.
|
|
||||||
</li>
|
|
||||||
<li>
|
|
||||||
Ghidra relies on using directories outside of its installation directory to manage both
|
|
||||||
temporary and longer-living cache files. Ghidra attempts to use standard OS directories that
|
|
||||||
are designed for these purposes in order to avoid several issues, such as storing large amounts
|
|
||||||
of data to a roaming profile. If it is suspected that the default location of these directories
|
|
||||||
is causing a problem, they can be changed by modifying the relevant properties in the
|
|
||||||
<i>support/launch.properties</i> file.
|
|
||||||
</li>
|
|
||||||
</ul>
|
|
||||||
<h3><a name="JavaNotes"></a>Java Notes</h3>
|
|
||||||
<ul>
|
|
||||||
<li>
|
|
||||||
Ghidra requires a <a href="#Requirements">supported</a> version of a Java Runtime and
|
|
||||||
Development Kit on the PATH to run. However, if there is a version of Java on the PATH that
|
|
||||||
Ghidra does not support, it will use that version of Java (if 1.8 or later) to assist in
|
|
||||||
locating a supported version on your system. If one cannot be automatically located, the user
|
|
||||||
will be prompted to enter a path to the Java home directory to use (the Java home directory is
|
|
||||||
the parent directory of Java's <i>bin</i> directory). This minimizes the impact Ghidra has on
|
|
||||||
pre-existing configurations of Java that other software may rely on.
|
|
||||||
</li>
|
|
||||||
<li>
|
|
||||||
Depending on your operating system, it may be possible to find and install a
|
|
||||||
<a href="#Requirements">supported</a> version of a Java Runtime and Development Kit through
|
|
||||||
your package manager, without the need to set the Path environment variables as described
|
|
||||||
below.
|
|
||||||
</li>
|
|
||||||
<li>
|
|
||||||
If Ghidra failed to run because <i>no versions</i> of Java were on the PATH, a
|
|
||||||
<a href="#Requirements">supported</a> JDK should be installed via a Linux package manager
|
|
||||||
(aptitude, yum, etc), Windows installer program (*.exe, *.msi), macOS Installer package
|
|
||||||
(*.pkg), or manually extracted and added to the PATH. The following steps outline how to
|
|
||||||
manually extract and add a JDK distribution to the operating system's PATH.
|
|
||||||
<ul>
|
|
||||||
<li>
|
|
||||||
<p><b>Windows: </b>Extract the JDK distribution (.zip file) to your desired location
|
|
||||||
and add the JDK's bin directory to your PATH:</p>
|
|
||||||
<ol>
|
|
||||||
<li>
|
|
||||||
<p>Extract the JDK:</p>
|
|
||||||
<ol>
|
|
||||||
<li>Right-click on the zip file and click <b>Extract All...</b></li>
|
|
||||||
<li>Click <b>Extract</b></li>
|
|
||||||
</ol>
|
|
||||||
</li>
|
|
||||||
<li>
|
|
||||||
<p>Open Environment Variables window:</p>
|
|
||||||
<ol>
|
|
||||||
<li>Right-click on Windows start button, and click <b>System</b></li>
|
|
||||||
<li>Click <b>Advanced system settings</b></li>
|
|
||||||
<li>Click <b>Environment variables...</b></li>
|
|
||||||
</ol>
|
|
||||||
</li>
|
|
||||||
<li>
|
|
||||||
<p>Add the JDK bin directory to the PATH variable:</p>
|
|
||||||
<ol>
|
|
||||||
<li>Under <b>System variables</b>, highlight <i>Path</i> and click <b>Edit...</b></li>
|
|
||||||
<li>
|
|
||||||
At the end of the the <i>Variable value</i> field, add a semicolon followed by
|
|
||||||
<i><path of extracted JDK dir>\bin</i>, or use the <b>New</b> button in the
|
|
||||||
<i>Edit environment variable</i> window to add a new entry to the <i>Path</i>.
|
|
||||||
</li>
|
|
||||||
<li>Click <b>OK</b></li>
|
|
||||||
<li>Click <b>OK</b></li>
|
|
||||||
<li>Click <b>OK</b></li>
|
|
||||||
</ol>
|
|
||||||
</li>
|
|
||||||
<li>
|
|
||||||
Restart any open Command Prompt windows for changes to take effect
|
|
||||||
</li>
|
|
||||||
</ol>
|
|
||||||
</li>
|
|
||||||
<li>
|
|
||||||
<p><b>Linux and macOS (OS X): </b>Extract the JDK distribution (.tar.gz file) to your
|
|
||||||
desired location, and add the JDK's bin directory to your PATH:</p>
|
|
||||||
<ol>
|
|
||||||
<li>
|
|
||||||
Extract the JDK:
|
|
||||||
<blockquote><i>tar xvf <JDK distribution .tar.gz></i></blockquote>
|
|
||||||
</li>
|
|
||||||
<li>
|
|
||||||
Open ~/.bashrc with an editor of your choice. For example:
|
|
||||||
<blockquote><i>vi ~/.bashrc</i></blockquote>
|
|
||||||
</li>
|
|
||||||
<li>
|
|
||||||
At the very end of the file, add the JDK bin directory to the PATH variable:
|
|
||||||
<blockquote><i>export PATH=<path of extracted JDK dir>/bin:$PATH</i></blockquote>
|
|
||||||
</li>
|
|
||||||
<li>
|
|
||||||
Save file
|
|
||||||
</li>
|
|
||||||
<li>
|
|
||||||
Restart any open terminal windows for changes to take effect
|
|
||||||
</li>
|
|
||||||
</ol>
|
|
||||||
</li>
|
|
||||||
</ul>
|
|
||||||
</li>
|
|
||||||
<li>
|
|
||||||
In some cases, you may want Ghidra to launch with a specific version of Java instead of the
|
|
||||||
version that Ghidra automatically locates. To force Ghidra to launch with a specific version of
|
|
||||||
Java, set the <b>JAVA_HOME_OVERRIDE</b> property in the <i>support/launch.properties</i> file.
|
|
||||||
If this property is set to an incompatible version of Java, Ghidra will revert to automatically
|
|
||||||
locating a compatible version. Note that <i>some</i> Java must still be on the PATH in order
|
|
||||||
for Ghidra to use the <b>JAVA_HOME_OVERRIDE</b> property. This limitation will be addressed in
|
|
||||||
a future version of Ghidra.
|
|
||||||
</li>
|
|
||||||
</ul>
|
|
||||||
<p>(<a href="#top">Back to Top</a>)</p>
|
|
||||||
|
|
||||||
<h2><a name="Layout"></a>Ghidra Installation Directory Layout</h2>
|
|
||||||
<p>When Ghidra is installed, the runnable software gets extracted to a new directory we will refer
|
|
||||||
to as <i><GhidraInstallDir></i>. Below is a description of the top-level directories and
|
|
||||||
files that can be found in <i><GhidraInstallDir></i> once extraction of the distribution file
|
|
||||||
is complete.</p>
|
|
||||||
<table border="0" width="80%">
|
|
||||||
<col width="15%">
|
|
||||||
<col width="85%">
|
|
||||||
<tr>
|
|
||||||
<td valign="top"><b>Ghidra</b></td>
|
|
||||||
<td valign="top">
|
|
||||||
Base directory for Ghidra distribution. Contains files needed to run Ghidra.
|
|
||||||
</td>
|
|
||||||
</tr>
|
|
||||||
<tr>
|
|
||||||
<td valign="top"><b>Extensions</b></td>
|
|
||||||
<td valign="top">
|
|
||||||
Optional components that can extend Ghidra's functionality and integrate Ghidra with other
|
|
||||||
tools.<br>See the <a href="#Extensions">Extensions</a> section for more information.
|
|
||||||
</td>
|
|
||||||
</tr>
|
|
||||||
<tr>
|
|
||||||
<td valign="top"><b>GPL</b></td>
|
|
||||||
<td valign="top">
|
|
||||||
Standalone GPL support programs.
|
|
||||||
</td>
|
|
||||||
</tr>
|
|
||||||
<tr>
|
|
||||||
<td valign="top"><b>server</b></td>
|
|
||||||
<td valign="top">
|
|
||||||
Contains files related to Ghidra Server installation and administration.
|
|
||||||
</td>
|
|
||||||
</tr>
|
|
||||||
<tr>
|
|
||||||
<td valign="top"><b>support</b></td>
|
|
||||||
<td valign="top">
|
|
||||||
Contains files useful for debugging Ghidra, running Ghidra in advanced modes, and controlling
|
|
||||||
how Ghidra launches.
|
|
||||||
</td>
|
|
||||||
</tr>
|
|
||||||
<tr>
|
|
||||||
<td valign="top"><b>docs</b></td>
|
|
||||||
<td valign="top">
|
|
||||||
Contains documentation for Ghidra, such as release notes, API files, tutorials, etc.
|
|
||||||
</td>
|
|
||||||
</tr>
|
|
||||||
<tr>
|
|
||||||
<td valign="top"><b>ghidraRun(.bat)</b></td>
|
|
||||||
<td valign="top">
|
|
||||||
Script used to launch Ghidra.
|
|
||||||
</td>
|
|
||||||
</tr>
|
|
||||||
<tr>
|
|
||||||
<td valign="top"><b>LICENSE</b></td>
|
|
||||||
<td valign="top">Ghidra license information.</td>
|
|
||||||
</tr>
|
|
||||||
<tr>
|
|
||||||
<td valign="top"><b>licenses</b></td>
|
|
||||||
<td valign="top">Contains licenses used by Ghidra.</td>
|
|
||||||
</tr>
|
|
||||||
<tr>
|
|
||||||
<td valign="top"><b>bom.json</b></td>
|
|
||||||
<td valign="top">Software Bill of Materials (SBOM) in CycloneDX JSON format.</td>
|
|
||||||
</tr>
|
|
||||||
</table>
|
|
||||||
<p>(<a href="#top">Back to Top</a>)</p>
|
|
||||||
|
|
||||||
<h2><a name="Build"></a>Building Native Components</h2>
|
|
||||||
<p>Ghidra requires several native binaries to be present in order to successfully run. An official
|
|
||||||
public Ghidra release includes native binaries for the following platforms.
|
|
||||||
</p>
|
|
||||||
<p>NOTE: For some non-public Ghidra releases macOS natives may be omitted.</p>
|
|
||||||
<ul>
|
|
||||||
<li>Windows 10 or later, x86 64-bit</li>
|
|
||||||
<li>Windows 10 or later, ARM 64-bit (using x86 emulation)</li>
|
|
||||||
<li>Linux x86 64-bit</li>
|
|
||||||
<li>macOS x86 64-bit</li>
|
|
||||||
<li>macOS ARM 64-bit</li>
|
|
||||||
</ul>
|
|
||||||
<p>Ghidra supports running on the following additional platforms with user-built native binaries:
|
|
||||||
</p>
|
|
||||||
<ul>
|
|
||||||
<li>Linux ARM 64-bit</li>
|
|
||||||
<li>FreeBSD x86 64-bit (no debugger support)</li>
|
|
||||||
<li>FreeBSD ARM 64-bit (no debugger support)</li>
|
|
||||||
</ul>
|
|
||||||
<p>For supported systems where native binaries have not been supplied, or those that are supplied
|
|
||||||
fail to run properly, it may be necessary to build the native Ghidra binaries.
|
|
||||||
In order to build native binaries for your platform, you will need the following installed on your
|
|
||||||
system:</p>
|
|
||||||
<ul>
|
|
||||||
<li>A <a href="#Requirements">supported</a> version of a Java Development Kit</li>
|
|
||||||
<li><a href="https://gradle.org/releases/">Gradle 8.5+</a> (or supplied Gradle wrapper with
|
|
||||||
Internet connection)
|
|
||||||
</li>
|
|
||||||
|
|
||||||
<li>Software C/C++ build tools and library packages</li>
|
|
||||||
<ul>
|
|
||||||
<li>macOS: <I>Xcode</I> or the abbreviated <I>Command Line Tools for Xcode</I> will supply the
|
|
||||||
necessary build tools. Assuming you are connected to the Internet, <I>Xcode</I>
|
|
||||||
(which includes the command tools) may be installed directly from the App Store
|
|
||||||
while <I>Command Line Tools for Xcode</I> may be installed using the following command:
|
|
||||||
<pre> xcode-select --install</pre></li>
|
|
||||||
<li>Linux/FreeBSD: the 64-bit versions of the following packages should installed:
|
|
||||||
<ul>
|
|
||||||
<li>gcc 8.5 or later</li>
|
|
||||||
<li>gcc-c++ / g++ 8.5 or later</li>
|
|
||||||
<li>make</li>
|
|
||||||
</ul>
|
|
||||||
</li>
|
|
||||||
<li>Windows:
|
|
||||||
<a href="https://visualstudio.microsoft.com/vs/community/">Microsoft Visual Studio</a>
|
|
||||||
2017 or later, or <a href="https://visualstudio.microsoft.com/visual-cpp-build-tools/">
|
|
||||||
Microsoft C++ Build Tools</a> with the following components installed:
|
|
||||||
<ul>
|
|
||||||
<li>MSVC</li>
|
|
||||||
<li>Windows SDK</li>
|
|
||||||
<li>C++ ATL</li>
|
|
||||||
</ul>
|
|
||||||
</li>
|
|
||||||
</ul>
|
|
||||||
</ul>
|
|
||||||
<p>To build the native binaries for your current platform, execute the following commands:</p>
|
|
||||||
<blockquote>
|
|
||||||
<pre>
|
|
||||||
<i>cd <GhidraInstallDir></i>/support/gradle/
|
|
||||||
gradle buildNatives
|
|
||||||
</pre>
|
|
||||||
</blockquote>
|
|
||||||
<p>If you are connected to the Internet and do not have Gradle installed, execute:</p>
|
|
||||||
<blockquote>
|
|
||||||
<pre>
|
|
||||||
<i>cd <GhidraInstallDir></i>/support/gradle/
|
|
||||||
./gradlew(.bat) buildNatives
|
|
||||||
</pre>
|
|
||||||
</blockquote>
|
|
||||||
<p>When the commands successfully complete, Ghidra will contain newly built native binaries in
|
|
||||||
the relevant modules' <i>build/os/<platform>/</i> subdirectories, which will override any
|
|
||||||
existing pre-built native binaries in the <i>os/<platform>/</i> subdirectories.</p>
|
|
||||||
<p>(<a href="#top">Back to Top</a>)</p>
|
|
||||||
|
|
||||||
<h2><a name="DebuggerPython"></a>Installing the Debugger's Python Dependencies</h2>
|
|
||||||
<p>The Debugger now uses Python to connect to the host platform's native debuggers. This requires
|
|
||||||
Python3 (3.9 to 3.12) and some additional packages. These packages are included in the distribution,
|
|
||||||
but you may still install them from PyPI if you prefer:</p>
|
|
||||||
<ul>
|
|
||||||
<li>psutil</li>
|
|
||||||
<li>protobuf==3.20.3</li>
|
|
||||||
<li>Pybag>=2.2.10 (for WinDbg support)</li>
|
|
||||||
</ul>
|
|
||||||
<p>Different native debuggers have varying requirements, so you do not necessarily have to install
|
|
||||||
all of the above packages. Each connector will inform you of its specific requirements and where
|
|
||||||
they must be installed. In some cases, you may need to install packages on the target system.</p>
|
|
||||||
|
|
||||||
<h2><a name="Run"></a>Running Ghidra</h2>
|
|
||||||
<h3><a name="RunGUI"></a>GUI Mode</h3>
|
|
||||||
<ol>
|
|
||||||
<li>
|
|
||||||
Navigate to <i><GhidraInstallDir></i>
|
|
||||||
</li>
|
|
||||||
<li>
|
|
||||||
<p>Run <i>ghidraRun.bat</i> (Windows) or <i>ghidraRun</i> (Linux or macOS)</p>
|
|
||||||
<p>If Ghidra failed to launch, see the <a href="#Troubleshooting">Troubleshooting</a> section.
|
|
||||||
</p>
|
|
||||||
</li>
|
|
||||||
</ol>
|
|
||||||
|
|
||||||
<h3><a name="RunServer"></a>Ghidra Server</h3>
|
|
||||||
<p>Ghidra can support multiple users working together on a single project. Individual Ghidra users
|
|
||||||
launch and work on their own local copies of a particular Ghidra project but check changes into a
|
|
||||||
common repository containing all commits to that repository. For detailed information on
|
|
||||||
installing/configuring the Ghidra Server see the
|
|
||||||
<i><GhidraInstallDir></i>/server/svrREADME.html file.</p>
|
|
||||||
|
|
||||||
<h3><a name="RunHeadless"></a>Headless (Batch) Mode</h3>
|
|
||||||
<p>Ghidra is traditionally run in GUI mode. However, it is also capable of running in headless batch
|
|
||||||
mode using the command line. For more information, see the
|
|
||||||
<i><GhidraInstallDir></i>/support/analyzeHeadlessREADME.html file.</p>
|
|
||||||
|
|
||||||
<h3><a name="RunJar"></a>Single Jar Mode</h3>
|
|
||||||
<p>Normally, Ghidra is installed as an entire directory structure that allows modular inclusion or
|
|
||||||
removal of feature sets and also provides many files that can be extended or configured. However,
|
|
||||||
there are times when it would be useful to have all or some subset of Ghidra compressed into a
|
|
||||||
single jar file at the expense of configuration options. This makes Ghidra easier to run from the
|
|
||||||
command line for headless operation or to use as a library of reverse engineering capabilities for
|
|
||||||
another Java application.</p>
|
|
||||||
<p>A single ghidra.jar file can be created using the
|
|
||||||
<i><GhidraInstallDir></i>/support/buildGhidraJar script.</p>
|
|
||||||
|
|
||||||
<h3><a name="RunPyGhidra"></a>PyGhidra Mode</h3>
|
|
||||||
<p>Ghidra has integrated the the popular PyGhidra extension to enable native CPython 3 support out of
|
|
||||||
the box. To enable this support, Ghidra must be launched from a Python environment using special
|
|
||||||
launch scripts.</p>
|
|
||||||
<ol>
|
|
||||||
<li>
|
|
||||||
Navigate to <i><GhidraInstallDir></i>/support/
|
|
||||||
</li>
|
|
||||||
<li>
|
|
||||||
<p>Run <i>pyghidraRun.bat</i> (Windows) or <i>pyghidraRun</i> (Linux or macOS)</p>
|
|
||||||
<p>If the <b>pyghidra</b> Python module has not yet been installed, the script will offer to
|
|
||||||
install it for you, along with its dependencies. If you prefer to install it manually, execute:
|
|
||||||
<pre>python3 -m pip install --no-index -f <i><GhidraInstallDir></i>/Ghidra/Features/PyGhidra/pypkg/dist pyghidra</pre>
|
|
||||||
<b>NOTE: </b>You may also install and run PyGhidra from within a
|
|
||||||
<a href="https://docs.python.org/3/tutorial/venv.html">virtual environment</a> if you desire.
|
|
||||||
<p>If Ghidra failed to launch, see the <a href="#Troubleshooting">Troubleshooting</a> section.
|
|
||||||
</p>
|
|
||||||
</li>
|
|
||||||
</ol>
|
|
||||||
<p>Once PyGhidra has been installed, you are free to use it like any other Python module. You may
|
|
||||||
import it from other Python scripts, or launch PyGhidra using the <i>pyghidra</i> or <i>pyghidraw</i>
|
|
||||||
commands. For more information on using PyGhidra, see the
|
|
||||||
<i><GhidraInstallDir></i>/Ghidra/Features/PyGhidra/PyGhidra_README.html file.</p>
|
|
||||||
|
|
||||||
<p>(<a href="#top">Back to Top</a>)</p>
|
|
||||||
|
|
||||||
<h2><a name="Extensions"></a>Extensions</h2>
|
|
||||||
<p>Extensions are optional components that can:</p>
|
|
||||||
<ul>
|
|
||||||
<li>
|
|
||||||
Extend Ghidra's functionality with experimental or user-contributed Ghidra plugins or
|
|
||||||
analyzers.
|
|
||||||
</li>
|
|
||||||
<li>Integrate other tools with Ghidra, such as Eclipse or IDAPro.</li>
|
|
||||||
</ul>
|
|
||||||
<p>Ghidra comes with the following extensions available for use (and by default uninstalled), which
|
|
||||||
can be found in the <i><GhidraInstallDir></i>/Extensions directory.</p>
|
|
||||||
<ul>
|
|
||||||
<li>
|
|
||||||
<b>Eclipse: </b>The GhidraDev Eclipse plugin for a pre-existing Eclipse installation. For
|
|
||||||
information on installing and using the GhidraDev Eclipse plugin, see
|
|
||||||
<i><GhidraInstallDir></i>/Extensions/Eclipse/GhidraDev/GhidraDev_README.md.
|
|
||||||
</li>
|
|
||||||
<li>
|
|
||||||
<b>Ghidra: </b>Ghidra extensions (formerly known as contribs). See
|
|
||||||
<a href="#GhidraExtensionNotes">Ghidra Extension Notes</a> for more information.
|
|
||||||
</li>
|
|
||||||
<li>
|
|
||||||
<b>IDAPro: </b>IDAPro plugins/loaders for transferring items with Ghidra.
|
|
||||||
</li>
|
|
||||||
</ul>
|
|
||||||
<h3><a name="GhidraExtensionNotes"></a>Ghidra Extension Notes</h3>
|
|
||||||
<ul>
|
|
||||||
<li>
|
|
||||||
<p>Ghidra extensions are designed to be installed and uninstalled from the Ghidra front-end GUI:
|
|
||||||
</p>
|
|
||||||
<ol>
|
|
||||||
<li>Click <b>File → Install Extensions</b></li>
|
|
||||||
<li>Check boxes to install extensions; uncheck boxes to uninstall extensions</li>
|
|
||||||
<li>Restart Ghidra for the changes to take effect</li>
|
|
||||||
</ol>
|
|
||||||
</li>
|
|
||||||
<li>
|
|
||||||
Extensions installed from the Ghidra front-end GUI get installed at
|
|
||||||
<i><UserSettings></i>/Extensions, where <i><UserSettings></i> can be looked up in
|
|
||||||
the Ghidra front-end GUI under <i>Help -> Runtime Information -> Application Layout ->
|
|
||||||
Settings Directory.
|
|
||||||
</li>
|
|
||||||
<li>
|
|
||||||
<p>It is possible to install Ghidra extensions directly into the Ghidra installation directory.
|
|
||||||
This may be required if a system administrator is managing extensions for multiple users that
|
|
||||||
all use a shared installation of Ghidra. It may also be more convenient to manage extensions
|
|
||||||
this way if a Ghidra installation is only ever used headlessly.<p>
|
|
||||||
<p>To install an extension in these cases, simply extract the desired Ghidra extension archive
|
|
||||||
file(s) to the <i><GhidraInstallDir></i>/Ghidra/Extensions directory. For example, on
|
|
||||||
Linux or macOS:</p>
|
|
||||||
<ol>
|
|
||||||
<li>Set current directory to the Ghidra installed-extensions directory:</li>
|
|
||||||
<blockquote><i>cd <GhidraInstallDir>/Ghidra/Extensions</i></blockquote>
|
|
||||||
<li>Extract desired extension archive file(s) to the current directory:</li>
|
|
||||||
<blockquote><i>unzip ../../Extensions/Ghidra/<extension>.zip</i></blockquote>
|
|
||||||
<li>The extension(s) will be installed the next time Ghidra is started.</li>
|
|
||||||
</ol>
|
|
||||||
<p>To uninstall extensions, simply delete the extracted extension directories from
|
|
||||||
<i><GhidraInstallDir></i>/Ghidra/Extensions. The extension(s) will be uninstalled
|
|
||||||
the next time Ghidra is started.</p>
|
|
||||||
<p><b>NOTE: </b>It may not be possible to uninstall an extension in this manner if there is an
|
|
||||||
instance of Ghidra running that holds a file lock on the extension directory that is trying to
|
|
||||||
be deleted.</p>
|
|
||||||
</li>
|
|
||||||
</ul>
|
|
||||||
<p>(<a href="#top">Back to Top</a>)</p>
|
|
||||||
|
|
||||||
<h2><a name="Development"></a>Ghidra Development</h2>
|
|
||||||
<p>Users can extend the functionality of Ghidra through the development of custom Ghidra scripts,
|
|
||||||
plugins, analyzers, etc.</p>
|
|
||||||
<p>Ghidra supports development in Eclipse by providing a custom Eclipse plugin called
|
|
||||||
<b>GhidraDev</b>, which can be found in the <i><GhidraInstallDir></i>/Extensions/Eclipse
|
|
||||||
directory. For more information on installing and using the GhidraDev Eclipse plugin, see
|
|
||||||
<i><GhidraInstallDir></i>/Extensions/Eclipse/GhidraDev/GhidraDev_README.md.</p>
|
|
||||||
<p><b>NOTE: </b>Eclipse is not provided with Ghidra. The GhidraDev Eclipse plugin is designed to
|
|
||||||
be installed in a pre-existing Eclipse installation.</p>
|
|
||||||
<p>Ghidra scripting API javadocs can be found at
|
|
||||||
<i><GhidraInstallDir></i>/docs/GhidraAPI_javadoc.zip.</p>
|
|
||||||
<p>(<a href="#top">Back to Top</a>)</p>
|
|
||||||
|
|
||||||
<h2><a name="Upgrading"></a>Upgrade Instructions</h2>
|
|
||||||
<h3><a name="GeneralUpgrade"></a>General Upgrade Instructions</h3>
|
|
||||||
<ol>
|
|
||||||
<li>
|
|
||||||
<b><font color="red">!!!Important!!!</font> BACKUP YOUR OLD PROJECTS FIRST!!<font color="red">
|
|
||||||
!!!Important!!!</font></b>
|
|
||||||
</li>
|
|
||||||
<ul>
|
|
||||||
<li>
|
|
||||||
Backup by manually copying the <i>.rep</i> directory and <i>.gpr</i> file from any Ghidra
|
|
||||||
project directories to a safe location on your file system.
|
|
||||||
</li>
|
|
||||||
</ul>
|
|
||||||
<li>
|
|
||||||
New installations of Ghidra will, by default, use the saved profile from a user's most recent
|
|
||||||
version of Ghidra. This allows any saved tool configurations to be automatically ported to new
|
|
||||||
projects. However, this may also prevent new tool options and features from automatically being
|
|
||||||
configured in some cases. To open new tools containing the latest configurations, users should,
|
|
||||||
from the Project Manager Window, choose <b>Tools → Default Tools...</b>
|
|
||||||
</li>
|
|
||||||
<li>
|
|
||||||
When you open a program that was created using a previous version of Ghidra, you will be
|
|
||||||
prompted to upgrade the program before it can be opened. The upgrade will not overwrite your old
|
|
||||||
file until you save it. If you save it (to its original file), you will no longer be able to
|
|
||||||
open it using an older version of Ghidra. You could, however, choose to perform a
|
|
||||||
“Save As” instead, creating a new file and leaving the old version unchanged. Be
|
|
||||||
very careful about upgrading shared program files since everyone accessing the file must also
|
|
||||||
upgrade their Ghidra installation.
|
|
||||||
</li>
|
|
||||||
</ol>
|
|
||||||
|
|
||||||
<h3><a name="ServerUpgrade"></a>Server Upgrade Instructions</h3>
|
|
||||||
<ul>
|
|
||||||
<li>
|
|
||||||
Please refer to the<i><GhidraInstallDir></i>/server/svrREADME.html file for details on
|
|
||||||
upgrading your Ghidra Server.
|
|
||||||
</li>
|
|
||||||
</ul>
|
|
||||||
<p>(<a href="#top">Back to Top</a>)</p>
|
|
||||||
|
|
||||||
<h2><a name="Troubleshooting"></a>Troubleshooting & Help</h2>
|
|
||||||
<h3><a name="LaunchIssues"></a>Launching Ghidra</h3>
|
|
||||||
<p>When launching Ghidra with the provided scripts in <i><GhidraInstallDir></i> and
|
|
||||||
<i><GhidraInstallDir></i>/support, you may encounter the following error messages:
|
|
||||||
<ul>
|
|
||||||
<li>
|
|
||||||
<b><font color="red">Problem: </font></b><i>Java runtime not found.</i>
|
|
||||||
<ul>
|
|
||||||
<li>
|
|
||||||
<p><b><font color="green">Solution: </font></b>A Java runtime (java/java.exe) is required to
|
|
||||||
be on the system PATH. Please see the <a href="#Requirements"> Requirements</a> section for
|
|
||||||
what version of Java must be pre-installed for Ghidra to launch.</p>
|
|
||||||
</li>
|
|
||||||
</ul>
|
|
||||||
</li>
|
|
||||||
<li>
|
|
||||||
<b><font color="red">Problem: </font></b><i>Failed to find a supported JDK.</i>
|
|
||||||
<ul>
|
|
||||||
<li>
|
|
||||||
<p><b><font color="green">Solution: </font></b>The Ghidra launch script uses the Java
|
|
||||||
runtime on the system PATH to find a supported version of a Java Development Kit (JDK) that
|
|
||||||
Ghidra needs to complete its launch. Please see the <a href="#Requirements">
|
|
||||||
Requirements</a> section for what version of JDK must be pre-installed for Ghidra to launch.
|
|
||||||
</p>
|
|
||||||
</li>
|
|
||||||
</ul>
|
|
||||||
</li>
|
|
||||||
<li>
|
|
||||||
<b><font color="red">Problem: </font></b><i>Exited with error. Run in foreground (fg) mode for
|
|
||||||
more details.</i>
|
|
||||||
<ul>
|
|
||||||
<li>
|
|
||||||
<p><b><font color="green">Solution: </font></b>Ghidra failed to launch in the background and
|
|
||||||
the error message describing the cause of the failure is being suppressed. Rerun Ghidra in
|
|
||||||
the foreground by setting the LAUNCH_MODE variable in the launch script you ran to
|
|
||||||
<b>fg</b>. Alternatively, you can use the
|
|
||||||
<i><GhidraInstallDir></i>/support/ghidraDebug script to run Ghidra in debug mode,
|
|
||||||
which will also allow you to see the error message as well as additional debug output.
|
|
||||||
<b>NOTE:</b> By default, running Ghidra in debug mode listens on 127.0.0.1:18001.</p>
|
|
||||||
</li>
|
|
||||||
</ul>
|
|
||||||
</li>
|
|
||||||
</ul>
|
|
||||||
<h3><a name="GhidraHelp"></a>Using Ghidra</h3>
|
|
||||||
<p>There are several ways you can get help with using Ghidra:</p>
|
|
||||||
<ul>
|
|
||||||
<li>
|
|
||||||
Tutorials and other documentation can be found in <i><GhidraInstallDir></i>/docs.
|
|
||||||
</li>
|
|
||||||
<li>
|
|
||||||
When Ghidra is running, extensive context sensitive help is available on many topics. To
|
|
||||||
access Help on a topic, place your mouse on a window, menu or component and press
|
|
||||||
<F1>. Help for that window/menu/component will be displayed.
|
|
||||||
</li>
|
|
||||||
<li>
|
|
||||||
When Ghidra is running, indexed help can be found under <b>Help → Topics...</b>
|
|
||||||
</li>
|
|
||||||
</ul>
|
|
||||||
<p>(<a href="#top">Back to Top</a>)</p>
|
|
||||||
|
|
||||||
<h2><a name="KnownIssues"></a>Known Issues for current release</h3>
|
|
||||||
<h3><a name="CommonIssues"></a>All Platforms</h3>
|
|
||||||
<ul>
|
|
||||||
<li>
|
|
||||||
Displaying the correct processor manual page for an instruction requires the installation of
|
|
||||||
Adobe Reader 8.0.x or later. Adobe broke the goto page in Reader version 7.x. If a
|
|
||||||
newer version of Reader is not installed, then the manual for the processor will display at the
|
|
||||||
top of the manual. Using an Adobe Reader version later than 8.0.x works for most
|
|
||||||
platforms, but some platforms and version of the reader still have issues.
|
|
||||||
</li>
|
|
||||||
<li>
|
|
||||||
Some actions may block the GUI update thread if they are long running.
|
|
||||||
</li>
|
|
||||||
<li>
|
|
||||||
Project archives only store private and checked out files within the archive. Project
|
|
||||||
archives do not support server-based repositories.
|
|
||||||
</li>
|
|
||||||
<li>
|
|
||||||
When using a Ghidra server, all clients and the server must have a valid Domain Name Server
|
|
||||||
(DNS) defined which has been properly configured on the network for both forward and reverse
|
|
||||||
lookups.
|
|
||||||
</li>
|
|
||||||
<li>
|
|
||||||
Image base may not be changed to an address which falls within an existing memory block.
|
|
||||||
</li>
|
|
||||||
<li>
|
|
||||||
Language versioning and migration does not handle complex changes in the use of the context
|
|
||||||
register.
|
|
||||||
</li>
|
|
||||||
<li>
|
|
||||||
Ghidra will not launch when its path contains a "!" character. This is to avoid issues that
|
|
||||||
Java's internal libraries have parsing these paths ("!" is used as a jar-separator by Java).
|
|
||||||
</li>
|
|
||||||
</ul>
|
|
||||||
<h3><a name="WindowsIssues"></a>Windows</h3>
|
|
||||||
<ul>
|
|
||||||
<li>
|
|
||||||
Older versions of 7-Zip may not be able to unpack the Ghidra distribution file if it contains
|
|
||||||
any files with a 0-byte length. Upgrade to a newer version of 7-Zip to fix this problem.
|
|
||||||
</li>
|
|
||||||
<li>
|
|
||||||
Ghidra will fail to launch when its path contains a "^" character.
|
|
||||||
</li>
|
|
||||||
</ul>
|
|
||||||
<h3><a name="LinuxIssues"></a>Linux</h3>
|
|
||||||
<ul>
|
|
||||||
<li>
|
|
||||||
Ghidra may not display correctly when run from a Linux remote desktop session that uses 32-bit
|
|
||||||
color depth. Setting the remote desktop application's color depth to 24-bit has been known to
|
|
||||||
improve this issue.
|
|
||||||
<li>
|
|
||||||
Some users have reported Ghidra GUI rendering issues on multi-monitor thin client setups.
|
|
||||||
These problems are attributed to reported bugs in Java, which will hopefully be fixed in the
|
|
||||||
future. Disabling the 2nd or 3rd monitor may be necessary to work around the issue.
|
|
||||||
</li>
|
|
||||||
<li>
|
|
||||||
GUI icons may not render correctly in some configurations of Linux. Setting
|
|
||||||
<i>VMARGS=-Dsun.java2d.opengl</i> to <b>true</b> in
|
|
||||||
<i><GhidraInstallDir></i>/support/launch.properties may fix this issue.
|
|
||||||
</li>
|
|
||||||
</ul>
|
|
||||||
<h3><a name="MacOSIssues"></a>macOS (OS X)</h3>
|
|
||||||
<ul>
|
|
||||||
<li>
|
|
||||||
Building new Ghidra module extensions on macOS (OS X) using a network drive (including a
|
|
||||||
network-mapped home directory) throws a Java exception. This issue is known to the Java/macOS
|
|
||||||
community but a fix has not yet been released. See
|
|
||||||
<i><GhidraInstallDir></i>/Extensions/Eclipse/GhidraDev/GhidraDev_README.md for more
|
|
||||||
information on building Ghidra module extensions from Eclipse.
|
|
||||||
</li>
|
|
||||||
</ul>
|
|
||||||
<p>(<a href="#top">Back to Top</a>)</p>
|
|
||||||
|
|
||||||
<!-- Some padding -->
|
|
||||||
<br>
|
|
||||||
<br>
|
|
||||||
<br>
|
|
||||||
|
|
||||||
</body>
|
|
||||||
</html>
|
|
||||||
453
GhidraDocs/InstallationGuide.md
Normal file
453
GhidraDocs/InstallationGuide.md
Normal file
@ -0,0 +1,453 @@
|
|||||||
|
# Ghidra Installation Guide
|
||||||
|
The installation information provided is effective as of Ghidra 11.3 and is subject to change with
|
||||||
|
future releases.
|
||||||
|
|
||||||
|
## Table of Contents
|
||||||
|
1. [Platforms Supported](#platforms-supported)
|
||||||
|
2. [Minimum Requirements](#minimum-requirements)
|
||||||
|
* [Hardware](#hardware)
|
||||||
|
* [Software](#software)
|
||||||
|
3. [Installing Ghidra](#installing-ghidra)
|
||||||
|
* [Installation Notes](#installation-notes)
|
||||||
|
* [Java Notes](#java-notes)
|
||||||
|
4. [Ghidra Installation Directory Layout](#ghidra-installation-directory-layout)
|
||||||
|
5. [Building Native Components](#building-native-components)
|
||||||
|
6. [Running Ghidra](#running-ghidra)
|
||||||
|
* [GUI Mode](#gui-mode)
|
||||||
|
* [Ghidra Server](#ghidra-server)
|
||||||
|
* [Headless (Batch) Mode](#headless-batch-mode)
|
||||||
|
* [Single Jar Mode](#single-jar-mode)
|
||||||
|
* [PyGhidra Mode](#pyghidra-mode)
|
||||||
|
7. [Extensions](#extensions)
|
||||||
|
* [Ghidra Extension Notes](#ghidra-extension-notes)
|
||||||
|
8. [Ghidra Development](#ghidra-development)
|
||||||
|
9. [Upgrade Instructions](#upgrade-instructions)
|
||||||
|
* [General Upgrade Instructions](#general-upgrade-instructions)
|
||||||
|
* [Server Upgrade Instructions](#server-upgrade-instructions)
|
||||||
|
10. [Troubleshooting and Help](#troubleshooting-and-help)
|
||||||
|
* [Launching Ghidra](#launching-ghidra)
|
||||||
|
* [Using Ghidra](#using-ghidra)
|
||||||
|
11. [Known Issues](#known-issues)
|
||||||
|
* [All Platforms](#all-platforms)
|
||||||
|
* [Windows](#windows)
|
||||||
|
* [Linux](#linux)
|
||||||
|
* [macOS](#macos)
|
||||||
|
|
||||||
|
## Platforms Supported
|
||||||
|
* Windows 10 or later
|
||||||
|
* Linux
|
||||||
|
* macOS 10.13 or later
|
||||||
|
|
||||||
|
__NOTE:__ All 32-bit OS installations are now deprecated. Please contact the Ghidra team if you have
|
||||||
|
a specific need.
|
||||||
|
|
||||||
|
## Minimum Requirements
|
||||||
|
|
||||||
|
### Hardware
|
||||||
|
* 4 GB RAM
|
||||||
|
* 1 GB storage (for installed Ghidra binaries)
|
||||||
|
* Dual monitors strongly suggested
|
||||||
|
|
||||||
|
### Software
|
||||||
|
* Java 21 64-bit Runtime and Development Kit (JDK) (see [Java Notes](#java-notes))
|
||||||
|
* Free long term support (LTS) versions of JDK 21 are provided by:
|
||||||
|
* [Adoptium Temurin](https://adoptium.net/temurin/releases)
|
||||||
|
* [Amazon Corretto](https://docs.aws.amazon.com/corretto/latest/corretto-21-ug/downloads-list.html)
|
||||||
|
* Python3 (3.9 to 3.12)
|
||||||
|
* Python 3.7 to 3.12 for [Debugger support](#installing-the-debuggers-python-dependencies)
|
||||||
|
* Python 3.9 to 3.12 for [PyGhidra support](#pyghidra-mode)
|
||||||
|
* This is available from [Python.org](https://python.org) or most operating system's app stores or
|
||||||
|
software repositories. For Linux it is recommended that the system's package repository be used
|
||||||
|
to install a suitable version of Python.
|
||||||
|
|
||||||
|
## Installing Ghidra
|
||||||
|
To install Ghidra, simply extract the Ghidra distribution file to the desired filesystem destination
|
||||||
|
using any unzip program (built-in OS utilities, 7-Zip, WinZip, WinRAR, etc).
|
||||||
|
|
||||||
|
### Installation Notes
|
||||||
|
* Ghidra does not use a traditional installer program. Instead, the Ghidra distribution file is
|
||||||
|
simply extracted in-place on the filesystem. This approach has advantages and disadvantages. On
|
||||||
|
the up side, administrative privilege is not required to install Ghidra for personal use. Also,
|
||||||
|
because installing Ghidra does not update any OS configurations such as the registry on Windows,
|
||||||
|
removing Ghidra is as simple as deleting the Ghidra installation directory. On the down side,
|
||||||
|
Ghidra will not automatically create a shortcut on the desktop or appear in application start
|
||||||
|
menus.
|
||||||
|
|
||||||
|
* When launching Ghidra for the first time on macOS, the macOS Gatekeeper feature may attempt to
|
||||||
|
quarantine the pre-built unsigned Ghidra native components. Two techniques can be used to prevent
|
||||||
|
this from happening:
|
||||||
|
* Prior to extracting the Ghidra distribution file, running
|
||||||
|
`xattr -d com.apple.quarantine ghidra_<version>_<date>.zip` from a terminal.
|
||||||
|
* Prior to first launch, following the instructions in the
|
||||||
|
[Building Native Components](#building-native-components) section.
|
||||||
|
|
||||||
|
* Administrative privilege may be required to extract Ghidra to certain filesystem destinations
|
||||||
|
(such as `C:\`), as well as install the Ghidra Server as a service.
|
||||||
|
|
||||||
|
* Ghidra relies on using directories outside of its installation directory to manage both temporary
|
||||||
|
and longer-living cache files. Ghidra attempts to use standard OS directories that are designed
|
||||||
|
for these purposes in order to avoid several issues, such as storing large amounts of data to a
|
||||||
|
roaming profile. If it is suspected that the default location of these directories is causing a
|
||||||
|
problem, they can be changed by modifying the relevant properties in the
|
||||||
|
`support/launch.properties` file.
|
||||||
|
|
||||||
|
### Java Notes
|
||||||
|
* Ghidra requires a [supported](#minimum-requirements) version of a Java Runtime and Development Kit
|
||||||
|
on the PATH to run. However, if there is a version of Java on the PATH that Ghidra does not
|
||||||
|
support, it will use that version of Java (if 1.8 or later) to assist in locating a supported
|
||||||
|
version on your system. If one cannot be automatically located, the user will be prompted to
|
||||||
|
enter a path to the Java home directory to use (the Java home directory is the parent directory of
|
||||||
|
Java's `bin` directory). This minimizes the impact Ghidra has on pre-existing configurations of
|
||||||
|
Java that other software may rely on.
|
||||||
|
|
||||||
|
* Depending on your operating system, it may be possible to find and install a
|
||||||
|
[supported](#minimum-requirements) version of a Java Runtime and Development Kit through
|
||||||
|
your package manager, without the need to set the Path environment variables as described
|
||||||
|
below.
|
||||||
|
|
||||||
|
* If Ghidra failed to run because _no versions_ of Java were on the PATH, a
|
||||||
|
[supported](#minimum-requirements) JDK should be installed via a Linux package manager
|
||||||
|
(aptitude, yum, etc), Windows installer program (*.exe, *.msi), macOS Installer package
|
||||||
|
(*.pkg), or manually extracted and added to the PATH. The following steps outline how to
|
||||||
|
manually extract and add a JDK distribution to the operating system's PATH.
|
||||||
|
|
||||||
|
* __Windows:__ Extract the JDK distribution (.zip file) to your desired location and add the
|
||||||
|
JDK's `bin` directory to your PATH:
|
||||||
|
1. Extract the JDK:
|
||||||
|
1. Right-click on the zip file and click `Extract All...`
|
||||||
|
2. Click `Extract`
|
||||||
|
2. Open Environment Variables window:
|
||||||
|
1. Right-click on Windows start button, and click `System`
|
||||||
|
2. Click `Advanced system settings`
|
||||||
|
3. Click `Environment variables...`
|
||||||
|
3. Add the JDK bin directory to the PATH variable:
|
||||||
|
1. Under `System variables`, highlight `Path` and click `Edit...`
|
||||||
|
2. At the end of the the `Variable value` field, add a semicolon followed by
|
||||||
|
`<path of extracted JDK dir>\bin`, or use the `New` button in the
|
||||||
|
`Edit environment variable` window to add a new entry to the `Path`.
|
||||||
|
3. Click `OK`
|
||||||
|
4. Click `OK`
|
||||||
|
5. Click `OK`
|
||||||
|
4. Restart any open Command Prompt windows for changes to take effect
|
||||||
|
|
||||||
|
* __Linux and macOS (OS X):__ Extract the JDK distribution (.tar.gz file) to your desired
|
||||||
|
location, and add the JDK's bin directory to your PATH:
|
||||||
|
1. Extract the JDK:
|
||||||
|
```bash
|
||||||
|
tar xvf <JDK distribution .tar.gz>
|
||||||
|
```
|
||||||
|
2. Open `~/.bashrc` with an editor of your choice. For example:
|
||||||
|
```bash
|
||||||
|
vi ~/.bashrc
|
||||||
|
```
|
||||||
|
3. At the very end of the file, add the JDK bin directory to the PATH variable:
|
||||||
|
```bash
|
||||||
|
export PATH=<path of extracted JDK dir>/bin:$PATH
|
||||||
|
```
|
||||||
|
4. Save file
|
||||||
|
5. Restart any open terminal windows for changes to take effect
|
||||||
|
|
||||||
|
* In some cases, you may want Ghidra to launch with a specific version of Java instead of the
|
||||||
|
version that Ghidra automatically locates. To force Ghidra to launch with a specific version of
|
||||||
|
Java, set the `JAVA_HOME_OVERRIDE` property in the `support/launch.properties` file. If this
|
||||||
|
property is set to an incompatible version of Java, Ghidra will revert to automatically locating a
|
||||||
|
compatible version. Note that _some_ Java must still be on the PATH in order for Ghidra to use
|
||||||
|
the `JAVA_HOME_OVERRIDE` property.
|
||||||
|
|
||||||
|
### Debugger Notes
|
||||||
|
The Debugger now uses Python to connect to the host platform's native debuggers. This requires
|
||||||
|
a [supported](#minimum-requirements) version of Python and some additional packages. These packages
|
||||||
|
are included in the distribution, but you may still install them from PyPI if you prefer:
|
||||||
|
* psutil
|
||||||
|
* protobuf==3.20.3
|
||||||
|
* Pybag>=2.2.10 (for WinDbg support)
|
||||||
|
|
||||||
|
Different native debuggers have varying requirements, so you do not necessarily have to install all
|
||||||
|
of the above packages. Each connector will inform you of its specific requirements and where they
|
||||||
|
must be installed. In some cases, you may need to install packages on the target system.
|
||||||
|
|
||||||
|
## Ghidra Installation Directory Layout
|
||||||
|
When Ghidra is installed, the runnable software gets extracted to a new directory we will refer
|
||||||
|
to as `<GhidraInstallDir>`. Below is a description of the top-level directories and files that can
|
||||||
|
be found in `<GhidraInstallDir>` once extraction of the distribution file is complete.
|
||||||
|
* __Ghidra:__ Base directory for Ghidra distribution. Contains files needed to run Ghidra.
|
||||||
|
* __Extensions:__ Optional components that can extend Ghidra's functionality and integrate Ghidra
|
||||||
|
with other tools. See the [Extensions](#extensions) section for more information.
|
||||||
|
* __GPL:__ Standalone GPL support programs.
|
||||||
|
* __server:__ Contains files related to [Ghidra Server](#ghidra-server) installation and
|
||||||
|
administration.
|
||||||
|
* __support:__ Contains files useful for debugging Ghidra, running Ghidra in advanced modes, and
|
||||||
|
controlling how Ghidra launches.
|
||||||
|
* __docs:__ Contains documentation for Ghidra, such as release notes, API files, tutorials, etc.
|
||||||
|
* __ghidraRun(.bat):__ Script used to launch Ghidra.
|
||||||
|
* __LICENSE:__ Ghidra license information.
|
||||||
|
* __licenses:__ Contains licenses used by Ghidra.
|
||||||
|
* __bom.json:__ Software Bill of Materials (SBOM) in CycloneDX JSON format.
|
||||||
|
|
||||||
|
## Building Native Components
|
||||||
|
Ghidra requires several native binaries to be present in order to successfully run. An official
|
||||||
|
public Ghidra release includes native binaries for the following platforms:
|
||||||
|
* Windows 10 or later, x86 64-bit
|
||||||
|
* Windows 10 or later, ARM 64-bit (using x86 emulation)
|
||||||
|
* Linux x86 64-bit
|
||||||
|
* macOS x86 64-bit (may be omitted for some non-public builds)
|
||||||
|
* macOS ARM 64-bit (may be omitted for some non-public builds)
|
||||||
|
|
||||||
|
Ghidra supports running on the following additional platforms with user-built native binaries:
|
||||||
|
* Linux ARM 64-bit
|
||||||
|
* FreeBSD x86 64-bit (no debugger support)
|
||||||
|
* FreeBSD ARM 64-bit (no debugger support)
|
||||||
|
|
||||||
|
For supported systems where native binaries have not been supplied, or those that are supplied fail
|
||||||
|
to run properly, it may be necessary to build the native Ghidra binaries. In order to build native
|
||||||
|
binaries for your platform, you will need the following installed on your system:
|
||||||
|
* A [supported](#minimum-requirements) version of a Java Development Kit
|
||||||
|
* [Gradle 8.5+](https://gradle.org/releases) (or supplied Gradle wrapper with Internet connection)
|
||||||
|
* Software C/C++ build tools and library packages
|
||||||
|
* __macOS:__ _Xcode_ or the abbreviated _Command Line Tools for Xcode_. Assuming you are connected
|
||||||
|
to the Internet, _Xcode_ (which includes the command tools) may be installed directly from the
|
||||||
|
App Store while _Command Line Tools for Xcode_ may be installed using the command:
|
||||||
|
`xcode-select --install`.
|
||||||
|
* __Linux/FreeBSD:__ the 64-bit versions of the following packages should installed:
|
||||||
|
* gcc 8.5 or later
|
||||||
|
* gcc-c++ / g++ 8.5 or later
|
||||||
|
* make
|
||||||
|
* __Windows:__
|
||||||
|
[Microsoft Visual Studio](https://visualstudio.microsoft.com/vs/community) 2017 or later, or
|
||||||
|
[Microsoft C++ Build Tools](https://visualstudio.microsoft.com/visual-cpp-build-tools)
|
||||||
|
with the following components installed:
|
||||||
|
* MSVC
|
||||||
|
* Windows SDK
|
||||||
|
* C++ ATL
|
||||||
|
|
||||||
|
To build the native binaries for your current platform, execute the following commands:
|
||||||
|
```bash
|
||||||
|
cd <GhidraInstallDir>/support/gradle/
|
||||||
|
gradle buildNatives
|
||||||
|
```
|
||||||
|
|
||||||
|
If you are connected to the Internet and do not have Gradle installed, execute:
|
||||||
|
```bash
|
||||||
|
cd <GhidraInstallDir>/support/gradle/
|
||||||
|
./gradlew(.bat) buildNatives
|
||||||
|
```
|
||||||
|
|
||||||
|
When the commands successfully complete, Ghidra will contain newly built native binaries in
|
||||||
|
the relevant modules' `build/os/<platform>/` subdirectories, which Ghidra will prefer to any
|
||||||
|
existing pre-built native binaries in the `os/<platform>/` subdirectories.
|
||||||
|
|
||||||
|
## Running Ghidra
|
||||||
|
|
||||||
|
### GUI Mode
|
||||||
|
1. Navigate to `<GhidraInstallDir>`
|
||||||
|
2. Run `ghidraRun.bat` (Windows) or `ghidraRun` (Linux or macOS)
|
||||||
|
|
||||||
|
If Ghidra failed to launch, see the [Troubleshooting](#troubleshooting-and-help) section.
|
||||||
|
|
||||||
|
### Ghidra Server
|
||||||
|
Ghidra can support multiple users working together on a single project. Individual Ghidra users
|
||||||
|
launch and work on their own local copies of a particular Ghidra project but check changes into a
|
||||||
|
common repository containing all commits to that repository. For detailed information on
|
||||||
|
installing/configuring the Ghidra Server see the `<GhidraInstallDir>/server/svrREADME.html` file.
|
||||||
|
|
||||||
|
### Headless (Batch) Mode
|
||||||
|
Ghidra is traditionally run in GUI mode. However, it is also capable of running in headless batch
|
||||||
|
mode using the command line. For more information, see the
|
||||||
|
`<GhidraInstallDir>/support/analyzeHeadlessREADME.html` file.
|
||||||
|
|
||||||
|
### Single Jar Mode
|
||||||
|
Normally, Ghidra is installed as an entire directory structure that allows modular inclusion or
|
||||||
|
removal of feature sets and also provides many files that can be extended or configured. However,
|
||||||
|
there are times when it would be useful to have all or some subset of Ghidra compressed into a
|
||||||
|
single jar file at the expense of configuration options. This makes Ghidra easier to run from the
|
||||||
|
command line for headless operation or to use as a library of reverse engineering capabilities for
|
||||||
|
another Java application.
|
||||||
|
|
||||||
|
A single `ghidra.jar` file can be created using the `<GhidraInstallDir>/support/buildGhidraJar`
|
||||||
|
script.
|
||||||
|
|
||||||
|
### PyGhidra Mode
|
||||||
|
Ghidra has integrated the the popular Pyhidra extension to enable native CPython 3 support out of
|
||||||
|
the box. To enable this support, Ghidra must be launched from a Python environment using special
|
||||||
|
launch scripts.
|
||||||
|
1. Navigate to `<GhidraInstallDir>/support/`
|
||||||
|
2. Run `pyghidraRun.bat` (Windows) or `pyghidraRun` (Linux or macOS).
|
||||||
|
|
||||||
|
If the `pyghidra` Python module has not yet been installed, the script will offer to
|
||||||
|
install it for you, along with its dependencies. If you prefer to install it manually, execute:
|
||||||
|
```bash
|
||||||
|
python3 -m pip install --no-index -f <GhidraInstallDir>/Ghidra/Features/PyGhidra/pypkg/dist pyghidra
|
||||||
|
```
|
||||||
|
__NOTE:__ You may also install and run PyGhidra from within a
|
||||||
|
[virtual environment](https://docs.python.org/3/tutorial/venv.html) if you desire.
|
||||||
|
|
||||||
|
If Ghidra failed to launch, see the [Troubleshooting](#troubleshooting-and-help) section.
|
||||||
|
|
||||||
|
Once PyGhidra has been installed, you are free to use it like any other Python module. You may
|
||||||
|
import it from other Python scripts, or launch PyGhidra using the `pyghidra` or `pyghidraw`
|
||||||
|
commands. For more information on using PyGhidra, see
|
||||||
|
[`<GhidraInstallDir>/Ghidra/Features/PyGhidra/README.html`](
|
||||||
|
../Ghidra/Features/PyGhidra/src/main/py/README.md).
|
||||||
|
|
||||||
|
## Extensions
|
||||||
|
Extensions are optional components that can:
|
||||||
|
* Extend Ghidra's functionality with experimental or user-contributed Ghidra plugins or analyzers.
|
||||||
|
* Integrate other tools with Ghidra, such as Eclipse or IDAPro.
|
||||||
|
|
||||||
|
Ghidra comes with the following extensions available for use (and by default uninstalled), which
|
||||||
|
can be found in the `<GhidraInstallDir>/Extensions` directory:
|
||||||
|
* __Eclipse:__ The `GhidraDev` and `GhidraSleighEditor` Eclipse plugins for a pre-existing Eclipse
|
||||||
|
installation. For information on installing and using the `GhidraDev` Eclipse plugin, see
|
||||||
|
[`<GhidraInstallDir>/Extensions/Eclipse/GhidraDev/README.html`](
|
||||||
|
../GhidraBuild/EclipsePlugins/GhidraDev/GhidraDevPlugin/README.md).
|
||||||
|
* __Ghidra:__ Ghidra extensions (formerly known as contribs). See
|
||||||
|
[Ghidra Extension Notes](#ghidra-extension-notes) for more information.
|
||||||
|
* __IDAPro:__ IDAPro plugins/loaders for transferring items with Ghidra.
|
||||||
|
|
||||||
|
### Ghidra Extension Notes
|
||||||
|
* Ghidra extensions are designed to be installed and uninstalled from the Ghidra front-end GUI:
|
||||||
|
1. Click `File -> Install Extensions`
|
||||||
|
2. Check boxes to install extensions; uncheck boxes to uninstall extensions
|
||||||
|
3. Restart Ghidra for the changes to take effect
|
||||||
|
|
||||||
|
* Extensions installed from the Ghidra front-end GUI get installed at `<UserSettings>/Extensions`,
|
||||||
|
where `<UserSettings>` can be looked up in the Ghidra front-end GUI under
|
||||||
|
`Help -> Runtime Information -> Application Layout -> Settings Directory`.
|
||||||
|
|
||||||
|
* It is possible to install Ghidra extensions directly into the Ghidra installation directory. This
|
||||||
|
may be required if a system administrator is managing extensions for multiple users that all use a
|
||||||
|
shared installation of Ghidra. It may also be more convenient to manage extensions this way if a
|
||||||
|
Ghidra installation is only ever used headlessly. To install an extension in these cases, simply
|
||||||
|
extract the desired Ghidra extension archive file(s) to the `<GhidraInstallDir>/Ghidra/Extensions`
|
||||||
|
directory. For example, on Linux or macOS:
|
||||||
|
1. Set current directory to the Ghidra installed-extensions directory:
|
||||||
|
```bash
|
||||||
|
cd <GhidraInstallDir>/Ghidra/Extensions
|
||||||
|
```
|
||||||
|
2. Extract desired extension archive file(s) to the current directory:
|
||||||
|
```bash
|
||||||
|
unzip ../../Extensions/Ghidra/<extension>.zip
|
||||||
|
```
|
||||||
|
3. The extension(s) will be installed the next time Ghidra is started.
|
||||||
|
|
||||||
|
To uninstall extensions, simply delete the extracted extension directories from
|
||||||
|
`<GhidraInstallDir>/Ghidra/Extensions`. The extension(s) will be uninstalled the next time
|
||||||
|
Ghidra is started.
|
||||||
|
|
||||||
|
__NOTE:__ It may not be possible to uninstall an extension in this manner if there is an
|
||||||
|
instance of Ghidra running that holds a file lock on the extension directory that is trying to
|
||||||
|
be deleted.
|
||||||
|
|
||||||
|
## Ghidra Development
|
||||||
|
Users can extend the functionality of Ghidra through the development of custom Ghidra scripts,
|
||||||
|
plugins, analyzers, etc.
|
||||||
|
|
||||||
|
Ghidra supports development in Eclipse by providing a custom Eclipse plugin called
|
||||||
|
`GhidraDev`, which can be found in the `<GhidraInstallDir>/Extensions/Eclipse` directory. For more
|
||||||
|
information on installing and using the GhidraDev Eclipse plugin, see
|
||||||
|
[`<GhidraInstallDir>/Extensions/Eclipse/GhidraDev/README.html`](
|
||||||
|
../GhidraBuild/EclipsePlugins/GhidraDev/GhidraDevPlugin/README.md).
|
||||||
|
|
||||||
|
__NOTE:__ Eclipse is not provided with Ghidra. The `GhidraDev` Eclipse plugin is designed to
|
||||||
|
be installed in a pre-existing Eclipse installation.
|
||||||
|
|
||||||
|
Ghidra scripting API javadocs can be found at `<GhidraInstallDir>/docs/GhidraAPI_javadoc.zip`.
|
||||||
|
|
||||||
|
## Upgrade Instructions
|
||||||
|
|
||||||
|
### General Upgrade Instructions
|
||||||
|
1. __!!!Important!!!__ BACKUP YOUR OLD PROJECTS FIRST!!
|
||||||
|
* Backup by manually copying the `.rep` directory and `.gpr` file from any Ghidra project
|
||||||
|
directories to a safe location on your file system.
|
||||||
|
2. New installations of Ghidra will, by default, use the saved profile from a user's most recent
|
||||||
|
version of Ghidra. This allows any saved tool configurations to be automatically ported to new
|
||||||
|
projects. However, this may also prevent new tool options and features from automatically being
|
||||||
|
configured in some cases. To open new tools containing the latest configurations, users should,
|
||||||
|
from the Project Manager Window, choose `Tools -> Default Tools...`
|
||||||
|
3. When you open a program that was created using a previous version of Ghidra, you will be prompted
|
||||||
|
to upgrade the program before it can be opened. The upgrade will not overwrite your old file
|
||||||
|
until you save it. If you save it (to its original file), you will no longer be able to open it
|
||||||
|
using an older version of Ghidra. You could, however, choose to perform a `Save As` instead,
|
||||||
|
creating a new file and leaving the old version unchanged. Be very careful about upgrading shared
|
||||||
|
program files since everyone accessing the file must also upgrade their Ghidra installation.
|
||||||
|
|
||||||
|
### Server Upgrade Instructions
|
||||||
|
Please refer to the `<GhidraInstallDir>/server/svrREADME.html` file for details on upgrading your
|
||||||
|
Ghidra Server.
|
||||||
|
|
||||||
|
## Troubleshooting and Help
|
||||||
|
|
||||||
|
### Launching Ghidra
|
||||||
|
When launching Ghidra with the provided scripts in `<GhidraInstallDir>` and
|
||||||
|
`<GhidraInstallDir>/support`, you may encounter the following error messages:
|
||||||
|
|
||||||
|
* __Problem:__ _Java runtime not found._
|
||||||
|
* __Solution:__ A Java runtime (java/java.exe) is required to be on the system PATH. Please see
|
||||||
|
the [requirements](#minimum-requirements) section for what version of Java must be pre-installed
|
||||||
|
for Ghidra to launch.
|
||||||
|
|
||||||
|
* __Problem:__ _Failed to find a supported JDK._
|
||||||
|
* __Solution:__ The Ghidra launch script uses the Java runtime on the system PATH to find a
|
||||||
|
supported version of a Java Development Kit (JDK) that Ghidra needs to complete its launch.
|
||||||
|
Please see the [requirements](#minimum-requirements) section for what version of JDK must be
|
||||||
|
pre-installed for Ghidra to launch.
|
||||||
|
|
||||||
|
* __Problem:__ _Exited with error. Run in foreground (fg) mode for more details._
|
||||||
|
* __Solution:__ Ghidra failed to launch in the background and the error message describing the
|
||||||
|
cause of the failure is being suppressed. Rerun Ghidra in the foreground by setting the
|
||||||
|
`LAUNCH_MODE` variable in the launch script you ran to `fg`. Alternatively, you can use the
|
||||||
|
`<GhidraInstallDir>/support/ghidraDebug` script to run Ghidra in debug mode, which will also
|
||||||
|
allow you to see the error message as well as additional debug output.
|
||||||
|
__NOTE:__ By default, running Ghidra in debug mode listens on `127.0.0.1:18001`.
|
||||||
|
|
||||||
|
### Using Ghidra
|
||||||
|
There are several ways you can get help with using Ghidra:
|
||||||
|
* Tutorials and other documentation can be found in `<GhidraInstallDir>/docs`.
|
||||||
|
* When Ghidra is running, extensive context sensitive help is available on many topics. To access
|
||||||
|
Help on a topic, place your mouse on a window, menu or component and press `F1`. Help for that
|
||||||
|
window/menu/component will be displayed.
|
||||||
|
* When Ghidra is running, indexed help can be found under `Help -> Topics...`
|
||||||
|
|
||||||
|
## Known Issues
|
||||||
|
|
||||||
|
### All Platforms
|
||||||
|
* Displaying the correct processor manual page for an instruction requires the installation of
|
||||||
|
Adobe Reader 8.0.x or later. Adobe broke the goto page in Reader version 7.x. If a newer version
|
||||||
|
of Reader is not installed, then the manual for the processor will display at the top of the
|
||||||
|
manual. Using an Adobe Reader version later than 8.0.x works for most platforms, but some
|
||||||
|
platforms and version of the reader still have issues.
|
||||||
|
* Some actions may block the GUI update thread if they are long running.
|
||||||
|
* Project archives only store private and checked out files within the archive. Project archives do
|
||||||
|
not support server-based repositories.
|
||||||
|
* When using a Ghidra server, all clients and the server must have a valid Domain Name Server
|
||||||
|
(DNS) defined which has been properly configured on the network for both forward and reverse
|
||||||
|
lookups.
|
||||||
|
* Image base may not be changed to an address which falls within an existing memory block.
|
||||||
|
* Language versioning and migration does not handle complex changes in the use of the context
|
||||||
|
register.
|
||||||
|
* Ghidra will not launch when its path contains a `!` character. This is to avoid issues that
|
||||||
|
Java's internal libraries have parsing these paths (`!` is used as a jar-separator by Java).
|
||||||
|
|
||||||
|
### Windows
|
||||||
|
* Older versions of 7-Zip may not be able to unpack the Ghidra distribution file if it contains any
|
||||||
|
files with a 0-byte length. Upgrade to a newer version of 7-Zip to fix this problem.
|
||||||
|
* Ghidra will fail to launch when its path contains a `^` character.
|
||||||
|
|
||||||
|
### Linux
|
||||||
|
* Ghidra may not display correctly when run from a Linux remote desktop session that uses 32-bit
|
||||||
|
color depth. Setting the remote desktop application's color depth to 24-bit has been known to
|
||||||
|
improve this issue.
|
||||||
|
* Some users have reported Ghidra GUI rendering issues on multi-monitor thin client setups. These
|
||||||
|
problems are attributed to reported bugs in Java, which will hopefully be fixed in the future.
|
||||||
|
Disabling the 2nd or 3rd monitor may be necessary to work around the issue.
|
||||||
|
* GUI icons may not render correctly in some configurations of Linux. Setting
|
||||||
|
`VMARGS=-Dsun.java2d.opengl` to `true` in `<GhidraInstallDir>/support/launch.properties` may fix
|
||||||
|
this issue.
|
||||||
|
|
||||||
|
### macOS
|
||||||
|
* Building new Ghidra module extensions on macOS (OS X) using a network drive (including a
|
||||||
|
network-mapped home directory) throws a Java exception. This issue is known to the Java/macOS
|
||||||
|
community but a fix has not yet been released. See
|
||||||
|
[`<GhidraInstallDir>/Extensions/Eclipse/GhidraDev/README.html`](
|
||||||
|
../GhidraBuild/EclipsePlugins/GhidraDev/GhidraDevPlugin/README.md) for more information on
|
||||||
|
building Ghidra module extensions from Eclipse.
|
||||||
@ -48,6 +48,11 @@ rootProject.assembleDistribution {
|
|||||||
exclude "**/build/**"
|
exclude "**/build/**"
|
||||||
exclude "**/bin/**"
|
exclude "**/bin/**"
|
||||||
into "docs"
|
into "docs"
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
rootProject.assembleMarkdownToHtml {
|
||||||
|
from ("${this.projectDir}/InstallationGuide.md") {
|
||||||
|
into "docs"
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
|
|||||||
@ -202,7 +202,7 @@ GhidraClass/Intermediate/VersionTracking.html||GHIDRA|||This file contains mostl
|
|||||||
GhidraClass/Intermediate/VersionTracking_withNotes.html||Public Domain|||Slight modification of code that is available for distribution, without restrictions, (original extremely permissive wtf license allows us to change IP to Public Domain),from https://github.com/paulrouget/dzslides.|END|
|
GhidraClass/Intermediate/VersionTracking_withNotes.html||Public Domain|||Slight modification of code that is available for distribution, without restrictions, (original extremely permissive wtf license allows us to change IP to Public Domain),from https://github.com/paulrouget/dzslides.|END|
|
||||||
GhidraCodingStandards.html||GHIDRA||||END|
|
GhidraCodingStandards.html||GHIDRA||||END|
|
||||||
GhidraFilesystemStorage.html||GHIDRA||||END|
|
GhidraFilesystemStorage.html||GHIDRA||||END|
|
||||||
InstallationGuide.html||GHIDRA||||END|
|
InstallationGuide.md||GHIDRA||||END|
|
||||||
images/B.gif||GHIDRA||||END|
|
images/B.gif||GHIDRA||||END|
|
||||||
images/D.gif||GHIDRA||||END|
|
images/D.gif||GHIDRA||||END|
|
||||||
images/F.gif||GHIDRA||||END|
|
images/F.gif||GHIDRA||||END|
|
||||||
|
|||||||
@ -38,8 +38,8 @@ To install an official pre-built multi-platform Ghidra release:
|
|||||||
* Launch Ghidra: `./ghidraRun` (or `ghidraRun.bat` for Windows)
|
* Launch Ghidra: `./ghidraRun` (or `ghidraRun.bat` for Windows)
|
||||||
|
|
||||||
For additional information and troubleshooting tips about installing and running a Ghidra release,
|
For additional information and troubleshooting tips about installing and running a Ghidra release,
|
||||||
please refer to `docs/InstallationGuide.html` which can be found in your extracted Ghidra release
|
please refer to the [Installation Guide][installationguide] which can be found in a Ghidra release
|
||||||
directory.
|
at `docs/InstallationGuide.html`.
|
||||||
|
|
||||||
## Build
|
## Build
|
||||||
|
|
||||||
@ -126,6 +126,7 @@ source project.
|
|||||||
[nsa]: https://www.nsa.gov
|
[nsa]: https://www.nsa.gov
|
||||||
[contrib]: CONTRIBUTING.md
|
[contrib]: CONTRIBUTING.md
|
||||||
[devguide]: DevGuide.md
|
[devguide]: DevGuide.md
|
||||||
|
[installationguide]: GhidraDocs/InstallationGuide.md
|
||||||
[known-issues]: DevGuide.md#known-issues
|
[known-issues]: DevGuide.md#known-issues
|
||||||
[career]: https://www.intelligencecareers.gov/nsa
|
[career]: https://www.intelligencecareers.gov/nsa
|
||||||
[releases]: https://github.com/NationalSecurityAgency/ghidra/releases
|
[releases]: https://github.com/NationalSecurityAgency/ghidra/releases
|
||||||
|
|||||||
Loading…
Reference in New Issue
Block a user