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: ClassPrimary 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: usizeInstructions earning at least one label (R11).
mem_pointer_deps: usizeMemory 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: usizeConditional 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: i32Deterministic quality score (R12); higher = cleaner gadget.
dispatcher: boolJOP/COP dispatcher heuristic (R8) — also reflected as the
dispatcher label when it fires.
terminator: TerminatorHow the gadget hands control on.
terminator_target: TerminatorTargetHow 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.
| arch | computed |
|---|---|
| arch | computed for |
| — | — |
| x86, x86-64 | fully, 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-Thumb | push {…} / 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 |
| ARM64 | add/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/64 | addi(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/64 | addi 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 path | never — 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: boolThe 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: boolTrue 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
impl Classification
Sourcepub fn terminator(&self) -> Terminator
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.)
Sourcepub fn terminator_class(&self) -> TerminatorClass
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.
Sourcepub fn sets_reg(&self, reg: &str) -> bool
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.
Sourcepub fn clobbers_reg(&self, reg: &str) -> bool
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.
Sourcepub fn clobbers_any<I, S>(&self, regs: I) -> bool
pub fn clobbers_any<I, S>(&self, regs: I) -> bool
Does the gadget clobber any of regs? --no-clobber rsi,rdx is
!c.clobbers_any(["rsi", "rdx"]).
Sourcepub fn reg_from_stack(&self, reg: &str) -> bool
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.
Sourcepub fn stack_offset_of(&self, reg: &str) -> Option<i64>
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.
Sourcepub fn last_transfer_to(&self, reg: &str) -> Option<&Transfer>
pub fn last_transfer_to(&self, reg: &str) -> Option<&Transfer>
The last Transfer whose destination is register reg.
Sourcepub fn memory_writes(&self) -> impl Iterator<Item = &Transfer>
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.
Sourcepub fn reads_reg(&self, reg: &str) -> bool
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:
Classification::regs_read, the v0.3 list. It keeps the operand’s spelling (al,edi), so on its ownreads_reg("rax")would missadd al, cl.- 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. - The terminator’s own target register.
jmp raxreads 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
impl Clone for Classification
Source§impl Debug for Classification
impl Debug for Classification
Auto Trait Implementations§
impl Freeze for Classification
impl RefUnwindSafe for Classification
impl Send for Classification
impl Sync for Classification
impl Unpin for Classification
impl UnsafeUnpin for Classification
impl UnwindSafe for Classification
Blanket Implementations§
Source§impl<T> BorrowMut<T> for Twhere
T: ?Sized,
impl<T> BorrowMut<T> for Twhere
T: ?Sized,
Source§fn borrow_mut(&mut self) -> &mut T
fn borrow_mut(&mut self) -> &mut T
Source§impl<T> CloneToUninit for Twhere
T: Clone,
impl<T> CloneToUninit for Twhere
T: Clone,
Source§impl<T> IntoEither for T
impl<T> IntoEither for T
Source§fn into_either(self, into_left: bool) -> Either<Self, Self> ⓘ
fn into_either(self, into_left: bool) -> Either<Self, Self> ⓘ
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 moreSource§fn into_either_with<F>(self, into_left: F) -> Either<Self, Self> ⓘ
fn into_either_with<F>(self, into_left: F) -> Either<Self, Self> ⓘ
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