Permission firewall: MCP tool classification fails open for unknown write tools

[PavelDo]

While evaluating the permission firewall for use as a shared enforcement standard across Keboola agent projects, we found an asymmetry in how unknown operations are classified:

• CLI operations fail closed (unknown command -> denied), which is correct.
• MCP tool classification uses a name-prefix heuristic that fails open: a tool whose name does not match a known write prefix is classified as a read and allowed. Example: a hypothetical truncate_table tool would be classified read-only and pass the firewall.

Suggested fix: invert the default for MCP tools — treat unknown/unclassified tool names as writes (deny or confirm), and maintain an explicit read allowlist, mirroring the CLI side's fail-closed behavior.

Related question: ADR-0002 describes a "locked mode" (privilege separation + config pinning) as the answer to the same-uid config rewrite concern — is that shipped, and if so where is it documented? We would like to depend on it.

Context: this came out of a July 2026 comparison of enforcement regimes (kbagent firewall vs Claude Code hooks/sandbox vs native permission rules) for a Keboola-wide standard. Happy to share the full memo internally.

[padak]

Thanks for the report — confirmed, and the finding runs deeper than the classification default. Here is the plan we are executing; the strategic answer changes the frame, so laying it out in full:

Strategic direction: retire the MCP passthrough, keep one fail-closed surface

Rather than hardening the MCP tool classifier indefinitely, we are converging on full CLI parity with the keboola-mcp-server toolset and subsequent removal of the tool call passthrough (tracked as epic #390). For your enforcement-standard evaluation this is the important part: the end state has a single enforcement surface — the fail-closed CLI operation registry you already assessed as correct — with no name-heuristic classification of a second tool namespace at all.

Phase 0 — immediate fail-closed hardening (lands in v0.73.0)

Already implemented on feat/mcp-fail-closed-and-parity-390; PR link will follow here. Until the passthrough retires, it is fail-closed:

1. Unknown MCP tool names classify as destructive (the strictest category — blocked by both --deny-writes and --deny-destructive), no longer falling through to read. Your hypothetical truncate_table now hits an explicit destructive prefix rule; a name matching nothing at all fails closed.
2. The audit undersold the exposure, worth noting: the old prefix list also misclassified real catalog tools — run_job, run_sync_action, deploy_data_app, modify_* all classified as reads, passed --deny-writes, and were fanned out in parallel to every configured project by the multi-project dispatcher. Dispatch now derives from the same classifier: only known-read tools fan out; everything else (including unknowns) stays single-project.
3. Session-flag gap closed: --deny-writes/--deny-destructive (session-only flags) were enforced at the coarse tool.call operation level, while per-tool-name checks consulted only the persisted policy — so a session --deny-destructive still allowed tool call delete_bucket. The command now checks the session engine against tool:<name> before dispatch. Live-verified: delete_bucket and unknown names are denied, reads pass.

We deliberately did not adopt a pure read-allowlist (your suggested variant) for the interim: keboola-mcp-server annotates its catalog with MCP ToolAnnotations (readOnlyHint/destructiveHint), but trusting server-supplied annotations inverts the trust direction the firewall is meant to enforce, and an allowlist frozen into the CLI would break on every server release. Fail-closed default + explicit prefix rules gets the same guarantee without either problem — and retires with the passthrough anyway.

Phase 1 — CLI parity (in progress, same branch)

Native commands for the last unported tools: docs query (#392), config examples (#393), semantic-layer schema (#394), component sync-action (#395), transformation create/show/edit (#396), flow examples (#397). query_data's CLI answer is the existing workspace query.

Phases 2–3 — deprecation, then removal

Once parity ships: tool call/tool list and the mcp_tool agent-task flavour print deprecation warnings with a tool→command map (0.74.x), then the MCP passthrough (McpService, transports, the mcp dependency and its runtime uvx fetch — itself a supply-chain surface you may want in the memo) is removed. A CI canary will diff the mcp-server tool catalog against the parity map so new server tools open an issue instead of silently widening the gap.

ADR-0002 "locked mode" — direct answer

Not shipped as an in-process feature, and it intentionally never will be. A same-uid process can always rewrite the config the firewall reads, so an in-process lock would be security theater; this was settled during the #271 security-audit triage. The firewall's contract is guard rails against agent mistakes. Hard lockout — what ADR-0002 calls locked mode — is a deployment pattern: run the enforcement config under a different uid (OS privilege separation), or terminate enforcement outside the process entirely. If your shared standard needs tamper-proof enforcement, build it at that layer and treat the kbagent firewall as defense-in-depth below it. Happy to review the internal memo with this framing.

[padak]

Phase 2 is implemented in #509 (0.74.0, stacked on #508): parity map as code with offline registry-pinning tests, per-tool deprecation warnings on tool call (exact native replacement; additive JSON key), cli_equivalent in tool list, warnings on agent --type mcp_tool, /mcp/tools* marked deprecated in OpenAPI, and a weekly CI canary diffing the live mcp-server catalog (39/39 covered today) against the map. Remaining: phase 3 removal after the deprecation window.

[padak]

Phases 0–2 are now shipped and released.

• v0.73.0 (PR feat: MCP parity commands + fail-closed tool firewall (0.73.0, epic #390 + #478 phase 0) #508): phase 0 — fail-closed classify_mcp_tool (unknown → destructive), fail-closed multi-project dispatch, and per-tool session-firewall enforcement in tool call (so a session-only --deny-destructive blocks tool call delete_bucket). Plus phase 1 — the six native commands that reach CLI parity with the keboola-mcp-server toolset (closed feat(docs): kbagent docs query — answer questions from Keboola documentation (port docs_query) #392–feat(flow): kbagent flow examples + fix drifted flow schema (port get_flow_examples) #397).
• v0.74.0 (PR feat: MCP passthrough deprecation -- parity map, warnings, CI canary (0.74.0, #478 phase 2) #509): phase 2 — the passthrough is formally deprecated. Parity map as code (src/keboola_agent_cli/mcp_parity.py, 39/39 catalog coverage), per-tool deprecation warnings on tool call, cli_equivalent in tool list, warnings on agent --type mcp_tool, /mcp/tools* marked deprecated in OpenAPI, and a weekly mcp-parity-canary workflow diffing the live upstream catalog against the map. Nothing breaks — everything keeps working through the deprecation window.

Net effect for your enforcement-standard evaluation: the original fail-open finding is closed, and the direction is set toward a single fail-closed enforcement surface (the CLI operation registry) as the passthrough retires. ADR-0002 "locked mode" remains a deployment pattern (OS privilege separation), never an in-process guard — as discussed above.

Remaining: phase 3 (passthrough removal + agents.json mcp_tool migration story) stays open on #390, to land after the deprecation window. Keeping this issue open until phase 3 ships; happy to review the internal memo against the shipped behavior whenever it's useful.