mcp-rce-guard

Part of the StudioMeyer MCP Stack — Built in Mallorca 🌴 · ⭐ if you use it

mcp-rce-guard

Policy-synthesis + behavioral CVE-replay + canary-tracking library for MCP servers. Foundation Pillar 9.

v0.1 Scope: Policy-Synthesizer, Not Kernel-Level Sandbox

Be precise about what this is and is not. v0.1 is a building-block library that synthesizes isolation policy descriptors (landlock JSON profiles, sandbox-exec .sb scheme files, cgroups-v2 spec maps) and provides behavioral predicates that scan subprocess commands for known RCE-vulnerability shapes. It does not apply those policies to a running process. The host spawning the subprocess is responsible for translating a descriptor into the platform-specific syscall (Linux landlock, macOS sandbox-exec, cgroups-v2 fs write).

Native enforcement (NAPI-RS landlock binding, sandbox-exec execa wrap, cgroups-v2 file writes with cleanup-on-exit, cross-platform integration tests) is the v0.2 tranche and is not bundled with v0.1. Layered defense relies on the host wiring policy emission to actual enforcement; this library does the first half cleanly.

Use this library if you want:

• A typed, validated way to describe what an MCP subprocess is allowed to read, write, spawn, and talk to.
• A reproducible scanner for known RCE-vulnerability classes in subprocess commands (MCP-SDK-RCE-2026-04-22, CVE-2026-27124, Nginx-MCP RCE 9.8, interpreter inline-eval RCE) plus 5 shell-injection + 3 fullwidth-unicode payload patterns from the simulate_attacker_input corpus.
• An append-only NDJSON audit log of every isolation decision. Verified tamper-evident signing (Acra-pattern key derivation + rotation + integrated verifier) is on the v0.2 roadmap; v0.1 ships the log unsigned and treats signing as a v0.2 deliverable.

Do not use v0.1 if you need a sandbox that actually contains a hostile subprocess at the kernel boundary. For that, the v0.1 descriptor needs to be paired with an enforcement helper. v0.2 ships that helper.

What it does (v0.1)

• Process isolation policy synthesis — emits landlock (Linux >=5.13) policy descriptors, sandbox-exec (macOS) Scheme profiles, cgroups-v2 specs (memory.max, pids.max, cpu.max). Descriptors only; no syscalls are made.
• Network egress allowlist — default-deny policy with wildcard / exact / suffix / port:* matching. Descriptors only; no nftables / packet-filter integration.
• CVE replay suite — behavioral predicates for known MCP-server RCE vectors (mcp-sdk-rce-2026-04-22, cve-2026-27124, nginx-mcp-rce-9.8, mcp-interpreter-eval-rce). Not exploit payloads — predicates that scan a target command for the vulnerable shape. The mcp-interpreter-eval-rce fixture (added 0.1.1) flags interpreter inline-eval sinks (node -e/--eval/-p, python -c, perl -e, ruby -e, php -r, deno eval, bun -e) that execute arbitrary code without a shell binary or shell metacharacter; the shell-metachar predicate also flags newline/CR command separators as of 0.1.1. Exact-token matching keeps benign launch flags (--experimental-vm-modules, --max-old-space-size, --inspect) out of the detection.
• Cross-server canary tokens — issue tokens, scan downstream stdout / fs-write / network-egress streams for leaks (MCPHunt arXiv 2604.27819 pattern).
• NDJSON append-only audit log — every tool call appended at $MCP_RCE_GUARD_HOME/audit.log. 100MB rotation with max 10 backups. v0.1 ships unsigned (no in-process verifier); v0.2 adds Acra-pattern HMAC chain with key derivation, rotation safety and an integrated verifier.
• NFKC + zero-width strip + Bidi-block normalization shared with Pillar 8 (mcp-stdio-shellguard).

Install

npm install -g mcp-rce-guard

Or run via npx:

npx -y mcp-rce-guard serve

Tools (MCP, Spec 2025-06-18)

Tool	Purpose	readOnly	destructive
register_subprocess	Register a child MCP server with isolation profile, get back a handle + fingerprint + policy descriptor	yes	no
audit_subprocess	Verify requested args match registered allowlist (post-NFKC, smell-test for invisibles)	yes	no
scan_cve_replay	Run behavioral predicates against a target server command	yes	no
track_canary	Issue a canary token + scan downstream servers for leaks	yes	no
inject_egress_policy	Emit network-egress allowlist descriptor for a registered subprocess (v0.1 descriptor-only)	yes	no
get_audit_log	Read NDJSON audit log entries with filters	yes	no

v0.1 Honesty Note: all six tools are readOnlyHint=true, destructiveHint=false in v0.1 because they emit policy descriptors + append to the audit log but do not modify subprocess state. v0.2 will flip inject_egress_policy to destructiveHint=true when native enforcement is wired in.

CLI

mcp-rce-guard serve            # start MCP server on stdio
mcp-rce-guard platform         # detect isolation backend (landlock/sandbox-exec/unsupported)
mcp-rce-guard scan-cve <cmd>   # one-shot CVE replay against a command
mcp-rce-guard audit-log        # tail the audit log
mcp-rce-guard policy <profile.json>  # synthesize landlock+cgroups+sandbox-exec from JSON

Compatibility matrix

