rustrip 0.1.14

Make stripped Rust binaries readable again: recover slice-string boundaries, demangle symbols, and reconstruct panic source locations from release/stripped ELF, PE, and Mach-O binaries.
Documentation
# rustrip

[![CI](https://github.com/rolanfreeman6-png/rustrip/actions/workflows/ci.yml/badge.svg)](https://github.com/rolanfreeman6-png/rustrip/actions/workflows/ci.yml)
[![Release](https://img.shields.io/github/v/release/rolanfreeman6-png/rustrip?label=release)](https://github.com/rolanfreeman6-png/rustrip/releases/latest)
[![crates.io](https://img.shields.io/crates/v/rustrip.svg)](https://crates.io/crates/rustrip)
[![docs.rs](https://docs.rs/rustrip/badge.svg)](https://docs.rs/rustrip)
[![Fuzz](https://github.com/rolanfreeman6-png/rustrip/actions/workflows/fuzz.yml/badge.svg)](https://github.com/rolanfreeman6-png/rustrip/actions/workflows/fuzz.yml)
[![CodeQL](https://github.com/rolanfreeman6-png/rustrip/actions/workflows/codeql.yml/badge.svg)](https://github.com/rolanfreeman6-png/rustrip/actions/workflows/codeql.yml)
[![SonarCloud](https://github.com/rolanfreeman6-png/rustrip/actions/workflows/sonar.yml/badge.svg)](https://sonarcloud.io/summary/new_code?id=rolanfreeman6-png_rustrip)
[![Codacy](https://github.com/rolanfreeman6-png/rustrip/actions/workflows/codacy.yml/badge.svg)](https://github.com/rolanfreeman6-png/rustrip/actions/workflows/codacy.yml)
[![Coverage](https://img.shields.io/badge/coverage-94%25-brightgreen.svg)](https://sonarcloud.io/summary/new_code?id=rolanfreeman6-png_rustrip)
[![Mutants v0.1.0 baseline](https://img.shields.io/badge/mutants-v0.1.0%20baseline%2081.0%25-green.svg)](https://github.com/rolanfreeman6-png/rustrip/actions/workflows/mutants.yml)
[![Ghidra](https://img.shields.io/badge/Ghidra%2011.2.1-headless%20verified-brightgreen.svg)](#verification)
[![MSRV](https://img.shields.io/badge/MSRV-1.85-orange.svg)](Cargo.toml)
[![License](https://img.shields.io/badge/license-MIT%20OR%20Apache--2.0-blue.svg)](#license)

**Make stripped Rust binaries readable again.**

`rustrip` recovers three classes of artifacts that disassembly tools miss
on stripped, release-mode Rust binaries:

1. **String boundaries** — `&str` fat pointers `(ptr, len)` are
   reconstructed into individual labeled strings instead of one
   stretching blob of bytes.
2. **Demangled symbol names** — both legacy `_ZN...E` and v0
   `_R...` mangling, including generic-parameter context, are rendered
   as `core::fmt::write` instead of
   `<core::fmt::Write as core::fmt::Write>::write_fmt`.
3. **Panic site source paths** &mdash; every `core::panic::Location` is
   recovered as `path/to/source.rs:line:col`, letting you map a binary
   back to its source tree.

Output goes to a CLI table, JSON, or a Ghidra / Binary Ninja Python
script that re-applies the annotations to whichever view you open it in.

---

## Demo

![rustrip terminal demo](docs/rustrip-demo.gif)

```text
$ rustrip target/release/rustrip.exe

  vaddr               kind     label
  ------------------  -------  --------------------------------------------------------
  0x1400b87d0         panic    /rustc/.../library/std/src/io/stdio.rs:854:20
  0x1400b9728         string   /rustc/.../library/alloc/src/wtf8/mod.rs
  0x1400b9888         string   /rustc/.../library/alloc/src/fmt.rs
  0x1400b9b40         string   BOLD
  0x1400b9b48         string   DIMMED
  0x1400b9b52         string   ITALIC
  0x1400b9b69         string   UNDERLINE
  0x1400b9b93         string   DOTTED_UNDERLINE
  ...
  0x1400c2100         symbol   rustrip::binary::Binary::parse
  0x1400c2280         symbol   rustrip::analyzers::strings::StringsAnalyzer::analyze
  0x1400c2450         symbol   rustrip::output::table::Table::render

  131 annotations recovered in 0.02s
```

> **Where symbol rows come from:** rustrip annotates in-file symbol names —
> ELF `.symtab`/`.dynsym`, Mach-O symtab, and PE exports. A stripped Windows
> PE *executable* normally has no in-file names (they live in a sidecar PDB),
> so `rustrip some.exe` recovers strings and panic sites but no symbol rows;
> PE *exports* (DLLs) and ELF/Mach-O symbols are annotated and demangled.

```text
$ rustrip target/release/my_app -f ghidra -o annotations.py
$ # paste annotations.py into Ghidra: Window > Script Manager > New > Python
```

---

## Install

```sh
cargo install rustrip
```

If crates.io still shows an older version, use the published binaries from the
latest GitHub release while the crates index catches up.

Or grab a prebuilt binary from
[Releases](https://github.com/rolanfreeman6-png/rustrip/releases/latest).

## Use

```sh
# Default: CLI table
rustrip path/to/binary

# JSON for scripting / piping
# `--output` creates a new file and refuses to overwrite an existing path.
# If rendering fails, rustrip retains the partial new file and reports its path.
rustrip foo.exe -f json -o foo.json

# Ghidra script (paste into Script Manager)
rustrip foo.exe -f ghidra -o foo_ghidra.py

# Binary Ninja script (paste into Python console)
rustrip foo.exe -f binja  -o foo_binja.py

# Read from stdin
# File and stdin input are bounded to 64 MiB.
cat suspicious.bin | rustrip - -f json

# Skip analyzers you don't need
rustrip foo.exe --no-strings --no-symbols

# Limit string recovery length
rustrip foo.exe --max-string-len 256
```

Open the generated script in Ghidra
(`Window > Script Manager > New > Python > paste`),
or in Binary Ninja's Python console, and run it on the open view.

---

## How it works

```
                    rustrip pipeline

  ┌─────────────┐     ┌──────────┐     ┌──────────────┐     ┌────────────┐
  │   goblin    │────▶│  Binary  │────▶│  Analyzers   │────▶│  Output    │
│ ELF/PE/Mach-O│    │  vaddr↔  │     │  strings     │     │  table     │
  │   parser    │     │  offset  │     │  symbols     │     │  json      │
  └─────────────┘     │  readers │     │  panics      │     │  ghidra    │
                      └──────────┘     └──────────────┘     │  binja     │
                                                             └────────────┘
```

- **`binary.rs`** &mdash; goblin-backed model with `vaddr <-> file-offset`
  translation and size-aware readers (`read_ptr`, `read_at_vaddr`).
  All pointer arithmetic uses `checked_add` &mdash; malicious binaries
  with `u64::MAX` vaddrs can't overflow.
- **`analyzers/`** &mdash; independent passes. Each walks the binary and
  emits typed annotations. Add a new analyzer without touching the others.
- **`output/`** &mdash; backends receive only the merged annotation list
  and render it. Add a new backend without touching analyzers.

The architecture is intentionally narrow: only data analysis, no full
disassembly in v0.1. That keeps the tool fast (sub-second on multi-MB
binaries) and reliable on stripped output where disassembly is messy.

---

## Verification

rustrip is verified by **15 free tools** across **9 GitHub Actions workflows**:

| Tool | What it checks | Result |
|---|---|---|
| `cargo test` | 287 declared: 287 run on Unix, 286 on Windows (one Unix-only) | **0 failed** |
| `cargo clippy` | Lints (pedantic + nursery) | **0 warnings** |
| `cargo fmt` | Format consistency | **0 diffs** |
| `cargo audit` | Dependency vulnerabilities | **0 advisories** (49 deps) |
| `cargo-deny` | Supply chain: licenses + bans | **all ok** |
| `cargo-mutants` | Integrated-source full workflow is non-gating; targeted output/analyzer subset | **70 caught, 0 missed, 6 unviable** |
| `cargo-fuzz` | Coverage-guided fuzzing (6 targets) | **0 crashes** |
| `cargo-llvm-cov` | Line + function coverage | **94%** lines, **98%** functions |
| `cargo-nextest` | Flaky test detection (3 retries) | **0 flaky** |
| **MIRI** | Undefined behavior detection | **0 UB** |
| **CodeQL** | SAST (GitHub) | **0 alerts** |
| **semgrep** | Custom SAST rules | **0 ERROR findings** |
| **SonarCloud** | Code quality + coverage dashboard | [link]https://sonarcloud.io/summary/new_code?id=rolanfreeman6-png_rustrip |
| **Codacy** | Second-opinion static analysis dashboard | [link]https://github.com/rolanfreeman6-png/rustrip/actions/workflows/codacy.yml |
| **Ghidra 11.2.1** | Headless import + generated annotation script | **128 comments, 301 labels, 0 failures** |

The core build/test workflow runs on **Linux, Windows, and macOS** for pushes
to `main`, PRs targeting `main`, its weekly schedule, and manual dispatches.
Fuzzing is nightly or manual, mutation testing also runs weekly, and releases
run only for version tags.

Current mutation status is tracked as a quality signal, not a release gate.
The latest full GitHub run completed with artifacts and warnings for remaining
missed/time-budgeted mutants. A focused local rerun after the v0.1.9 tests
showed the output/analyzer subset at **70 caught / 0 missed / 6 unviable**, and
the binary/property subset at **151 caught / 74 missed / 4 timeout / 4 unviable**.
The remaining work is concentrated in synthetic malformed ELF/PE/Mach-O
preflight fixtures.

The parser also has a benign synthetic corpus smoke test for popular container
formats: ELF32/i386, ELF64/x86_64, PE32/i386, PE32+/x86_64, Mach-O32/i386,
and Mach-O64/x86_64. The corpus is byte-generated inside tests, never executed,
and validates parse + analyzer + JSON/Table/Ghidra/Binary Ninja rendering.

### A bug this suite actually caught

Verification isn't just a badge wall. In `v0.1.1`, adversarial-input testing
found a real script-injection bug before it shipped to a tagged release:

> Recovered strings were embedded into Ghidra/Binary Ninja scripts as Python
> **raw** literals (`r'''...'''`). Raw strings can't end in a backslash — and
> a recovered `&str` ending in `\` (trivial in a Windows path, and trivially
> craftable in a hostile binary) desynced the closing quote and corrupted the
> *entire* generated script, silently dropping every annotation.

Fixed by switching both backends to fully-escaped normal string literals,
then verified end-to-end by compiling the generated scripts under CPython —
see [`CHANGELOG.md`](CHANGELOG.md#011---2026-07-05). This is exactly the
class of bug `cargo-fuzz` and the property/metamorphic suites exist to catch
on a tool whose whole job is parsing untrusted, potentially adversarial
binaries.

---

## Roadmap

- **v0.1** (now): string-slice recovery, symbol demangling, panic-site
  recovery. ELF, PE, Mach-O. CLI + table / JSON / Ghidra / Binary Ninja.
- **v0.2**: instruction-aware slice recovery via `iced-x86`
  (catches slices that aren't stored as static `(ptr, len)` pairs).
- **v0.3**: enum discriminant and monomorphized generic-type recovery.
- **v1.0**: native Ghidra and Binary Ninja plugins; type propagation.

---

## Reliability & threat model

rustrip is intended for reverse-engineering and malware triage. It must
not panic on adversarial input. The pipeline returns an empty or
parser-error result rather than crashing &mdash; verified by 6 fuzz
targets with a nightly budget of 4 hours per target.

---

## Contributing

PRs welcome. See [CONTRIBUTING.md](CONTRIBUTING.md). Checks triggered for the
PR must pass before review; scheduled fuzzing and tag-only releases do not run
on pull requests.

---

## License

MIT OR Apache-2.0 &mdash; pick whichever you prefer.