Skip to content

fix(security): keep a verified tool-identity title out of the path tier - #17344

Closed
chenmingwei23 wants to merge 1 commit into
kirodotdev:mainfrom
chenmingwei23:fix/12723-tool-name-path-tier
Closed

chenmingwei23 wants to merge 1 commit into
kirodotdev:mainfrom
chenmingwei23:fix/12723-tool-name-path-tier

Conversation

@chenmingwei23

@chenmingwei23 chenmingwei23 commented Oct 6, 2026 •

Copy link
Copy Markdown
Contributor

Problem / Motivation

Goal: a tool call whose permission title is its own tool name is no longer refused as a "sensitive path" when the path resolver is slow.

On a gateway under path-resolver load, a wait tool call was refused fail-closed with Path: @kirocrew-core/wait. That string is a tool name, not a path. It reached the sensitive-path tier because both the _resolve_permission title tier (llm_helpers._title_denial) and hooks.on_tool_call's security_targets loop hand the permission title to sensitive_path_refusal as a filename. When the resolver stalls, that check refuses whatever it was given.

Why it matters

Any MCP tool call can be refused at random under load, with a refusal that tells the agent a credential path was involved when none was. The agent then retries, re-spells, or goes looking for a credential that does not exist.

Not a goal

What changed (motivation → approach → change)

  • Symptom: a tool-name title is refused as a path under resolver load.
  • Root cause: the title tier reads every title as a filename, including a title that is the call's own tool identity.
  • Approach: the issue listed three options. This is the smallest form of option 1, restated so it covers @server/tool (a "no separator" test cannot, since every MCP identity contains /). It follows the pattern fix(security): do not hand shell command text to the path tier #11223 used for shell command text: one exact string, identified by the client's own provenance, is spared the resolver. Keying on the verified identity rather than on the title's shape is the fail-safe choice. A path-shaped title can never qualify, because it would have to equal the verified identity byte for byte.
  • Change:
    • New title_is_trusted_mcp_identity() in hook_runtime/tool_identity.py. It is true only when mcp_identity_trusted is set, the server name is non-empty, neither segment holds a separator, and the title equals mcp_identity_ref(server, tool) or mcp_identity_ref(server, "").
    • _title_denial takes identity_exempt, and _resolve_permission computes it from the event's trusted identity. hooks.on_tool_call applies the same predicate per target. In both places only the path tier is skipped. The bash and deny-rule tiers still read the title.
    • docs/system-specs/modules/security.md records the exemption next to the shell-command one.

Backwards compatibility

Compatible: the only behaviour change is that one string, a title equal to the call's own verified MCP identity, is no longer resolved as a path. Every other title, every unverified identity, and every argument are judged exactly as before.

Removes nothing: no key, record, validator or function is removed. The path tier is narrowed for one non-path string only.

Tests

  • test/test_llm_helpers_tool_input_offload.py::TestToolIdentityTitleLeavesThePathTier:
    • the predicate matches only the verified identity (not an unverified one, an empty server, a display-prefixed title, or a segment holding a separator);
    • _title_denial with identity_exempt never calls the path tier, and the bash tier still runs;
    • end to end through _resolve_permission, a stalled path tier no longer refuses @kirocrew-core/wait;
    • mutations stay refused: an unverified identity, a path title on a verified MCP call, an extra segment, and another server's identity.
  • test/test_hooks.py: the same two directions at the hook gate (a verified identity title is not resolved; an unverified identity, a path title or an extra segment still is and is denied).
  • Both files pass in full locally. flake8, isort and mypy are clean on the touched files.

Manual verification

N/A: the defect is a pure decision in the gate, and the unit tests drive both gate entry points with a stalled resolver.

Related Issues

Fixes #12723

Pattern harvest

Not generalizable: the path tier already carries one provenance-keyed exemption (shell command text); this adds the only other non-path string a permission frame's title can be: the call's own identity.

Checklist

  • At most two commits (one is the norm), with a Conventional Commits title (feat|fix|docs|style|refactor|perf|test|chore|ci|build|revert: ...)
  • Existing tests pass and new tests added for new functionality
  • Self-review completed; code follows project style guidelines
  • Documentation updated (if applicable)
  • No secrets, credentials, or internal references in the diff

Contribution License Agreement

Contributions are accepted under the project's Apache-2.0 license; see the Licensing section of CONTRIBUTING.md.

@chenmingwei23
chenmingwei23 requested a review from a team as a code owner October 6, 2026 11:19
@github-actions github-actions Bot added fork Pull request from a fork (external contributor) readiness: checking Automated validation is still running readiness: action required A blocking check or review needs attention and removed readiness: checking Automated validation is still running labels Oct 6, 2026
A permission title such as `@kirocrew-core/wait` is a tool name, but both
the `_resolve_permission` title tier and `hooks.on_tool_call` handed it to
`sensitive_path_refusal` as a filename. Under resolver load that check
stalled and refused the call fail-closed with a "Path:" wording that
names no path.

