Skip to main content

Crate rf_classify

Crate rf_classify 

Source
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:

archdecodermetadata
x86 / x64iced-x86 InstructionInfoFactoryfull
ARM, ARM64, MIPS, PPC, SPARC, RISC-Vcapstone detail mode (rf_scan::Detailer)full
anything whose bytes no capstone mode reproducesdisassembly textbest 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 RankKey is best-first.
Transfer
One value movement inside a gadget: dst <- src.

Enums§

Class
Semantic classes (TAXONOMY.md table). Other is 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.
TerminatorClass
The nine-way terminator classification the query layer filters on.
TerminatorTarget
How the terminating control transfer picks its target.
ValueDst
Where a value went.
ValueSrc
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_score plus the two terms CLS-07 names as missing:
rank_key
Build the RankKey for one classified gadget.
usability
Usability tier, 0..=3 — the dimension that makes ranking work (CLS-07).