This article is based on the public release of Ghidra 11.0.1.

Ghidra’s graphical user interface is intuitive to use, customisable, and allows one to easily analyse, compare, and contrast code. There is one thing its not made for: bulk actions. While bulk import of files is possible via drag-and-drop into an open Ghidra project, it still requires manual interaction to alter settings for all (or a subset thereof) binaries, just to give an example. Executing Ghidra headless fixes this issue, as it allows Ghidra to work without a graphical user interface.

Table of contents

• Location
• Options

Location

To run Ghidra headless, use the analyzeHeadless file within the support folder in Ghidra’s installation folder. The file has a .bat extension on Windows, the file without extension is to be used on MacOS and Linux distributions. For additional help please refer to the analyzeHeadlessREADME.html file within the same folder.

Options

Upon executing the headless analyser, a plethora of options is given at once. The complete overview is given below.

Headless Analyzer Usage: analyzeHeadless
           <project_location> <project_name>[/<folder_path>]
             | ghidra://<server>[:<port>]/<repository_name>[/<folder_path>]
           [[-import [<directory>|<file>]+] | [-process [<project_file>]]]
           [-preScript <ScriptName>]
           [-postScript <ScriptName>]
           [-scriptPath "<path1>[;<path2>...]"]
           [-propertiesPath "<path1>[;<path2>...]"]
           [-scriptlog <path to script log file>]
           [-log <path to log file>]
           [-overwrite]
           [-recursive]
           [-readOnly]
           [-deleteProject]
           [-noanalysis]
           [-processor <languageID>]
           [-cspec <compilerSpecID>]
           [-analysisTimeoutPerFile <timeout in seconds>]
           [-keystore <KeystorePath>]
           [-connect <userID>]
           [-p]
           [-commit ["<comment>"]]
           [-okToDelete]
           [-max-cpu <max cpu cores to use>]
           [-loader <desired loader name>]
 
     - All uses of $GHIDRA_HOME or $USER_HOME in script path must be preceded by '\'

For any headless run, one must specify the Ghidra project’s location and name. This can be a remote or local project. If the remote project requires authentication, the headless run also needs to be able to successfully authenticate.

To provide the Ghidra project, specify the folder where the project resides, followed by the name. To clarify: do not include the project name in the path. To illustrate, please see the two examples below.

#Incorrect
analyzeHeadless /home/user/ghidraProjects/specificProject specificProject
 
#Correct
analyzeHeadless /home/user/ghidraProjects specificProject

Keep in mind that setting, for example, a loader is not required, but can resolve misidentified binaries. The automatic analyser will try to correctly identify a given file as its type, but it isn’t guaranteed to be correct. As such, in some cases it is required to set a given loader, processor, or compiler specification for imported binaries, based on prior research.

Binaries can (recursively, use -recursive) be imported in bulk from a given folder using -import /path/to/folder. For each imported binary, arbitrary code can be executed in the form of Ghidra scripts. These scripts can be written in Java or Python 2 by default. Using third party extensions can allow the usage of Python 3 and other languages, although Python 3 is the most used non-official supported language.

Make sure Ghidra knows the location of the script(s), either by entering it manually into Ghidra’s graphical user interface, or by specifying the path to the folder with the scripts by using -scriptPath /path/to/scripts.

The two methods to execute scripts on each imported binary are -preScript scriptName and -postScript scriptName. Within a script, one can run other scripts using the runScript(String scriptName function. An example is given here.

The prescript scripts are executed prior to the initial analysis, and can still change the settings for the initial analysis. The postscript scripts are executed once the initial analysis has completed. As such, scripts which execute as postscripts can fully utilise Ghidra’s API and services.

To illustrate, assume a script to iterate over all functions is required for a given reason. Before the initial analysis, no functions are defined within the program in Ghidra. Iterating over all functions then equals iterating over an empty iterator. The postscript will find a program within Ghidra with defined functions, and can iterate over said functions to perform arbitrary logic.

To contact me, you can e-mail me at [info][at][maxkersten][dot][nl], or DM me on Twitter @Libranalysis.