Repository navigation
mcp-moat 0.3.0
Behavior changes (breaking: calls that 0.2.x allowed can now be blocked or need approval)
- The path jail is checked first. All path arguments are extracted and checked before commands, approval, presets or allow lists are looked at. 0.2.x asked the operator for a call such as
write_file {"path": "/etc/passwd", "command": "echo hi"}; it is now blocked. A path outside the jail is a block for every tool name and every other argument. A relativecwdor an absolutecwdoutside the jail is now checked as a path as well. - A tool is only allowed by a list, a preset or its exact standard name. A name that matches a file pattern (
read_*,write_*,get_*,*_file) is no longer allowed because its path is inside the jail. An unlisted tool that modifies needs operator approval (denied with--no-prompt), any other unlisted tool is blocked. To keep using such a tool, add it toalways_allow_toolsorcustom_always_allow_tools. custom_modifying_toolsonly classifies. In 0.2.x a tool in this list with a path in the jail was allowed. Now--read-onlyblocks it and it counts as a write, but it needs approval (or an entry inalways_allow_tools) to run. This changes the built-in presets too:filesystem:delete_fileneeds approval.git:git_add,git_commit,git_create_branchandgit_checkoutare in the allow list and still run without a prompt.git_push,git_resetandgit_mergenow need approval.sqlite:write_query,execute_query,create_tableanddrop_tableneed approval.memory:create_entities,create_relations,delete_entities,delete_relationsandadd_observationsneed approval.
To allow one of them without a prompt, list it inalways_allow_tools.
- The standard tool names are the exact tools of
@modelcontextprotocol/server-filesystem(read_file,read_text_file,read_media_file,read_multiple_files,write_file,edit_file,append_file,copy_file,create_directory,list_directory,list_directory_with_sizes,directory_tree,move_file,search_files,get_file_info,list_allowed_directories). The match is exact.rm,cp,mv,cat,shred,wipe,purge_dir,delete_file,create_fileand similar names are no longer allowed automatically (they are still treated as file tools, and the modifying ones as writes). Different case or-instead of_(READ_FILE,read-file) is no longer the standard name. - A file tool without a path is blocked ("Path argument could not be verified for file tool"), also with no arguments,
{}ornull, unless it is listed innon_file_tools. Onlylist_allowed_directoriesis exempt.list_tables,show_schemaandread_graphare no longer exempt by name; thesqlite,memoryandfetchpresets now setnon_file_toolsfor their own tools (read_query,describe_table,search_nodes,open_nodes,read_urland the rest). A tool that is allowed by name but takes no path (get-env) needsnon_file_tools.non_file_toolsdoes not allow a tool. http://andhttps://URLs are not paths. A URL inurl,uri,hrefor a*_urlargument is not checked against the jail. In 0.2.x thefetchpreset rejectedhttps://example.com/as a path.file://URLs and bare paths in a URL argument are still jail-checked, and anhttp(s)URL in a path argument (path,file) is still rejected. The tool that fetches the URL must still be authorized.require_approval_on_writeapplies to every modifying tool, also one that takes no path (create_entities,write_query).- An unlisted tool that does not modify is blocked even with a
commandargument. It was sent to the operator before. An unlisted modifying tool still asks. - Percent-encoded traversal in plain paths (
%2e%2e/,..%2f, double-encoded) is rejected. - Preset
ignore_path_keysapply only to the tools of that preset (git:target,revision,branch_nameand similar; memory:from,to). Before, they were merged into the global list and disabled path checks for those keys on every tool.ignore_path_keysinmoat.tomlstays global, as an operator decision. - Unknown JSON-RPC methods are refused (breaking). Until 0.2.x every method other than
tools/callandresources/read/subscribewas forwarded. Now only the standard MCP client-to-server methods are forwarded (initialize,ping,tools/list,tools/call,resources/list,resources/templates/list,resources/read,resources/subscribe,resources/unsubscribe,prompts/list,prompts/get,completion/complete,logging/setLevel,notifications/initialized,notifications/cancelled,notifications/progress,notifications/roots/list_changed), and replies to server requests. Any other request gets-32601, any other notification is dropped, and both are audited as blocked. If your server needs an extension method, add it toallowed_methodsinmoat.toml.--monitorstill forwards and logs the category. - A failed audit write answers the client. A request with an id that is not forwarded because the audit log could not be written now gets
-32603("Request not forwarded: the audit log could not be written") instead of no response. Notifications get none.resources/readand the generic forward path are now held back on audit failure liketools/call. - The
--monitordiagnostic no longer prints the block reason. It names the tool (control characters replaced, length-capped) and a fixed category such as "path outside allowed folder", "unknown tool", "blocked command" or "read-only", never the path or URI from the request. The approval prompt andmoat auditoutput replace control characters in request-derived text. - The block message for policy violations says "external MCP protocol policy proxy" instead of "OS-level security proxy". The path error says "allowed root" instead of "sandbox root". Some code comments no longer say "Zero-Trust firewall".
Removed
moat sse-proxy,moat sse-bridgeand theexperimental-ssefeature. They were removed because their audit and secret-masking guarantees did not match the stdio proxy. They may return in a later release.
Added
PresetConfig.non_file_tools: a preset can list its pathless tools.crates/mcp-moat-core/tests/invariants.rs: one test section per invariant indocs/security-model.md, a decision table for every built-in preset and tool, a decision matrix over authorization, classification, path, command argument,require_approval_on_writeandread_only(also run through the proxy without a console) that must equal an independent rule function, and deterministic property checks (fixed seed): a path outside the jail is always a block, and a tool that nothing authorizes is never allowed.crates/mcp-moat-proxy/tests/no_prompt.rschecks that nothing that needs approval is forwarded with--no-prompt.
Logging
- Log output never contains request lines, arguments, server responses, malformed input or environment values, at any
RUST_LOGlevel.debuglogs method, id and byte length; the log lines for blocked calls no longer include the reason or the URI. A test runsmoat wrapwithRUST_LOG=traceand checks that test secrets do not appear.
CI and scripts
- A release build fails if the tag (
vX.Y.Z) does not matchworkspace.package.version. - A release requires the
cargo auditjob to pass. - The Intel macOS binary is executed on the ARM runner under Rosetta (
--version). Before, its smoke test was skipped. - The CI jobs run clippy and the tests once; there is no feature matrix any more.
- The real-server servers are pinned:
@modelcontextprotocol/server-filesystem@2.3.0,@modelcontextprotocol/server-everything@2.3.0,mcp-server-git==2026.11.11(scripts/real_server_check.py,scripts/demo.py, CI).
Documentation
SECURITY.md: the supported version is the latest published release.docs/security-model.mdand the README describe the order of checks, the authorization sources, classification versus authorization, pathless preset tools and URLs versus paths. The model document used the key nameallowed_dirs; the key isallowed_paths.moat.toml: the header and theread_onlycomment no longer overstate what moat does.- The README demo output comes from a real run of
scripts/demo.py. The text calls the client a scripted MCP client.
Install
cargo install --locked mcp-moat --version 0.3.0Binaries for Linux, macOS and Windows are attached below. Check them against SHA256SUMS.