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.
v2026.11.2-fa386625 installazioni+5 in 7 giorni★ 400 Stellesincronizzato 12 ore fa
Installa
Non hai ancora la CLI di NotHoly? Installala prima.
A CLI daemon that exposes Ghidra reverse engineering capabilities over a local socket
(a Unix domain socket; token-authenticated loopback TCP on Windows).
You interact with it by running ghidra-rpc commands via the bash tool - every command
outputs JSON to stdout.
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 accept
--timeout SECS (seconds to wait for the daemon to respond; for start it only applies
with --detach; default: 60 s headless, 180 s GUI) and log daemon output to
/tmp/ghidra-rpc-<hash>.log (%LOCALAPPDATA%\ghidra-rpc\ghidra-rpc-<hash>.log
on Windows).
GUI mode: verify the correct project is active. The daemon passes the --project path
directly to GhidraRun so Ghidra opens the requested project immediately. After
start --detach (GUI mode), confirm the right project is loaded before issuing any
analysis commands:bash
uv run ghidra-rpc list-project-programs --project /path/to/project.gpr
Cross-check the returned binary names against what you expect. If the names don't match
(or a warning field appears in the response), stop and ask the user to open the correct
project in Ghidra's Project window before proceeding.
GUI mode: programs outside the project's root folder must be open in CodeBrowser.
The daemon sees programs open in any running tool plus every program in the project's
root folder (which is where load puts them). A program in a project subfolder that
isn't open in CodeBrowser is invisible and commands fail with "Binary not found"; use
list-project-programs to see what's stored, then double-click it in Ghidra's Project
window.
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. A clean stop deletes that
session, so after it you need start (or restart --headless) again.
Every command except list-instances and stop --all accepts --project <path> (or reads
GHIDRA_RPC_PROJECT).
All output is JSON. Exit code 0 = success, nonzero = error.
Examples below omit the cd <skill-dir> && uv run prefix.
Restart daemon in background (--headless to override mode)
ghidra-rpc restart -p /tmp/re.gpr --headless
ghidra-rpc list-binaries --project <gpr>
List binaries loaded in daemon
ghidra-rpc list-binaries -p /tmp/re.gpr
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
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
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 died without a clean
stop), and null if no session exists (never started, or cleanly stopped).
--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.
Either way the CLI waits for the whole load (import, analysis, save) to finish — on large
binaries, pass it or run load in the background so your shell doesn't block.
<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.
Addresses. Every address in command output is 0x-prefixed (0x00101139;
non-default spaces keep their qualifier: EXTERNAL:0x00000001, overlays ov1::0x00001000;
stack offsets stay Stack[-0x10]). Pass them back verbatim. Only 0x-prefixed input is
treated as an address — bare hex like 00101139 is a name query and will not match
auto-named FUN_00101139.
search-decompiled is especially useful on multidex Android projects, where xrefs-to
on a method only sees callers within the same DEX program (see the Android APK/DEX
section) — use it in place of a symbols+decompile+grep loop, e.g.
search-decompiled app.apk targetF1 --class com::example::Foo. --max-scan (default 5000)
caps how many functions get decompiled per call, so a search on a 50k+-function binary can't
run away; raise --socket-timeout (default 1800s) alongside it if you do widen the scan.
Check coverage before concluding "no matches".truncated: true means only
scanned_range was searched, not the whole binary. Resume with
--address-min <next_unscanned_address> (keeping the same --address-max, if any)
until next_unscanned_address is null.
symbols normalizes literal spaces and underscores as equivalent before matching, so a
query pasted straight from strings output (real spaces) still finds the corresponding
label even though Ghidra auto-generates labels from string content by turning each space
into _ (and leaving every other character, including non-ASCII/CJK text, untouched).
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}
Ghidra's reference manager is per-binary: a call whose caller and target live in two
different loaded binaries is invisible to a single-binary xrefs-to lookup (most
commonly hit on multidex Android projects, where a method in one classesN.dex is
called from another, but this isn't DEX-specific — it applies to any project with more
than one binary loaded in the daemon). Pass --all-binaries to also search every other
currently loaded binary for a symbol with the same fully-qualified name and merge in
real callers found there; each merged entry carries a binary field so you can tell
which binary it came from.
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
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)
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
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)
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:
Any type in the program's data type manager by name or path: MyStruct, /POSIX/size_t
Order of operations — set signatures/types before naming locals. Each of
set-signature, set-data-type, retype-variable, and rename-variable re-runs the
decompiler, which re-numbers the remaining auto-named locals (uVar1, dVar2, …). So
chaining single-variable edits is fragile: after renaming dVar1, the old dVar2 may
now be dVar1. Do all signature/this-typing first, then name locals — or, better, use
batch-edit-variable to apply every rename and retype against a single decompiler
snapshot in one call (it also lets you address a variable by its stable storage string
instead of the volatile auto name).
--category is a case-insensitive substring filter. On heavily auto-analyzed binaries
(large native programs, and especially DEX/Dalvik — 50k+ functions is normal), Ghidra
generates many Analysis-type bookmarks (commonly category Address Table) that can
bury a handful of your own; filter them out with --category (or --type to isolate
your own type, e.g. Note) instead of paging through the unfiltered list.
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.
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.
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}
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}
ghidra-rpc create-union <binary> <name> TYPE FIELD [TYPE FIELD ...] [--if-not-exists|--or-replace]
decompile-all's default --socket-timeout (1800s) assumes a bulk sweep can take much
longer than any single function's --timeout; raise it further for binaries with tens of
thousands of functions (e.g. large DEX/APK programs).
version-track and match-function are headless-only and need two different loaded
binaries; their --socket-timeout defaults to 1800s.
For the full patch-diff workflow see docs/flows/patch-analysis.md.
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.
All CLI output is JSON, including usage errors. A malformed invocation (unknown
option, invalid --type choice, unknown subcommand, missing required argument) is also
reported as {"ok": false, "error": "...", "message": "..."} on stdout, with a nonzero
exit code — never a plain-text Click usage string. Scripted callers can always
json.loads() stdout unconditionally, without special-casing argument errors.
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)
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.
Most single-item edits (rename-function, rename-symbol, create-label, set-comment,
set-signature, retype-variable, rename-variable, set-calling-convention, set-thunk,
set-flow-override, set-equate, set-processor-context, write-bytes, and each
batch-edit-variable result) include a verified boolean that confirms the change was read
back after committing. verified: false also prints a warning on stderr.
You can also save explicitly at any time:
bash
ghidra-rpc save # saves all loaded programsghidra-rpc save <binary> # saves one program
On clean shutdown (stop or Ctrl+C), all programs are saved automatically.
Ghidra has built-in APK and DEX support (Dalvik processor + FileFormats
loaders) — no extension install needed. load a .dex or .apk directly and
the usual commands (decompile, functions, strings, xrefs-*, …) work on
the Dalvik program, which decompiles to Java-like pseudocode. Note the
multi-dex caveat: load app.apk imports only the primary classes.dex.
For the full workflow — multi-dex extraction, class-qualified :: symbols and
ambiguous methods, the DEX string-vs-xrefs-to gotcha, minified apps, and
manifest/.so extraction — read docs/flows/android-apk.md.
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
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)
Get overview: metadata, functions, imports, exports
Investigate: decompile interesting functions, xrefs-to to trace callers
Annotate: rename-function, set-comment to document findings
Search: strings for hardcoded values, symbols for specific patterns
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:
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:
bash
# 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:
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:
bash
# Load response: {"binary": "/WinHelloCPP.exe-85cbcc", "short_name": "WinHelloCPP.exe", ...}ghidra-rpc decompile WinHelloCPP.exe main # short_name worksghidra-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 missing a program in GUI mode: The daemon sees programs open in a
running tool plus those in the project's root folder. For a program in a subfolder, use
list-project-programs to find it, then open it in CodeBrowser from the 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
daemon endpoint, so on Windows that is
%LOCALAPPDATA%\ghidra-rpc\ghidra-rpc-<hash>.log. If the daemon fails to start or
become responsive, check that file first:
bash
tail -50 /tmp/ghidra-rpc-*.log
The timeout error message always prints the exact log path, on every platform.
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:
Pass --ghidra-install-dir /path/to/ghidra to start or restart - the value is
persisted in the session file and reused by auto-restart and restart for as long as
that session exists. A clean stop deletes the session, so the next start takes the
flag or env var afresh — that is how you switch to a different Ghidra version
(restart --ghidra-install-dir NEW also overrides it).
Export GHIDRA_INSTALL_DIR in your shell profile (~/.bashrc, ~/.zshrc) so it
survives login sessions.
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:
bash
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. The
retype-variable and rename-variable commands also accept --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:
bash
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:
If disassemble is called at an address with no instruction (e.g. an address
that is mid-instruction or undefined), the response 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:
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:
bash
# 1. Diagnose: check TMode at the affected addressghidra-rpc get-processor-context binary 0x03288100 --register TMode# Result: {"address": "0x03288100", "registers": {"TMode": 0}} ← TMode 0 is the problem# 2. Clear the bad data/code classificationghidra-rpc clear-data-range binary 0x03288100 0x032883ff# 3. Set Thumb mode for the rangeghidra-rpc set-processor-context binary 0x03288100 TMode 1 --end 0x032883ff# 4. Verify disassembly now shows Thumb-2 instructionsghidra-rpc disassemble binary 0x03288100 --count 20# 5. Re-create the functionghidra-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:
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:
Batch rename / comment 40+ functions without round-trip overhead:
Use batch-rename and batch-set-comment to apply many annotations in a single
server round-trip and Ghidra transaction:
bash
# Rename functions from a JSON fileghidra-rpc batch-rename binary --json-file renames.json# Or inlineghidra-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 commentsghidra-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.
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:
bash
cat > /tmp/ghidra-rpc-issues-$(date +%Y%m%d-%H%M%S).md << 'EOF'## ghidra-rpc Issue Report**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. On Windows write it to %TEMP% instead; the
snippet above is bash, so adapt it to the shell you are actually running.