ghidra-rpc

Ghidra RPC

A CLI daemon that exposes Ghidra reverse engineering capabilities over a Unix domain socket. You interact with it by running ghidra-rpc commands via the bash tool - every command outputs JSON to stdout.

Running Commands

All `ghidra-rpc` commands must be run with `uv run` from the ghidra-rpc skill directory (the directory containing this SKILL.md file):

cd <skill-dir> && uv run ghidra-rpc <command> ...

Prerequisites Check

Before using any commands, verify the setup:

1. Is the daemon running? Run uv run ghidra-rpc status --project <path>. If not running,

the user needs to start it in a separate terminal: uv run ghidra-rpc start --project /path/to/project.gpr (blocking, human-only). The --headless flag skips the GUI. For non-blocking / automated startup use start --detach --headless or restart --headless. Both commands accept --timeout SECS (default: 60 s headless, 180 s GUI) and log daemon output to /tmp/ghidra-rpc-<hash>.log.

1. GUI mode: open the binary in CodeBrowser. In GUI mode the daemon discovers programs

via the running CodeBrowser tool. If the binary is in the project but not currently open in CodeBrowser, list-binaries will return empty and all commands will fail with "Binary not found". Use list-project-programs to see what's stored in the project, then double-click the program in Ghidra's Project window to open it.

1. Is `GHIDRA_INSTALL_DIR` set? The daemon will fail loudly if this is missing.

Once the daemon is running, all commands below work automatically. If the daemon dies, commands will attempt auto-restart from the saved session.

Command Reference

Every command accepts --project <path> (or reads GHIDRA_RPC_PROJECT env var). All output is JSON. Exit code 0 = success, 1 = error.

Project Management

status output: {running, socket, mode, mode_source, project, binaries}. binaries is the loaded-binary list when the daemon is running, null when stopped (one-shot health check without a second list-binaries call). mode_source is "running" when the daemon is live, "session" when the mode is from the saved session only (daemon stopped), and null if no session exists.

Loading & Analysis

load flags:

• •--no-analyze - skip auto-analysis entirely (fast; useful when you only need the

listing or plan to run analysis later via Ghidra GUI).

• •--analysis-timeout SECS - abort auto-analysis after the given wall-clock budget

(best-effort); the binary is saved with whatever analysis completed in time.

Listing

Decompilation

<func> can be a function name or hex address (e.g., main or 0x401000). If the name is ambiguous, the error message lists matches so you can use the address instead.

Search

Cross-References

Navigation (GUI mode only)

Memory & Disassembly

Modifications

Comment types: plate, pre, post, eol (default), repeatable.

Signature input is sanitised automatically: trailing semicolons are stripped, whitespace is trimmed, and inline calling conventions (__thiscall, __fastcall, __stdcall, __cdecl, __vectorcall, __pascal) are extracted from the string and applied via the proper Ghidra API. So you can paste a C prototype directly (e.g. void __thiscall Foo::Bar(int x); works without manual cleanup).

Type expressions for set-data-type, retype-variable, and struct field types:

• •Built-ins: byte, char, int, uint, short, long, float, double, void, string, unicode
• •Pointer: char *, void *, int **
• •Array: char[11], int[4]
• •Any type in the program's data type manager by name or path: MyStruct, /POSIX/size_t

Bookmarks

Bookmark types: Note (default), Warning, Error, Info, Analysis.

Bookmarks are visible in the Ghidra GUI's Bookmarks window. Use them to persistently mark interesting locations, track analysis progress, or flag findings for human review.

Function Tags

Tags are string labels (e.g. crypto, vuln-sink, analyzed, needs-review) visible in Ghidra's Function Tags window. Use them to classify functions and track analysis progress.

Data-Type Authoring

Version Tracking & Diff

For the full patch-diff workflow see docs/flows/patch-analysis.md.

Error Handling

Error responses look like:

{"id": "...", "ok": false, "error": "FunctionNotFound", "message": "Function 'foo' not found."}

Common errors:

