Ghidra Advanced Development Class

Topics

Ghidra and Eclipse Background
Development and Extensions
Program API vs Flat Program API
Scripting
Plugins
Ghidra GUI Components
Handling Binary Formats
Writing Analyzers
Writing Binary Loaders
Writing File System Loaders
Writing Languages: Sleigh
Building your Extension

What is Ghidra?

Integrated environment for software reverse engineering ("IDE" for SRE)
Developed by NSA Research
Written almost entirely in Java
Some native code (C/C++, Objective-C, Assembly)

What is Ghidra?

Consists of six major parts

Programs
Plugins
Scripts
Tools
Project Manager
Server

Programs

Information stored about a binary/executable in a Ghidra database

Symbols
Bytes / Memory
References
Instructions / Data
Comments
...etc.

Plugins

Each plugin provides a specific functionality
All plugins communicate within the tool
Users can choose which plugins are active
Users can write their own plugins
Written in Java
Preferred IDE is Eclipse with GhidraDev

Others possible, but not supported

Scripts

Can be written in Java or Python
Extensible to other JVM-based languages
Simplifies Ghidra programming API
Full API is still available
Run-time compilation for fast dev cycles
Preferred IDE is Eclipse with GhidraDev

Ghidra provides very basic editor without Eclipse
Others possible, but not supported

Tools

Collection of plugins and state
Ghidra includes pre-configured tools

Code Browser
Version Tracker

Extensions may provide more

Project Manager

Manages projects, tools, and data for a particular group of programs
Programs must be imported into a project before work can be done
Project configurations are saved for future use

Server

Used when multiple users want to collaborate on the same project
Provides network shared repository
Provides user access control
Keeps revision history (like Subversion)
Supports check-in, check-out, history
Does not support branching

Why Use Ghidra?

Tools can dynamically share data
Designed to handle large data sets
Supports teaming
Highly configurable environment
Highly extensible via plugins and scripts
Multi-platform (Linux, Mac, Windows)

How to Install Ghidra

Install the required version of Java
Extract the Ghidra distribution .zip
For development, install a supported version of Eclipse

See the documentation for version requirements

What is Eclipse?

Eclipse

Integrated Development Environment (IDE)

Java, C/C++, Python, and more!

Can be used for script development
Can be used for extension development

Eclipse

To integrate with Ghidra:

Install the GhidraDev plugin
Connect Ghidra to GhidraDev/Eclipse

GhidraDev is distributed with Ghidra
See "GhidraDev_README.html"

Eclipse

Eclipse Java Editor Tips and Tricks (1/3)

Open Type: Ctrl Shift T

Allows you to find a class without knowing the package

Organize Imports: Ctrl Shift O

Automatically fixes import statements

Navigate to: F3

Navigate to the class, method, variable, etc., at the current cursor location

Eclipse

Eclipse Java Editor Tips and Tricks (2/3)

Type Hierarchy: F4

Show inheritance hierarchy of current class/interface

Find References to: Ctrl Shift G

Finds all references to the item at current cursor location

Toggle Comments: Ctrl /

Comment or uncomment the selection

Eclipse

Eclipse Java Editor Tips and Tricks (3/3)

Outline View: Ctrl O

Lists members of the class

Code Completion: Ctrl Space

Displays a list of matches to complete the current expression

Quick Fix: Ctrl 1

Offer corrections to most problems (errors, warnings, etc.)

Eclipse

Provides templates and common tasks for Ghidra development

GhidraDevNewGhidra Module Project
GhidraDevNewGhidra Script
GhidraDevExportGhidra Module Extension

Lab 1

Launch Ghidra through Eclipse in debug mode

Development

Every piece of Ghidra is extensible

Plugins, Scripts, Analyzers, Fields, Importers, Exporters, etc.

Extensible components implement ExtensionPoint

List suffix in ExtensionPoint.manifest

Create a New Ghidra Module Project...

You may be prompted to locate Ghidra

Anatomy of an Extension Project

Extension Project

MyExtension/

src/main/java/
src/main/help/
src/main/resources/
ghidra_scripts/
data/
lib/
os/
extension.properties
Module.manifest

Extension Project

src/main/java/
src/main/resoures/

Hold the Java source for this extension
Packaged into a .jar file
Add src/test/java/ manually to include unit tests

Unit tests are not included in the .jar file

Extension Project

src/main/help/

Holds online help for this extension
Contains the table of contents to append
Contains the CSS and HTML contents
Java help does not support the latest HTML/CSS. Please preview using the help viewer rather than your browser.

