From 3de9f998834ea53cceb2cc24c70898a82d4f939c Mon Sep 17 00:00:00 2001 From: Ryan Kurtz Date: Thu, 17 Oct 2024 15:25:42 -0400 Subject: [PATCH] GP-0: Converting InstallationGuide.html to Markdown --- .../GhidraDevPlugin/GhidraDev_README.html | 497 ------------ .../GhidraDev/GhidraDevPlugin/README.md | 2 +- .../GhidraDev/certification.manifest | 1 - GhidraDocs/InstallationGuide.html | 733 ------------------ GhidraDocs/InstallationGuide.md | 453 +++++++++++ GhidraDocs/build.gradle | 7 +- GhidraDocs/certification.manifest | 2 +- README.md | 5 +- 8 files changed, 464 insertions(+), 1236 deletions(-) delete mode 100644 GhidraBuild/EclipsePlugins/GhidraDev/GhidraDevPlugin/GhidraDev_README.html delete mode 100644 GhidraDocs/InstallationGuide.html create mode 100644 GhidraDocs/InstallationGuide.md diff --git a/GhidraBuild/EclipsePlugins/GhidraDev/GhidraDevPlugin/GhidraDev_README.html b/GhidraBuild/EclipsePlugins/GhidraDev/GhidraDevPlugin/GhidraDev_README.html deleted file mode 100644 index 571a332dc3..0000000000 --- a/GhidraBuild/EclipsePlugins/GhidraDev/GhidraDevPlugin/GhidraDev_README.html +++ /dev/null @@ -1,497 +0,0 @@ - - - - GhidraDev README - - - - - -

GhidraDev README

-

GhidraDev provides support for developing and debugging Ghidra scripts and modules in Eclipse. -

-

The information provided in this document is effective as of GhidraDev 4.0.0 and is subject to -change with future releases.

- - - -

Change History

-

4.0.0: -

-

3.1.0: -

-

3.0.2: -

-

3.0.1: -

-

3.0.0: -

-

2.1.5: Eclipse Python breakpoints now work when Eclipse installs PyDev in .p2 -bundle pool directory.

-

2.1.4: Fixed exception that occurred when performing a "Link Ghidra" on projects -that use a Gradle classpath container.

-

2.1.3: Fixed a bug that prevented Ghidra projects from recognizing extensions -installed in the user's ~/.ghidra/.ghidra_<version>/Extensions directory.

-

2.1.2: Fixed exception that occurred when creating a new Ghidra scripting project -if a ~/ghidra_scripts directory does not exist.

-

2.1.1: -

-

2.1.0: -

-

2.0.1: Fixed exception that occurred when performing certain actions on a Ghidra -project that was imported from a previously exported Archive File.

-

2.0.0: -

-

1.0.2: Fixed exception that occurred when performing a "Link Ghidra" on projects -that specify other projects on their build paths.

-

1.0.1: Initial Release.

- -

Minimum Requirements

- -

(Back to Top)

- -

Optional Requirements

- -

(Back to Top)

- -

Installing GhidraDev

-

GhidraDev can be installed either manually into Eclipse or automatically by Ghidra, depending on -your uses cases. The following two sections outline both procedures.

-

Manual Installation in Eclipse

-

GhidraDev can be installed into an existing installation of Eclipse the same way most Eclipse -plugins are installed. From Eclipse:

-
    -
  1. Click Help → Install New Software...
    2. -
  2. Click Add...
    3. -
  3. Click Archive...
    4. -
  4. - Select GhidraDev zip file from <GhidraInstallDir>/Extensions/Eclipse/GhidraDev/ -
    5. -
  5. Click OK (name field can be blank)
    6. -
  6. Check Ghidra category (or GhidraDev entry)
    7. -
  7. Click Next
    8. -
  8. Click Next
    9. -
  9. Accept the terms of the license agreement
    10. -
  10. Click Finish
    11. -
  11. Check Unsigned table entry
    12. -
  12. Click Trust Selected
    13. -
  13. Click Restart Now
    14. -
-

Automatic Installation through Ghidra

-

Ghidra has the ability to launch an externally linked Eclipse when certain actions are performed, -such as choosing to edit a Ghidra script by clicking the Eclipse icon in the Ghidra Script Manager. -Ghidra requires knowledge of where Eclipse is installed before it can launch it, and will prompt the -user to enter this information if it has not been defined. Before Ghidra attempts to launch -Eclipse, it will attempt to install GhidraDev into Eclipse's dropins directory if GhidraDev -is not already installed.

