Skip to content
Back to search

ghidra-rpc

SkillWorks with Claude CodeGitHub

Reverse engineering assistant powered by Ghidra. Use for binary analysis, decompilation, vulnerability research, auditing compiled code, renaming symbols, annotating disassembly, cross-references, or any RE task - even without explicit mention of Ghidra.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/cellebrite-labs--ghidra-rpc/badge.svg)](/listings/cellebrite-labs--ghidra-rpc)

HTML

<a href="/listings/cellebrite-labs--ghidra-rpc"><img src="/api/listings/cellebrite-labs--ghidra-rpc/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

# Prerequisites: Ghidra 11+, Python 3.11+, Java 17+, uv
export GHIDRA_INSTALL_DIR=/opt/ghidra_12.0
uv tool install /path/to/ghidra-rpc

Once installed, tell your AI assistant to start a session:

> *"Load /usr/bin/ls into Ghidra and find any unsafe string operations."*

For manual use or debugging:

# Start the daemon (use --detach for background)
ghidra-rpc start --project /tmp/work.gpr --headless

export GHIDRA_RPC_PROJECT=/tmp/work.gpr
ghidra-rpc load /usr/bin/ls
ghidra-rpc decompile ls main
ghidra-rpc xrefs-to ls strcmp
ghidra-rpc rename-function ls FUN_00401234 parse_args

To see all running daemon instances and attach to an existing one:

ghidra-rpc list-instances
# {"ok": true, "result": {"instances": [{"project": "/tmp/work.gpr", "mode": "headless", "pid": 84712, ...}], "count": 1}}

export GHIDRA_RPC_PROJECT=/tmp/work.gpr
ghidra-rpc list-binaries   # attach to the existing session

See [docs/install.md](docs/install.md) for prerequisites and [docs/quickstart.md](docs/quickstart.md) for a full walkthrough.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

