Expand description
rf-chain — ROP chain builders (Phase 4a, PLAN.md §6.2).
Chain IR first (the review-driven design): builders produce a
structured RopChain — a Vec<ChainWord> where every word knows its
kind, its comment, and which gadget it came from — and renderers turn
the IR into ROPgadget-compatible Python exploit text, JSON, or raw
little-endian bytes. ROPgadget’s stdout-text design is why nothing can
consume its chains programmatically; the IR is the fix.
Invariants are checked at build/validation time and reported as
structured ChainErrors, never panics:
- every
GadgetAddrword’s value is the vaddr of an actually-reported gadget (checked against the scan’s vaddr universe); - every non-gadget word (
Immediate/DataAddr/Padding) must be badbyte-free when bad bytes are configured — bad bytes are a property of the final packed word (PLAN.md §6.4); - per-target invariant hooks (
ChainInvariant) are the Phase 4b extension point — the Win64 16-byte stack-alignment invariant lands there; Linux execve needs no extra invariants.
§Getting started
use rf_chain::{build_linux, DataSection, LinuxChainOpts, WordKind};
use rf_core::{Arch, Binary, Image};
use rf_scan::{scan_binary, ScanOptions};
let elf = Binary::parse(bytes)?;
let gadgets = scan_binary(&elf, &ScanOptions::default())?;
let data: Vec<DataSection> = elf
.sections()
.iter()
.filter(|s| !s.executable)
.map(|s| DataSection { name: s.name.clone(), vaddr: s.vaddr, writable: s.writable })
.collect();
let chain = build_linux(
&gadgets,
&data,
Image::arch(&elf),
"elf",
&[],
&LinuxChainOpts::default(),
)?;
// The IR is the point: every word knows what it is.
assert!(chain.words.iter().any(|w| w.kind == WordKind::GadgetAddr));
let _python = chain.to_python();
let _json = chain.to_json();
let _bytes = chain.to_bytes();§Semver policy
Covered by semver from 1.0: the signatures of build_linux,
build_windows_virtualprotect, plan_linux and plan_windows;
the fields of RopChain, ChainWord, GadgetRef and
plan::ChainPlan; the WordKind and ChainError variant sets;
and the --chain target names in LinuxTarget::NAMES.
Not covered, and free to change in a patch release: which gadgets
a chain picks and therefore its exact byte payload — a better strategy
is a bug fix, and the emulator harness (tests/emulate.py) is what
holds the behaviour, not the byte sequence; the exact Python script text
beyond the ROPgadget-compatible header; and every error and comment
string. Adding a WordKind variant or a chain target is a minor
release. Pin rf-chain = "1".
See docs/API-STABILITY.md in the repository for the workspace-wide
statement.
Re-exports§
pub use linux::plan_linux;pub use linux::build_linux;pub use linux::build_linux_execve;pub use linux::DataSection;pub use linux::LinuxChainOpts;pub use linux::LinuxTarget;pub use plan::ChainPlan;pub use plan::PlanAssumptions;pub use plan::Relaxation;pub use plan::Requirement;pub use plan::SatisfiedRequirement;pub use plan::Strategy;pub use windows::plan_windows;pub use windows::build_windows_virtualprotect;pub use windows::PeExport;pub use windows::WinChainOpts;
Modules§
- linux
- Linux execve chain builders — originally a faithful port of ROPgadget’s
ropchain/arch/ropmakerx64.py(syscall, 59 =__NR_execve) andropmakerx86.py(int 0x80, 11). The oracle’s shape is still here — write “/bin//sh” and a NULL word into a data section with a write-what-where gadget, load the three syscall arguments, set the syscall number, fire — but v0.5 replaced the oracle’s single hard-coded gadget recipe with a small planner, because the recipe failed outright on binaries where a chain is plainly constructible (CHLX-01). - plan
ECO-04: machine-readable chain feasibility.- windows
- Windows VirtualProtect / VirtualAlloc chain builders (PLAN sec. 6.2).
Structs§
- Chain
Word - One machine word of the chain (8 bytes on x64, 4 on x86).
- Gadget
Ref - A gadget referenced by the chain.
- RopChain
- A generated ROP chain in target-independent form.
- Stack
Accounting - The outcome of the static stack-word accounting walk (CHLX-04).
Enums§
- Chain
Error - Structured chain-building failure. Builders never panic and never emit
partial garbage: any missing gadget or violated invariant is an
Err. - Word
Kind - What a chain word is for.
- Word
Role - What consumed a stack word, as reconstructed by
RopChain::verify_stack_accounting.
Constants§
- PY_
COMMENT_ MAX - Maximum length of a comment rendered into the generated Python script.
Functions§
- arch_
name - Arch display name used in the IR (
"x86"/"x64"/ …). - py_
comment - Sanitise a string for use inside a
#comment of the generated Python script (ROB-01).
Type Aliases§
- Chain
Invariant - Per-target invariant hook (Phase 4b extension point). Receives the full
chain; returns
Errto reject it. Example for Phase 4b (Win64): “rsp must be 16-byte aligned at the VirtualProtect call site”.