Scripting and Extension System

Relevant source files

• Ghidra/Features/Base/ghidra_scripts/FindSharedReturnFunctionsScript.java
• Ghidra/Features/Base/ghidra_scripts/FixupNoReturnFunctionsScript.java
• Ghidra/Features/Base/ghidra_scripts/HelloWorldScript.java
• Ghidra/Features/Base/src/main/java/ghidra/app/plugin/core/analysis/FindNoReturnFunctionsAnalyzer.java
• Ghidra/Features/Base/src/main/java/ghidra/app/plugin/core/cparser/ParseDialog.java
• Ghidra/Features/Base/src/main/java/ghidra/app/plugin/core/disassembler/CallFixupAnalyzer.java
• Ghidra/Features/Base/src/main/java/ghidra/app/plugin/core/osgi/BundleHost.java
• Ghidra/Features/Base/src/main/java/ghidra/app/plugin/core/osgi/BundleHostListener.java
• Ghidra/Features/Base/src/main/java/ghidra/app/plugin/core/osgi/BundleStatus.java
• Ghidra/Features/Base/src/main/java/ghidra/app/plugin/core/osgi/BundleStatusChangeRequestListener.java
• Ghidra/Features/Base/src/main/java/ghidra/app/plugin/core/osgi/BundleStatusComponentProvider.java
• Ghidra/Features/Base/src/main/java/ghidra/app/plugin/core/osgi/BundleStatusTableModel.java
• Ghidra/Features/Base/src/main/java/ghidra/app/plugin/core/osgi/GhidraBundle.java
• Ghidra/Features/Base/src/main/java/ghidra/app/plugin/core/osgi/GhidraBundleException.java
• Ghidra/Features/Base/src/main/java/ghidra/app/plugin/core/osgi/GhidraJarBundle.java
• Ghidra/Features/Base/src/main/java/ghidra/app/plugin/core/osgi/GhidraPlaceholderBundle.java
• Ghidra/Features/Base/src/main/java/ghidra/app/plugin/core/osgi/GhidraSourceBundle.java
• Ghidra/Features/Base/src/main/java/ghidra/app/plugin/core/osgi/OSGiUtils.java
• Ghidra/Features/Base/src/main/java/ghidra/app/plugin/core/script/GhidraScriptActionManager.java
• Ghidra/Features/Base/src/main/java/ghidra/app/plugin/core/script/GhidraScriptComponentProvider.java
• Ghidra/Features/Base/src/main/java/ghidra/app/script/GhidraScript.java
• Ghidra/Features/Base/src/main/java/ghidra/app/script/GhidraScriptProperties.java
• Ghidra/Features/Base/src/main/java/ghidra/app/script/GhidraScriptUtil.java
• Ghidra/Features/Base/src/main/java/ghidra/app/script/JavaScriptProvider.java
• Ghidra/Features/Base/src/main/java/ghidra/app/script/ResourceFileJavaFileManager.java
• Ghidra/Features/Base/src/main/java/ghidra/app/tablechooser/TableChooserDialog.java
• Ghidra/Features/Base/src/main/java/ghidra/app/tablechooser/TableChooserExecutor.java
• Ghidra/Features/Base/src/main/java/ghidra/app/tablechooser/TableChooserTableModel.java
• Ghidra/Features/Base/src/main/java/ghidra/app/util/demangler/Demangled.java
• Ghidra/Features/Base/src/main/java/ghidra/app/util/demangler/DemanglerUtil.java
• Ghidra/Features/Base/src/main/java/ghidra/app/util/headless/GhidraScriptRunner.java
• Ghidra/Features/Base/src/main/java/ghidra/app/util/headless/HeadlessAnalyzer.java
• Ghidra/Features/Base/src/main/java/ghidra/app/util/headless/HeadlessOptions.java
• Ghidra/Features/Base/src/main/java/ghidra/app/util/headless/HeadlessScript.java
• Ghidra/Features/Base/src/test.slow/java/ghidra/app/plugin/core/cparser/ParseDialogParsingAndPromptsTest.java
• Ghidra/Features/Base/src/test.slow/java/ghidra/app/plugin/core/cparser/ParseDialogTest.java
• Ghidra/Features/Base/src/test.slow/java/ghidra/app/plugin/core/script/AbstractGhidraScriptMgrPluginTest.java
• Ghidra/Features/Base/src/test.slow/java/ghidra/app/plugin/core/script/BundleHostTest.java
• Ghidra/Features/Base/src/test.slow/java/ghidra/app/plugin/core/script/GhidraScriptMgrPlugin2Test.java
• Ghidra/Features/Base/src/test.slow/java/ghidra/app/plugin/core/script/GhidraScriptMgrPlugin3Test.java
• Ghidra/Features/Base/src/test.slow/java/ghidra/app/tablechooser/TableChooserDialogTest.java
• Ghidra/Features/Base/src/test.slow/java/ghidra/framework/plugintool/dialog/ManagePluginsTest.java
• Ghidra/Features/Decompiler/ghidra_scripts/ShowConstantUse.java
• Ghidra/Framework/Project/src/main/java/ghidra/framework/plugintool/dialog/ManagePluginsDialog.java
• Ghidra/Framework/SoftwareModeling/src/main/java/ghidra/program/model/symbol/IllegalCharCppTransformer.java
• Ghidra/Test/IntegrationTest/src/screen/java/help/screenshot/GhidraScriptMgrPluginScreenShots.java

