Ghidra: install the tool and open a project

What you are installing

Ghidra is a framework for reading programs when all you have is the compiled file. It stores a database of instructions, data, names, and comments, and it draws a C-like view on top of that database. The National Security Agency released it as free software. You download a release from the project’s own distribution channel, check the published checksum, and unpack it. A repacked archive from a random page is a different program that happens to use the same name.

The workbench is a Java application. Ghidra 11 releases expect a current long-term JDK, and 17 is the baseline those notes have used. The notes shipped with your tarball are the authority if they name a different update. On Linux and macOS the launcher is ghidraRun. On Windows it is ghidraRun.bat. If the script cannot find Java, set JAVA_HOME to the JDK you just installed and start it again. A window with a project list means the install worked.

The project window and CodeBrowser

Ghidra splits the work into tools. The project window is the catalog. CodeBrowser is the tool that shows one program’s bytes, instructions, and decompiler text. Version Tracking, which a later lesson uses to compare two builds, is a third tool. You launch CodeBrowser by opening a program, or from the tool chest when you already know its name. An install that only ever shows the project window is finished enough to begin the lab.

Keep the project on a disk that belongs to the lab. A project that will later contain a hostile sample belongs on the isolated virtual machine where that sample is allowed to sit. Analysis does not execute the file, and the project is still a copy of those bytes plus your notes. Treat the folder with the same care as the file you imported.

What a local project actually is

File > New Project asks whether the project is non-shared or shared. Non-shared means a directory you choose. Ghidra writes a project marker file ending in .gpr and a repository directory ending in .rep beside it. Programs you import later live inside that repository, together with every name, comment, and type you add. The original executable on disk is left alone.

Shared projects connect to a Ghidra Server so several people can check work in and out. That is a team setup, covered when the curriculum reaches saving and handoff. For the harbor lab, a non-shared project named harbor-lab is the whole container. You can close the window at any time. Reopening the same project brings the catalog back. Until you import a file, the catalog is empty, and an empty catalog is the correct first state.

• Download a release from the project’s own channel and check its checksum.
• Install the JDK the release notes name.
• Create a non-shared project in a lab directory you can find again.
• Leave the original binaries outside the project folder so a backup of the project is obviously a backup of analysis.

Lab: an empty project you can reopen

Create a directory for the lab, start Ghidra, and make a non-shared project called harbor-lab inside it. Confirm that the directory now holds the project marker and the repository directory. Close Ghidra completely. Start it again and open the same project. The program list is empty. That empty list is the result you want: the tool runs, the project persists, and nothing has been imported yet.

Write one line in your lab notebook: the path of the project, the Ghidra version from the Help > About dialog, and the JDK version you ran it with. Every later lesson in this curriculum opens this same project. If the launcher fails, stop on the JDK the release notes named. The rest of the course assumes this window opens.

harbor-lab/
  harbor-lab.gpr
  harbor-lab.rep/

Notebook:
  project: ~/labs/harbor-lab
  ghidra:  <version from Help > About>
  jdk:     <version the release notes required>