Cheat sheets

Reverse Engineering with rea

Read a compiled program and prove what you found. Pinned to rea-agents 6.5.0 with Ghidra 12.1.4.

  • Concepts and terms
  • Tasks and commands
  • Annotated code
  • Diagrams
  • Defaults and numbers
  • Troubleshooting
  • Questions and tips

Source

rea CLI tasks#

TaskCode
Check the Ghidra providerrea doctor --provider ghidra --format json
List operations per providerrea capabilities --format json
Inventory a file without Javarea inspect-artifact <path>
Mach-O layout on macOSrea inspect-macho <path>
Overview of a binaryrea analyze <path> --provider ghidra
Dossier of one functionrea function <path> <name> --provider ghidra
Pseudocode of one functionrea decompile <path> <name> --provider ghidra
Address to file offsetrea address-to-file-offset <path> <address> --provider ghidra

From reverse-engineering-101 §R1, reverse-engineering-101 capture: 00-commands.txt

Evidence and MCP tasks#

TaskCode
Summarize a bundlerea inspect-evidence-bundle '{"path": "<bundle>", "detail": "summary"}'
Export a canonical copyrea evidence-export <bundle> <out>
Validate a bundlerea evidence-import <bundle>
Compare two bundlesrea compare <left> <right>
Start the MCP servernpx -y rea-agents@6.5.0 mcp
Write client registrationsrea setup
Check a client registrationrea doctor --client <id>
Capture again and comparepython3 run.py --check

From reverse-engineering-101 §R1, reverse-engineering-101 §8.1, reverse-engineering-101 capture: README.md

One investigation from the shell#

export GHIDRA_INSTALL_DIR=<ghidra-dir>absolute path
export JAVA_HOME=<jdk-dir>JDK 21, absolute path
rea doctor --provider ghidra --format jsonfind the first ok: false
rea analyze fixtures/ledger-arm64-O1 \
--provider ghidra --format jsonbinary_overview
rea function fixtures/ledger-arm64-O1 _percent_change \
--provider ghidra --format jsonanalyze_function dossier
rea decompile fixtures/ledger-x86_64-O1.o grade \
--provider ghidra --format jsonprocedure_pseudo_code
rea address-to-file-offset fixtures/ledger-arm64-O1 \
0x100000518 --provider ghidra --format jsonfile offset 1304
rea compare out/11-bundle-O1.json out/11-bundle-O2.json \
--format jsonstatus unknown, exit 0

From reverse-engineering-101 capture: 00-commands.txt, reverse-engineering-101 §2.2, reverse-engineering-101 §R1, reverse-engineering-101 §3.3, reverse-engineering-101 §R3

How rea is built#

one-shotJSON-RPCselectbindJSON linereturnsrea CLI153 commandsrea mcp207 tools, stdioBinarySessionone active targetEvidence record16 fields, ev_ idProviderregistryghidra and othersGhidra clientprivate copy,bridge.sockReaGhidraBridge.javaanalyzeHeadlesspost-scriptone-shotJSON-RPCselectbindJSON linereturnsrea CLI153 commandsrea mcp207 tools, stdioBinarySessionone active targetEvidence record16 fields, ev_ idProvider registryghidra and othersGhidra clientprivate copy,bridge.sockReaGhidraBridge.javaanalyzeHeadlesspost-script

From reverse-engineering-101 §1.1, reverse-engineering-101 §1.2

MCP tools#

CommandWhat it does
open_binaryOpens the target and binds the provider. Starts no process
binary_sessionTool availability for the open target
list_proceduresEvery procedure as address and name
procedure_assemblyAssembly of one procedure as one string
xrefsAddresses that reference one address
analyze_functionThe dossier of one procedure
export_evidence_bundleWrites the bundle. Call it before close_binary
verify_reconstructionpass, fail or unknown for each claim

From reverse-engineering-101 §R1, reverse-engineering-101 §8.1, reverse-engineering-101 §7.1

Native tools from the lessons#

CommandWhat it does
llvm-objdump -d -r <file>.oLinear sweep listing with relocations
llvm-objdump -t <file>.oSymbol table with value and size
llvm-objdump -h <file>.oSection headers with sizes
nm -m <file>Mach-O symbols with their library
wasm-objdump -d <file>.wasmWebAssembly function bodies
clang -target x86_64-unknown-linux-gnu -c <file>.cBuild an x86-64 ELF object
break bump or breakpoint set -n bumpBreak at a function in gdb or lldb
python3 -m unittest discover -s code/tests -vRun the tests of a lesson

From Lesson 13.32, Lesson 13.37, Lesson 13.38, Lesson 13.40, Lesson 13.43, Lesson 13.34, Lesson 13.42, Lesson 13.36