-

(Back to Top)

- -

Features

-

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".

- -

Most GhidraDev features can also be accessed by right-clicking on appropriate project elements in -Eclipse's Project/Package Explorer. For example, the Link Ghidra feature -can be accessed by right-clicking on an existing Java project, and then clicking Ghidra → -Link Ghidra... -

-

(Back to Top)

- -

Launching and Debugging Ghidra

-

GhidraDev introduces two new run configurations to Eclipse which are capable of launching the -installation of Ghidra that an Eclipse Ghidra project is linked to:

- -

There are two ways to create Ghidra run configurations:

-
    -
  1. Click Run → Run Configurations...
    2. -
  2. Right-click on Ghidra (or Ghidra Headless), and click New
    3. -
  3. In the Main tab, click Browse... and select the Ghidra project to launch
    4. -
  4. Optionally rename the new run configuration by editing the Name field at the top -
-

Alternatively, you can right-click on any Ghidra project in the Eclipse package explorer, and -then click Run As → Ghidra.

-

To debug Ghidra, click Debug As → Ghidra. GhidraDev will automatically switch -Eclipse to the debug perspective.

-

NOTE: Ghidra can only be launched/debugged from an existing Eclipse Ghidra project. -Launching Ghidra from Eclipse independent of a project is not supported.

-

(Back to Top)

- -

PyDev Support

-

GhidraDev is able to integrate with PyDev to conveniently configure Python support into Ghidra -script and module projects.

-

Installing PyDev

-

From Eclipse:

-
    -
  1. - Download PyDev (see optional requirements for supported - versions) -
    2. -
  2. Unzip PyDev
    3. -
  3. Click Help → Install New Software...
    4. -
  4. Click Add...
    5. -
  5. Click Local...
    6. -
  6. Select unzipped PyDev directory
    7. -
  7. Click OK (name field can be blank)
    8. -
  8. Uncheck Group items by category (if applicable)
    9. -
  9. Check PyDev for Eclipse
    10. -
  10. Click Next
    11. -
  11. Click Next
    12. -
  12. Accept the terms of the license agreement
    13. -
  13. Click Finish
    14. -
  14. Click Restart Now
    15. -
-

Configuring PyDev

-

GhidraDev can add Python support to a Ghidra project when: -

-

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 + icon. -When the + 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.

-

(Back to Top)

- -

Upgrading

-

GhidraDev is upgraded differently depending on how it was installed. If GhidraDev was -manually installed in Eclipse, it can be upgraded the same was it was -installed.

-

If GhidraDev was automatically installed through Ghidra, it can be -upgraded by simply removing the GhidraDev file from Eclipse's dropins directory before -following one of the two techniques described in the Installing GhidraDev -section.

-

(Back to Top)

- -

Uninstalling

-

GhidraDev is uninstalled differently depending on how it was installed. If GhidraDev was -manually installed in Eclipse, it can be uninstalled as follows from -Eclipse:

-
    -
  1. Click Help → About Eclipse
    2. - -
  2. Click Installation Details
    3. -
  3. Select GhidraDev
    4. -
  4. Click Uninstall...
    5. -
  5. Select GhidraDev
    6. -
  6. Click Finish
    7. -
  7. Click Restart Now
    8. -
-

If GhidraDev was automatically installed through Ghidra, it can be -uninstalled by simply removing the GhidraDev file from Eclipse's dropins directory and -restarting Eclipse. The dropins directory can be found at the top level of Eclipse's -installation directory.

-

(Back to Top)

- -

Frequently Asked Questions

- -

(Back to Top)

- -

Additional Resources

-

For more information on the GhidraDev plugin and developing for Ghidra in an Eclipse environment, -please see: -

-

(Back to Top)