Ghidra provides a robust scripting and extension framework designed to automate reverse engineering tasks. The system supports multiple languages and runtime environments, primarily centered around a Java-based OSGi infrastructure and a Python integration layer.

1. Java Scripts: Compiled on-demand through an OSGi (Apache Felix) framework. Source directories are treated as bundles with automatic manifest generation, dependency resolution, and incremental compilation.
2. Python Scripts: Executed via PyGhidra, which uses JPype to bridge a native CPython interpreter to the JVM, enabling access to the full Ghidra API from Python.

System Architecture

The scripting system operates through several key components that manage the lifecycle from script discovery through execution:

Extension System Overview

Sources:

• Ghidra/Features/Base/src/main/java/ghidra/app/plugin/core/osgi/BundleHost.java59-72
• Ghidra/Features/Base/src/main/java/ghidra/app/plugin/core/script/GhidraScriptComponentProvider.java63-140
• Ghidra/Features/Base/src/main/java/ghidra/app/script/GhidraScriptUtil.java39-85

Core Components

BundleHost - OSGi Framework Manager

BundleHost is the central manager for the embedded Apache Felix OSGi framework. It maintains a registry of GhidraBundle objects representing script directories and JAR files Ghidra/Features/Base/src/main/java/ghidra/app/plugin/core/osgi/BundleHost.java59-67

Key Responsibilities:

• Lifecycle management of the OSGi framework (felixFramework) Ghidra/Features/Base/src/main/java/ghidra/app/plugin/core/osgi/BundleHost.java70
• Bundle registration and tracking via bundleMap Ghidra/Features/Base/src/main/java/ghidra/app/plugin/core/osgi/BundleHost.java67
• Activation/deactivation of bundles and notifying BundleHostListener objects Ghidra/Features/Base/src/main/java/ghidra/app/plugin/core/osgi/BundleHost.java97-125

Bundle Types:

Type	Class	Description
Source Directory	GhidraSourceBundle	Java source compiled on-demand with manifest generation Ghidra/Features/Base/src/main/java/ghidra/app/plugin/core/osgi/GhidraSourceBundle.java59-132
JAR Bundle	GhidraJarBundle	Pre-compiled OSGi bundles loaded directly Ghidra/Features/Base/src/main/java/ghidra/app/plugin/core/osgi/GhidraJarBundle.java1-32
Placeholder	GhidraPlaceholderBundle	Represents missing/invalid bundles Ghidra/Features/Base/src/main/java/ghidra/app/plugin/core/osgi/BundleHost.java171-172

For details, see OSGi Bundle Management.

Sources:

• Ghidra/Features/Base/src/main/java/ghidra/app/plugin/core/osgi/BundleHost.java59-173
• Ghidra/Features/Base/src/main/java/ghidra/app/plugin/core/osgi/GhidraSourceBundle.java59-132

GhidraSourceBundle - Compile-on-Demand

GhidraSourceBundle represents a Java source directory compiled into an OSGi bundle as needed Ghidra/Features/Base/src/main/java/ghidra/app/plugin/core/osgi/GhidraSourceBundle.java59-62 The compilation output is cached in a directory derived from the source directory path hash Ghidra/Features/Base/src/main/java/ghidra/app/plugin/core/osgi/GhidraSourceBundle.java150-168

Compilation Process:

1. Change Detection: Identifies newSources requiring compilation Ghidra/Features/Base/src/main/java/ghidra/app/plugin/core/osgi/GhidraSourceBundle.java99-103
2. Incremental Compilation: Uses the system JavaCompiler to build the source directory Ghidra/Features/Base/src/main/java/ghidra/app/plugin/core/osgi/GhidraSourceBundle.java105
3. Manifest Generation: Automatically generates OSGi manifests and BundleActivator classes Ghidra/Features/Base/src/main/java/ghidra/app/plugin/core/osgi/GhidraSourceBundle.java57-62