Extension Project

ghidra_scripts/

Holds scripts for this extension
Expect the user to copy and modify scripts
Unpacked as source to the file system on installation
May provide examples to use an extension's API

Extension Project

data/

Holds data files for this extension
Will not end up inside the .jar file
Will be present in the distribution .zip file
Unpacked to the file system on installation
Allows user to easily edit or append data compared to resources in the .jar

Extension Project

lib/

Holds external Java dependencies for this extension
When working in Eclipse, the contents of this directory must be manually added to the class path of the Eclipse project
Optional

This directory may be deleted if there are no external dependencies

Extension Project

os/

Holds native components for this extension
Optional

This directory may be deleted if there are no native components

NEVER EVER USE JNI!

Communicate with a native process using sockets, I/O stream, etc.

Extension Project

os/
- linux64/
- osx64/
- win64/

Lab 2

Create a new Ghidra module project
From the Eclipse menu bar, select:

GhidraDevNewGhidra Module Project

In the "Module name" field, enter "gadc"
Click the "Finish" button to complete

Program API

High-Level Classes

Note: this diagram is not complete.

Flat vs. Program API

Program API

Ghidra Program API

Object-Oriented
Very deep
Can change from version to version

Program

Listing

Instructions
Data
Functions
Comments

Memory

Memory Blocks
Bytes

Symbol Table

Symbols

Reference Manager

References

Memory
Stack
External

...etc.

Flat Program API

Flat
Provides access to most common features
Is not complete
Will not change on you*

Flat Program API

public class FlatProgramAPI { FlatProgramAPI(Program) analyze() clear...() create...() find...() get...() remove...() save() set...() to...() }

Scripting

Script Manager

Script Category Tree

Displays dynamic tree of categories

Script Table

Displays name, description, key binding

Filter

Matches filter to name or description
Wildcard and case-insensitive

Scripting

Script Directories

Allows management of script directories
Default directories

HOME/ghidra_scripts/
INSTALL/Features/Base/ghidra_scripts/
Each other module/ghidra_scripts/

Useful for sharing scripts in multi-user

Scripting

GhidraScript API

public abstract class GhidraScript extends FlatProgramAPI { ask...() create...() get...() goto...() print...() run...() to...() }

Scripting

Sample script template in Java

Must fill in the TODO areas
Create a description
Fill in the run() method

//TODO add description here //TODO add metadata here public class MyScript extends GhidraScript { public void run() throws Exception { //TODO add code here } }

Scripting

Script Meta-data

Special tags in header comment
Describe the script
All are optional
Handle all the messy Java GUI stuff (buttons, menus, etc.)
Do not insert blank lines between meta-data

Scripting

Script Meta-data

@category

The category path for the script
Levels are separated by "."
Example

@category A.B.C

Scripting

Script Meta-data

@keybinding

Default key binding for a script
Format is [ctrl] [alt] [shift] [A-Z,0-9,F1-F12] and is case-sensitive
Examples

@keybinding L
@keybinding ctrl alt shift F1
@keybinding ctrl shift COMMA

Scripting

Script Meta-data

@menupath

Top-level menu path for a script
Use with caution!

Overcrowded menu
Collide with system action

Example

@menupath File.Run.My Script

Scripting

Script Meta-data

@toolbar

Image for top-level toolbar button to launch this script
Searches for image in script directories and then Ghidra installation directory
Also use with caution! (same issues as @menupath)
Example

@toolbar myScriptImage.gif

Scripting

Script State (1/3)

currentProgram

The current active open program

currentAddress

The current address of the location of the cursor

currentLocation

The program location of the cursor

Scripting

Script State (2/3)

currentSelection

The current selection or null if no selection exists

currentHighlight

The current highlight or null if no highlight exists

state

Provides place to store environment variables
Static and non-static

Scripting

Script State (3/3)

monitor

Allows script writer to inform user

messages and progress

Allows user to cancel script
Always use inside loops

while (!monitor.isCancelled()) { ... }

Console

Provides a place to dump information
Any text representing a symbol or address can be navigated by double-clicking
Example

Run PropagateExternalParametersScript.java

Scripting Lab

Lab 3

Create a new Java script: Lab3Script.java
Set the description
Set category: Category A.Category B
Set key binding: Alt Shift 6
Set menu path: ScriptMy Class Script
Set toolbar button: Info.png
Change the body of the run() method to: println("Hello class");
Save it
Run it