- - -
-
-
- - - diff --git a/GhidraBuild/EclipsePlugins/GhidraDev/GhidraDevPlugin/README.md b/GhidraBuild/EclipsePlugins/GhidraDev/GhidraDevPlugin/README.md index 4f8a0931af..f114b7983b 100644 --- a/GhidraBuild/EclipsePlugins/GhidraDev/GhidraDevPlugin/README.md +++ b/GhidraBuild/EclipsePlugins/GhidraDev/GhidraDevPlugin/README.md @@ -54,7 +54,7 @@ __3.0.2:__ * GhidraDev now prevents unsupported versions of PyDev from being used. __3.0.1:__ -* Exporting a Ghidra Module Extension produces an intermediate `build<` directory within the +* Exporting a Ghidra Module Extension produces an intermediate `build` directory within the project. This `build` directory now gets automatically cleaned up to avoid Ghidra runtime/debugging issues. * GhidraDev now prevents unsupported Ghidra source repositories from being added as a Ghidra diff --git a/GhidraBuild/EclipsePlugins/GhidraDev/certification.manifest b/GhidraBuild/EclipsePlugins/GhidraDev/certification.manifest index 29cff7d9fa..7ef12ea347 100644 --- a/GhidraBuild/EclipsePlugins/GhidraDev/certification.manifest +++ b/GhidraBuild/EclipsePlugins/GhidraDev/certification.manifest @@ -5,7 +5,6 @@ GhidraDevFeature/category.xml||GHIDRA||||END| GhidraDevFeature/feature.xml||GHIDRA||||END| GhidraDevPlugin/.launch/GhidraDev.launch||GHIDRA||||END| GhidraDevPlugin/GhidraDev.target||GHIDRA||||END| -GhidraDevPlugin/GhidraDev_README.html||GHIDRA||||END| GhidraDevPlugin/META-INF/MANIFEST.MF||GHIDRA||||END| GhidraDevPlugin/README.md||GHIDRA||||END| GhidraDevPlugin/build.properties||GHIDRA||||END| diff --git a/GhidraDocs/InstallationGuide.html b/GhidraDocs/InstallationGuide.html deleted file mode 100644 index a8e3649e3c..0000000000 --- a/GhidraDocs/InstallationGuide.html +++ /dev/null @@ -1,733 +0,0 @@ - - - - Ghidra Installation Guide - - - - - -

Ghidra Installation Guide

-

-The installation information provided is effective as of Ghidra 11.2 and is subject to change with -future releases. -

- - - - -

Platforms Supported

- -

NOTE: All 32-bit OS installations are now deprecated. Please contact the -Ghidra team if you have a specific need.

- -

Minimum Requirements

-

Hardware

- -

Software

- -

(Back to Top)

- -

- -

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

- -

Java Notes

- -

(Back to Top)

- -

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 section for more information. -
GPL - Standalone GPL support programs. -
server - Contains files related to 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. -
LICENSEGhidra license information.
licensesContains licenses used by Ghidra.
bom.jsonSoftware Bill of Materials (SBOM) in CycloneDX JSON format.
-

(Back to Top)

- -

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. -

-

NOTE: For some non-public Ghidra releases macOS natives may be omitted.

- -

Ghidra supports running on the following additional platforms with user-built native binaries: -

- -

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:

- -

To build the native binaries for your current platform, execute the following commands:

-
- 
-    cd <GhidraInstallDir>/support/gradle/
-    gradle buildNatives
-
-
-

If you are connected to the Internet and do not have Gradle installed, execute:

-
- 
-    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 will override any -existing pre-built native binaries in the os/<platform>/ subdirectories.

-

(Back to Top)

- -

Installing the Debugger's Python Dependencies

-

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:

- -

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.

- -

Running Ghidra

-

GUI Mode

-
    -
  1. - Navigate to <GhidraInstallDir> -
    2. -
  2. -

    Run ghidraRun.bat (Windows) or ghidraRun (Linux or macOS)

    -

    If Ghidra failed to launch, see the Troubleshooting section. -

    -
    3. -
- -

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 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.

-
    -
  1. - Navigate to <GhidraInstallDir>/support/ -
    2. -
  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: - 

    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 if you desire. -

    If Ghidra failed to launch, see the Troubleshooting section. -

    -
    3. -
-

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 the -<GhidraInstallDir>/Ghidra/Features/PyGhidra/PyGhidra_README.html file.

- -

(Back to Top)

- -

Extensions

-

Extensions are optional components that can:

- -

Ghidra comes with the following extensions available for use (and by default uninstalled), which -can be found in the <GhidraInstallDir>/Extensions directory.

- -

Ghidra Extension Notes

- -

(Back to Top)

- -

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/GhidraDev_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.

-

(Back to Top)

- -

Upgrade Instructions

-

General Upgrade Instructions

-
    -
  1. - !!!Important!!! BACKUP YOUR OLD PROJECTS FIRST!! - !!!Important!!! -
    2. -
      -
    • - 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. -
  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. -
    4. -
- -

Server Upgrade Instructions

- -

(Back to Top)

- -

Troubleshooting & Help

-

