Skip to main content

Crate rf_cache

Crate rf_cache 

Source
Expand description

rf-cache — the one scan cache shared by rop-finder (rf-cli) and rop-finder-mcp (rf-mcp).

This crate exists because the duplication was the bug. Two copies of the cache meant two copies of the hex decoder, and the ROB-04 char-boundary panic lived in both of them; it meant two key builders, and only one of them ever learned about --align. Everything that decides whether a cached result may be believed now lives here:

  • make_key — a versioned key. Every output-affecting parameter goes in (CLI-01/ENG-05: the old rf-cli key omitted --rawArch, --rawMode and --rawEndian, so --cache served an x86 scan for an ARM query), and the schema version is in both the hashed material and the file name, so the next key change misses instead of mismatching.
  • DiskCache — HMAC-SHA256 over key || 0x00 || body with a per-directory random key, 0600 entries in a 0700 directory, create_new + rename for atomicity, and a byte-weighted LRU with a TTL (CLI-07/MCP-04, CLI-08/PERF-12).
  • MemCache — the in-memory half: a byte-weighted LRU with a TTL, weighted by CachedScan::heap_bytes and evicted on insert (MCP-05/ROB-07). The unbounded HashMap it replaces walked the MCP server’s RSS from 5 MB to 84 MB over twelve scans of one 900 KB binary and pinned 2.57 GB from a single depth-40 request.
  • CachedScan::validate — run on every deserialize, so a corrupt or hostile entry is a miss with a counter rather than a panic or a lie (ROB-04).

A cache that cannot prove an entry is its own does not fall back to trusting it: DiskCache::open fails, and the caller runs uncached.

§Semver policy

Covered by semver from 1.0: the signatures of make_key, DiskCache’s and MemCache’s methods, and the fields of CacheLimits, CacheStats and MemStats.

Not covered: the on-disk format. CACHE_FORMAT_VERSION and the key schema version are in both the hashed material and the file name precisely so that changing them MISSES rather than mismatching — a format change is a cold cache, never a wrong answer, and so it is not a breaking change. The text of an OpenError is not covered either. Pin rf-cache = "1".

See docs/API-STABILITY.md in the repository for the workspace-wide statement.

Structs§

CacheLimits
CLI-08/PERF-12 budget.
CacheStats
Counters. tampered is the one that matters: it is non-zero only when a file in the cache directory carried a body the cache did not write.
CachedGadget
One cached gadget.
CachedScan
One cached scan.
DiskCache
An opened, authenticated cache directory.
MemCache
Byte-weighted, TTL’d LRU over CachedScan values.
MemLimits
Budget for MemCache.
MemStats
Counters for get_server_stats (MCP-09).
OpenError
Why the on-disk cache is not available. The caller warns and continues without a cache: an unauthenticated read is never the fallback.

Constants§

CACHE_FORMAT_VERSION
Payload schema version. Bumped whenever the record shape changes; a mismatch is a miss, never a mis-parse. (The key carries its own schema version — see crate::make_key — so an old entry is not even looked up under a new key format.)
DEFAULT_MAX_ENTRY_BYTES
Default per-entry cap. Enforced by stat before the file is read, so an oversized entry never costs the memory it claims.
DEFAULT_MAX_TOTAL_BYTES
Default total on-disk budget for cache entries.
DEFAULT_MEM_MAX_BYTES
Default --cache-mem-mb, in bytes (512 MiB).
DEFAULT_MEM_TTL
Default --cache-ttl-secs (24 h).
DEFAULT_TTL
Default entry lifetime.
GADGET_OVERHEAD_BYTES
Fixed cost charged to every cached gadget by CachedGadget::heap_bytes: the struct itself plus the allocation headers for vaddr, bytes and text. MCP-DESIGN fix #5 part D specifies 48 bytes per gadget; keeping the constant named means the eviction weight can be re-derived rather than re-guessed.
KEY_FILE
Name of the entry-authentication key inside the cache directory.
KEY_SCHEMA_VERSION
Key schema version.
KNOWN_CLASSES
The classifier’s Class::name() values. class: "../../etc" in an entry is not a path — nothing joins it to anything — but an unknown class is still evidence the entry did not come from this program, so it is refused. known_classes_match_rf_classify keeps the list honest.
MAC_LEN
Tag length in bytes.
MAX_GADGETS_PER_ENTRY
Largest number of gadgets in one entry. The entry byte cap (crate::CacheLimits::max_entry_bytes) is the primary bound — it is enforced by stat before a byte is read — and this is the backstop for an entry that is small on disk but expands.
MAX_GADGET_BYTES
Longest gadget byte string a cache entry may carry. A gadget is at most depth instructions of at most 15 bytes each; 4 KiB is far above any real value and still bounds an adversarial entry.
MAX_INSNS_PER_GADGET
Largest number of instructions in one gadget (--depth is bounded well below this).
MAX_LABEL_BYTES
Cap on the small free-text fields (arch, section, class).
MAX_PREV_BYTES
Largest prev context, in bytes: gadgets.py captures at most 9.
MAX_TEXT_BYTES
Largest gadget text a cache entry may carry.
SCAN_OVERHEAD_BYTES
Fixed cost charged to a whole entry (Vec header plus the Arc and map slot the cache holds it in).

Functions§

ct_eq
Length-independent, data-independent-time comparison. A cache tag check is not a remote timing oracle, but a byte-at-a-time == on a security tag is the kind of thing that gets copied somewhere it matters.
decode_hex
Decode s as hex. None unless the length is even, every byte is an ASCII hex digit, and the result is at most max_bytes long.
encode_hex
Lowercase hex, no separators.
hmac_sha256
HMAC-SHA256 of msg under key.
is_hex_bytes
True when s is a well-formed hex byte string of at most max_bytes bytes — the validation half of decode_hex with no allocation.
key_prefix
First 16 characters of a key, for log lines. Char-safe by construction (str::get, not a byte-range slice) — the same discipline that ROB-04 was a failure of.
make_key
Build a cache key from the input file’s SHA-256 (hex) and a rendering of every parameter that can change the output.
now_unix
Seconds since the epoch, saturating rather than panicking on a clock that predates it.
parse_hex_u64
Parse an address written in hex, with or without a 0x/0X prefix. None on an empty string, on more than 16 digits (would overflow), or on any non-hex byte — so vaddr: "not-hex" is a clean miss.
sha256_hex
SHA-256 as lowercase hex. Both front ends hash the input file with it, so it lives here with the rest of the key machinery.