SKILL.md · Manifest · 614 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. ---
  2. name: ghidra-rpc
  3. description: >
  4. Reverse engineering assistant powered by Ghidra. Use for binary analysis,
  5. decompilation, vulnerability research, auditing compiled code, renaming symbols,
  6. annotating disassembly, cross-references, or any RE task - even without explicit
  7. mention of Ghidra.
  8. ---
  9. # Ghidra RPC
  10. A CLI daemon that exposes Ghidra reverse engineering capabilities over a local socket
  11. (a Unix domain socket; token-authenticated loopback TCP on Windows).
  12. You interact with it by running `ghidra-rpc` commands via the bash tool - every command
  13. outputs JSON to stdout.
  14. ## Running Commands
  15. **All `ghidra-rpc` commands must be run with `uv run` from the ghidra-rpc skill directory
  16. (the directory containing this SKILL.md file):**
  17. ```bash
  18. cd <skill-dir> && uv run ghidra-rpc <command> ...
  19. ```
  20. ## Prerequisites Check
  21. Before using any commands, verify the setup:
  22. 1. **Is the daemon running?** Run `uv run ghidra-rpc status --project <path>`. If not running,
  23. the user needs to start it in a separate terminal: `uv run ghidra-rpc start --project /path/to/project.gpr`
  24. (blocking, human-only). The `--headless` flag skips the GUI. For non-blocking / automated
  25. startup use `start --detach --headless` or `restart --headless`. Both accept
  26. `--timeout SECS` (seconds to wait for the daemon to respond; for `start` it only applies
  27. with `--detach`; default: 60 s headless, 180 s GUI) and log daemon output to
  28. `/tmp/ghidra-rpc-<hash>.log` (`%LOCALAPPDATA%\ghidra-rpc\ghidra-rpc-<hash>.log`
  29. on Windows).
  30. 2. **GUI mode: verify the correct project is active.** The daemon passes the `--project` path
  31. directly to GhidraRun so Ghidra opens the requested project immediately. After
  32. `start --detach` (GUI mode), confirm the right project is loaded before issuing any
  33. analysis commands:
  34. ```bash
  35. uv run ghidra-rpc list-project-programs --project /path/to/project.gpr
  36. ```
  37. Cross-check the returned binary names against what you expect. If the names don't match
  38. (or a `warning` field appears in the response), stop and ask the user to open the correct
  39. project in Ghidra's Project window before proceeding.
  40. 3. **GUI mode: programs outside the project's root folder must be open in CodeBrowser.**
  41. The daemon sees programs open in any running tool plus every program in the project's
  42. root folder (which is where `load` puts them). A program in a project subfolder that
  43. isn't open in CodeBrowser is invisible and commands fail with "Binary not found"; use
  44. `list-project-programs` to see what's stored, then double-click it in Ghidra's Project
  45. window.
  46. 4. **Is `GHIDRA_INSTALL_DIR` set?** The daemon will fail loudly if this is missing.
  47. Once the daemon is running, all commands below work automatically. If the daemon dies,
  48. commands will attempt auto-restart from the saved session. A clean `stop` deletes that
  49. session, so after it you need `start` (or `restart --headless`) again.
  50. ## Command Reference
  51. Every command except `list-instances` and `stop --all` accepts `--project <path>` (or reads
  52. `GHIDRA_RPC_PROJECT`).
  53. All output is JSON. Exit code 0 = success, nonzero = error.
  54. Examples below omit the `cd <skill-dir> && uv run` prefix.
  55. ### Project Management
  56. | Command | Description | Example |
  57. |---------|-------------|---------|
  58. | `ghidra-rpc start --project <gpr> [--headless] [--detach] [--ghidra-install-dir DIR]` | Start daemon (blocking by default; `--detach` backgrounds it) | `ghidra-rpc start -p /tmp/re.gpr --headless --detach` |
  59. | `ghidra-rpc stop --project <gpr>` | Stop the daemon (returns once it has saved and shut down) | `ghidra-rpc stop -p /tmp/re.gpr` |
  60. | `ghidra-rpc status --project <gpr>` | Check if daemon is running | `ghidra-rpc status -p /tmp/re.gpr` |
  61. | `ghidra-rpc list-instances [--all]` | List running daemons and their projects (`--all` also lists registered-but-dead ones); use it to find the `--project` of a daemon that is already up | `ghidra-rpc list-instances` |
  62. | `ghidra-rpc stop --all` | Stop every running daemon | `ghidra-rpc stop --all` |
  63. | `ghidra-rpc restart --project <gpr> [--headless] [--timeout SECS] [--ghidra-install-dir DIR]` | Restart daemon in background (`--headless` to override mode) | `ghidra-rpc restart -p /tmp/re.gpr --headless` |
  64. | `ghidra-rpc list-binaries --project <gpr>` | List binaries loaded in daemon | `ghidra-rpc list-binaries -p /tmp/re.gpr` |
  65. | `ghidra-rpc list-project-programs --project <gpr>` | List all programs stored in the project repo (reads project folder, not CodeBrowser live state; returns `warning` if the active Ghidra project doesn't match) | `ghidra-rpc list-project-programs -p /tmp/re.gpr` |
  66. | `ghidra-rpc save [binary] --project <gpr>` | Save program(s) to disk (auto-save also runs after every write) | `ghidra-rpc save -p /tmp/re.gpr` |
  67. `status` output: `{running, socket, mode, mode_source, project, binaries}`. `binaries` is the
  68. loaded-binary list when the daemon is running, `null` when stopped (one-shot health check
  69. without a second `list-binaries` call). `mode_source` is `"running"` when the daemon is live,
  70. `"session"` when the mode is from the saved session only (daemon died without a clean
  71. `stop`), and `null` if no session exists (never started, or cleanly stopped).
  72. `list-instances` output: `{instances: [{running, socket, project, mode, pid}], count}`.
  73. ### Loading & Analysis
  74. | Command | Description | Example |
  75. |---------|-------------|---------|
  76. | `ghidra-rpc load <path> -p <gpr> [--no-analyze] [--analysis-timeout SECS]` | Import & analyze a binary | `ghidra-rpc load /usr/bin/target -p /tmp/re.gpr` |
  77. | `ghidra-rpc metadata <binary> -p <gpr>` | Binary metadata (arch, bits, format) | `ghidra-rpc metadata target -p /tmp/re.gpr` |
  78. `load` flags:
  79. - `--no-analyze` - skip auto-analysis entirely (fast; useful when you only need the
  80. listing or plan to run analysis later via Ghidra GUI).
  81. - `--analysis-timeout SECS` - abort auto-analysis after the given wall-clock budget
  82. (best-effort); the binary is saved with whatever analysis completed in time.
  83. Either way the CLI waits for the whole load (import, analysis, save) to finish — on large
  84. binaries, pass it or run `load` in the background so your shell doesn't block.
  85. ### Listing
  86. | Command | Description | Output shape |
  87. |---------|-------------|--------------|
  88. | `ghidra-rpc functions <binary> [--offset N] [--limit N] [--address-min ADDR] [--address-max ADDR] [--with-body]` | List functions (paginated); `--address-min/max` for server-side range filter; `--with-body` adds body range fields | `{functions: [{name, address, signature[, body_min, body_max, body_size]}], count, total, offset}` |
  89. | `ghidra-rpc imports <binary>` | List imports | `{imports: [{name, address, library}], count}` |
  90. | `ghidra-rpc exports <binary>` | List exports | `{exports: [{name, address}], count}` |
  91. | `ghidra-rpc relocations <binary> [--address ADDR] [--limit N]` | List relocation table entries | `{relocations: [{address, type, symbol, bytes, status}], count, total}` |
  92. | `ghidra-rpc list-calling-conventions <binary>` | List valid calling convention names for the architecture | `{conventions: [str], default, count}` |
  93. ### Decompilation
  94. | Command | Description | Output shape |
  95. |---------|-------------|--------------|
  96. | `ghidra-rpc decompile <binary> <func> [--timeout SECS]` | Decompile to pseudo-C (default **120 s**) | `{name, address, signature, c_code}` |
  97. | `ghidra-rpc basic-blocks <binary> <func> [--limit N]` | Get basic blocks (CFG) of a function | `{name, address, blocks:[{start,end,size,instructions,successors,predecessors}], num_blocks, edges}` |
  98. | `ghidra-rpc pcode <binary> <func> [--high] [--timeout SECS] [--limit N]` | Get P-code (Ghidra IR); raw or high SSA form (--high) | `{name, address, mode, ops:[{address,seq,opcode,output,inputs}], count, truncated}` |
  99. | `ghidra-rpc search-decompiled <binary> <regex> [--class NAME] [--case-sensitive] [--limit N] [--max-scan N] [--address-min ADDR] [--address-max ADDR] [--timeout SECS] [--socket-timeout SECS]` | Regex-search decompiled C across many functions in one call (skips one-RPC-per-function `decompile`+grep loops) | `{matches:[{function,address,matching_lines:[{line,text}]}], count, functions_searched, functions_total, truncated, scanned_range:{min,max}, next_unscanned_address}` |
  100. `<func>` can be a function name or hex address (e.g., `main` or `0x401000`). If the name
  101. is ambiguous, the error message lists matches so you can use the address instead.
  102. **Addresses.** Every address in command output is `0x`-prefixed (`0x00101139`;
  103. non-default spaces keep their qualifier: `EXTERNAL:0x00000001`, overlays `ov1::0x00001000`;
  104. stack offsets stay `Stack[-0x10]`). Pass them back verbatim. Only `0x`-prefixed input is
  105. treated as an address — bare hex like `00101139` is a name query and will not match
  106. auto-named `FUN_00101139`.
  107. `search-decompiled` is especially useful on multidex Android projects, where `xrefs-to`
  108. on a method only sees callers within the same DEX program (see the Android APK/DEX
  109. section) — use it in place of a symbols+decompile+grep loop, e.g.
  110. `search-decompiled app.apk targetF1 --class com::example::Foo`. `--max-scan` (default 5000)
  111. caps how many functions get decompiled per call, so a search on a 50k+-function binary can't
  112. run away; raise `--socket-timeout` (default 1800s) alongside it if you do widen the scan.
  113. **Check coverage before concluding "no matches".** `truncated: true` means only
  114. `scanned_range` was searched, not the whole binary. Resume with
  115. `--address-min <next_unscanned_address>` (keeping the same `--address-max`, if any)
  116. until `next_unscanned_address` is `null`.
  117. ### Search
  118. | Command | Description | Output shape |
  119. |---------|-------------|--------------|
  120. | `ghidra-rpc find-bytes <binary> <pattern> [--limit N] [--address ADDR]` | Search for byte pattern with wildcards (e.g. `"55 8b ?? 83 ec"`) | `{pattern, matches: [{address, context_hex}], count, truncated}` |
  121. | `ghidra-rpc strings <binary> [query] [--limit N]` | Search strings (substring; omit the query to list all) | `{strings: [{address, value, type}], count}` |
  122. | `ghidra-rpc symbols <binary> <query> [--limit N] [--offset N]` | Search symbols | `{symbols: [{name, address, type}], count, total}` |
  123. `symbols` normalizes literal spaces and underscores as equivalent before matching, so a
  124. query pasted straight from `strings` output (real spaces) still finds the corresponding
  125. label even though Ghidra auto-generates labels from string content by turning each space
  126. into `_` (and leaving every other character, including non-ASCII/CJK text, untouched).
  127. ### Cross-References
  128. | Command | Description | Output shape |
  129. |---------|-------------|--------------|
  130. | `ghidra-rpc xrefs-to <binary> <target> [--limit N] [--all-binaries]` | Who references this? | `{xrefs: [{from_address, from_function, type}], count}` |
  131. | `ghidra-rpc xrefs-from <binary> <target> [--limit N] [--no-stack]` | What does this reference? A function (name or entry address) scans its whole body; any other address or label lists only its own references. `--no-stack` hides `Stack[-0x...]` entries | `{xrefs: [{to_address, to_function, type}], count}` |
  132. Ghidra's reference manager is per-binary: a call whose caller and target live in two
  133. *different* loaded binaries is invisible to a single-binary `xrefs-to` lookup (most
  134. commonly hit on multidex Android projects, where a method in one `classesN.dex` is
  135. called from another, but this isn't DEX-specific — it applies to any project with more
  136. than one binary loaded in the daemon). Pass `--all-binaries` to also search every other
  137. currently loaded binary for a symbol with the same fully-qualified name and merge in
  138. real callers found there; each merged entry carries a `binary` field so you can tell
  139. which binary it came from.
  140. ### Navigation (GUI mode only)
  141. | Command | Description | Output shape |
  142. |---------|-------------|--------------|
  143. | `ghidra-rpc goto <binary> <target> [function\|address]` | Navigate GUI | `{address, success}` |
  144. ### Memory & Disassembly
  145. | Command | Description | Output shape |
  146. |---------|-------------|--------------|
  147. | `ghidra-rpc memory-map <binary>` | List all memory segments (name, address range, size, rwx flags, type) | `{segments: [{name, start, end, size, read, write, execute, initialized, type, source_name}], count}` |
  148. | `ghidra-rpc write-bytes <binary> <address> <hex>` | Write raw bytes (max 4096) to an address. Fails over a disassembled instruction — `clear-data-range` it first, then `assemble` to rebuild the instruction (`disassemble` only reads); data bytes write directly | `{address, length, hex, verified}` |
  149. | `ghidra-rpc read-bytes <binary> <address> <length>` | Read raw bytes; LENGTH accepts decimal or `0x` hex | `{address, length, hex, hexdump}` |
  150. | `ghidra-rpc read-pointers <binary> <address> <count> [--pointer-size N]` | Read COUNT pointers and resolve each to its symbol (vtables, import/jump tables, RTTI arrays) | `{address, count, pointer_size, endian, pointers:[{index, offset, slot_address, value, target_address, target_name, target_kind}]}` |
  151. | `ghidra-rpc list-vtable <binary> <address> [--count N] [--pointer-size N]` | Dump a C++ vtable's slots as resolved methods; ADDRESS may be a symbol name. Without `--count`, stops at the next vftable symbol / first non-function pointer (see `stopped_reason`) | `{vtable_address, symbol, count, pointer_size, stopped_reason, slots:[{index, offset, slot_address, target_address, target_name, target_kind}]}` |
  152. | `ghidra-rpc disassemble <binary> <address> [--count N] [--with-instructions]` | Disassemble N instructions (default 20); returns `listing` text, which already carries address/bytes/mnemonic/operands/comment — pass `--with-instructions` only when you need the machine-parseable array (~4× the output); `warning` field if start address had no instruction | `{address, count, listing[, instructions][, warning]}` |
  153. | `ghidra-rpc assemble <binary> <address> <instr> [<instr> ...]` | Assemble instruction text at address (Ghidra SLEIGH assembler) | `{address, bytes_written, hex, instructions:[{address,bytes,mnemonic,operands,length}]}` |
  154. ### Modifications
  155. | Command | Description | Output shape |
  156. |---------|-------------|--------------|
  157. | `ghidra-rpc create-function <binary> <address> [--name NAME]` | Create a function at an address (auto-detects body from flow) | `{name, address, size, body}` |
  158. | `ghidra-rpc delete-function <binary> <target>` | Remove a function definition (bytes unchanged; address reverts to undefined) | `{address, name, deleted}` |
  159. | `ghidra-rpc rename-function <binary> <target> <new_name> [--namespace NS]` | Rename function; `--namespace` moves it into a namespace | `{address, old_name, new_name, verified[, old_namespace, new_namespace]}` |
  160. | `ghidra-rpc rename-symbol <binary> <address> <new_name> [--create]` | Rename symbol; `--create` makes a new label if none exists | `{address, old_name, new_name, created, verified}` |
  161. | `ghidra-rpc create-label <binary> <address> <name>` | Create-or-rename a label at any address (upsert) | `{address, name, old_name, action, created, verified}` |
  162. | `ghidra-rpc set-comment <binary> <address> --comment <text> [--type TYPE]` | Set comment at a `0x` address, or at a function or label given by name (comment text is `--comment`, matching `set-bookmark`) | `{address, comment_type, comment, verified}` |
  163. | `ghidra-rpc batch-rename <binary> --json \|--json-file FILE [--mode function\|label]` | Rename 40+ functions/labels in one transaction; per-item error reporting | `{results:[{ok, index, address, old_name, new_name}], count, ok_count, error_count}` |
  164. | `ghidra-rpc batch-set-comment <binary> --json \|--json-file FILE` | Set comments at many addresses in one transaction | `{results:[{ok, index, address, comment_type, comment}], count, ok_count, error_count}` |
  165. | `ghidra-rpc set-signature <binary> <target> <signature>` | Set function signature | `{address, old_signature, new_signature, verified}` |
  166. | `ghidra-rpc set-data-type <binary> <address> <type>` | Define data type in listing | `{address, data_type, length, value}` |
  167. | `ghidra-rpc retype-variable <binary> <func> <variable> <type> [--timeout SECS]` | Retype decompiler variable | `{function, variable, old_type, new_type, verified}` |
  168. | `ghidra-rpc rename-variable <binary> <func> <variable> <new_name> [--timeout SECS]` | Rename decompiler variable | `{function, variable, new_name, verified}` |
  169. | `ghidra-rpc batch-edit-variable <binary> <func> --json \|--json-file FILE [--timeout SECS]` | Rename and/or retype many locals in ONE decompiler snapshot — avoids the auto-name renumbering that breaks chained single edits. Each op: `{variable\|storage, new_name?, data_type?}` (identify by name or storage string; at least one of new_name/data_type) | `{function, results:[{ok, index, variable, storage, old_name, new_name, old_type, new_type, verified}], count, ok_count, error_count, verified_count}` |
  170. | `ghidra-rpc set-calling-convention <binary> <target> <convention>` | Change a function's calling convention | `{address, name, old_convention, new_convention, verified}` |
  171. | `ghidra-rpc set-thunk <binary> <thunk> <target>` | Mark a function as a thunk (forwarding wrapper) | `{thunk_address, thunk_name, target_address, target_name, verified}` |
  172. | `ghidra-rpc set-flow-override <binary> <address> <override>` | Override instruction flow type (NONE/BRANCH/CALL/CALL_RETURN/RETURN) | `{address, override, old_override, verified}` |
  173. | `ghidra-rpc get-processor-context <binary> <address> [--register REG]` | Inspect ISA context register values (e.g. TMode on ARM) | `{address, registers:{name:value}}` |
  174. | `ghidra-rpc set-processor-context <binary> <address> <register> <value> [--end ADDR]` | Set ISA context register over a range — fixes ARM Thumb mis-classification | `{address, end, register, value, verified}` |
  175. | `ghidra-rpc create-namespace <binary> <name> [--parent NS]` | Create or look up a namespace | `{name, path, id, created}` |
  176. | `ghidra-rpc list-namespaces <binary> [--limit N]` | List all namespaces with symbol counts | `{namespaces:[{name,path,id,type,symbol_count}], count}` |
  177. Comment types: `plate`, `pre`, `post`, `eol` (default), `repeatable`.
  178. Signature input is sanitised automatically: trailing semicolons are stripped,
  179. whitespace is trimmed, and inline calling conventions (`__thiscall`, `__fastcall`,
  180. `__stdcall`, `__cdecl`, `__vectorcall`, `__pascal`) are extracted from the string
  181. and applied via the proper Ghidra API. So you can paste a C prototype directly
  182. (e.g. `void __thiscall Foo::Bar(int x);` works without manual cleanup).
  183. Type expressions for `set-data-type`, `retype-variable`, and struct field types:
  184. - Built-ins: `byte`, `char`, `int`, `uint`, `short`, `long`, `float`, `double`, `void`, `string`, `unicode`
  185. - Pointer: `char *`, `void *`, `int **`
  186. - Array: `char[11]`, `int[4]`
  187. - Any type in the program's data type manager by name or path: `MyStruct`, `/POSIX/size_t`
  188. **Order of operations — set signatures/types before naming locals.** Each of
  189. `set-signature`, `set-data-type`, `retype-variable`, and `rename-variable` re-runs the
  190. decompiler, which re-numbers the remaining auto-named locals (`uVar1`, `dVar2`, …). So
  191. chaining single-variable edits is fragile: after renaming `dVar1`, the old `dVar2` may
  192. now be `dVar1`. Do all signature/`this`-typing first, then name locals — or, better, use
  193. `batch-edit-variable` to apply every rename **and** retype against a single decompiler
  194. snapshot in one call (it also lets you address a variable by its stable `storage` string
  195. instead of the volatile auto name).
  196. ### Bookmarks
  197. | Command | Description | Output shape |
  198. |---------|-------------|--------------|
  199. | `ghidra-rpc set-bookmark <binary> <address> [--type TYPE] [--category CAT] [--comment TEXT]` | Create/update a bookmark at an address | `{address, type, category, comment, action}` |
  200. | `ghidra-rpc list-bookmarks <binary> [--type TYPE] [--category CAT] [--address ADDR] [--limit N]` | List bookmarks (all, by type, category, or at address) | `{bookmarks: [{address, type, category, comment}], count, total}` |
  201. | `ghidra-rpc remove-bookmark <binary> <address> [--type TYPE] [--category CAT]` | Remove a bookmark at an address | `{address, type, removed}` |
  202. Bookmark types: `Note` (default), `Warning`, `Error`, `Info`, `Analysis`.
  203. `--category` is a case-insensitive substring filter. On heavily auto-analyzed binaries
  204. (large native programs, and especially DEX/Dalvik — 50k+ functions is normal), Ghidra
  205. generates many `Analysis`-type bookmarks (commonly category `Address Table`) that can
  206. bury a handful of your own; filter them out with `--category` (or `--type` to isolate
  207. your own type, e.g. `Note`) instead of paging through the unfiltered list.
  208. Bookmarks are visible in the Ghidra GUI's Bookmarks window. Use them to
  209. persistently mark interesting locations, track analysis progress, or flag
  210. findings for human review.
  211. ### Function Tags
  212. | Command | Description | Output shape |
  213. |---------|-------------|--------------|
  214. | `ghidra-rpc tag-function <binary> <target> --tag TAG` | Add a tag to a function for classification | `{address, name, tag, all_tags}` |
  215. | `ghidra-rpc untag-function <binary> <target> --tag TAG` | Remove a tag from a function | `{address, name, tag, removed, all_tags}` |
  216. | `ghidra-rpc list-tags <binary>` | List all defined tags with use counts | `{tags:[{name,count}], count}` |
  217. | `ghidra-rpc functions-by-tag <binary> --tag TAG [--limit N]` | List functions with a specific tag | `{tag, functions:[{name,address,signature}], count, total}` |
  218. Tags are string labels (e.g. `crypto`, `vuln-sink`, `analyzed`, `needs-review`)
  219. visible in Ghidra's Function Tags window. Use them to classify functions
  220. and track analysis progress.
  221. ### Data-Type Authoring
  222. | Command | Description | Output shape |
  223. |---------|-------------|--------------|
  224. | `ghidra-rpc create-struct <binary> <name> TYPE FIELD [TYPE FIELD ...] [--if-not-exists\|--or-replace]` | Create a named struct; `--if-not-exists` is idempotent, `--or-replace` rebuilds it (if the new definition fails, the old one is kept) | `{name, path, size, fields:[...], already_existed}` |
  225. | `ghidra-rpc create-struct <binary> <name> --field OFFSET TYPE NAME [--field ...]` | Create a struct laying fields at explicit byte offsets (OFFSET is decimal or 0x hex); gaps between fields are auto-padded with undefined bytes (no manual pad fields). Overlaps are rejected. | `{name, path, size, fields:[...], already_existed}` |
  226. | `ghidra-rpc create-union <binary> <name> TYPE FIELD [TYPE FIELD ...] [--if-not-exists\|--or-replace]` | Create a named union; all fields share offset 0 | `{name, path, size, fields:[...], already_existed}` |
  227. | `ghidra-rpc modify-struct <binary> <struct_name> --field-offset N\|--field-name NAME [--new-type TYPE] [--new-name NAME] [--new-comment TEXT]` | Retype, rename, or re-comment a struct field (`--field-offset` is decimal) | `{name, path, size, fields:[...], modified_field:{...}}` |
  228. | `ghidra-rpc clear-data-range <binary> <start> <end>` | Reset inclusive byte range to undefined | `{start, end, cleared}` |
  229. | `ghidra-rpc apply-data-type-range <binary> <start> <end> <type> [--clear]` | Stamp a type repeatedly across an inclusive range; `--clear` clears the region atomically before stamping | `{start, end, data_type, type_size, applied_count, cleared}` |
  230. | `ghidra-rpc list-labels <binary> <address> [--end ADDR] [--limit N]` | List symbols at an address or in a range, including data type at each location | `{labels:[{address,name,type,source,is_primary,data_type,data_length}], count, total}` |
  231. | `ghidra-rpc create-enum <binary> <name> NAME VAL [NAME VAL ...] [--size 1\|2\|4\|8] [--if-not-exists\|--or-replace]` | Create a named enum in the DTM | `{name, path, size, values:[{name,value}], already_existed}` |
  232. | `ghidra-rpc modify-enum <binary> <name> [--add NAME:VAL ...] [--remove NAME ...]` | Add/remove individual entries from an existing enum | `{name, path, size, values:[{name,value}]}` |
  233. | `ghidra-rpc set-equate <binary> <addr> <equate_name> <value> [--operand-index N] [--enum-path PATH]` | Attach a named scalar constant to an instruction operand; auto-links to enum if found | `{address, operand_index, equate_name, value, enum_linked, verified}` |
  234. | `ghidra-rpc list-equates <binary> [address] [--limit N]` | List all equates in the program or only those applied at an address | `{equates:[{name,value[,operand_index,address]}], count, total}` |
  235. | `ghidra-rpc list-data-types <binary> [--category CAT] [--query SUBSTR] [--limit N]` | List types in the DTM; category: struct, enum, union, typedef, pointer, array, other, all | `{data_types:[{name,path,category,size}], count, total}` |
  236. ### Version Tracking & Diff
  237. | Command | Description | Output shape |
  238. |---------|-------------|--------------|
  239. | `ghidra-rpc version-track <old> <new> [--changed-only] [--limit N] [--min-similarity F] [--include-data] [--socket-timeout SECS]` | Match functions between two versions; find what changed. Results deduplicated per source function. | `{matched:[{source_name,destination_name,similarity,confidence,correlator}], unmatched_source, unmatched_destination, summary:{source_functions_total, changed_functions, identical_functions, ...}}` |
  240. | `ghidra-rpc function-diff <bin1> <func1> <bin2> <func2> [--mode decompile\|disassembly] [--timeout SECS]` | Unified diff of a function between two versions; normalises auto-generated names (`FUN_*`, `DAT_*`, `local_*`, `param_*`) to suppress relocation noise | `{is_identical, diff, raw_code1, raw_code2, func1_address, func2_address}` |
  241. | `ghidra-rpc match-function <bin1> <func> <bin2> [--threshold F] [--socket-timeout SECS]` | Find best match for a function in another binary using BSim + correlators | `{source:{name,address}, candidates:[{name,address,similarity,confidence,correlator}], count}` |
  242. | `ghidra-rpc decompile-all <binary> [--limit N] [--offset N] [--timeout SECS] [--socket-timeout SECS]` | Bulk decompile all functions; for export and external diff tools | `{functions:[{name,address,signature,c_code}], count, total, offset, errors}` |
  243. `decompile-all`'s default `--socket-timeout` (1800s) assumes a bulk sweep can take much
  244. longer than any single function's `--timeout`; raise it further for binaries with tens of
  245. thousands of functions (e.g. large DEX/APK programs).
  246. `version-track` and `match-function` are headless-only and need two different loaded
  247. binaries; their `--socket-timeout` defaults to 1800s.
  248. For the full patch-diff workflow see `docs/flows/patch-analysis.md`.
  249. ## Error Handling
  250. Error responses look like:
  251. ```json
  252. {"id": "...", "ok": false, "error": "ValueError", "message": "Function 'foo' not found. ..."}
  253. ```
  254. Common errors:
  255. - **DaemonNotRunning**: Daemon isn't started. Tell the user to run `ghidra-rpc start`.
  256. - **ValueError**: Bad argument (ambiguous name, invalid address). The message usually tells
  257. you what to do - e.g., use a more specific name or an address.
  258. - **RuntimeError**: Ghidra-level error. For GUI-only commands in headless mode, the error
  259. says so explicitly.
  260. **All CLI output is JSON, including usage errors.** A malformed invocation (unknown
  261. option, invalid `--type` choice, unknown subcommand, missing required argument) is also
  262. reported as `{"ok": false, "error": "...", "message": "..."}` on stdout, with a nonzero
  263. exit code — never a plain-text Click usage string. Scripted callers can always
  264. `json.loads()` stdout unconditionally, without special-casing argument errors.
  265. ## Write Operations & Persistence
  266. Write operations (rename-function, rename-symbol, create-label, create-function, delete-function, set-comment, batch-rename, batch-set-comment, set-signature, set-data-type, retype-variable, rename-variable, batch-edit-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, remove-bookmark, clear-data-range, apply-data-type-range, write-bytes, assemble, tag-function, untag-function, create-namespace)
  267. use Ghidra transactions internally. **Every write is automatically saved to the project
  268. database on disk** after the transaction commits, so changes survive daemon restarts and
  269. are visible when the project is reopened in the Ghidra GUI.
  270. Most single-item edits (`rename-function`, `rename-symbol`, `create-label`, `set-comment`,
  271. `set-signature`, `retype-variable`, `rename-variable`, `set-calling-convention`, `set-thunk`,
  272. `set-flow-override`, `set-equate`, `set-processor-context`, `write-bytes`, and each
  273. `batch-edit-variable` result) include a `verified` boolean that confirms the change was read
  274. back after committing. `verified: false` also prints a warning on stderr.
  275. You can also save explicitly at any time:
  276. ```bash
  277. ghidra-rpc save # saves all loaded programs
  278. ghidra-rpc save <binary> # saves one program
  279. ```
  280. On clean shutdown (`stop` or Ctrl+C), all programs are saved automatically.
  281. ## Patch / Diff Analysis Quick Start
  282. ```bash
  283. # 1. Load both versions
  284. ghidra-rpc load /path/to/binary_v1 -p project.gpr
  285. ghidra-rpc load /path/to/binary_v2 -p project.gpr
  286. # 2. Find changed functions (summary counts all changes; matched list is filtered)
  287. ghidra-rpc version-track binary_v1 binary_v2 --changed-only
  288. # 3. Diff a specific changed function
  289. ghidra-rpc function-diff binary_v1 <func> binary_v2 <func>
  290. ```
  291. Full workflow — correlator details, unmatched analysis, bulk decompile:
  292. read `docs/flows/patch-analysis.md`.
  293. ## Android APK / DEX Analysis
  294. Ghidra has **built-in** APK and DEX support (Dalvik processor + FileFormats
  295. loaders) — no extension install needed. `load` a `.dex` or `.apk` directly and
  296. the usual commands (`decompile`, `functions`, `strings`, `xrefs-*`, …) work on
  297. the Dalvik program, which decompiles to Java-like pseudocode. Note the
  298. **multi-dex caveat**: `load app.apk` imports only the primary `classes.dex`.
  299. For the full workflow — multi-dex extraction, class-qualified `::` symbols and
  300. ambiguous methods, the DEX string-vs-`xrefs-to` gotcha, minified apps, and
  301. manifest/`.so` extraction — read `docs/flows/android-apk.md`.
  302. ## Typical Workflow
  303. 1. User starts daemon: `cd <skill-dir> && uv run ghidra-rpc start --project /path/to/project.gpr --headless`
  304. For automation / non-blocking start: `uv run ghidra-rpc start --project /path/to/project.gpr --headless --detach`
  305. 2. Load binary: `uv run ghidra-rpc load /path/to/binary -p /path/to/project.gpr`
  306. Response includes `short_name` (usable alias in all subsequent commands).
  307. (add `--no-analyze` to skip analysis, `--analysis-timeout SECS` to cap it)
  308. 3. Get overview: `metadata`, `functions`, `imports`, `exports`
  309. 4. Investigate: `decompile` interesting functions, `xrefs-to` to trace callers
  310. 5. Annotate: `rename-function`, `set-comment` to document findings
  311. 6. Search: `strings` for hardcoded values, `symbols` for specific patterns
  312. ## FAQ / Common Gotchas
  313. **`create-label` properly replaces DEFAULT (auto-analysis) symbols**:
  314. `create-label` creates a USER_DEFINED label and sets it as the primary symbol at the
  315. address. If a DEFAULT symbol (e.g. `DAT_00418138`) already exists, it is demoted to
  316. secondary. The decompiler will then use the new name. `rename-symbol` renames in
  317. place but requires an existing symbol; `create-label` is preferred for annotating
  318. addresses regardless of existing symbols.
  319. **Annotating an address with no existing symbol** (`rename-symbol` fails with "No symbol found"):
  320. `rename-symbol` requires a symbol to already exist at the address. Auto-analysis only
  321. places `DAT_` symbols where it detects data; inside arrays or dense struct regions
  322. many addresses have no symbol. Use `create-label` instead - it creates a new USER_DEFINED
  323. label if none exists, or renames the existing one:
  324. ```bash
  325. ghidra-rpc create-label <binary> 0x0040e4ac topPtrErrorMsg
  326. ```
  327. You can also add `--create` to `rename-symbol` for the same upsert behaviour.
  328. **Defining and applying a struct across a memory region**:
  329. Full workflow to stamp a struct across a repeated data table:
  330. ```bash
  331. # 1. Create the struct type in the DTM (--if-not-exists makes the call idempotent)
  332. ghidra-rpc create-struct binary ErrorEntry int errorNumber "char *" ptrErrorMsg --if-not-exists
  333. # 2. Stamp the struct across the range with --clear to atomically clear + apply
  334. # (23 × 8-byte ErrorEntry structs, both endpoints inclusive)
  335. ghidra-rpc apply-data-type-range binary 0x0040e4a8 0x0040e55f ErrorEntry --clear
  336. ```
  337. After this, each address `0x0040e4a8`, `0x0040e4b0`, ... has type `ErrorEntry`.
  338. Without `--clear`, `apply-data-type-range` skips positions where existing data
  339. conflicts and reports them in the `errors` list. Use `clear-data-range` first if
  340. you need finer control over which region is cleared.
  341. **Discovering what labels exist at an address or range**:
  342. ```bash
  343. # Single address
  344. ghidra-rpc list-labels binary 0x0040e4a8
  345. # Range
  346. ghidra-rpc list-labels binary 0x0040e4a8 --end 0x0040e55f --limit 50
  347. ```
  348. **Using the binary name after `load`**:
  349. `load` returns both a full key (`binary`) with a hash suffix and a `short_name`
  350. (the original filename). Use `short_name` in all subsequent commands - it works
  351. because commands match binary names by substring:
  352. ```bash
  353. # Load response: {"binary": "/WinHelloCPP.exe-85cbcc", "short_name": "WinHelloCPP.exe", ...}
  354. ghidra-rpc decompile WinHelloCPP.exe main # short_name works
  355. ghidra-rpc decompile WinHelloCPP main # even without extension, if unambiguous
  356. ```
  357. If two binaries share the same stem, use the full key to disambiguate.
  358. **Trailing semicolons in signatures**: Ghidra's parser rejects C prototypes that end
  359. with `;`. ghidra-rpc strips trailing semicolons automatically, so you can paste verbatim.
  360. **`list-binaries` is missing a program in GUI mode**: The daemon sees programs open in a
  361. running tool plus those in the project's root folder. For a program in a subfolder, use
  362. `list-project-programs` to find it, then open it in CodeBrowser from the Project window.
  363. **Daemon log file**: When started in the background (`start --detach` or `restart`),
  364. logs are written to `/tmp/ghidra-rpc-<hash>.log` — same directory and stem as the
  365. daemon endpoint, so on Windows that is
  366. `%LOCALAPPDATA%\ghidra-rpc\ghidra-rpc-<hash>.log`. If the daemon fails to start or
  367. become responsive, check that file first:
  368. ```bash
  369. tail -50 /tmp/ghidra-rpc-*.log
  370. ```
  371. The timeout error message always prints the exact log path, on every platform.
  372. **`GHIDRA_INSTALL_DIR` not found after backgrounding**: Environment variables may be
  373. lost when daemonising (nohup, cron, systemd units, etc.). Fix options, in order of preference:
  374. 1. Pass `--ghidra-install-dir /path/to/ghidra` to `start` or `restart` - the value is
  375. persisted in the session file and reused by auto-restart and `restart` for as long as
  376. that session exists. A clean `stop` deletes the session, so the next `start` takes the
  377. flag or env var afresh — that is how you switch to a different Ghidra version
  378. (`restart --ghidra-install-dir NEW` also overrides it).
  379. 2. Export `GHIDRA_INSTALL_DIR` in your shell profile (`~/.bashrc`, `~/.zshrc`) so it
  380. survives login sessions.
  381. 3. Use `start --detach --headless` from the same terminal where the env var is set.
  382. **Session file location**: By default the session file (`.ghidra-rpc-<hash>.json`) is
  383. written alongside the `.gpr` project file, keeping all state self-contained. To use a
  384. custom directory (e.g. a shared location or a RAM-disk), set `GHIDRA_RPC_STATE_DIR`:
  385. ```bash
  386. export GHIDRA_RPC_STATE_DIR=/tmp/ghidra-sessions
  387. ```
  388. **Changes not visible in the Ghidra GUI**: Make sure you open the project copy
  389. (e.g. `basic_code-501243` in the Project window), not the raw binary via File → Open.
  390. Also ensure you are not running two separate Ghidra instances on the same project
  391. (causes lock conflicts). Changes made by ghidra-rpc are auto-saved to disk and will
  392. be visible the next time the program is opened in the GUI.
  393. **`restart` without a prior session**: Pass `--headless` so `restart` can create
  394. a fresh headless session instead of requiring a prior `start`.
  395. **Decompiler timeout on certain functions**: Some functions trigger expensive
  396. decompiler analysis paths and time out even with simple assembly. Use
  397. `decompile --timeout 300` (or higher) for stubborn functions. The default timeout
  398. is **120 s**. The
  399. `retype-variable` and `rename-variable` commands also accept `--timeout` since it
  400. triggers an internal decompilation pass.
  401. **`decompile` returns bad-instruction warnings — use `pcode --high` as fallback**:
  402. When `decompile` produces output like *"Bad instruction data"* or fails to decode
  403. a function body (common on ARM Thumb code in regions that auto-analysis
  404. mis-classified as data), try `pcode --high` instead:
  405. ```bash
  406. ghidra-rpc pcode binary 0x03288102 --high
  407. ```
  408. The P-code engine re-decodes bytes from the *function object's* context rather
  409. than from the listing-level disassembler, so it often succeeds where `decompile`
  410. fails. High P-code also reveals all CALL / CALLIND / BRANCHIND targets and data
  411. flow, making it useful for tracing arguments even without valid decompilation.
  412. Fix the root cause with `set-processor-context` (see below).
  413. **`disassemble` starts from the wrong address**:
  414. If `disassemble` is called at an address with no instruction (e.g. an address
  415. that is mid-instruction or undefined), the response includes a `warning`
  416. field explaining that disassembly started from the next available instruction.
  417. Check for `warning` in the JSON response when the listing looks wrong.
  418. **ARM Thumb mis-classification — `set-processor-context` is the fix**:
  419. When ARM auto-analysis classifies Thumb code as data, the listing disassembler
  420. decodes it as 32-bit ARM (TMode=0) and produces garbage. The full recovery
  421. workflow:
  422. ```bash
  423. # 1. Diagnose: check TMode at the affected address
  424. ghidra-rpc get-processor-context binary 0x03288100 --register TMode
  425. # Result: {"address": "0x03288100", "registers": {"TMode": 0}} ← TMode 0 is the problem
  426. # 2. Clear the bad data/code classification
  427. ghidra-rpc clear-data-range binary 0x03288100 0x032883ff
  428. # 3. Set Thumb mode for the range
  429. ghidra-rpc set-processor-context binary 0x03288100 TMode 1 --end 0x032883ff
  430. # 4. Verify disassembly now shows Thumb-2 instructions
  431. ghidra-rpc disassemble binary 0x03288100 --count 20
  432. # 5. Re-create the function
  433. ghidra-rpc create-function binary 0x03288100
  434. ```
  435. If `create-function` fails because a bad stub still exists at the address,
  436. use `delete-function` first to remove it.
  437. **Bad stubs blocking re-creation — use `delete-function`**:
  438. If `create-function 0x03288103` (wrong parity) left a stub, and now
  439. `create-function 0x03288102` (correct address) fails with *"already exists at
  440. overlapping address"*, delete the bad stub first:
  441. ```bash
  442. ghidra-rpc delete-function binary 0x03288103
  443. ghidra-rpc create-function binary 0x03288102
  444. ```
  445. **Batch rename / comment 40+ functions without round-trip overhead**:
  446. Use `batch-rename` and `batch-set-comment` to apply many annotations in a single
  447. server round-trip and Ghidra transaction:
  448. ```bash
  449. # Rename functions from a JSON file
  450. ghidra-rpc batch-rename binary --json-file renames.json
  451. # Or inline
  452. ghidra-rpc batch-rename binary --json \
  453. '[{"target":"sub_401234","new_name":"init_uart"},{"target":"0x400200","new_name":"isr_handler"}]'
  454. # Label-mode (symbol/label rename by address)
  455. ghidra-rpc batch-rename binary --mode label --json \
  456. '[{"address":"0x0333afcc","new_name":"g_debugStr"}]'
  457. # Batch comments
  458. ghidra-rpc batch-set-comment binary --json \
  459. '[{"address":"0x03288102","comment":"Thumb ISR entry","comment_type":"plate"}]'
  460. ```
  461. All items that succeed are committed in one transaction; failed items are
  462. reported per-item in `results[].ok=false` and do not roll back the successes.
  463. **Concurrent write operations are serialised**: The daemon serialises all command
  464. handler invocations internally to prevent Ghidra transaction conflicts. You do
  465. not need to serialize write commands externally — parallel writes are queued
  466. automatically. This is slightly slower than concurrent execution but eliminates
  467. silent partial failures.
  468. ## Reporting Bugs and Missing Features
  469. While using ghidra-rpc you may encounter bugs, errors, or missing capabilities.
  470. **Please report them** - real-world usage drives continuous improvement.
  471. At the end of any analysis session where you hit a problem, save a brief report:
  472. ```bash
  473. cat > /tmp/ghidra-rpc-issues-$(date +%Y%m%d-%H%M%S).md << 'EOF'
  474. ## ghidra-rpc Issue Report
  475. **Binary:** <name of binary analysed>
  476. ### Bugs encountered
  477. <!-- Describe: command used, error message / unexpected output, expected behaviour -->
  478. ### Missing features
  479. <!-- Describe what you needed but couldn't do with the current command set -->
  480. ### Suggestions
  481. <!-- Any UX improvements or new commands that would have helped -->
  482. EOF
  483. ```
  484. Then inform the user:
  485. > "I saved a ghidra-rpc issue report to `/tmp/ghidra-rpc-issues-<timestamp>.md`.
  486. > If you'd like to submit it, run: `cat /tmp/ghidra-rpc-issues-*.md`"
  487. The report is written to `/tmp` so it stays local to the machine and is lost on reboot -
  488. it is never sent anywhere automatically. On Windows write it to `%TEMP%` instead; the
  489. snippet above is bash, so adapt it to the shell you are actually running.
  490. ## Further Documentation
  491. For detailed guidance on specific workflows:
  492. - **Installation & setup**: read `docs/install.md`
  493. - **Quick start tutorial**: read `docs/quickstart.md`
  494. - **Troubleshooting**: read `docs/troubleshooting.md`
  495. - **Binary audit workflow**: read `docs/flows/binary-audit.md`
  496. - **Vulnerability research**: read `docs/flows/vulnerability-research.md`
  497. - **Patch/diff analysis**: read `docs/flows/patch-analysis.md`
  498. - **Android APK / DEX analysis**: read `docs/flows/android-apk.md`
README.md · README · 123 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. # ghidra-rpc
  2. An agentic skill that gives an LLM access to [Ghidra](https://ghidra-sre.org/) so
  3. it can perform reverse engineering tasks autonomously: decompile functions, trace
  4. call graphs, rename and annotate symbols, define data structures, diff binary
  5. versions, and more — all without human intervention.
  6. `ghidra-rpc` runs Ghidra as a persistent background daemon and exposes its
  7. capabilities through a CLI that returns structured JSON. Any AI coding assistant
  8. that can run shell commands (pi, Claude Code, Cursor, etc.) can drive a full RE
  9. session by issuing commands and reasoning over the results.
  10. Developed at **[Cellebrite Labs](https://github.com/cellebrite-labs)**.
  11. ## What the AI Can Do
  12. | Area | Capabilities |
  13. |------|-------------|
  14. | **Understand code** | Decompile functions to pseudo-C, disassemble, inspect CFG and P-code |
  15. | **Navigate** | Trace callers/callees, search strings and byte patterns, find cross-references |
  16. | **Annotate** | Rename functions and symbols, add comments, set bookmarks and tags |
  17. | **Type recovery** | Define structs/unions/enums, retype variables, set function signatures |
  18. | **Patch** | Assemble instructions (SLEIGH), write raw bytes, override flow types |
  19. | **Diff binaries** | Version-track two builds, diff changed functions, match functions via BSim |
  20. ## Quick Start
  21. ```bash
  22. # Prerequisites: Ghidra 11+, Python 3.11+, Java 17+, uv
  23. export GHIDRA_INSTALL_DIR=/opt/ghidra_12.0
  24. uv tool install /path/to/ghidra-rpc
  25. ```
  26. Once installed, tell your AI assistant to start a session:
  27. > *"Load /usr/bin/ls into Ghidra and find any unsafe string operations."*
  28. For manual use or debugging:
  29. ```bash
  30. # Start the daemon (use --detach for background)
  31. ghidra-rpc start --project /tmp/work.gpr --headless
  32. export GHIDRA_RPC_PROJECT=/tmp/work.gpr
  33. ghidra-rpc load /usr/bin/ls
  34. ghidra-rpc decompile ls main
  35. ghidra-rpc xrefs-to ls strcmp
  36. ghidra-rpc rename-function ls FUN_00401234 parse_args
  37. ```
  38. To see all running daemon instances and attach to an existing one:
  39. ```bash
  40. ghidra-rpc list-instances
  41. # {"ok": true, "result": {"instances": [{"project": "/tmp/work.gpr", "mode": "headless", "pid": 84712, ...}], "count": 1}}
  42. export GHIDRA_RPC_PROJECT=/tmp/work.gpr
  43. ghidra-rpc list-binaries # attach to the existing session
  44. ```
  45. See [docs/install.md](docs/install.md) for prerequisites and
  46. [docs/quickstart.md](docs/quickstart.md) for a full walkthrough.
  47. ## How It Works
  48. ```
  49. ┌─────────────┐ Local Transport ┌──────────────────────────┐
  50. │ LLM agent │ ──── JSON/newline ──→ │ ghidra-rpc daemon │
  51. │ (via CLI) │ ←── JSON/newline ─── │ (PyGhidra + Ghidra JVM) │
  52. └─────────────┘ └──────────────────────────┘
  53. ```
  54. The daemon runs Ghidra in-process via
  55. [PyGhidra](https://github.com/NationalSecurityAgency/ghidra/tree/master/Ghidra/Features/PyGhidra).
  56. Ghidra loads the binary once and stays warm between commands — no re-analysis on
  57. every invocation. All changes (renames, comments, type definitions, patches) are
  58. saved to the Ghidra project after every command and remain visible when you open the
  59. project in the Ghidra GUI.
  60. ## Runtime Paths
  61. All paths use an 8-character hash derived from the absolute `.gpr` project path,
  62. so each project gets its own deterministic endpoint and session file with no
  63. collisions.
  64. | Path | Purpose |
  65. |------|---------|
  66. | `/tmp/ghidra-rpc-<hash>.sock` | Unix socket for a running daemon (Linux/macOS) |
  67. | `%LOCALAPPDATA%\ghidra-rpc\ghidra-rpc-<hash>.sock` | Authenticated loopback TCP endpoint metadata (Windows) |
  68. | `/tmp/ghidra-rpc-<hash>.log` or `%LOCALAPPDATA%\ghidra-rpc\ghidra-rpc-<hash>.log` | Background daemon log (`--detach` mode) |
  69. | `<project-dir>/.ghidra-rpc-<hash>.json` | Per-project session file (default, alongside `.gpr`) |
  70. | `$GHIDRA_RPC_STATE_DIR/<hash>.json` | Per-project session file when override is set |
  71. | `~/Library/Application Support/ghidra-rpc/sessions.json` | Global session registry (macOS) |
  72. | `~/.local/state/ghidra-rpc/sessions.json` | Global session registry (Linux) |
  73. | `$XDG_STATE_HOME/ghidra-rpc/sessions.json` | Global session registry (Linux, if `$XDG_STATE_HOME` set) |
  74. | `%LOCALAPPDATA%\ghidra-rpc\sessions.json` | Global session registry (Windows) |
  75. | `$GHIDRA_RPC_STATE_DIR/sessions.json` | Global session registry when override is set |
  76. `$GHIDRA_RPC_STATE_DIR` is a single knob that redirects **both** per-project
  77. session files and the global registry to a custom directory — useful in
  78. sandboxed or CI environments.
  79. The global session registry is maintained automatically: `start` adds an entry,
  80. `stop` removes it, and `list-instances` prunes any entries whose endpoint file has
  81. disappeared (e.g. after a crash).
  82. ## Documentation
  83. - [Installation](docs/install.md)
  84. - [Quick Start](docs/quickstart.md)
  85. - [Troubleshooting](docs/troubleshooting.md)
  86. - [Internals](docs/internals.md) — session/socket design, Ghidra API notes
  87. ### Workflow Guides
  88. - [Binary Audit](docs/flows/binary-audit.md)
  89. - [Vulnerability Research](docs/flows/vulnerability-research.md)
  90. - [Patch Analysis](docs/flows/patch-analysis.md)
  91. - [Android APK / DEX](docs/flows/android-apk.md)
  92. ## License
  93. MIT

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.