# rustrip
[](https://github.com/rolanfreeman6-png/rustrip/actions/workflows/ci.yml)
[](https://github.com/rolanfreeman6-png/rustrip/releases/latest)
[](https://crates.io/crates/rustrip)
[](https://docs.rs/rustrip)
[](https://github.com/rolanfreeman6-png/rustrip/actions/workflows/fuzz.yml)
[](https://github.com/rolanfreeman6-png/rustrip/actions/workflows/codeql.yml)
[](https://sonarcloud.io/summary/new_code?id=rolanfreeman6-png_rustrip)
[](https://github.com/rolanfreeman6-png/rustrip/actions/workflows/codacy.yml)
[](https://sonarcloud.io/summary/new_code?id=rolanfreeman6-png_rustrip)
[](https://github.com/rolanfreeman6-png/rustrip/actions/workflows/mutants.yml)
[](#verification)
[](Cargo.toml)
[](#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** — 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

```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.
# 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`** — goblin-backed model with `vaddr <-> file-offset`
translation and size-aware readers (`read_ptr`, `read_at_vaddr`).
All pointer arithmetic uses `checked_add` — malicious binaries
with `u64::MAX` vaddrs can't overflow.
- **`analyzers/`** — independent passes. Each walks the binary and
emits typed annotations. Add a new analyzer without touching the others.
- **`output/`** — 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**:
| `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 — 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 — pick whichever you prefer.