Lab 3 Answer

//It prints "Hello class" to the console. //@category Category A.Category B //@keybinding alt shift 6 //@menupath Script.My Class Script //@toolbar Info.png import ghidra.app.script.GhidraScript; public class Lab3Script extends GhidraScript { @Override public void run() throws Exception { println("Hello class"); } }

Lab 4

Create new script that will ask for an integer and print the current program's name that many times to the console

Lab 4 Answer

//Ask for an integer and print the current //program’s name that many times to the console //@category GADC import ghidra.app.script.GhidraScript; public class Lab4Script extends GhidraScript { @Override public void run() throws Exception { int n = askInt("How Many Times?", "N"); for (int i = 0; i < n; ++i) { if (monitor.isCancelled()) { break; } println(i + ". " + currentProgram.getName()); Thread.sleep(1000); } } }

Lab 5

Write a script that will search for instructions that move a scalar into a register
Pull the scalar from the instruction and create an EOL comment in the form:

setting [register] = [value]

Lab 5 Answer

//This script searches through all instructions that are //moving a scalar into a register //and sets an EOL comment in the form "[register] = [value]" //@category GADC import ghidra.app.script.GhidraScript; import ghidra.program.model.lang.Register; import ghidra.program.model.listing.Instruction; import ghidra.program.model.scalar.Scalar; public class Lab5Script extends GhidraScript { @Override public void run() throws Exception { for (Instruction instruction = getFirstInstruction(); instruction != null; instruction = getInstructionAfter(instruction)) { if ( monitor.isCancelled() ) { break; } if (instruction.getNumOperands() != 2) { continue; } Object[] opObjects0 = instruction.getOpObjects(0); if (opObjects0.length != 1 || !(opObjects0[0] instanceof Register)) { continue; } Object[] opObjects1 = instruction.getOpObjects(1); if (opObjects1.length != 1 || !(opObjects1[0] instanceof Scalar)) { continue; } Register register = (Register) opObjects0[0]; Scalar scalar = (Scalar) opObjects1[0]; String comment = "[" + register.getName() + "]=[" + scalar.toString(16, false, false, "", "") + "]"; setEOLComment(instruction.getMinAddress(), comment); } } }

Headless Scripting

Ghidra can be run from the command line without invoking the user interface
Can be run on one or more programs
Any script that does not invoke the GUI can be run in headless mode
See analyzeHeadlessREADME.html

Plugins

Must extend Plugin class
Can provide and consume services
Can provide actions

Extend DockingAction

Can provide GUIs

Extend ComponentProvider

Plugins

Must provide a plugin description

Use the @PluginInfo annotation

In constructor

In init()

Retrieve services consumed
Create actions

In dispose()

Release resources

ProgramPlugin

Extends Plugin class
Adds helper methods for events

Program activated/deactivated
Location changes
Selection changes
Highlight changes

Lab 6

Create a plugin: AdvancedGhidraClassPlugin
Extend ProgramPlugin
Apply the @PluginInfo annotation
Restart Ghidra
Verify plugin displays in the "Configure" dialog

Docking Windows

GUIs

Ghidra has custom docking window components
We recommend you use our components

GTable, GTree, GComboBox
Provide:

Custom filtering
Event handling
Threaded models
Navigation
Look-and-feel

Docking Windows

Allow users to customize the layout of components within a tool
Title bar
Local toolbar
Menu icon
Close button
Arranging components

Mouse cursor provides feedback
Components can be stacked, docked, or floating

Actions

Right mouse actions are context sensitive

This is determined by the plugin author

List of actions that appear will change based on where the cursor is located
User can assign/override key bindings

Tables

Use GTable
Filters
Columns
Export to CSV

Trees

Use GTree
Filters
Lazy loading to support large data

Lab 7

Add a global action to the plugin
Make the action popup a dialog message
Use Ghidra’s dialog class OptionDialog

Component Provider

ComponentProvider

Managed GUI component in the tool
Created and added to the tool by the plugin myComponent = new MyComponent(...); tool.addComponent(this, myComponent);
Components can be permanent or transient

Permanent - are always available in Window menu and closing just hides them (e.g., Listing)
Transient - created on the fly and when closed are destroyed and removed from Window menu (e.g., Search Results)

See ComponentProviderAdapter class

Lab 8

Create a ComponentProvider that contains only a JLabel
Update your previously-created plugin to add this component to the tool
Override the programActivated() method to update the label with the name of the active program