• •DaemonNotRunning: Daemon isn't started. Tell the user to run ghidra-rpc start.
• •ValueError: Bad argument (ambiguous name, invalid address). The message usually tells

you what to do - e.g., use a more specific name or an address.

• •RuntimeError: Ghidra-level error. For GUI-only commands in headless mode, the error

says so explicitly.

Write Operations & Persistence

Write operations (rename, create-label, create-function, delete-function, set-comment, batch-rename, batch-set-comment, set-signature, set-data-type, retype-variable, set-calling-convention, set-thunk, set-flow-override, set-processor-context, create-struct, create-union, modify-struct, create-enum, modify-enum, set-equate, set-bookmark, clear-data-range, apply-data-type-range, write-bytes, assemble, tag-function, untag-function, create-namespace) use Ghidra transactions internally. Every write is automatically saved to the project database on disk after the transaction commits, so changes survive daemon restarts and are visible when the project is reopened in the Ghidra GUI.

Every write response includes a verified boolean that confirms whether the change was read back successfully after committing.

You can also save explicitly at any time:

ghidra-rpc save              # saves all loaded programs
ghidra-rpc save <binary>     # saves one program

On clean shutdown (stop or Ctrl+C), all programs are saved automatically.

Patch / Diff Analysis Quick Start

# 1. Load both versions
ghidra-rpc load /path/to/binary_v1 -p project.gpr
ghidra-rpc load /path/to/binary_v2 -p project.gpr

# 2. Find changed functions (summary counts all changes; matched list is filtered)
ghidra-rpc version-track binary_v1 binary_v2 --changed-only

# 3. Diff a specific changed function
ghidra-rpc function-diff binary_v1 <func> binary_v2 <func>

Full workflow — correlator details, unmatched analysis, bulk decompile: read docs/flows/patch-analysis.md.

Typical Workflow

1. User starts daemon: cd <skill-dir> && uv run ghidra-rpc start --project /path/to/project.gpr --headless

For automation / non-blocking start: uv run ghidra-rpc start --project /path/to/project.gpr --headless --detach

1. Load binary: uv run ghidra-rpc load /path/to/binary -p /path/to/project.gpr

Response includes short_name (usable alias in all subsequent commands). (add --no-analyze to skip analysis, --analysis-timeout SECS to cap it)

1. Get overview: metadata, functions, imports, exports
2. Investigate: decompile interesting functions, xrefs-to to trace callers
3. Annotate: rename-function, set-comment to document findings
4. Search: strings for hardcoded values, symbols for specific patterns

FAQ / Common Gotchas

`create-label` properly replaces DEFAULT (auto-analysis) symbols: create-label creates a USER_DEFINED label and sets it as the primary symbol at the address. If a DEFAULT symbol (e.g. DAT_00418138) already exists, it is demoted to secondary. The decompiler will then use the new name. rename-symbol renames in place but requires an existing symbol; create-label is preferred for annotating addresses regardless of existing symbols.

Annotating an address with no existing symbol (rename-symbol fails with "No symbol found"): rename-symbol requires a symbol to already exist at the address. Auto-analysis only places DAT_ symbols where it detects data; inside arrays or dense struct regions many addresses have no symbol. Use create-label instead - it creates a new USER_DEFINED label if none exists, or renames the existing one:

ghidra-rpc create-label <binary> 0x0040e4ac topPtrErrorMsg

You can also add --create to rename-symbol for the same upsert behaviour.

Defining and applying a struct across a memory region: Full workflow to stamp a struct across a repeated data table:

# 1. Create the struct type in the DTM (--if-not-exists makes the call idempotent)
ghidra-rpc create-struct binary ErrorEntry int errorNumber "char *" ptrErrorMsg --if-not-exists

# 2. Stamp the struct across the range with --clear to atomically clear + apply
#    (23 × 8-byte ErrorEntry structs, both endpoints inclusive)
ghidra-rpc apply-data-type-range binary 0x0040e4a8 0x0040e55f ErrorEntry --clear