Platform	Isolation backend	Network egress	cgroups
Linux >= 5.13	landlock	nftables hook (out-of-band)	cgroups-v2
Linux < 5.13	unsupported	unsupported	unsupported
macOS 11+	sandbox-exec (.sb)	sandbox-exec network rules	n/a
Windows	unsupported (planned: AppContainer)	n/a	n/a

Layer architecture (v0.1)

Pillar 1 (mcp-protocol-conformance) — protocol input shape
        ↓
Pillar 8 (mcp-stdio-shellguard)     — argv allowlist + invisible-codepoint detection
        ↓
Pillar 9 (mcp-rce-guard, this lib)  — policy synthesis + CVE-replay scan + canary
        ↓
Host spawner (caller responsibility) — applies the policy descriptor via real syscalls

In v0.2 the bottom box collapses into Pillar 9 (NAPI-RS landlock binding, sandbox-exec exec wrap, cgroups-v2 fs writes with cleanup). Until then, the host has to bridge the descriptor to the platform.

Trust tiers

Tier	mem	pids	egress	use
LOW	256MB	32	none	untrusted MCP from registry
MEDIUM	512MB	64	api-only	known vendor with limited scope
HIGH	1024MB	128	broad	first-party MCP with reviewed source
CRITICAL	2048MB	256	unrestricted	local OS-integrated MCP, you own the source

Audit log location

$MCP_RCE_GUARD_HOME/audit.log     # default: ~/.mcp-rce-guard/audit.log

Entries are written as one JSON document per line (NDJSON) and read back via JSON.parse per line, so arbitrary characters inside args strings (tabs, quotes, embedded escape sequences) round-trip safely. Rotation happens at 100MB; up to 10 backups (audit.log.1 .. audit.log.10) are kept.

v0.1 does not sign entries. The previous MCP_RCE_GUARD_SIGNING_KEY HMAC-SHA256 path was removed pre-publish: there was no in-process verifier, no key-length validation, and no rotation strategy, which would have been security theatre. v0.2 ships a verified Acra-pattern chain (KDF(master) → per-entry HMAC, key rotation, an integrated verify_audit_log tool).

Notes

• v0.1 emits policy descriptors. Actual landlock syscall application is the responsibility of the spawning helper (separation-of-concerns: policy synthesis is portable, syscall is platform-specific). A native bindings wrapper is planned for v0.2.
• CVE fixtures are behavioral predicates, not runnable exploits. They check: "does the target command match the shape known to be exploitable?" Not "can we trigger the exploit?"
• Canary tokens use crypto-random 64-hex bodies inside __MCP_CANARY_<hex>__ markers. Pattern uniqueness is statistical, not crypto-guaranteed against an adversary that controls the generator.

Known Issues v0.1

These are real but accepted limitations of the v0.1 line. They are tracked in the v0.2 roadmap below; if any of them blocks your use case, pin to a future v0.2.x release once it ships.

• Audit-log rotation has a TOCTOU window (src/audit/log.ts rotateAuditLog). The size check and the rename are not atomic. In multi-process / high-concurrency setups two appenders may both observe "needs rotation" and both attempt the rename; the loser's append lands in the freshly-created empty active log. Workaround: serialize writes or run one writer per process. v0.2 will gate rotation behind proper-lockfile.
• In-memory state lost on restart (src/state.ts). Registered subprocesses and canary chains live in process memory. A process restart empties the registry; the operator has to re-register. v0.2 plans a SQLite-backed store as an opt-in persistence layer.
• mcp-protocol-validator CI step is not a hard gate (.github/workflows/ci.yml). The validator runs with continue-on-error: true because the upstream tool is still stabilising; failures surface as CI annotations but do not block. v0.2 promotes it to a hard gate once upstream is stable.
• Audit log is unsigned in v0.1. See "Audit log location" above. v0.2 adds a verified Acra-pattern signed chain.

v0.2 Roadmap (parked, no commit date)

• pnpm-workspace mit mcp-rce-guard + mcp-rce-demo + mcp-rce-fixtures (Marketplace-Distribution-Hygiene: CVE-Fixtures separate distribution).
• NAPI-RS Landlock binding fuer Linux (kernel >=5.13). Plain child_process.spawn mit prctl + LANDLOCK_CREATE_RULESET ist nicht testbar ohne C-Bridge.
• macOS sandbox-exec execa wrap mit profile-file lifecycle (deny-network triggert connection-refused, deny-fs-read triggert EACCES).
• cgroups-v2 fs.writeFile mit Permission-Checks + cleanup-on-exit + signal handlers.
• Integration tests tests/integration/linux-landlock.test.ts + tests/integration/macos-sandbox-exec.test.ts.
• Reference server mcp-rce-demo mit 6 Tools die jede Capability live demonstrieren (read_isolated_file, attempt_egress_blocked, spawn_subprocess_audited, replay_cve_demo, inject_canary_demo, get_demo_audit).
• Latency test "subprocess-Spawn p95 <200ms" auf ubuntu-latest GitHub Actions runner.
• Sigstore Trusted Publishing OIDC fuer alle 3 npm-Packages.
• Verified Acra-pattern audit-log chain: KDF master-key → per-entry HMAC, key rotation with overlap window, integrated verify_audit_log tool. Replaces the v0.1 HMAC-SHA256 prototype that was removed pre-publish for lacking a verifier.

License

MIT — Copyright (c) 2026 Matthias Meyer (StudioMeyer)