Add `title_is_trusted_mcp_identity`: true only when the title is exactly
the call's own `@server/tool` (or `@server`) reference built from the
provenance-verified `_meta.kiro` identity (`mcp_identity_trusted`), with
no separator in either segment. Both sites skip the path tier for that
one string. Any other title of an MCP call, an unverified identity, and
every argument stay path-gated; the bash and deny-rule tiers still read
the title.

Fixes kirodotdev#12723
@chenmingwei23
chenmingwei23 force-pushed the fix/12723-tool-name-path-tier branch from 3285b18 to 4efbeb9 Compare October 6, 2026 11:44
@github-actions github-actions Bot added readiness: checking Automated validation is still running and removed readiness: action required A blocking check or review needs attention labels Oct 6, 2026
@github-actions

github-actions Bot commented Oct 6, 2026

Copy link
Copy Markdown
Contributor

Design Review (Opus 5.5, fork) — ✅ PASS

Design-level review of 4efbeb9434de25e1d53d0463ab7aab455e9ba178 via the fork AI-review pipeline — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS/CONCERNS are advisory.

Design-Verdict: PASS

Check that a real kiro-cli wait frame's normalized title equals @kirocrew-core/wait exactly. If the live title differs at all, the exemption never matches and #12723 stays unfixed.

[DESIGN-REVIEWED] 4efbeb9

Description read

[DESCRIPTION-READ] ced6bbeb3b786b32f303715d2271cfb62771e8cb0a22fd8103ba5fdee46cf1ef

That sha256 names everything this verdict read: the PR description, plus the 1 evidence file(s) the workflow collected from it and handed this review. It covers that evidence because the media strip replaces every attachment URL with the same placeholder, so an edit swapping one attachment for another would leave the description's captured text identical while what this review judged changed. Recompute it with .github/scripts/pr-description-capture.sh over the same inputs; if it differs, the description or that evidence changed after this verdict was formed and any finding drawn from either is unproven.

@github-actions

github-actions Bot commented Oct 6, 2026

Copy link
Copy Markdown
Contributor

First Principles Review (Opus 5.5, fork) — 🟡 CONCERNS

Premise-level review of 4efbeb9434de25e1d53d0463ab7aab455e9ba178 via the fork AI-review pipeline — why this exists and whether the shipped surface is the smallest honest version. Updated in place on each push. A BLOCK verdict blocks PR readiness; PASS/CONCERNS are advisory.

First-Principles-Verdict: CONCERNS

The exemption only matches the bare @server/tool title. kiro-cli's own MCP title, Running: @server/tool, still goes to the path tier and is still refused under a stall.

Not justified as shipped

  • Item 1 — symptom-level: base tool_call_title.py:2000 says "an MCP call is Running: @server/tool", and _resolve_permission sets normalized = event.title (llm_helpers.py:2919) without stripping that prefix. The new test also pins the gap: assert not match("Running: @srv/tool", ...). Of the three identity spellings at hooks.py:1362, this covers 2 (@s/t and @s) and leaves out Running: @s/t.
    Clears when: the description names the backend that sends the bare @kirocrew-core/wait title and shows that kiro-cli's Running: form never reaches _title_denial, or a stalled-resolver test shows that form is not refused.
  • Item 3 — inherited: the bare @server match has no reported defect behind it. Its only support is the deny-loop spellings at hooks.py:1362.
    Subtraction: delete the mcp_identity_ref(mcp_server_name, "") alternative in title_is_trusted_mcp_identity.
    Clears when: a real permission frame whose title is bare @server is named.

What this change ships

Inventory (5 items) — 3 justified

Intent: stop MCP tool calls being refused as a "sensitive path" when the path resolver stalls. FIX (#12723).

  1. A title equal to the verified @server/tool is no longer path-checked by _resolve_permission's title tier — symptom-level: misses the Running: form
  2. The same exemption at hooks.on_tool_call's target loop — justified
  3. A bare @server title is also spared — inherited: deny-list symmetry, no defect named
  4. New helper title_is_trusted_mcp_identity, re-exported from hooks (2 consumers) — justified
  5. A security.md paragraph recording the exemption — justified

[FIRST-PRINCIPLES-REVIEWED] 4efbeb9

Description read

[DESCRIPTION-READ] bb6d1b7f9ee8b99336a6d0919edb221ffe65b70d75f931ce50fa4712c83864c6

That sha256 names the PR description this verdict read. Recompute it with .github/scripts/pr-description-capture.sh; if it differs, the description changed after this verdict was formed and any finding drawn from the description is unproven.

@github-actions

github-actions Bot commented Oct 6, 2026

Copy link
Copy Markdown
Contributor

Opus 5.5 Review (fork) — ✅ no blocking findings

Reviewed 4efbeb9434de25e1d53d0463ab7aab455e9ba178 via the fork AI-review pipeline; updated in place on each push.

Review details

No findings.

[OPUS-REVIEWED] 4efbeb9

@github-actions

github-actions Bot commented Oct 6, 2026

Copy link
Copy Markdown
Contributor

GPT 6.1 Review (fork) — ✅ no blocking findings

Reviewed 4efbeb9434de25e1d53d0463ab7aab455e9ba178 via the fork AI-review pipeline; updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] 4efbeb9

