Skip to main content

rf_cache/
record.rs

1//! The one on-disk cache record, shared by rf-cli and rf-mcp.
2//!
3//! Before this crate existed there were two of these — `rf_cli::CacheFile`
4//! and `rf_mcp::CachedScan` — with two reconstruction functions, and the
5//! ROB-04 char-boundary panic lived in *both* of them. One record, one
6//! reconstruction, one [`CachedScan::validate`].
7
8use serde::{Deserialize, Serialize};
9
10use crate::hex::{decode_hex, encode_hex, is_hex_bytes, parse_hex_u64, MAX_GADGET_BYTES};
11
12/// Payload schema version. Bumped whenever the record shape changes; a
13/// mismatch is a miss, never a mis-parse. (The *key* carries its own
14/// schema version — see [`crate::make_key`] — so an old entry is not even
15/// looked up under a new key format.)
16pub const CACHE_FORMAT_VERSION: u32 = 2;
17
18/// Largest gadget text a cache entry may carry.
19pub const MAX_TEXT_BYTES: usize = 64 * 1024;
20/// Largest number of gadgets in one entry. The entry byte cap
21/// ([`crate::CacheLimits::max_entry_bytes`]) is the primary bound — it is
22/// enforced by `stat` before a byte is read — and this is the backstop for
23/// an entry that is small on disk but expands.
24pub const MAX_GADGETS_PER_ENTRY: usize = 10_000_000;
25/// Largest number of instructions in one gadget (`--depth` is bounded well
26/// below this).
27pub const MAX_INSNS_PER_GADGET: usize = 4096;
28/// Largest `prev` context, in bytes: `gadgets.py` captures at most 9.
29pub const MAX_PREV_BYTES: usize = 16;
30/// Cap on the small free-text fields (`arch`, `section`, `class`).
31pub const MAX_LABEL_BYTES: usize = 256;
32
33/// Fixed cost charged to every cached gadget by
34/// [`CachedGadget::heap_bytes`]: the struct itself plus the allocation
35/// headers for `vaddr`, `bytes` and `text`. MCP-DESIGN fix #5 part D
36/// specifies 48 bytes per gadget; keeping the constant named means the
37/// eviction weight can be re-derived rather than re-guessed.
38pub const GADGET_OVERHEAD_BYTES: usize = 48;
39
40/// Fixed cost charged to a whole entry (`Vec` header plus the `Arc` and
41/// map slot the cache holds it in).
42pub const SCAN_OVERHEAD_BYTES: usize = 128;
43
44/// The classifier's `Class::name()` values. `class: "../../etc"` in an
45/// entry is not a path — nothing joins it to anything — but an unknown
46/// class is still evidence the entry did not come from this program, so it
47/// is refused. `known_classes_match_rf_classify` keeps the list honest.
48pub const KNOWN_CLASSES: &[&str] = &[
49    "reg-write",
50    "stack-pivot",
51    "mem-read",
52    "mem-write",
53    "arithmetic",
54    "syscall",
55    "dispatcher",
56    "other",
57];
58
59fn is_false(b: &bool) -> bool {
60    !*b
61}
62
63/// One cached gadget.
64///
65/// The serialized shape is the union of what both front ends need, and
66/// every field either front end does not use is skipped when empty — so
67/// rf-mcp's response objects are byte-identical to what they were before
68/// this crate existed (`vaddr`, `bytes`, `text`, and the optional `arch`,
69/// `section`, `quality`, `class`).
70#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
71pub struct CachedGadget {
72    /// Address in hex, with or without a `0x` prefix. rf-mcp stores the
73    /// zero-padded display form; rf-cli stores bare hex.
74    pub vaddr: String,
75    /// Gadget bytes as lowercase hex.
76    pub bytes: String,
77    /// `insns.join(" ; ")` — what rf-mcp returns to the agent. Empty (and
78    /// then omitted) in an rf-cli entry, which carries `insns` instead:
79    /// storing both would put every instruction in the file twice, and
80    /// CLI-08 is a finding about how much disk this cache uses.
81    #[serde(default, skip_serializing_if = "String::is_empty")]
82    pub text: String,
83    /// The architecture the gadget was decoded as, for a fat container.
84    #[serde(default, skip_serializing_if = "Option::is_none")]
85    pub arch: Option<String>,
86    /// The `--section` the gadget's address falls in, when one was used.
87    #[serde(default, skip_serializing_if = "Option::is_none")]
88    pub section: Option<String>,
89    /// Phase 5 quality score (TAXONOMY.md R12), computed once at scan time.
90    #[serde(default, skip_serializing_if = "Option::is_none")]
91    pub quality: Option<i32>,
92    /// Phase 5 primary class.
93    #[serde(default, skip_serializing_if = "Option::is_none")]
94    pub class: Option<String>,
95    /// Instruction list. Present when the producer had it (rf-cli), so the
96    /// reconstruction does not have to re-split `text`.
97    #[serde(default, skip_serializing_if = "Option::is_none")]
98    pub insns: Option<Vec<String>>,
99    /// MIPS/SPARC delay slot flag.
100    #[serde(default, skip_serializing_if = "is_false")]
101    pub delay_slot: bool,
102    /// Hex of the section bytes preceding the gadget — `--callPreceded`
103    /// scans only.
104    #[serde(default, skip_serializing_if = "Option::is_none")]
105    pub prev: Option<String>,
106}
107
108impl Default for CachedGadget {
109    fn default() -> Self {
110        CachedGadget {
111            vaddr: "0".to_string(),
112            bytes: String::new(),
113            text: String::new(),
114            arch: None,
115            section: None,
116            quality: None,
117            class: None,
118            insns: None,
119            delay_slot: false,
120            prev: None,
121        }
122    }
123}
124
125impl CachedGadget {
126    /// The rf-cli flavour: everything the scanner produced, nothing the
127    /// classifier adds.
128    #[must_use]
129    pub fn from_scan_gadget(g: &rf_scan::Gadget) -> Self {
130        CachedGadget {
131            vaddr: format!("{:x}", g.vaddr),
132            bytes: g.bytes_hex(),
133            insns: Some(g.insns.clone()),
134            delay_slot: g.delay_slot,
135            prev: g.prev.as_ref().map(|p| encode_hex(p)),
136            ..CachedGadget::default()
137        }
138    }
139
140    /// Rebuild an [`rf_scan::Gadget`]. `None` for any record that does not
141    /// validate — the caller treats that as a cache miss.
142    ///
143    /// The producing anchor table is not recorded, and `Rop` is the
144    /// conservative reconstruction: `--cfg-aware` keeps ROP gadgets
145    /// unconditionally, so a wrong guess can never *narrow* a cached
146    /// result. (Plumbing the real table through the record is what
147    /// `--cfg-aware` on cached results would need; it is not free, because
148    /// it changes the stored shape for a flag that currently reads it.)
149    #[must_use]
150    pub fn to_scan_gadget(&self) -> Option<rf_scan::Gadget> {
151        Some(rf_scan::Gadget {
152            vaddr: parse_hex_u64(&self.vaddr)?,
153            bytes: decode_hex(&self.bytes, MAX_GADGET_BYTES)?,
154            insns: match &self.insns {
155                Some(i) => i.clone(),
156                // rf-mcp records carry the joined text and no list.
157                None if self.text.is_empty() => return None,
158                None => self.text.split(" ; ").map(str::to_string).collect(),
159            },
160            delay_slot: self.delay_slot,
161            prev: match &self.prev {
162                Some(p) => Some(decode_hex(p, MAX_PREV_BYTES)?),
163                None => None,
164            },
165            table: rf_scan::TableKind::Rop,
166        })
167    }
168
169    /// Retained heap size of this record, the eviction weight used by
170    /// [`crate::MemCache`] (MCP-05/ROB-07).
171    ///
172    /// It is an *estimate*, deliberately: the exact figure would need the
173    /// allocator's bucket sizes. What matters for a budget is that it is
174    /// proportional to what the process actually holds and never smaller
175    /// than the fixed per-record cost, so a million one-byte gadgets
176    /// cannot look free. `String`/`Vec` capacity is not tracked (these
177    /// records are built by `serde` and by `format!`, both of which land
178    /// close to length), so [`GADGET_OVERHEAD_BYTES`] carries the struct
179    /// itself plus the three unavoidable allocation headers.
180    #[must_use]
181    pub fn heap_bytes(&self) -> usize {
182        let opt = |s: &Option<String>| s.as_deref().map_or(0, str::len);
183        GADGET_OVERHEAD_BYTES
184            + self.vaddr.len()
185            + self.bytes.len()
186            + self.text.len()
187            + opt(&self.arch)
188            + opt(&self.section)
189            + opt(&self.class)
190            + opt(&self.prev)
191            + self
192                .insns
193                .as_ref()
194                .map_or(0, |v| v.iter().map(|i| i.len() + 24).sum::<usize>() + 24)
195    }
196
197    fn validate(&self) -> Result<(), String> {
198        if parse_hex_u64(&self.vaddr).is_none() {
199            return Err(format!(
200                "vaddr {:?} is not a hex address",
201                trunc(&self.vaddr)
202            ));
203        }
204        if !is_hex_bytes(&self.bytes, MAX_GADGET_BYTES) {
205            return Err(format!("bytes {:?} is not hex", trunc(&self.bytes)));
206        }
207        check_text("text", &self.text, MAX_TEXT_BYTES)?;
208        if self.insns.is_none() && self.text.is_empty() {
209            return Err("gadget has neither an instruction list nor text".to_string());
210        }
211        if let Some(insns) = &self.insns {
212            if insns.len() > MAX_INSNS_PER_GADGET {
213                return Err(format!("{} instructions in one gadget", insns.len()));
214            }
215            for i in insns {
216                check_text("insn", i, MAX_TEXT_BYTES)?;
217            }
218        }
219        if let Some(p) = &self.prev {
220            if !is_hex_bytes(p, MAX_PREV_BYTES) {
221                return Err(format!("prev {:?} is not hex", trunc(p)));
222            }
223        }
224        if let Some(a) = &self.arch {
225            check_text("arch", a, MAX_LABEL_BYTES)?;
226        }
227        if let Some(s) = &self.section {
228            check_text("section", s, MAX_LABEL_BYTES)?;
229        }
230        if let Some(q) = self.quality {
231            if !(0..=100).contains(&q) {
232                return Err(format!("quality {q} outside 0..=100"));
233            }
234        }
235        if let Some(c) = &self.class {
236            if !KNOWN_CLASSES.contains(&c.as_str()) {
237                return Err(format!("unknown class {:?}", trunc(c)));
238            }
239        }
240        Ok(())
241    }
242}
243
244/// One cached scan.
245#[derive(Debug, Clone, Serialize, Deserialize)]
246pub struct CachedScan {
247    /// [`CACHE_FORMAT_VERSION`]. Absent (0) in anything not written by this
248    /// crate, which fails [`CachedScan::validate`].
249    #[serde(default)]
250    pub version: u32,
251    /// The cached gadgets, in the order the scan produced them.
252    pub gadgets: Vec<CachedGadget>,
253    /// rf-mcp's `fallback_section_names` flag.
254    #[serde(default)]
255    pub fallback_names: bool,
256}
257
258impl Default for CachedScan {
259    fn default() -> Self {
260        CachedScan {
261            version: CACHE_FORMAT_VERSION,
262            gadgets: Vec::new(),
263            fallback_names: false,
264        }
265    }
266}
267
268impl CachedScan {
269    /// Build a record from an rf-scan listing (the rf-cli flavour: `insns`,
270    /// no rendered `text`).
271    #[must_use]
272    pub fn from_scan_gadgets(gadgets: &[rf_scan::Gadget]) -> Self {
273        CachedScan {
274            gadgets: gadgets.iter().map(CachedGadget::from_scan_gadget).collect(),
275            ..CachedScan::default()
276        }
277    }
278
279    /// Rebuild the scanner's gadget list. `None` if any record is
280    /// unusable, so a partly-corrupt entry is a miss rather than a
281    /// silently short result.
282    #[must_use]
283    pub fn to_scan_gadgets(&self) -> Option<Vec<rf_scan::Gadget>> {
284        self.gadgets
285            .iter()
286            .map(CachedGadget::to_scan_gadget)
287            .collect()
288    }
289
290    /// Retained heap size of the whole entry: the eviction weight for
291    /// [`crate::MemCache`]. Linear in the gadget count, which is exactly
292    /// the axis MCP-05's 2.57 GB grew along.
293    #[must_use]
294    pub fn heap_bytes(&self) -> usize {
295        SCAN_OVERHEAD_BYTES
296            + self
297                .gadgets
298                .iter()
299                .map(CachedGadget::heap_bytes)
300                .sum::<usize>()
301    }
302
303    /// ROB-04. Called on **every** deserialize, before any field is used.
304    /// Anything that fails is a clean miss plus a counter, never a panic
305    /// and never a served result.
306    pub fn validate(&self) -> Result<(), String> {
307        if self.version != CACHE_FORMAT_VERSION {
308            return Err(format!(
309                "record version {} (expected {CACHE_FORMAT_VERSION})",
310                self.version
311            ));
312        }
313        if self.gadgets.len() > MAX_GADGETS_PER_ENTRY {
314            return Err(format!("{} gadgets in one entry", self.gadgets.len()));
315        }
316        for (n, g) in self.gadgets.iter().enumerate() {
317            g.validate().map_err(|e| format!("gadget {n}: {e}"))?;
318        }
319        Ok(())
320    }
321}
322
323/// Reject control characters (including the NUL, newline and ANSI escapes
324/// that would let a poisoned entry rewrite a terminal) and cap the length.
325fn check_text(what: &str, s: &str, max: usize) -> Result<(), String> {
326    if s.len() > max {
327        return Err(format!("{what} is {} bytes (max {max})", s.len()));
328    }
329    if let Some(c) = s.chars().find(|c| c.is_control()) {
330        return Err(format!("{what} contains control character {:?}", c as u32));
331    }
332    Ok(())
333}
334
335/// Keep a diagnostic bounded: an attacker-supplied field must not be able
336/// to print a megabyte to the operator's terminal.
337fn trunc(s: &str) -> String {
338    let mut out: String = s.chars().take(32).collect();
339    if out.len() < s.len() {
340        out.push('…');
341    }
342    out
343}
344
345#[cfg(test)]
346mod tests {
347    // Panicking on a bad index is the *desired* behaviour in a test; the
348    // crate-level deny exists to keep it out of the library.
349    #![allow(clippy::indexing_slicing)]
350
351    use super::*;
352
353    fn ok_gadget() -> CachedGadget {
354        CachedGadget {
355            vaddr: "0x401000".to_string(),
356            bytes: "5fc3".to_string(),
357            text: "pop rdi ; ret".to_string(),
358            ..CachedGadget::default()
359        }
360    }
361
362    fn scan_of(g: CachedGadget) -> CachedScan {
363        CachedScan {
364            gadgets: vec![g],
365            ..CachedScan::default()
366        }
367    }
368
369    #[test]
370    fn valid_record_round_trips() {
371        let s = scan_of(ok_gadget());
372        s.validate().unwrap();
373        let g = s.to_scan_gadgets().unwrap();
374        assert_eq!(g.len(), 1);
375        assert_eq!(g[0].vaddr, 0x0040_1000);
376        assert_eq!(g[0].bytes, vec![0x5f, 0xc3]);
377        assert_eq!(g[0].insns, vec!["pop rdi", "ret"]);
378    }
379
380    /// ROB-04, at the record level: the exact `bytes` value that panicked.
381    #[test]
382    fn non_ascii_bytes_field_is_a_miss() {
383        let bad = CachedGadget {
384            bytes: "€€".to_string(),
385            ..ok_gadget()
386        };
387        assert!(bad.to_scan_gadget().is_none());
388        assert!(scan_of(bad).validate().is_err());
389    }
390
391    #[test]
392    fn malformed_matrix() {
393        let cases: Vec<(&str, CachedGadget)> = vec![
394            (
395                "odd-length hex",
396                CachedGadget {
397                    bytes: "5fc".to_string(),
398                    ..ok_gadget()
399                },
400            ),
401            (
402                "non-hex alphabet",
403                CachedGadget {
404                    bytes: "zz".to_string(),
405                    ..ok_gadget()
406                },
407            ),
408            (
409                "1 MB text",
410                CachedGadget {
411                    text: "a".repeat(1024 * 1024),
412                    ..ok_gadget()
413                },
414            ),
415            (
416                "vaddr not-hex",
417                CachedGadget {
418                    vaddr: "not-hex".to_string(),
419                    ..ok_gadget()
420                },
421            ),
422            (
423                "quality 99999",
424                CachedGadget {
425                    quality: Some(99999),
426                    ..ok_gadget()
427                },
428            ),
429            (
430                "class ../../etc",
431                CachedGadget {
432                    class: Some("../../etc".to_string()),
433                    ..ok_gadget()
434                },
435            ),
436            (
437                "control characters in text",
438                CachedGadget {
439                    text: "pop rdi\u{1b}[2J ; ret".to_string(),
440                    ..ok_gadget()
441                },
442            ),
443            (
444                "prev not hex",
445                CachedGadget {
446                    prev: Some("qq".to_string()),
447                    ..ok_gadget()
448                },
449            ),
450        ];
451        for (what, g) in cases {
452            assert!(scan_of(g).validate().is_err(), "{what} must not validate");
453        }
454    }
455
456    #[test]
457    fn version_must_match() {
458        let mut s = scan_of(ok_gadget());
459        s.version = 0;
460        assert!(s.validate().is_err());
461        s.version = CACHE_FORMAT_VERSION + 1;
462        assert!(s.validate().is_err());
463    }
464
465    /// rf-mcp's response objects are these records. Adding rf-cli's fields
466    /// to the shared struct must not add keys to the MCP wire shape.
467    #[test]
468    fn mcp_shape_unchanged_when_cli_fields_are_empty() {
469        let g = CachedGadget {
470            arch: Some("x86_64".to_string()),
471            section: Some(".text".to_string()),
472            quality: Some(70),
473            class: Some("reg-write".to_string()),
474            ..ok_gadget()
475        };
476        let v = serde_json::to_value(&g).unwrap();
477        let mut keys: Vec<&str> = v.as_object().unwrap().keys().map(String::as_str).collect();
478        keys.sort_unstable();
479        assert_eq!(
480            keys,
481            ["arch", "bytes", "class", "quality", "section", "text", "vaddr"]
482        );
483    }
484
485    /// An rf-cli record carries `insns` and no `text`; an rf-mcp record
486    /// carries `text` and no `insns`. Both reconstruct; a record with
487    /// neither is refused rather than producing a one-instruction gadget
488    /// whose instruction is the empty string.
489    #[test]
490    fn either_insns_or_text_reconstructs_and_neither_does_not() {
491        let cli = CachedGadget::from_scan_gadget(&rf_scan::Gadget {
492            vaddr: 0x0040_1000,
493            bytes: vec![0x5f, 0xc3],
494            insns: vec!["pop rdi".to_string(), "ret".to_string()],
495            delay_slot: false,
496            prev: Some(vec![0xe8]),
497            table: rf_scan::TableKind::Rop,
498        });
499        assert_eq!(cli.text, "", "text is not stored twice");
500        let json = serde_json::to_string(&cli).unwrap();
501        assert!(!json.contains("\"text\""), "{json}");
502        let back = cli.to_scan_gadget().unwrap();
503        assert_eq!(back.vaddr, 0x0040_1000);
504        assert_eq!(back.insns, ["pop rdi", "ret"]);
505        assert_eq!(back.prev, Some(vec![0xe8]));
506        scan_of(cli).validate().unwrap();
507
508        let mcp = ok_gadget();
509        assert_eq!(mcp.to_scan_gadget().unwrap().insns, ["pop rdi", "ret"]);
510
511        let neither = CachedGadget {
512            text: String::new(),
513            ..ok_gadget()
514        };
515        assert!(neither.to_scan_gadget().is_none());
516        assert!(scan_of(neither).validate().is_err());
517    }
518
519    #[test]
520    fn known_classes_match_rf_classify() {
521        use rf_classify::Class;
522        let live = [
523            Class::RegWrite,
524            Class::StackPivot,
525            Class::MemRead,
526            Class::MemWrite,
527            Class::Arithmetic,
528            Class::Syscall,
529            Class::Dispatcher,
530            Class::Other,
531        ];
532        let mut live: Vec<&str> = live.iter().map(|c| c.name()).collect();
533        live.sort_unstable();
534        let mut known: Vec<&str> = KNOWN_CLASSES.to_vec();
535        known.sort_unstable();
536        assert_eq!(live, known, "KNOWN_CLASSES has drifted from rf_classify");
537    }
538}