Skip to main content

Classification

Struct Classification 

Source
pub struct Classification {
Show 18 fields pub primary: Class, pub labels: Vec<Class>, pub regs_written: Vec<String>, pub regs_read: Vec<String>, pub regs_from_stack: Vec<String>, pub side_effects: usize, pub mem_pointer_deps: usize, pub mid_branches: usize, pub quality: i32, pub dispatcher: bool, pub terminator: Terminator, pub terminator_target: TerminatorTarget, pub stack_delta: Option<i64>, pub transfers: Vec<Transfer>, pub sets: Vec<String>, pub clobbers: Vec<String>, pub privileged: bool, pub low_confidence: bool,
}
Expand description

Per-gadget semantic classification (R1-R13).

Fields§

§primary: Class

Primary class: class of the last side-effecting instruction (R10).

§labels: Vec<Class>

Full multi-label set (R9), sorted by name for determinism.

§regs_written: Vec<String>

Registers written by the gadget (R1-normalized: implicit stack-pointer effects of push/pop/call/ret excluded; hardwired-zero registers, float/vector/condition registers and the program counter excluded), lowercase and sigil-free ($sp -> sp, %o0 -> o0), deduped, in first-appearance order.

§regs_read: Vec<String>

Registers the gadget reads, normalized the same way as Classification::regs_written.

§regs_from_stack: Vec<String>

The subset of regs_written whose value comes off the stack — a pop, or a load whose base register is the stack pointer. This is the property that makes a gadget controllable from the chain payload, and it is what separates usability tier 3 from tier 2.

§side_effects: usize

Instructions earning at least one label (R11).

§mem_pointer_deps: usize

Memory operands whose base or index register must already hold an attacker-controlled pointer before the gadget is usable — an add byte ptr [rax], al needs rax set up first, an absolute or RIP-relative operand does not. Counted per instruction.

§mid_branches: usize

Conditional branches sitting in the MIDDLE of the gadget: the tail executes only if the flags happen to be right, so the gadget’s effect is not guaranteed. Counted per instruction.

§quality: i32

Deterministic quality score (R12); higher = cleaner gadget.

§dispatcher: bool

JOP/COP dispatcher heuristic (R8) — also reflected as the dispatcher label when it fires.

§terminator: Terminator

How the gadget hands control on.

§terminator_target: TerminatorTarget

How the terminating transfer picks its target — the register/memory distinction Terminator deliberately does not carry, so that the v0.3 spellings of terminator stayed byte-identical (CLS-09). Combined with terminator by Classification::terminator_class.

Default for the text path and for gadgets with no terminator: TerminatorTarget::Implicit.

§stack_delta: Option<i64>

Net change of the stack pointer across the whole gadget, in bytes, or None when the effect is not provably constant (CLS-09).

The terminating transfer is included, because the payload bytes it consumes are payload bytes: pop rdi ; ret is Some(16) on x86-64, ret alone is Some(8), add rsp, 0x28 ; ret is Some(0x30). This is what a concrete execution of the gadget would leave in rsp, which is how tests/ground-truth/oracle_unicorn.py measures it.

None is a real answer. A confident wrong stack delta silently corrupts a chain layout, so every gadget whose rsp effect depends on a register, on memory, or on a path not taken reports None rather than a number: xchg rsp, rax, pop rsp, mov rsp, rbp, add rsp, rax, and rsp, -16, leave (rsp becomes rbp+8), iret* (the pop count depends on a privilege change), add esp, 8 in 64-bit code (a 32-bit write truncates rsp), and any gadget with a branch before its last instruction or a byte that does not decode.

Which architectures compute it.

archcomputed
archcomputed for
——
x86, x86-64fully, via iced-x86: the pop/push family, call, ret, ret imm16, retf, pusha/popa, pushf/popf, enter, inc/dec rsp, add/sub rsp, imm, lea rsp, [rsp+d]
ARM, ARM-Thumbpush {…} / pop {…} register lists, and add/sub sp, sp, #imm. ldm/stm are None, because their base register is printed inside the same operand list as the transfer list
ARM64add/sub sp, sp, #imm only. ldp/stp/ldr/str through sp are None: rf_scan::InsnDetail does not carry capstone’s write-back flag, so ldr x0, [sp], #16 and ldr x0, [sp, #16] are indistinguishable here and they differ by 16
MIPS 32/64, RISC-V 32/64addi(u)/daddi(u)/addiw/c.addi/c.addi16sp on the stack pointer. Loads and stores through the stack pointer contribute 0, which is sound because neither ISA has a write-back addressing mode
PowerPC 32/64addi r1, r1, imm and the stwu/stdu/lwzu/… update forms based on r1. The indexed update forms (stwux) are None; plain r1-based loads and stores contribute 0
SPARC (all)never, not even 0 — save/restore rotate a register window, so they move the stack pointer without naming it and “this instruction does not mention %sp” proves nothing
any gadget on the text fallback pathnever — no decoder metadata