Launching Ghidra

-

When launching Ghidra with the provided scripts in <GhidraInstallDir> and -<GhidraInstallDir>/support, you may encounter the following error messages: -

-

Using Ghidra

-

There are several ways you can get help with using Ghidra:

- -

(Back to Top)

- -

Known Issues for current release

-

All Platforms

- -

Windows

- -

Linux

- -

macOS (OS X)

- -

(Back to Top)

- - -
-
-
- - - diff --git a/GhidraDocs/InstallationGuide.md b/GhidraDocs/InstallationGuide.md new file mode 100644 index 0000000000..952ca70946 --- /dev/null +++ b/GhidraDocs/InstallationGuide.md @@ -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__.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 + `\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 + ``` + 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=/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 ``. Below is a description of the top-level directories and files that can +be found in `` 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 /support/gradle/ +gradle buildNatives +``` + +If you are connected to the Internet and do not have Gradle installed, execute: +```bash +cd /support/gradle/ +./gradlew(.bat) buildNatives +``` + +When the commands successfully complete, Ghidra will contain newly built native binaries in +the relevant modules' `build/os//` subdirectories, which Ghidra will prefer to any +existing pre-built native binaries in the `os//` subdirectories. + +## Running Ghidra + +### GUI Mode +1. Navigate to `` +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 `/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 +`/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 `/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 `/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 /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 +[`/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 `/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 + [`/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 `/Extensions`, + where `` 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 `/Ghidra/Extensions` + directory. For example, on Linux or macOS: + 1. Set current directory to the Ghidra installed-extensions directory: + ```bash + cd /Ghidra/Extensions + ``` + 2. Extract desired extension archive file(s) to the current directory: + ```bash + unzip ../../Extensions/Ghidra/.zip + ``` + 3. The extension(s) will be installed the next time Ghidra is started. + + To uninstall extensions, simply delete the extracted extension directories from + `/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 `/Extensions/Eclipse` directory. For more +information on installing and using the GhidraDev Eclipse plugin, see +[`/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 `/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 `/server/svrREADME.html` file for details on upgrading your +Ghidra Server. + +## Troubleshooting and Help + +### Launching Ghidra +When launching Ghidra with the provided scripts in `` and +`/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 + `/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 `/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 `/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 + [`/Extensions/Eclipse/GhidraDev/README.html`]( + ../GhidraBuild/EclipsePlugins/GhidraDev/GhidraDevPlugin/README.md) for more information on + building Ghidra module extensions from Eclipse. diff --git a/GhidraDocs/build.gradle b/GhidraDocs/build.gradle index 2243c7eb90..97cded2550 100644 --- a/GhidraDocs/build.gradle +++ b/GhidraDocs/build.gradle @@ -48,6 +48,11 @@ rootProject.assembleDistribution { exclude "**/build/**" exclude "**/bin/**" into "docs" - + } +} + +rootProject.assembleMarkdownToHtml { + from ("${this.projectDir}/InstallationGuide.md") { + into "docs" } } diff --git a/GhidraDocs/certification.manifest b/GhidraDocs/certification.manifest index 2549d7664b..e720cc3653 100644 --- a/GhidraDocs/certification.manifest +++ b/GhidraDocs/certification.manifest @@ -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| GhidraCodingStandards.html||GHIDRA||||END| GhidraFilesystemStorage.html||GHIDRA||||END| -InstallationGuide.html||GHIDRA||||END| +InstallationGuide.md||GHIDRA||||END| images/B.gif||GHIDRA||||END| images/D.gif||GHIDRA||||END| images/F.gif||GHIDRA||||END| diff --git a/README.md b/README.md index 27e59a10c5..6c67946c4d 100644 --- a/README.md +++ b/README.md @@ -38,8 +38,8 @@ To install an official pre-built multi-platform Ghidra release: * Launch Ghidra: `./ghidraRun` (or `ghidraRun.bat` for Windows) 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 -directory. +please refer to the [Installation Guide][installationguide] which can be found in a Ghidra release +at `docs/InstallationGuide.html`. ## Build @@ -126,6 +126,7 @@ source project. [nsa]: https://www.nsa.gov [contrib]: CONTRIBUTING.md [devguide]: DevGuide.md +[installationguide]: GhidraDocs/InstallationGuide.md [known-issues]: DevGuide.md#known-issues [career]: https://www.intelligencecareers.gov/nsa [releases]: https://github.com/NationalSecurityAgency/ghidra/releases