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,--rawModeand--rawEndian, so--cacheserved 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 overkey || 0x00 || bodywith 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 byCachedScan::heap_bytesand evicted on insert (MCP-05/ROB-07). The unboundedHashMapit 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§
- Cache
Limits - CLI-08/PERF-12 budget.
- Cache
Stats - Counters.
tamperedis the one that matters: it is non-zero only when a file in the cache directory carried a body the cache did not write. - Cached
Gadget - One cached gadget.
- Cached
Scan - One cached scan.
- Disk
Cache - An opened, authenticated cache directory.
- MemCache
- Byte-weighted, TTL’d LRU over
CachedScanvalues. - MemLimits
- Budget for
MemCache. - MemStats
- Counters for
get_server_stats(MCP-09). - Open
Error - 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
statbefore 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 forvaddr,bytesandtext. 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_classifykeeps 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 bystatbefore 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
depthinstructions 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 (
--depthis bounded well below this). - MAX_
LABEL_ BYTES - Cap on the small free-text fields (
arch,section,class). - MAX_
PREV_ BYTES - Largest
prevcontext, in bytes:gadgets.pycaptures at most 9. - MAX_
TEXT_ BYTES - Largest gadget text a cache entry may carry.
- SCAN_
OVERHEAD_ BYTES - Fixed cost charged to a whole entry (
Vecheader plus theArcand 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
sas hex.Noneunless the length is even, every byte is an ASCII hex digit, and the result is at mostmax_byteslong. - encode_
hex - Lowercase hex, no separators.
- hmac_
sha256 - HMAC-SHA256 of
msgunderkey. - is_
hex_ bytes - True when
sis a well-formed hex byte string of at mostmax_bytesbytes — the validation half ofdecode_hexwith 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/0Xprefix.Noneon an empty string, on more than 16 digits (would overflow), or on any non-hex byte — sovaddr: "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.