After this, each address 0x0040e4a8, 0x0040e4b0, ... has type ErrorEntry. Without --clear, apply-data-type-range skips positions where existing data conflicts and reports them in the errors list. Use clear-data-range first if you need finer control over which region is cleared.

Discovering what labels exist at an address or range:

# Single address
ghidra-rpc list-labels binary 0x0040e4a8

# Range
ghidra-rpc list-labels binary 0x0040e4a8 --end 0x0040e55f --limit 50

Using the binary name after `load`: load returns both a full key (binary) with a hash suffix and a short_name (the original filename). Use short_name in all subsequent commands - it works because commands match binary names by substring:

# Load response: {"binary": "/WinHelloCPP.exe-85cbcc", "short_name": "WinHelloCPP.exe", ...}
ghidra-rpc decompile WinHelloCPP.exe main        # short_name works
ghidra-rpc decompile WinHelloCPP main            # even without extension, if unambiguous

If two binaries share the same stem, use the full key to disambiguate.

Trailing semicolons in signatures: Ghidra's parser rejects C prototypes that end with ;. ghidra-rpc strips trailing semicolons automatically, so you can paste verbatim.

`list-binaries` is empty but I loaded a binary: In GUI mode, the binary must be open in CodeBrowser. Use list-project-programs to see what's stored in the project repo, then open it in CodeBrowser's Project window.

Daemon log file: When started in the background (start --detach or restart), logs are written to /tmp/ghidra-rpc-<hash>.log (same directory and stem as the Unix socket). If the daemon fails to start or become responsive, check that file first:

tail -50 /tmp/ghidra-rpc-*.log

The timeout error message always prints the exact log path.

`GHIDRA_INSTALL_DIR` not found after backgrounding: Environment variables may be lost when daemonising (nohup, cron, systemd units, etc.). Fix options, in order of preference:

1. Pass --ghidra-install-dir /path/to/ghidra to start or restart - the value is

persisted in the session file and forwarded to every subsequent restart automatically.

1. Export GHIDRA_INSTALL_DIR in your shell profile (~/.bashrc, ~/.zshrc) so it

survives login sessions.

1. Use start --detach --headless from the same terminal where the env var is set.

Session file location: By default the session file (.ghidra-rpc-<hash>.json) is written alongside the .gpr project file, keeping all state self-contained. To use a custom directory (e.g. a shared location or a RAM-disk), set GHIDRA_RPC_STATE_DIR:

export GHIDRA_RPC_STATE_DIR=/tmp/ghidra-sessions

Changes not visible in the Ghidra GUI: Make sure you open the project copy (e.g. basic_code-501243 in the Project window), not the raw binary via File → Open. Also ensure you are not running two separate Ghidra instances on the same project (causes lock conflicts). Changes made by ghidra-rpc are auto-saved to disk and will be visible the next time the program is opened in the GUI.

`restart` without a prior session: Pass --headless so restart can create a fresh headless session instead of requiring a prior start.

Decompiler timeout on certain functions: Some functions trigger expensive decompiler analysis paths and time out even with simple assembly. Use decompile --timeout 300 (or higher) for stubborn functions. The default timeout is 120 s (increased from 60 s to handle large firmware functions). The retype-variable command also accepts --timeout since it triggers an internal decompilation pass.

`decompile` returns bad-instruction warnings — use `pcode --high` as fallback: When decompile produces output like "Bad instruction data" or fails to decode a function body (common on ARM Thumb code in regions that auto-analysis mis-classified as data), try pcode --high instead:

ghidra-rpc pcode binary 0x03288102 --high

The P-code engine re-decodes bytes from the function object's context rather than from the listing-level disassembler, so it often succeeds where decompile fails. High P-code also reveals all CALL / CALLIND / BRANCHIND targets and data flow, making it useful for tracing arguments even without valid decompilation. Fix the root cause with set-processor-context (see below).

`disassemble` starts from the wrong address (B2 warning): If disassemble is called at an address with no instruction (e.g. an address that is mid-instruction or undefined), the response now includes a warning field explaining that disassembly started from the next available instruction. Check for warning in the JSON response when the listing looks wrong.

