Skip to main content

Crate rf_mcp

Crate rf_mcp 

Source
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 --info payload.
  • 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_path is 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 by confine, 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-errors restores detail inside allowed roots only.
  • run_ropgadget_command rejects 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 through guard::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: tracing to stderr only, --audit-log (one JSON object per line, mode 0600, rotated), the get_server_stats tool, and the MCP logging capability so warnings reach an operator who never sees stderr (MCP-09).
  • Responses are sampled: up to max_results gadgets plus total_count and truncated. (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 MCP isError flag; 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, a checksec an 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 search parameter — 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§

BytesQuery
CLI-05 / ECO-02 — find_bytes.
ChainQuery
EffectQuery
ECO-01 — the constraint search, as one call.
GadgetQuery
IdsQuery
get_gadgets — resolve stable ids back to full records.
InfoQuery
MitigationsQuery
ECO-06 — get_mitigations.
ParsedArgs
Parsed + validated run_ropgadget_command arguments.
RawCommandQuery
RopFinderMcp
SearchQuery
ServerConfig
StringQuery
CLI-05 / ECO-02 — find_string.
ToolError
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 a usage_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’s sections and imports arrays, 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’s symbols array: symbols are OPT-IN.
DEFAULT_PROBE_THRESHOLD
Default --probe-threshold: consecutive path_denied results in one session before responses are delayed and probing_suspected is 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 --align the way ROPgadget’s argparse does.
parse_ropgadget_args
Validate args against the PLAN §6.1 allowlist and map them onto a rf_api::ScanRequest. Anything outside the allowlist is rejected.