Lab 9

Add a local action to the component provider
Make the action toggle the label's background color between red and blue

Lab 10 (Optional)

Add a GTable to the component
Change the global action to search for instructions that move a scalar into a register
Populate the table with the search results (include an address column at minimum)

Handling Binary Formats

Binary Formats

Included formats:

ELF, PE, Mach-O, and more!

What is needed for a new format?

Data structure to parse the format
Analyzers to annotate the binary format
Loader for Ghidra's importer
Language, if not currently supported

A Toy Format

The "Ghidra Format" (see ghidra.h): struct ghidra_header { char magic[6]; // magic number identifier unsigned byte cputype; // cpu specifier unsigned short nsections; // number of sections unsigned short nsymbols; // number of symbols unsigned int flags; // flags }; struct ghidra_section { // for 32-bit architectures char name[16]; // name of this section unsigned int addr; // memory address of this section unsigned int size; // size in bytes of this section unsigned int offset; // file offset of this section unsigned int flags; // flags (section type and attributes }; struct ghidra_symbol { // for 32-bit architectures char name[25]; // name of this symbol unsigned int addr; // memory address of this symbol unsigned short type; // type of this symbol };

Lab 11

Create classes to parse Ghidra format binaries
Each class must have a constructor that takes a BinaryReader parameter
Each class must implement StructConverter
In this lab, you will need to create:

class GhidraFormatHeader
class GhidraFormatSection
class GhidraFormatSymbol
class GhidraFormatConstants

See ghidra.h for detailed definitions
For examples, see Img3* classes

Analyzers for Raw Binary Files

Analyzers

Must implement the Analyzer interface

// Display name, input type, priority String getName(); AnalyzerType getAnalysisType(); AnalysisPriority getPriority(); // Called for changes to analyzer inputs boolean added(...); boolean removed(...); // Register and react to user options void registerOptions(...); void optionsChanged(...);

Lab 12

Create an analyzer to annotate a raw Ghidra format binary

Place header data structures in listing

Loaders

Must implement Loader interface

Consider AbstractProgramLoader

package ghidra.app.util.opinion; // By convention public class MyLoader implements Loader { Collection<LoadSpec> findSupportedLoadSpecs(...); List<DomainObject> load(...); ... }

Must update the .opinion file for each processor supported by the format

Lab 13

Create a loader for Ghidra format binaries
Be sure to update the .opinion files:

x86.opinion
PowerPC.opinion
ARM.opinion

Lab 14

Write an analyzer that searches for instructions that move a scalar into a register
Pull the scalar from the instruction and create an EOL comment in the form:

setting [register] = [value]

Note: you already did this in a script!

File System Loaders

File System Viewer

Provides an alternative importer
Allows importing many programs from a single archive or image
Extensible using GFileSystem interface

Consider GFileSystemBase class

File System Viewer

Drills down into file systems, including nested file systems
Extract files
Import binaries
Perform static analysis
View as text
View as image (i.e., picture)

Lab 15

Create a GFileSystem for OSX Universal Binary (UBI), also known as Fat Binary

See FatHeader

Ghidra already contains code to parse this format
Use these parser classes to implement a GFileSystem to open universal binary files

Lab 16

Put several universal binaries into a .zip file
Verify the File System Browser plugin can handle nested universal binaries

Sleigh

Used to disassemble binary into assembly
Used to decompile assembly into C
Decompiler optimizes
Can be applied to any binary, assuming:

Sleigh language with pCode exists
See GhidraInstall/Ghidra/Processors

Performs data type propagation
Commit parameter / return types
Decompiler Parameter ID analyzer

Lab 17

Change R2 in the 8051 language to R2D2

GhidraInstall/Ghidra/Processors/8051/data/languages/8051_main.sinc

Restart Ghidra
Import any program as a raw binary and select 8051 as the language
Verify the register is changed

Making a Build of Your Extension

Making a Build

From Eclipse:

Select GhidraDevExportGhidra Module Extension in the menu bar
Select your module from the "Ghidra module project" drop-down
Click the "Finish" button

Making a Build (alt)

You must have a compatible version of Gradle installed
From the command line (bash):

cd /path/to/extension export GHIDRA_INSTALL_DIR=/path/to/ghidra gradle extensionDistZip #Substitute extension name

Output goes into build/distributions/
Gradle supports incremental builds: It only rebuilds what has changed since last build
Use the clean task first if you want to rebuild everything

Lab 18

Build your extension!