Sources:

• Ghidra/Features/Base/src/main/java/ghidra/app/plugin/core/osgi/GhidraSourceBundle.java59-188

Script Discovery and Metadata

Ghidra discovers scripts by scanning configured source directories, including the user scripts directory (typically ~/ghidra_scripts) and module-specific directories Ghidra/Features/Base/src/main/java/ghidra/app/script/GhidraScriptUtil.java152-185

Metadata Parsing: The GhidraScriptInfoManager tracks metadata parsed from script headers, such as @category, @keybinding, and @importpackage Ghidra/Features/Base/src/main/java/ghidra/app/plugin/core/script/GhidraScriptComponentProvider.java122-140

Sources:

• Ghidra/Features/Base/src/main/java/ghidra/app/script/GhidraScriptUtil.java152-185
• Ghidra/Features/Base/src/main/java/ghidra/app/plugin/core/script/GhidraScriptComponentProvider.java115-140

Script Execution Flow

The script execution pipeline varies between Java and Python but shares common GUI integration via GhidraScriptComponentProvider.

Java Script Lifecycle

JavaScriptProvider Details: For Java scripts, the JavaScriptProvider delegates to the OSGi bundle system:

1. Locates the GhidraSourceBundle containing the script Ghidra/Features/Base/src/main/java/ghidra/app/script/JavaScriptProvider.java55-61
2. Triggers bundle activation via bundleHost.activateAll() Ghidra/Features/Base/src/main/java/ghidra/app/script/JavaScriptProvider.java158
3. Loads the class using the OSGi bundle's class loader Ghidra/Features/Base/src/main/java/ghidra/app/script/JavaScriptProvider.java166
4. Instantiates the GhidraScript subclass Ghidra/Features/Base/src/main/java/ghidra/app/script/JavaScriptProvider.java100

For details, see Script Development and Execution.

Sources:

• Ghidra/Features/Base/src/main/java/ghidra/app/script/JavaScriptProvider.java34-174

Python Script Integration (PyGhidra)

PyGhidra provides Python scripting capabilities through a JPype bridge that connects a native CPython 3 interpreter to the JVM.

PyGhidra Architecture

PyGhidra can be used as a standalone library or within the Ghidra GUI. It utilizes PyGhidraLauncher to manage JVM startup and environment configuration.

API Highlights:

• pyghidra.start(): Initializes the JVM and Ghidra in headless mode.
• pyghidra.open_project(): Opens or creates a Ghidra project.
• pyghidra.analyze(): Triggers auto-analysis on a program.

For details, see PyGhidra - Python Integration.

Sources:

• Ghidra/Features/Base/src/main/java/ghidra/app/util/headless/HeadlessAnalyzer.java33 (Refers to Jython/Python stubbing)

Headless Script Execution

The HeadlessAnalyzer provides non-GUI script execution for automation Ghidra/Features/Base/src/main/java/ghidra/app/util/headless/HeadlessAnalyzer.java72-100 It manages its own application initialization and logging parameters Ghidra/Features/Base/src/main/java/ghidra/app/util/headless/HeadlessAnalyzer.java101-139

Sources:

• Ghidra/Features/Base/src/main/java/ghidra/app/util/headless/HeadlessAnalyzer.java72-170

GUI Components

Script Manager (GhidraScriptComponentProvider)

The main script management UI consists of:

• Category Tree: Hierarchical view based on script categories Ghidra/Features/Base/src/main/java/ghidra/app/plugin/core/script/GhidraScriptComponentProvider.java149-183
• Script Table: Filterable table showing script name, status, and metadata Ghidra/Features/Base/src/main/java/ghidra/app/plugin/core/script/GhidraScriptComponentProvider.java185-202
• Description Panel: Shows script documentation parsed from comments Ghidra/Features/Base/src/main/java/ghidra/app/plugin/core/script/GhidraScriptComponentProvider.java84-85

Sources:

• Ghidra/Features/Base/src/main/java/ghidra/app/plugin/core/script/GhidraScriptComponentProvider.java63-202

Bundle Manager (BundleStatusComponentProvider)

The BundleStatusComponentProvider visualizes bundle status and exposes actions for managing the OSGi environment, such as adding, removing, enabling, and refreshing bundles Ghidra/Features/Base/src/main/java/ghidra/app/plugin/core/osgi/BundleStatusComponentProvider.java68-73

Sources:

• Ghidra/Features/Base/src/main/java/ghidra/app/plugin/core/osgi/BundleStatusComponentProvider.java51-100