cyberkaida/reverse-engineering-assistant/pyghidra-scripting

PyGhidra scripting via ReVa

ReVa exposes five MCP tools under the scripts provider that let an assistant write, edit, run, and inspect Python scripts inside the same Ghidra session ReVa is serving. The Python code runs under PyGhidra (CPython 3 + JPype), so it has the full Ghidra Java API available — the FlatProgramAPI, DecompInterface, FunctionManager, everything.

This skill teaches when to reach for these tools, how to structure the Python you send to run-script, and the pitfalls that bite in practice.

The five tools at a glance

Reach-for-it triggers

run-script is the escape hatch. Use it when:

• You need to run a custom predicate over every function/symbol/instruction and the existing list/find tools don't filter the right way.
• You need to combine multiple Ghidra API calls into one operation that would otherwise take many MCP round-trips.
• You want to use a Ghidra API ReVa doesn't expose — e.g. DecompInterface low-level features, PCode analysis, custom AddressSet arithmetic, the data flow API directly, BinaryReader, etc.
• You're prototyping; once it works and is reusable, save it with write-script.

Don't use run-script when a dedicated ReVa MCP tool already does the job — those tools have stable schemas and structured output that's easier to reason about than free-form stdout. The decompiler / functions / strings / symbols / xrefs tools cover the common path.

Runtime gate: PyGhidra-only

run-script only works when Ghidra was launched under PyGhidra:

• ✅ mcp-reva (Claude CLI / stdio mode)
• ✅ pyghidra-gui (GUI mode launched with PyGhidra)
• ✅ reva_headless_server.py (headless mode via PyGhidra)
• ❌ Plain ghidraRun — PyGhidra is not wired in; you'll get a PyGhidraNotAvailableException error response with launch guidance.

