rsleigh

Reverse engineering from your terminal, built for coding agents and scripts.

Map an unfamiliar binary, find the functions that matter, and inspect assembly, P-code, and C-like pseudocode. Give your coding agent bounded evidence with cross-references, confidence labels, and machine-readable output for the next question.

Written in Rust, with no JVM or Ghidra installation required. Use the CLI on its own, call it from an agent's shell tools, or embed the decoder and lifter in your own Rust tools.

Download rsleigh · Run your first analysis · See real investigations

Contents

Installation · Quickstart · Examples · Features · LLM workflows · Framework · Targets · Documentation · Contributing

Installation

Download a prebuilt v0.4.3 CLI for your platform—no Rust toolchain needed:

Extract the archive and put rsleigh (Windows: rsleigh.exe) in a directory on your PATH. You can also run it directly from the extracted directory as ./rsleigh on macOS/Linux or .\rsleigh.exe in PowerShell. Running it without arguments prints usage. All releases and SHA-256 checksums.

Install v0.5.0 with Cargo. With a Rust toolchain, installation is one command:

cargo install rsleigh --version 0.5.0 --locked

The semantic slice selectors, analysis cache, and typed evidence described here are available in v0.5.0 through Cargo. The pinned v0.4.3 prebuilt downloads predate those features. To build the current source checkout instead:

git clone https://github.com/ShaneBreazeale/rsleigh.git
cd rsleigh
cargo run -p rsleigh-generate
cargo install --path rsleigh-cli

Prebuilt releases use the default features; optional SMT solving requires a source build with native Z3. See SMT setup and scope.

Quickstart

Replace ./sample.exe with your target. Start with a capped JSON map:

rsleigh ./sample.exe --agent-brief

The brief includes file hashes, architecture, ranked functions, findings, warnings, output limits, and address-specific follow-up commands. Pick a function from the map, then inspect it by name or address:

rsleigh ./sample.exe --xrefs main               # callers, callees, and strings
rsleigh ./sample.exe main --card --pcode        # bounded assembly and lifted semantics
rsleigh ./sample.exe main --card --pcode --decompile

For direct exploration, list discovered functions or request pseudocode:

rsleigh ./sample.exe
rsleigh ./sample.exe main
rsleigh ./sample.exe 0x140001000

Use an address from your own target when symbols are unavailable.

Features

• Rust throughout the core. SLEIGH parsing, decoder generation, P-code lifting, and the decompiler live in Rust. Analysis runs without a Ghidra installation, Java runtime, or bindings to Ghidra's C++ decompiler.
• Designed around a context budget. Ranked briefs and bounded function cards let an agent inspect a few useful functions at a time. Reusable indexes support follow-up queries across turns.
• Ask about a value directly. Select a call argument, return value, or branch condition without searching a full SSA dump for variable IDs. Bounded slices follow supported memory stores and helper calls, exposing unresolved dependencies and the raw instructions behind recovered values.
• Reuse analysis and limit work. Cache decoded instructions and SSA across queries. Set decode, SSA, traversal, and cooperative deadline limits to retain partial evidence when an investigation reaches its budget.
• Evidence at multiple levels. Move from pseudocode to SSA, P-code, and instruction bytes. Outputs expose confidence, analysis stage, warnings, and truncation so a model can distinguish an observation from a hypothesis.
• Useful beyond decompilation. Search strings and API calls, trace xrefs, triage executables, identify library functions, and investigate packed code or custom VMs.
• A framework you can embed. Rust crates expose the decoder, intermediate representation, function identification, and experimental analysis pipeline.

The decoder and P-code lifter are the stable core. Decompilation, discovery, and higher-level analysis remain experimental; check important conclusions against the assembly and lifted semantics.

Built for LLMs and coding agents

rsleigh exposes a CLI that agents can call through their shell tools. Copy the drop-in agent instructions into your analysis workspace to give an agent the workflow and evidence rules.

Ask a focused dependency question using addresses from your target's card:

rsleigh ./sample.exe --ssa-slice main --return --analysis-cache sample-cache/
rsleigh ./sample.exe --ssa-slice main --call-site 0x140001020 --arg 0 --analysis-cache sample-cache/
rsleigh ./sample.exe --ssa-slice main --condition 0x140001030 --max-nodes 32 --max-call-depth 1

Call arguments are zero-based ABI slots. For multiple returns, add --at 0xADDRESS; --var ID remains available for an exact SSA snapshot. Unknown aliases, unsupported calling conventions, and exhausted limits stay explicitly unresolved. Dependencies do not establish runtime reachability. See selectors and architecture limits.

Cards and slices also accept --max-decode-instructions, --max-ssa-work, and --deadline-ms. A warm cache reuses completed analysis without new decode/SSA work; small queries may still cost more to load than to recompute. See cache behavior and execution limits.

For a reusable binary-wide navigation map, build an index and query its files:

