Skip to main content

Crate rf_chain

Crate rf_chain 

Source
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 GadgetAddr word’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) and ropmakerx86.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§

ChainWord
One machine word of the chain (8 bytes on x64, 4 on x86).
GadgetRef
A gadget referenced by the chain.
RopChain
A generated ROP chain in target-independent form.
StackAccounting
The outcome of the static stack-word accounting walk (CHLX-04).

Enums§

ChainError
Structured chain-building failure. Builders never panic and never emit partial garbage: any missing gadget or violated invariant is an Err.
WordKind
What a chain word is for.
WordRole
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§

ChainInvariant
Per-target invariant hook (Phase 4b extension point). Receives the full chain; returns Err to reject it. Example for Phase 4b (Win64): “rsp must be 16-byte aligned at the VirtualProtect call site”.