On every architecture, anything not in that list that names the stack pointer as an operand, or reaches memory through it, yields None.

§transfers: Vec<Transfer>

Value movements inside the gadget, in program order (CLS-09).

This is the field --from-stack is built on: it distinguishes rdi <- [rsp+8] from rdi <- rax from rdi <- [rbx+0x10] (naming rbx as the register that must already be attacker-controlled) from rdi <- 0x1234. A register written twice appears twice; the last entry for a destination is the one that survives.

Empty on the text fallback path, and for instruction shapes the analysis does not model.

§sets: Vec<String>

Registers the gadget writes with a value the chain payload decides — a pop, an rsp-relative load, a folded constant, or any known function of those (CLS-09).

Names are architectural full-width (rax in 64-bit code, eax in 32-bit, x0 rather than w0 on ARM64), because mov al, [rsp] controls al but not rax and the question a chain author asks is about rax. sets and Classification::clobbers partition the full-width registers the gadget writes; neither ever contains the stack pointer, whose movement is Classification::stack_delta.

§clobbers: Vec<String>

Registers the gadget writes with a value the chain payload does not decide — it came from an incoming register, from non-stack memory, or from the incoming flags (CLS-09).

This is what --no-clobber rsi,rdx filters on, and it is a strictly stronger statement than “the register appears in regs_written”: pop rsi ; ret writes rsi and clobbers nothing, mov rsi, rax ; ret writes rsi and clobbers it. When a clobber has a known source, the corresponding Transfer names it, so a chain builder can decide to control the source instead of rejecting the gadget.

§privileged: bool

The gadget contains a privileged or undefined instruction (hlt, ud2, int3, cli, in/out, lgdt, …): it faults or traps in user mode, so it cannot appear in a chain.

§low_confidence: bool

True when the classification came from disassembly TEXT rather than decoder metadata (R13) — now only reachable when no capstone mode reproduces the gadget’s recorded text.

Implementations§

Source§

impl Classification

Source

pub fn terminator(&self) -> Terminator

How the gadget hands control on. (Accessor mirroring the field, so consumers that hold a &Classification behind an abstraction do not need field access.)

Source

pub fn terminator_class(&self) -> TerminatorClass

The nine-way ret / ret-imm / jmp-reg / jmp-mem / call-reg / call-mem / syscall / far / other classification the query layer filters on (CLS-09).

Derived from Classification::terminator and Classification::terminator_target rather than stored, so there is one source of truth. A direct jmp 0x400340 or call 0x401120 is Other: neither is reachable from a chain without the address being what you wanted anyway.

Source

pub fn sets_reg(&self, reg: &str) -> bool

Does the gadget write reg with a value the chain payload decides? The predicate behind --set-reg.

reg is matched case-insensitively against the full-width names in Classification::sets.

Source

pub fn clobbers_reg(&self, reg: &str) -> bool

Does the gadget write reg with a value the chain payload does not decide? The predicate behind --no-clobber.

Source

pub fn clobbers_any<I, S>(&self, regs: I) -> bool
where I: IntoIterator<Item = S>, S: AsRef<str>,

Does the gadget clobber any of regs? --no-clobber rsi,rdx is !c.clobbers_any(["rsi", "rdx"]).

Source

pub fn reg_from_stack(&self, reg: &str) -> bool

Is reg’s final value loaded straight off the chain payload — a pop, or a load whose base is the stack pointer? The predicate behind --from-stack, and strictly stronger than Classification::sets_reg: xor rdi, rdi ; ret sets rdi without taking it from the stack.

Uses the last transfer that writes reg, so pop rdi ; mov rdi, rax ; ret is not from-stack.

Source

pub fn stack_offset_of(&self, reg: &str) -> Option<i64>