rsleigh ./sample.exe --index sample-index/
rsleigh ./sample.exe --verify-index sample-index/
functions_path=$(jq -r '.files[] | select(.name == "functions.json") | .path' sample-index/index.json)
jq '.functions[] | select(.imports | index("recv"))' "sample-index/$functions_path"

Preserve the binary hash, function address, exact command, and relevant warnings with each conclusion. Agent commands exit 0 on completion, 2 for partial analysis, and 1 on failure; inspect status and diagnostics before reasoning from evidence. Pseudocode is a reconstruction; heuristic findings are leads. Check schemas, top-level errors, and reported limits before consuming output automatically.

The brief and index currently support PE, ELF, and Mach-O inputs. See the agent workflow reference for schemas, hard caps, ranking, and the reporting contract.

Explore, triage, investigate

Find an entry point into an unfamiliar binary:

rsleigh ./sample.exe --search "password"
rsleigh ./sample.exe --search --api LoadLibraryA
rsleigh ./sample.exe --search --const 0xCAFEBABE
rsleigh ./sample.exe --callgraph > callgraph.json

Extract file-level indicators and collect analysis leads:

rsleigh ./sample.exe --ioc --findings-ndjson > findings.ndjson
rsleigh ./sample.exe --sigcheck --json
rsleigh ./sample.exe --resources --dump extracted/
rsleigh ./sample.exe --vulnscan --findings-ndjson >> findings.ndjson

Packed-code analysis includes crypto annotations, API-hash recognition, PEB and timing probes, SEH/TLS patch discovery, and custom-VM dispatcher, handler, and bytecode helpers. Optional Z3-backed analysis produces ranked source-to-sink candidates within its documented model.

See the feature catalog, triage reference, and SMT candidates for the specialized workflows.

In practice

These investigations drove concrete improvements to the tool. The firmware notes link to the implementation history and describe remaining limits; SMT candidates are analysis leads, not confirmed vulnerabilities.

Under the hood

rsleigh uses Ghidra's SLEIGH processor specifications as input to its own Rust parser and code generator. Generated Rust decoders produce disassembly and P-code, an intermediate representation of instruction semantics. The analysis pipeline builds on that representation to recover data flow and pseudocode.

SLEIGH specifications → Rust parser + code generator → Rust decoders
                                                           │
Binary → load + discover → decode + lift → P-code → SSA → C-like pseudocode
                              │              │       │          │
                              └──────────────┴───────┴──────────┘
                                  CLI artifacts + Rust APIs

Ghidra provides the specification lineage and oracle fixtures for validation; it is not required to run rsleigh. WebAssembly uses a dedicated frontend.

Embed in Rust

[dependencies]
rsleigh-api = "0.4"

use rsleigh_api::{Architecture, Decoder};

let mut decoder = Decoder::new(Architecture::X86_64);
let inst = decoder.decode(&[0x48, 0x89, 0xd8], 0x1000).unwrap();

assert_eq!(inst.disassembly, "MOV RAX,RBX");
assert_eq!(inst.len, 3);

rsleigh-api exposes Decoder, Architecture, register-name lookup, and re-exported P-code types. Pin an exact patch version when depending on the experimental rsleigh-decompile internals.

Supported targets

The CLI loads PE32/64, ELF32/64, Mach-O 64, WebAssembly, and raw firmware. CPU targets include x86-64, x86-32, AArch64, ARM32/Thumb, MIPS32 big-endian, and RISC-V RV64GC.

Coverage varies by architecture and stage. x86-64 and scalar AArch64 have the strongest coverage; successful decoding does not imply complete lifting or decompilation. Consult the architecture matrix for tested paths and known gaps.

For raw firmware, supply the architecture and image base on every command:

rsleigh ./firmware.bin --raw arm32 --base 0x08000000
rsleigh ./firmware.bin --raw arm32 --base 0x08000000 0x08001235

The second raw example selects a Thumb function for pseudocode. Raw firmware uses a separate frontend; see raw workflow limits.

Documentation

Start with the documentation hub, command guide, and output format reference.

Context7 library ID: /shanebreazeale/rsleigh.

Contributing

rsleigh is a v0.x, single-maintainer project. Issues and pull requests are welcome, especially reproducible cases that improve decode, lift, discovery, or pseudocode quality.

From a checkout with a Rust toolchain and make:

make test                                      # generate decoders and run the harness
cargo test -p rsleigh-decompile --release --lib
make decomp-bench                              # pseudocode regression gate
cargo install --path rsleigh-cli

Include regression tests with bug fixes and architecture-level coverage for generated-decoder changes. The suite covers P-code, committed Ghidra oracle fixtures, decompiler regressions, random-byte panic checks, real binaries, and pseudocode scoring. See testing for validation workflows, including optional Ghidra comparisons and SMT calibration.

License

Apache-2.0. Bundled Ghidra .slaspec files are also Apache-2.0.