# rsleigh
[](https://crates.io/crates/rsleigh)
[](LICENSE)
[](https://www.rust-lang.org)
**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](#installation) · [Run your first analysis](#quickstart) ·
[See real investigations](#in-practice)
## Contents
[Installation](#installation) · [Quickstart](#quickstart) · [Examples](#in-practice) ·
[Features](#features) ·
[LLM workflows](#built-for-llms-and-coding-agents) · [Framework](#under-the-hood) ·
[Targets](#supported-targets) · [Documentation](#documentation) ·
[Contributing](#contributing)
## Installation
Download a prebuilt **v0.4.3** CLI for your platform—no Rust toolchain needed:
| macOS · Apple Silicon | [ARM64 `.tar.gz`](https://github.com/ShaneBreazeale/rsleigh/releases/download/v0.4.3/rsleigh-v0.4.3-aarch64-apple-darwin.tar.gz) |
| macOS · Intel | [x86-64 `.tar.gz`](https://github.com/ShaneBreazeale/rsleigh/releases/download/v0.4.3/rsleigh-v0.4.3-x86_64-apple-darwin.tar.gz) |
| Linux · x86-64 (glibc) | [x86-64 `.tar.gz`](https://github.com/ShaneBreazeale/rsleigh/releases/download/v0.4.3/rsleigh-v0.4.3-x86_64-unknown-linux-gnu.tar.gz) |
| Linux · ARM64 (glibc) | [ARM64 `.tar.gz`](https://github.com/ShaneBreazeale/rsleigh/releases/download/v0.4.3/rsleigh-v0.4.3-aarch64-unknown-linux-gnu.tar.gz) |
| Windows · x86-64 | [x86-64 `.zip`](https://github.com/ShaneBreazeale/rsleigh/releases/download/v0.4.3/rsleigh-v0.4.3-x86_64-pc-windows-msvc.zip) |
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](https://github.com/ShaneBreazeale/rsleigh/releases).
**Install v0.5.0 with Cargo.** With a Rust toolchain, installation is one command:
```bash
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:
```bash
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](docs/smt-backend.md).
## Quickstart
Replace `./sample.exe` with your target. Start with a capped JSON map:
```bash
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:
```bash
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:
```bash
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](docs/AGENTS-rsleigh.md) into your analysis
workspace to give an agent the workflow and evidence rules.
| `--agent-brief` | One JSON map: 25 functions by default, at most 50 findings, hashes, trust labels, warnings, and next commands |
| `FUNCTION --card --pcode [--json]` | A paginated view capped at 40 instructions and 120 P-code operations, with hashes and evidence references |
| `FUNCTION --card --pcode --decompile` | The same evidence plus up to 4,096 bytes of pseudocode |
| `--pcode-json FUNCTION` / `--ssa-json FUNCTION` | Structured instruction semantics or post-fold data flow for deeper reasoning |
| `--index DIR` / `--verify-index DIR` | Immutable generations with binary identity, artifact checksums, and atomic manifest publication |
| `--ssa-slice FUNCTION --return` | Bounded value dependencies through supported memory and helpers, with raw instruction origins |
| `--analysis-cache DIR` on a card or slice | Reusable complete analysis snapshots with identity checks and work counters |
| `--findings-ndjson` | Confidence- and stage-labeled records from supported analysis modes |
Ask a focused dependency question using addresses from your target's card:
```bash
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](docs/agent-workflow.md#bounded-backward-ssa-query).
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](docs/agent-workflow.md#reuse-analysis).
For a reusable binary-wide navigation map, build an index and query its files:
```bash
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)
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](docs/agent-workflow.md) for schemas, hard caps,
ranking, and the reporting contract.
## Explore, triage, investigate
Find an entry point into an unfamiliar binary:
```bash
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:
```bash
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](docs/features.md), [triage reference](docs/cli-triage.md),
and [SMT candidates](docs/smt-candidates.md) for the specialized workflows.
## In practice
| [Sony α7R II camera firmware](docs/showcase/firmware-investigations.md#sony-α7r-ii-camera-firmware) | Improved mixed ARM/Thumb function discovery in BIONZ X firmware and recovered functions from carved Windows updater components. |
| [TP-Link AX6000 v2 router firmware](docs/showcase/firmware-investigations.md#tp-link-ax6000-v2-router-firmware) | Resolved ARM32 network API imports in `tdpServer` and supported source-to-sink investigation across extracted router daemons. |
| [PyVMProtect crackme](docs/showcase/crackme3-pyvmprotect.md) | Helped recover `CTF{pyvm_r0cks}` by locating the Python entry point, annotating crypto, and classifying custom-VM handlers; emulation and Python scripts completed the solve. |
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.
```text
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.
| `rsleigh` / `rsleigh-generate` | SLEIGH parsing and Rust decoder generation; the root package also installs the CLI |
| `rsleigh-api` | Stable multi-architecture decoder and lifter API |
| `pcode-ir` | Shared instruction and P-code types |
| `rsleigh-fid` | Function identification from instruction fingerprints |
| `rsleigh-decompile` | Experimental IR, analysis passes, and pseudocode reconstruction |
| `rsleigh-cli` | Binary loading and command-line workflows |
### Embed in Rust
```toml
[dependencies]
rsleigh-api = "0.4"
```
```rust
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](docs/architectures.md) for
tested paths and known gaps.
For raw firmware, supply the architecture and image base on every command:
```bash
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](docs/cli-reference.md#raw-firmware-and-webassembly).
## Documentation
Start with the [documentation hub](docs/README.md),
[command guide](docs/cli-reference.md), and [output format reference](docs/output-formats.md).
| Agent setup and bounded analysis | [Agent instructions](docs/AGENTS-rsleigh.md) · [Workflow and schemas](docs/agent-workflow.md) |
| Analysis capabilities | [Feature catalog](docs/features.md) · [CLI triage](docs/cli-triage.md) |
| Structured findings | [NDJSON schema and confidence semantics](docs/findings-ndjson.md) |
| Architecture coverage | [Support matrix](docs/architectures.md) |
| Solver-assisted analysis | [SMT backend](docs/smt-backend.md) · [Candidate interpretation](docs/smt-candidates.md) |
| Pipeline and validation | [Decompiler passes](docs/decompiler-passes.md) · [Testing](docs/TESTING.md) |
| Agent RE results | [18-task evaluation](docs/agent-re-evaluation.md) · [Completed roadmap audit](docs/llm-re-completion-audit.md) |
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`:
```bash
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](docs/TESTING.md) for validation workflows,
including optional Ghidra comparisons and SMT calibration.
## License
[Apache-2.0](LICENSE). Bundled Ghidra `.slaspec` files are also Apache-2.0.