The payload offset, in bytes from the stack pointer at gadget entry, that supplies reg — Some(0) for rdi in pop rdi ; pop rsi ; ret and Some(8) for rsi. None when reg is not loaded from the stack or the offset is not constant.

Source

pub fn last_transfer_to(&self, reg: &str) -> Option<&Transfer>

The last Transfer whose destination is register reg.

Source

pub fn memory_writes(&self) -> impl Iterator<Item = &Transfer>

Every memory write the gadget performs, as (destination, source) pairs — the write-what-where primitive a chain builder looks for.

Source

pub fn reads_reg(&self, reg: &str) -> bool

Is reg an input of this gadget? The predicate behind --reads-reg / reads_reg.

No single field answers this, which is why it lives here rather than being re-derived per front end — it was, and the two spellings disagreed by 741 gadgets on elf-Linux-x64 at depth 4 because one of them left the terminator out. Three sources are unioned:

  1. Classification::regs_read, the v0.3 list. It keeps the operand’s spelling (al, edi), so on its own reads_reg("rax") would miss add al, cl.
  2. The transfer relations, which carry full-width names: a register read as a value source (ValueSrc::Register), as an address component (base or index, on either side), as a declared dependency (Transfer::needs), or as the destination of a read-modify-write.
  3. The terminator’s own target register. jmp rax reads rax — it is the branch target, and a chain builder asking which gadgets consume rax must be given the JOP dispatchers.

Matching is case-insensitive on every source.

Trait Implementations§

Source§

impl Clone for Classification

Source§

fn clone(&self) -> Self

Returns a duplicate of the value. Read more
1.0.0 (const: unstable) · Source§

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source. Read more
Source§

impl Debug for Classification

Source§

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter. Read more
Source§

impl Serialize for Classification

Source§

fn serialize<__S>(&self, __serializer: __S) -> Result<__S::Ok, __S::Error>
where __S: Serializer,

Serialize this value into the given Serde serializer. Read more

Auto Trait Implementations§

Blanket Implementations§

Source§

impl<T> Any for T
where T: 'static + ?Sized,

Source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
Source§

impl<T> Borrow<T> for T
where T: ?Sized,

Source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
Source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

Source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
Source§

impl<T> CloneToUninit for T
where T: Clone,

Source§

unsafe fn clone_to_uninit(&self, dest: *mut u8)

🔬This is a nightly-only experimental API. (clone_to_uninit)
Performs copy-assignment from self to dest. Read more
Source§

impl<T> From<T> for T

Source§

fn from(t: T) -> T

Returns the argument unchanged.

Source§

impl<T, U> Into<U> for T
where U: From<T>,

Source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

Source§

impl<T> IntoEither for T

Source§

fn into_either(self, into_left: bool) -> Either<Self, Self> ⓘ

Converts self into a Left variant of Either<Self, Self> if into_left is true. Converts self into a Right variant of Either<Self, Self> otherwise. Read more
Source§

fn into_either_with<F>(self, into_left: F) -> Either<Self, Self> ⓘ
where F: FnOnce(&Self) -> bool,

Converts self into a Left variant of Either<Self, Self> if into_left(&self) returns true. Converts self into a Right variant of Either<Self, Self> otherwise. Read more
Source§

impl<T> Pointable for T

Source§

const ALIGN: usize

The alignment of pointer.
Source§

type Init = T

The type for initializers.
Source§

unsafe fn init(init: <T as Pointable>::Init) -> usize

Initializes a with the given initializer. Read more
Source§

unsafe fn deref<'a>(ptr: usize) -> &'a T

Dereferences the given pointer. Read more
Source§

unsafe fn deref_mut<'a>(ptr: usize) -> &'a mut T

Mutably dereferences the given pointer. Read more
Source§

unsafe fn drop(ptr: usize)

Drops the object pointed to by the given pointer. Read more
Source§

impl<T> ToOwned for T
where T: Clone,

Source§

type Owned = T

The resulting type after obtaining ownership.
Source§

fn to_owned(&self) -> T

Creates owned data from borrowed data, usually by cloning. Read more
Source§

fn clone_into(&self, target: &mut T)

Uses borrowed data to replace owned data, usually by cloning. Read more
Source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

Source§

type Error = !

The type returned in the event of a conversion error.
Source§

fn try_from(value: U) -> Result<T, !>

Performs the conversion.
Source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

Source§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
Source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.