Expand description
rf-classify — semantic gadget classification and the ranking function (Phase 5, PLAN sec. 5.1; Phase 3 remediation for CLS-02..CLS-13, ECO-05).
The decision rules live in TAXONOMY.md; rule
numbers (R1-R13) are cited inline.
Three decode paths, one rule set:
| arch | decoder | metadata |
|---|---|---|
| x86 / x64 | iced-x86 InstructionInfoFactory | full |
| ARM, ARM64, MIPS, PPC, SPARC, RISC-V | capstone detail mode (rf_scan::Detailer) | full |
| anything whose bytes no capstone mode reproduces | disassembly text | best effort, low_confidence |
Before this release the middle row did not exist: cs::open never called
set_detail(true) (ECO-05), so eight of the ten supported architectures
fell through to the text path, regs_written was populated by splitting
the operand string on , — which is where {r4 and #0x12e44 came from
(CLS-05) — and the memory test was operands.contains('['), which is
false for every off(reg) architecture, so MIPS, PowerPC and RISC-V
reported zero mem-read, zero mem-write and zero stack-pivot across
an entire binary (CLS-04).
§Ranking (CLS-07)
quality_score alone cannot order gadgets: it is a function of two
integers that are both tiny for almost every gadget, so 92 % of a real
binary ties at 100. usability adds the dimension that actually
separates pop rdi ; ret from retf 0xce39 — what the gadget’s
terminator is and whether it loads a register off the stack — and
rank_key is the full order the CLI and the MCP server sort by.
§Getting started
One gadget in, one Classification out. The interesting part is not
the label — it is the semantic fields underneath it, which are what let
you ask “a gadget that loads rdi from the stack and clobbers neither rsi
nor rdx” without re-parsing disassembly text.
use rf_classify::{classify, Class, Terminator};
use rf_core::{Arch, Endianness, RawBinary};
use rf_scan::{scan_binary, ScanOptions};
// `pop rdi ; ret`
let image = RawBinary::new(&[0x5f, 0xc3], Arch::X64, Endianness::Little);
let gadgets = scan_binary(&image, &ScanOptions { depth: 4, ..ScanOptions::default() })?;
let g = gadgets.iter().find(|g| g.text() == "pop rdi ; ret").expect("pop rdi ; ret");
let c = classify(g, Arch::X64);
assert_eq!(c.primary, Class::RegWrite);
assert_eq!(c.terminator, Terminator::Ret);
assert_eq!(c.regs_written, ["rdi"]);
assert_eq!(c.regs_from_stack, ["rdi"]);
// The stack pointer moves 16 bytes: 8 for the pop, 8 for the return.
assert_eq!(c.stack_delta, Some(16));§Asking a real question
The predicates on Classification are the query vocabulary both front
ends expose (--set-reg, --from-stack, --no-clobber, --terminator),
so a filter written against them means the same thing as the flag:
use rf_classify::{Classifier, TerminatorClass};
use rf_core::{Arch, Endianness, RawBinary};
use rf_scan::{scan_binary, ScanOptions};
// `pop rdi ; ret`, `pop rsi ; ret`, `xor eax, eax ; ret`
let bytes = [0x5f, 0xc3, 0x5e, 0xc3, 0x31, 0xc0, 0xc3];
let image = RawBinary::new(&bytes, Arch::X64, Endianness::Little);
let gadgets = scan_binary(&image, &ScanOptions { depth: 4, ..ScanOptions::default() })?;
// One classifier for the whole listing: it holds the open decoders.
let cls = Classifier::new(Arch::X64);
let hits: Vec<String> = gadgets
.iter()
.filter(|g| {
let c = cls.classify(g);
c.sets_reg("rdi")
&& c.reg_from_stack("rdi")
&& !c.clobbers_any(["rsi", "rdx"])
&& c.terminator_class() == TerminatorClass::Ret
})
.map(|g| g.text())
.collect();
assert_eq!(hits, ["pop rdi ; ret"]);§Ranking
use rf_classify::{classify, rank_key};
use rf_core::{Arch, Endianness, RawBinary};
use rf_scan::{scan_binary, ScanOptions};
// `pop rdi ; ret` and a bare `ret`.
let image = RawBinary::new(&[0x5f, 0xc3], Arch::X64, Endianness::Little);
let mut gadgets = scan_binary(&image, &ScanOptions { depth: 4, ..ScanOptions::default() })?;
gadgets.sort_by_key(|g| rank_key(&classify(g, Arch::X64), g));
// RankKey orders best-first, so the useful gadget comes first.
assert_eq!(gadgets[0].text(), "pop rdi ; ret");§Semver policy
Covered by semver from 1.0: the fields of Classification and its
predicate methods, the Class, Terminator and TerminatorClass
variant sets and their Class::name spellings, and the signatures of
classify, quality_score, usability and rank_key.
Not covered, and free to change in a minor release: the numeric
output of quality_score / quality_score_full and the tier
boundaries of usability — these are a heuristic that is expected to
be re-tuned against measured precision, so compare ranks, never absolute
scores; and which class a particular gadget earns, since a rule fix
changes it (that is what TAXONOMY.md’s rule numbers are for — cite the
rule, not the outcome). Adding a Class or Terminator variant is a
minor release. Pin rf-classify = "1".
See docs/API-STABILITY.md in the repository for the workspace-wide
statement.
Structs§
- Classification
- Per-gadget semantic classification (R1-R13).
- Classifier
- A reusable classifier for one architecture.
- RankKey
- The default gadget order: ascending
RankKeyis best-first. - Transfer
- One value movement inside a gadget:
dst <- src.
Enums§
- Class
- Semantic classes (TAXONOMY.md table).
Otheris the fallback for gadgets with no labeled instruction (pure control flow, nop). - Terminator
- How a gadget hands control on — the single most important thing about it for chain construction, and the field the MCP surface filters on.
- Terminator
Class - The nine-way terminator classification the query layer filters on.
- Terminator
Target - How the terminating control transfer picks its target.
- Value
Dst - Where a value went.
- Value
Src - Where a value came from.
Functions§
- classify
- Classify one gadget.
- quality_
score - R12 (revised for CLS-07):
max(0, 100 - 15*|side_effects - 1| - 3*(n_insns - 2)). - quality_
score_ full quality_scoreplus the two terms CLS-07 names as missing:- rank_
key - Build the
RankKeyfor one classified gadget. - usability
- Usability tier, 0..=3 — the dimension that makes ranking work (CLS-07).