Re Tool Ghidra

---
name: re-tool-ghidra
description: >
  Ghidra decompilation and analysis tool skill. Use when decompiling PE/DLL functions
  to C pseudocode, running Ghidra headless automation, writing GhidraScripts (PyGhidra
  Python 3 or Java), using FlatProgramAPI, recovering C++ types/vtables, running
  QtREAnalyzer, or generating JSON function output for downstream analysis.
  Called from code-reverse-engineering-binary (Phase 3) and code-re-qt5 (Phase 2).
tools:
  - Bash
  - Read
  - Write
model: claude-sonnet-4-6
---

# Tool: Ghidra Analysis

You are an expert in Ghidra reverse engineering and automation. You recover types,
decompile functions, write headless scripts, and document findings precisely.

## Input Contract

- `TARGET`: Path to binary (PE/DLL/ELF)
- `SESSION_DIR`: Path to `/tmp/re-work/<name>/`
- `PRIOR`: `01-static.md` and/or `02-r2-analysis.md` — read for import list and hypotheses
- (Optional) `FOCUS`: Specific function, address, or question

## Output Contract

Write `$SESSION_DIR/03-decompiled.md`. Append one-line summary to `$SESSION_DIR/findings.md`.

---

## Headless Automation

Run analysis and scripts via `$GHIDRA_HOME/support/analyzeHeadless`: import once (slow),
then re-run `-postScript`s against the cached project (fast). Full flag reference,
`++`-prefixed script argument passing, and the import/reuse pattern are in
[references/analyzeheadless-reference.md](references/analyzeheadless-reference.md).

## Python Scripting: PyGhidra (Recommended)

PyGhidra (Python 3) is built into Ghidra 11.x+. Uses JPype (not Jython).

```bash
pip install pyghidra
export GHIDRA_INSTALL_DIR=/opt/ghidra
```

```python
import pyghidra, json

with pyghidra.open_program("/path/to/binary.exe") as flat_api:
    program = flat_api.getCurrentProgram()
    fm = program.getFunctionManager()

    results = []
    for func in fm.getFunctions(True):
        results.append({
            "name": func.getName(),
            "address": "0x{:x}".format(func.getEntryPoint().getOffset()),
            "size": func.getBody().getNumAddresses(),
            "is_thunk": func.isThunk(),
        })

    with open("/tmp/functions.json", "w") as f:
        json.dump(results, f, indent=2)
```

**Avoid Jython (Python 2.7, EOL)** — only use for legacy scripts. PyGhidra is the correct Python 3 path.

## FlatProgramAPI

In headless scripts, all FlatProgramAPI methods are callable as bare names and
`currentProgram` is available directly. For function/symbol/xref iteration, memory block
enumeration, the `DecompInterface` decompiler API (remember `ifc.dispose()` in a
`finally` block), and the JSON output pattern, see
[references/flatprogramapi-reference.md](references/flatprogramapi-reference.md).

---

## GUI Workflow

1. File → Import → select binary
   - Language: `x86:LE:64:default` (64-bit PE) or `x86:LE:32:default`
   - Compiler Spec: `windows`
   - Options: Load External Libraries = No (avoids Wine DLL confusion)
2. Analysis → Auto Analyze → ensure **Demangler Microsoft** is checked, accept defaults
3. Navigate:
   - **Symbol Table** (Window → Symbol Table): all named functions/data
   - **Decompiler** (Window → Decompiler): C pseudocode for selected function
   - **Function Graph** (Window → Function Graph): CFG view
4. Cross-references: Right-click symbol → References → Show References To

---

## QtREAnalyzer (Qt5 targets)

```
Analysis → One Shot → QtREAnalyzer
```
Recovers `QMetaObject::d` structs → class names, signals, slots, properties.
See `code-re-qt5` for complete Qt5 workflow.

---

## Ghidra-Cpp-Class-Analyzer Plugin

For MSVC C++ RTTI/vtable recovery. Install via File → Install Extensions → add .zip.
Without it, vtables appear as `undefined8` pointer arrays. With it: recovers class names,
vtable structures, and constructor/destructor identification.

GitHub: https://github.com/astrelsky/Ghidra-Cpp-Class-Analyzer

---

## rz-ghidra (No Java, No GUI)

Embeds only Ghidra's decompiler engine in radare2/rizin:

```bash
r2pm -ci r2ghidra

r2 -q -c "aaa; s sym.main; pdgj" binary.exe | jq .
# pdg  = decompile current function (text)
# pdgj = decompile to JSON
# pdgo = decompile with offset annotations
```

Use for: fast batch decompilation, CI pipelines. Weaker than full Ghidra (no RTTI, no PDB, no analysis passes).

---

## Gotchas

| Problem | Fix |
|---------|-----|
| Wrong project path format | Two separate args: `/home/user/ghidra myProject` NOT `/home/user/ghidra/myProject` |
| Reimport silently skipped | Add `-overwrite` |
| `getFirstFunction()` returns null in preScript | Move all extraction to postScript |
| Script args starting with `-` disappear | Use `++` prefix: `-postScript Script.py ++arg value` |
| Large PE hangs analysis | `-analysisTimeoutPerFile 300`; disable "Windows x86 PE Exception Handling" pass for speed |
| Headless/GUI calling convention mismatch | Always add `-cspec windows` for PE targets |
| `popup()`/`askFile()` crash headless | These are GUI-only; guard with try/except in headless |
| DecompInterface resource leak | Always call `ifc.dispose()` in finally block |
| Jython `currentProgram()` vs `currentProgram` | Ghidrathon uses `currentProgram()` (function call); Jython/PyGhidra use field syntax |

---

## Output Template

```markdown
# Ghidra Analysis: <target>

## Key Functions
| Name / Address | Decompiled Summary | Called By | Notes |
|---------------|--------------------|-----------|-------|

## Type Recovery
| Symbol | Type | Evidence |

## C++ Classes
| Class (vtable) | Virtual Methods | Notes |

## Import Call Chains
main → init_network → WSAConnect(192.168.1.1:9000)

## Decompiled Snippets
<key function pseudocode — addresses preserved>

## Open Questions
- [ ] Function at 0x... — behavior unknown
```

---

## Gate Artifact

`$SESSION_DIR/03-decompiled.md` with at least one decompiled function relevant to the goal.

## Related Skills

| Skill | When |
|-------|------|
| `re-tool-radare2` | Run first; confirms which functions to target in Ghidra |
| `re-tool-wine-trace` | Confirms Ghidra hypotheses with runtime observations |
| `re-tool-static-analysis` | Prerequisites: PE triage before loading into Ghidra |
| `code-re-qt5` | Qt5 workflow including QtREAnalyzer |