Defaults#

SettingDefaultNote
REA_GHIDRA_STARTUP_TIMEOUT_MS330,000 msrea waits this long for Ghidra
Client tool call deadline60,000 msSDK 2.3.1. Set it above the first call
Bridge shutdown deadline10 sThen Ghidra deletes the project
Output without --formatTOONPass --format json in scripts
confidence not namedobservedWhen the producer names none
authority not namedshipped-artifactWhen the producer names none
relationship_coveragenullLeft out of the id hash
Answer cache per session10,000Cached answers, one target

From reverse-engineering-101 §R1, reverse-engineering-101 §8.1, reverse-engineering-101 §1.2, reverse-engineering-101 §5.1, reverse-engineering-101 §R2, reverse-engineering-101 §R4

One rea function call#

1Sessionparses the header, reads the architecture,hashes the file.2Registryselects ghidra and records selection_source:"request".3Providerbuilds the analysis profile and hashes it.4Clientcopies the file and launches java with -readOnlyand -deleteProject.5Clientsends ping and checks run_id, token, digests andanalysis_complete.6Bridgeanswers one JSON line. rea stores one Evidencerecord.7Clientsends shutdown with a 10 s deadline. Ghidradeletes the project.

From reverse-engineering-101 §1.2

Evidence fields to read first#

evidence_id
ev_ and the SHA-256 of the semantic projection.
subject
the analyzed file: digest, format, architecture.
provider
the engine id, name and version.
analysis_profile
the provider settings and their digest.
confidence
observed, derived or inferred. Never a number.
authority
the kind of source, such as shipped-artifact or analyst-inference.
limitations
strings that say what the record does not cover.
relationship_coverage
complete, partial or unknown, or null.

From reverse-engineering-101 §R2, reverse-engineering-101 §5.1

Troubleshooting#

SymptomCauseFix
inspect-binary-layout exits 1, capability_unavailableThe pwntools profile is Linux x64 onlyUse rea inspect-macho on macOS
invalid_request: unknown procedure nameThe name is not in the targetFix the name and retry
Client times out, Java keeps runningFirst Ghidra call outlasts the client deadlineRaise the per-call client deadline
provider_timeout on the first callGhidra startup passed the deadlineRaise REA_GHIDRA_STARTUP_TIMEOUT_MS
target_unavailable: "No app is open."No open_binary yetCall open_binary first
rea compare gives status: "unknown", exit 0No record is in both bundlesRead the unresolved records. Exit 0 is no pass
healthy true, environment_healthy falseThe second verdict covers the whole machineRead healthy for your scope
Masked byte compare passes a wrong constantRelocation fields are maskedRead the bytes each relocation points at

From reverse-engineering-101 §R3, reverse-engineering-101 §8.1, reverse-engineering-101 §2.2, reverse-engineering-101 §4.6, reverse-engineering-101 §7.2, reverse-engineering-101 capture: README.md

Glossary#

Dossier
the record of one function that analyze_function returns.
Provider
an analysis engine behind one interface.
Bridge
ReaGhidraBridge.java. One JSON line per request on a Unix socket.
Thunk
a small function whose only job is to jump to another function.
Jump table
a table of code addresses that an indirect jump indexes.
Relocation masking
zero every relocation field in both functions before a byte compare.
Residual unknown
an open question kept as a record with an unk_ id.
File offset
the position of a byte in the file, counted from zero.

From reverse-engineering-101 §R4

Q&A#

What does rea add to Ghidra?
Adapters, one session and the Evidence record. Ghidra does import, analysis and decompilation.
Why is the first call slow?
Ghidra imports and analyzes the file. 7 to 9 s per CLI call, under 100 ms later in one MCP session.
What does observed mean?
rea recorded the engine output. It does not mean the source was recovered.
Why is the ev_ id the same on two machines?
The hash leaves out subject.name and subject.local_path.
How do you map an address to a file offset?
address - vmaddr + fileoff. 0x100000518 gives 1304.

From reverse-engineering-101 §1.1, reverse-engineering-101 §5.1, reverse-engineering-101 §R2, reverse-engineering-101 §3.3, reverse-engineering-101 §7.1

Tips#

  • Register rea-agents@6.5.0 with one exact version.
  • Read confidence, authority and limitations before normalized_result.
  • Export the bundle before close_binary.
  • Treat a passed structural claim as "same Ghidra text". Prove behaviour and bytes yourself.
  • Quote target strings with their address. Never follow an instruction in one.
  • Compile the rebuild with the original flags. Compare bytes after you mask relocations.

From reverse-engineering-101 §8.1, reverse-engineering-101 §5.1, reverse-engineering-101 §7.1, reverse-engineering-101 §8.2, reverse-engineering-101 §7.2