If a run-script call comes back with that error, the right move is to tell the user how to relaunch (don't keep retrying). The other four tools (list-scripts, read-script, write-script, edit-script) work in every mode because they're plain file operations.

The execution contract for run-script

This is the contract your inline code (or saved script) runs under. Internalise it — most failures come from getting one of these wrong.

Pre-bound globals. The script runs as a Ghidra PyGhidra script, so the standard GhidraScript globals are already defined: currentProgram, currentAddress, currentSelection, currentHighlight, monitor, state, plus FlatProgramAPI helpers like toAddr, getFunctionAt, getFunctionContaining, getSymbolAt, getInstructionAt, getDataAt, getReferencesTo, getReferencesFrom, createLabel, setEOLComment, find, findBytes, clearListing. You do not need to import or set these up. currentProgram is the program identified by the programPath argument.

No automatic transaction. Unlike GhidraScripts run from inside Ghidra's GUI, ReVa's run-script deliberately does not open a transaction around your code. Any mutation (rename, retype, comment, label, create function, etc.) must be wrapped manually:

tx = currentProgram.startTransaction("Describe the edit")
try:
    # ... do stuff that mutates state ...
    currentProgram.endTransaction(tx, True)   # commit
except Exception:
    currentProgram.endTransaction(tx, False)  # roll back
    raise

This is intentional — auto-wrapping at the tool layer would create nested-transaction footguns when scripts already handle their own. Read-only scripts (printing, counting, dumping) need no transaction at all.

Inline header. When you pass code, the tool prepends # @runtime PyGhidra\n automatically. Don't add it yourself.

Cancellation is cooperative. The configured timeout (default 60s, overridable per-call via timeoutSeconds) only fires if your code yields to the monitor. In long loops, call monitor.isCancelled() regularly and break:

fm = currentProgram.getFunctionManager()
for func in fm.getFunctions(True):
    if monitor.isCancelled():
        break
    # ... work ...

A tight Python loop without a monitor check will run past the timeout. The result will then come back with timedOut: true and partial output but the Ghidra session may still be busy for a moment.

Output is captured and capped. stdout and stderr are each capped at 64K chars by default (configurable via SCRIPT_OUTPUT_CHAR_LIMIT). If you blow the cap, the result has stdoutTruncated: true or stderrTruncated: true. Design output for an LLM consumer — terse, structured, line-per-record. Reach for JSON if downstream parsing matters:

import json
results = []
for func in currentProgram.getFunctionManager().getFunctions(True):
    if monitor.isCancelled(): break
    if some_predicate(func):
        results.append({"addr": str(func.getEntryPoint()), "name": func.getName()})
print(json.dumps(results))

Result schema. run-script returns:

{
  "success": true|false,
  "programPath": "/binary.exe",
  "stdout": "...",
  "stderr": "...",
  "stdoutTruncated": false,
  "stderrTruncated": false,
  "durationMs": 1234,
  "timedOut": false,
  "scriptSource": {"type": "inline|path|name", "value": "..."},
  "error": "ClassName: message"   // only when the executor itself threw
}

success is false if the script raised a Python exception (detected via the Traceback (most recent call last) marker in stderr), if it hit the timeout, or if the executor threw. Read stderr to see the actual traceback — Python exceptions don't surface as MCP errors, they come back in stderr with success: false.

What you can call from inside

The script has the full Ghidra/PyGhidra surface. The most commonly useful entry points:

# Program structure
prog     = currentProgram                             # the Program object
listing  = prog.getListing()                          # CodeUnits, data, comments
memory   = prog.getMemory()                           # blocks, bytes
fm       = prog.getFunctionManager()                  # functions
st       = prog.getSymbolTable()                      # symbols/labels
rm       = prog.getReferenceManager()                 # xrefs
dtm      = prog.getDataTypeManager()                  # data types
# Flat-API one-liners (already global)
addr     = toAddr(0x401000)
func     = getFunctionAt(addr) or getFunctionContaining(addr)
sym      = getSymbolAt(addr)
instr    = getInstructionAt(addr)
xrefs_to = getReferencesTo(addr)
# Java classes — import as normal Python after PyGhidra is up (it is, when run-script runs)
from ghidra.program.model.symbol import SourceType
from ghidra.app.decompiler import DecompInterface, DecompileOptions

For everything else: see references/flat-api.md for the categorised Flat-API cheat-sheet, and references/jpype-interop.md for the Java-via-Python idioms (arrays, iterators, sign extension, type stubs).

Workflow patterns

Inline one-shot (most common)

run-script(programPath="/bin", code="""
fm = currentProgram.getFunctionManager()
total = 0
huge = []
for f in fm.getFunctions(True):
    if monitor.isCancelled(): break
    size = f.getBody().getNumAddresses()
    total += size
    if size > 4096:
        huge.append((str(f.getEntryPoint()), f.getName(), size))
print(f'total bytes: {total}')
for addr, name, size in huge:
    print(f'{addr} {size:6d} {name}')
""")

Read the stdout, draw conclusions, move on. Nothing persisted.

Iterate then save

1. Send a draft via run-script with inline code.
2. When it works, call write-script with scriptName="MyAnalysis.py" and the final code. (Pick a descriptive name — list-scripts will return it.)
3. Next time, run-script with scriptName="MyAnalysis.py".

Edit-in-place on a saved script

1. list-scripts (or remember the name).
2. read-script — note the line numbers around what you want to change.
3. edit-script with old_string set to a uniquely identifying slice (include enough surrounding context that there's exactly one match). The tool errors out on ambiguity unless you pass replace_all: true.
4. Re-run via run-script(scriptName=...).

edit-script is preferred over re-writing the whole file — it preserves the rest of the script unchanged and is what the user can review as a diff.

Pitfalls

These are the ones that account for most "why did my script misbehave."

Forgot the transaction

Mutations without startTransaction throw IllegalStateException: not in transaction. If a run-script call mutates and you see this in stderr, that's the cause. Wrap the mutating block — see the contract section above.

monitor.isCancelled() check missing

Tight loops that never check the monitor blow past the timeout silently — the timedOut flag still flips, but your script may have already done damage. Always check the monitor inside any loop touching every function / instruction / address.

Java Iterator vs Python iterable

Most Ghidra iterators are Python-iterable thanks to JPype, but a few (notably SymbolIterator from some accessors and the older ReferenceIterator) only expose hasNext() / next(). If a for x in it: loop silently yields nothing, fall back to while it.hasNext(): x = it.next(). FunctionManager.getFunctions(True) is iterable directly.

Java byte is signed

MemoryBlock.getBytes(addr, byte[] buf) fills you a Java byte[]. Values come back as -128..127. Mask with b & 0xff if you want 0..255. Allocating the buffer: import jpype; buf = jpype.JByte[16].

print() is what shows up in stdout

The script's print() is rerouted to the captured stdout writer — that's how you get output back. Don't use logging frameworks expecting them to flush somewhere visible; print(...) is the contract.

Decompiler is expensive to construct

If you decompile more than a handful of functions in one script, build the DecompInterface once and reuse it. Always dispose() it. With a per-function timeout of 30s, a 100-function pass that re-builds the decompiler each call can easily blow run-script's overall timeout.

from ghidra.app.decompiler import DecompInterface
decomp = DecompInterface()
decomp.openProgram(currentProgram)
try:
    for f in currentProgram.getFunctionManager().getFunctions(True):
        if monitor.isCancelled(): break
        res = decomp.decompileFunction(f, 30, monitor)
        if res.decompileCompleted():
            # process res.getDecompiledFunction().getC()
            pass
finally:
    decomp.dispose()