1use serde::{Deserialize, Serialize};
9
10use crate::hex::{decode_hex, encode_hex, is_hex_bytes, parse_hex_u64, MAX_GADGET_BYTES};
11
12pub const CACHE_FORMAT_VERSION: u32 = 2;
17
18pub const MAX_TEXT_BYTES: usize = 64 * 1024;
20pub const MAX_GADGETS_PER_ENTRY: usize = 10_000_000;
25pub const MAX_INSNS_PER_GADGET: usize = 4096;
28pub const MAX_PREV_BYTES: usize = 16;
30pub const MAX_LABEL_BYTES: usize = 256;
32
33pub const GADGET_OVERHEAD_BYTES: usize = 48;
39
40pub const SCAN_OVERHEAD_BYTES: usize = 128;
43
44pub 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#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
71pub struct CachedGadget {
72 pub vaddr: String,
75 pub bytes: String,
77 #[serde(default, skip_serializing_if = "String::is_empty")]
82 pub text: String,
83 #[serde(default, skip_serializing_if = "Option::is_none")]
85 pub arch: Option<String>,
86 #[serde(default, skip_serializing_if = "Option::is_none")]
88 pub section: Option<String>,
89 #[serde(default, skip_serializing_if = "Option::is_none")]
91 pub quality: Option<i32>,
92 #[serde(default, skip_serializing_if = "Option::is_none")]
94 pub class: Option<String>,
95 #[serde(default, skip_serializing_if = "Option::is_none")]
98 pub insns: Option<Vec<String>>,
99 #[serde(default, skip_serializing_if = "is_false")]
101 pub delay_slot: bool,
102 #[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 #[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 #[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 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 #[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#[derive(Debug, Clone, Serialize, Deserialize)]
246pub struct CachedScan {
247 #[serde(default)]
250 pub version: u32,
251 pub gadgets: Vec<CachedGadget>,
253 #[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 #[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 #[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 #[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 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
323fn 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
335fn 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 #![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 #[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 #[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 #[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}