Expand description
rf-mcp — MCP (Model Context Protocol) server wrapping rop-finder (PLAN.md §6.1).
stdio transport only (v1): no network attack surface. The server exposes eight tools, all returning structured JSON:
find_gadgets/find_jop_gadgets/find_syscall_gadgets— gadget scans restricted to one anchor family.get_binary_info— the CLI’s--infopayload.search_gadgets_by_pattern— regex (or substring) over gadget text.run_ropgadget_command— flag passthrough restricted to the PLAN §6.1 allowlist.build_rop_chain— the PLAN §6.2 chain builder.get_server_config— the effective allowlist and caps, so an agent never has to guess a path.
Security model (hardened per PLAN §6.1, review-driven):
binary_pathis confined to a directory allowlist built only from--allow-dir(MCP-02: there is no cwd default; the server refuses to start without one). Confinement is enforced byconfine, which opens the file from a directory handle pinned at startup and hands the rest of the server a HANDLE, never a path — so nothing can be swapped between the check and the read (MCP-01).- Every rejected path returns exactly one code,
path_denied, with no OS error text, so the error taxonomy cannot be used to enumerate the filesystem (MCP-07).--verbose-path-errorsrestores detail inside allowed roots only. run_ropgadget_commandrejects any flag outside the allowlist — side-channel flags (--dump,--string,--memstr,--console) are never accepted.- Resource caps:
max_results(default 1000, hard max 50000), a per-request timeout (default 60 s),--max-depth(default 64, over-large values are rejected, not clamped),--max-file-bytes(default 256 MiB, enforced by fstat on the confined handle),--max-gadgets(default 5 000 000, enforced in the engine) and--max-concurrent(default 2). Every tool without exception runs throughguard::Guard::run, which cancels the work on timeout and JOINS it before releasing the permit (MCP-03/PERF-06), and inside an explicit rayon pool sized by--scan-threads. - Content-hash cache (SHA-256 of file + parameters): a byte-weighted
LRU with a TTL (
--cache-mem-mb,--cache-ttl-secs), with an optional authenticated on-disk spill via--cache-dir. - Observability:
tracingto stderr only,--audit-log(one JSON object per line, mode 0600, rotated), theget_server_statstool, and the MCPloggingcapability so warnings reach an operator who never sees stderr (MCP-09). - Responses are sampled: up to
max_resultsgadgets plustotal_countandtruncated. (PLAN calls for “top-N by quality rank”; ranking lands in Phase 5, so v1 returns the first N in the engine’s deterministic traversal order.) - Errors are structured JSON
{error: {code, message, details?}}with the MCPisErrorflag; the server never panics on malformed input.
Re-exports§
pub use audit::AuditLog;pub use audit::AuditRecord;pub use cache::Cache;pub use confine::AllowRoot;pub use confine::ConfinedFile;pub use cursor::Cursor;pub use guard::Guard;pub use logging::Notifier;pub use schema::ChainResponse;pub use schema::ErrorCode;pub use schema::GadgetRecord;pub use schema::InfoResponse;pub use schema::ScanResponse;pub use schema::ToolErrorBody;pub use schema::Warning;pub use semantics::GadgetFilter;pub use semantics::Order;pub use semantics::Semantics;pub use stats::ServerStats;pub use stats::Verdict;
Modules§
- audit
- MCP-09 — the JSONL audit trail.
- cache
- MCP-05/ROB-07 — the server’s two-level scan cache, both levels bounded.
- checksec
- ECO-06, the MCP half —
get_mitigations, achecksecan agent can run for itself. - confine
- Path confinement for the MCP server (MCP-01 / MCP-07).
- cursor
- MCP-DESIGN fix #8 part B — pagination.
- find
- CLI-05 / ECO-02, the MCP half — string, opcode and memory-string search, confined to the MAPPED SECTIONS of the loaded image.
- guard
- MCP-03/PERF-06 — the one place a request’s work is bounded.
- logging
- MCP-09 — stderr logs the operator can read, and MCP notifications the operator can actually see.
- pattern
- ECO-01’s
searchparameter — a ropper-style wildcard matcher over a gadget’s INSTRUCTION SEQUENCE, not over its rendered text. - resources
- MCP resources: a whole scan as a file an agent can grep.
- scan
- The cancellable scan pipeline the MCP server runs.
- schema
- CRIT-03 — the response contract, as real Rust types.
- semantics
- CLS-08 — the classification, kept rather than thrown away, and made queryable.
- stats
- MCP-09 — the counters behind
get_server_stats.
Structs§
- Bytes
Query - CLI-05 / ECO-02 —
find_bytes. - Chain
Query - Effect
Query - ECO-01 — the constraint search, as one call.
- Gadget
Query - IdsQuery
get_gadgets— resolve stable ids back to full records.- Info
Query - Mitigations
Query - ECO-06 —
get_mitigations. - Parsed
Args - Parsed + validated
run_ropgadget_commandarguments. - RawCommand
Query - RopFinder
Mcp - Search
Query - Server
Config - String
Query - CLI-05 / ECO-02 —
find_string. - Tool
Error - Structured tool error, rendered as
{error: {code, message, retryable, details, suggestion}}.
Constants§
- DEFAULT_
CACHE_ MEM_ BYTES - Default
--cache-mem-mb, in bytes. - DEFAULT_
CACHE_ TTL - Default
--cache-ttl-secs. - DEFAULT_
CURSOR_ TTL - Default
--cursor-ttl-secs: how long a paged scan stays pinned against eviction so an outstanding cursor can walk it (MCP-DESIGN fix #8 B). - DEFAULT_
MAX_ CONCURRENT - Default
--max-concurrent: how many scans may run at once. - DEFAULT_
MAX_ DEPTH - Default
--max-depth. A request asking for more is rejected with ausage_error, never silently clamped: an agent that quietly gets depth 64 when it asked for 100000 draws wrong conclusions from the result. - DEFAULT_
MAX_ FILE_ BYTES - Default
--max-file-bytes(256 MiB), enforced by fstat on the confined handle before a single byte is read. - DEFAULT_
MAX_ GADGETS - Default
--max-gadgets, enforced in the engine (MCP-DESIGN fix #4 E). Cancellation alone does not bound a scan that is legitimately huge; this is what bounds RSS. - DEFAULT_
MAX_ INFO_ ITEMS - Default cap on
get_binary_info’ssectionsandimportsarrays, so a hostile PE with a million import entries cannot produce a gigabyte of JSON (MCP-06). - DEFAULT_
MAX_ RESULTS - DEFAULT_
MAX_ SYMBOLS - Default cap on
get_binary_info’ssymbolsarray: symbols are OPT-IN. - DEFAULT_
PROBE_ THRESHOLD - Default
--probe-threshold: consecutivepath_deniedresults in one session before responses are delayed andprobing_suspectedis logged. - DEFAULT_
TIMEOUT_ SECS - HARD_
MAX_ RESULTS - HARD_
MAX_ TIMEOUT_ SECS - PROBE_
DELAY - How long a response is delayed once probing is suspected.
Functions§
- parse_
align - ANCH-02 - parse
--alignthe way ROPgadget’s argparse does. - parse_
ropgadget_ args - Validate
argsagainst the PLAN §6.1 allowlist and map them onto arf_api::ScanRequest. Anything outside the allowlist is rejected.