ARM Thumb mis-classification — `set-processor-context` is the fix (F1/F5): When ARM auto-analysis classifies Thumb code as data, the listing disassembler decodes it as 32-bit ARM (TMode=0) and produces garbage. The full recovery workflow:

# 1. Diagnose: check TMode at the affected address
ghidra-rpc get-processor-context binary 0x03288100 --register TMode
# Expected: {"TMode": 0}  ← this is the problem

# 2. Clear the bad data/code classification
ghidra-rpc clear-data-range binary 0x03288100 0x032883ff

# 3. Set Thumb mode for the range
ghidra-rpc set-processor-context binary 0x03288100 TMode 1 --end 0x032883ff

# 4. Verify disassembly now shows Thumb-2 instructions
ghidra-rpc disassemble binary 0x03288100 --count 20

# 5. Re-create the function
ghidra-rpc create-function binary 0x03288100

If create-function fails because a bad stub still exists at the address, use delete-function first to remove it.

Bad stubs blocking re-creation — use `delete-function` (F2): If create-function 0x03288103 (wrong parity) left a stub, and now create-function 0x03288102 (correct address) fails with "already exists at overlapping address", delete the bad stub first:

ghidra-rpc delete-function binary 0x03288103
ghidra-rpc create-function  binary 0x03288102

Batch rename / comment 40+ functions without round-trip overhead (F7): Use batch-rename and batch-set-comment to apply many annotations in a single server round-trip and Ghidra transaction:

# Rename functions from a JSON file
ghidra-rpc batch-rename binary --json-file renames.json

# Or inline
ghidra-rpc batch-rename binary --json \
  '[{"target":"sub_401234","new_name":"init_uart"},{"target":"0x400200","new_name":"isr_handler"}]'

# Label-mode (symbol/label rename by address)
ghidra-rpc batch-rename binary --mode label --json \
  '[{"address":"0x0333afcc","new_name":"g_debugStr"}]'

# Batch comments
ghidra-rpc batch-set-comment binary --json \
  '[{"address":"0x03288102","comment":"Thumb ISR entry","comment_type":"plate"}]'

All items that succeed are committed in one transaction; failed items are reported per-item in results[].ok=false and do not roll back the successes.

Concurrent write operations are serialised: The daemon serialises all command handler invocations internally to prevent Ghidra transaction conflicts. You do not need to serialize write commands externally — parallel writes are queued automatically. This is slightly slower than concurrent execution but eliminates silent partial failures.

Reporting Bugs and Missing Features

While using ghidra-rpc you may encounter bugs, errors, or missing capabilities. Please report them - real-world usage drives continuous improvement.

At the end of any analysis session where you hit a problem, save a brief report:

cat > /tmp/ghidra-rpc-issues-$(date +%Y%m%d-%H%M%S).md << 'EOF'
## ghidra-rpc Issue Report

**Date:** $(date)
**Binary:** <name of binary analysed>

### Bugs encountered
<!-- Describe: command used, error message / unexpected output, expected behaviour -->

### Missing features
<!-- Describe what you needed but couldn't do with the current command set -->

### Suggestions
<!-- Any UX improvements or new commands that would have helped -->
EOF

Then inform the user:

"I saved a ghidra-rpc issue report to /tmp/ghidra-rpc-issues-<timestamp>.md.

If you'd like to submit it, run: cat /tmp/ghidra-rpc-issues-*.md"

The report is written to /tmp so it stays local to the machine and is lost on reboot - it is never sent anywhere automatically.

Further Documentation

For detailed guidance on specific workflows:

• •Installation & setup: read docs/install.md
• •Quick start tutorial: read docs/quickstart.md
• •Troubleshooting: read docs/troubleshooting.md
• •Binary audit workflow: read docs/flows/binary-audit.md
• •Multi-binary analysis: read docs/flows/multi-binary.md
• •Vulnerability research: read docs/flows/vulnerability-research.md
• •Patch/diff analysis: read docs/flows/patch-analysis.md