@github-actions

github-actions Bot commented Oct 6, 2026

Copy link
Copy Markdown
Contributor

Security Scope Review (fork) — 🟡 CONCERNS

Which legitimate operations does 4efbeb9434de25e1d53d0463ab7aab455e9ba178 newly refuse? Model proposes, scripts/deny_diff.py decides — updated in place on each push. A script-confirmed regression blocks PR readiness.

the reviewer's own judgement; no confirmed regression

Scope-Verdict: CONCERNS

TIGHTENING: Nothing in this change gets stricter. It loosens the tool-gate sensitive-path tier for exactly one string: a permission title that matches the call's own verified MCP identity byte for byte, @server/tool or @server. In hooks.py the hunk is path_exempt = target == exempt_command or title_is_trusted_mcp_identity(...) followed by reason = None if path_exempt else sensitive_path_refusal(target). In llm_helpers._title_denial it is None if identity_exempt or _is_exempt_command_text(title, exempt_command) else sensitive_path_refusal(title). The threat this keeps out is a path-shaped title riding past the path tier on an MCP call. That is refused by the fail-closed checks in title_is_trusted_mcp_identity: if not (mcp_identity_trusted and mcp_server_name and title): return False and the //\\ segment rejection. No shell deny-composite tier is touched: the path fence over shell text, the sensitive-command tier, the exfil shapes and the rule catalog are all unchanged.

ADJUDICATED: 11 candidates. I have no verdicts: the harness classifies them at both refs after this review is captured. They are the touched tests run in posix and Windows spellings, identity-string searches, and history and diff reads of the touched modules. Because the diff leaves the shell composite alone, every row should classify the same at base and head.

PLATFORM COVERAGE: The rows cover posix and windows. Posix: .venv/bin/python pytest runs, grep, git and deny_diff.py. Windows: .venv\Scripts\python.exe with \ test paths, PowerShell Select-String, and rg over src\kiro_crew. The diff makes one platform assumption: the predicate rejects / and \ in the server and tool segments. That is checked on the title-tier strings, not in shell text, so no shell row on either platform reaches it. I wrote no any rows, because every row carries a path or an executable name.

UNADJUDICATED: The changed guard is the always-enforced path tier on the permission title. It lives at two sites:

  • Call path 1: HookManager.on_tool_call → security_targets loop → title_is_trusted_mcp_identity(target, mcp_server_name, mcp_tool_name, mcp_identity_trusted=...) → sensitive_path_refusal.
  • Call path 2: llm_helpers._resolve_permission → _title_denial(normalized, ..., identity_exempt=title_is_trusted_mcp_identity(normalized, event.mcp_server_name, event.tool_name, mcp_identity_trusted=event.mcp_identity_trusted)) → sensitive_path_refusal(title).

The shell-corpus classifier (deny_diff.py / verify_fix.py) does not include this tier, so it can't give a verdict here. Reading the code, the change can only remove refusals: path_exempt short-circuits to None and adds no deny branch. That is an argument from reading, not a confirmed result. These are the legitimate inputs I would have submitted:

  • a verified @kirocrew-core/wait title;
  • a verified bare @kirocrew-core title with an empty tool name;
  • a verified title whose server name contains - or ., such as @my.server/tool, to confirm it is still spared;
  • an unverified identity title, which should keep its base behaviour and be path-gated;
  • a Windows host title @srv/tool with mcp_identity_trusted=True, to confirm that only / and \ inside a segment are rejected.

One more point I could not confirm, since no verdict exists for it. In _resolve_permission, the predicate takes getattr(event, "tool_name", "") as the MCP tool segment. If event.tool_name there holds a display or prefixed name rather than the bare MCP tool name, the exact @server/tool match fails. The title would then go back to the path tier, and the stall refusal from #12723 would still happen at that site. That makes the fix weaker, but it refuses nothing new.

[SCOPE-REVIEWED] 4efbeb9

Security scope review -- adjudicated candidates

  • macos-latest (platform posix): 7 classified, 0 newly refused, 7 still allowed.
  • ubuntu-latest (platform posix): 7 classified, 0 newly refused, 7 still allowed.
  • windows-latest (platform windows): 4 classified, 0 newly refused, 4 still allowed.

No candidate flipped from allowed to refused.

@chenmingwei23

Copy link
Copy Markdown
Contributor Author

Superseded by #17373 (same commit, re-opened from a same-repo branch so Sensitive Change Review can run). Closing this fork PR.

@github-actions github-actions Bot removed the readiness: checking Automated validation is still running label Oct 6, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

fork Pull request from a fork (external contributor)

Projects

None yet

Development

Successfully merging this pull request may close these issues.

security: a tool name in the permission title reaches the sensitive-path tier and is refused as a path under resolver load

1 participant