Skip to content

fix(mcp-gateway): refuse a junctioned spill dir on both spill paths - #8973

Closed
leonlaiyc wants to merge 1 commit into
kirodotdev:mainfrom
leonlaiyc:fix/spill-cleanup-junction-containment
Closed

leonlaiyc wants to merge 1 commit into
kirodotdev:mainfrom
leonlaiyc:fix/spill-cleanup-junction-containment

Conversation

@leonlaiyc

@leonlaiyc leonlaiyc commented Sep 6, 2026 •

Copy link
Copy Markdown
Contributor

Problem / Motivation

src/kiro_crew/mcp_gateway/spill.py guards its spill directory in two
places, and both tested only spill_dir.is_symlink().

A Windows junction is a directory reparse point, not a symlink: is_symlink()
answers False for one while is_dir() answers True. So both guards admitted
a junction and both then operated through it.

1. The cleanup path — cleanup_old_spill_files():

if spill_dir.is_symlink() or not spill_dir.is_dir():
    return 0

The 24h sweep iterated the junction's target and called entry.unlink() on
every 24h-old regular file there. Its docstring names this exact threat:

an agent that swapped the spill dir (or planted a link inside it) could
otherwise aim this sweep at an arbitrary directory and have the gateway
delete 24h-old files there (confused deputy)

The per-entry screen does not compensate — lstat/S_ISREG skips links
inside the directory, while here the directory itself is the link and the
entries reached through it are ordinary regular files.

2. The write path — maybe_spill_response():

# Never operate through a symlinked spill dir (agent-swappable): an
# attacker-planted link would redirect the write outside the data home.
if spill_dir.is_symlink():

The spilled payload was written into the junction's target. What lands there is
a full tool response — exactly the content that may carry secrets. The
O_EXCL/O_NOFOLLOW open below it does not cover this: those constrain the
final path component, not the directory the path resolves through, and
os.O_NOFOLLOW does not exist on Windows at all — the only platform that has
junctions.

Both were measured end to end on Windows against the unpatched tree: the sweep
reported deleted == 1 with the victim's file gone, and the write path left a
spill file inside the victim directory.

Why it matters

One root cause, two consequences, both outside the data home and both performed
by the gateway rather than by whatever planted the link — the confused deputy
these guards were written to prevent, reached through a link kind neither could
see:

  • deletion of arbitrary 24h-old files in an attacker-chosen directory;
  • disclosure — a tool response, which is the payload most likely to carry
    secrets, written to an attacker-chosen directory.

Neither needs user action. gatewayd.py:496 schedules cleanup_old_spill_files
on the maintenance executor at gateway startup, and the write path runs on any
oversized tool result.

The worst part is that the protection reads as present. Each site has an
explicit link check and a comment describing this attack, so a reviewer
concludes the path is hardened — while on Windows neither is.

What changed (motivation → approach → change)

Observed symptom — with the spill directory replaced by a junction, the
startup sweep deletes files in the junction's target, and an oversized tool
result is written there.

Root cause — Path.is_symlink() is False for a Windows junction while
is_dir() is True, so the directory-level check passes at both sites. Every
downstream defence is scoped to something else: S_ISREG to directory
entries, O_EXCL/O_NOFOLLOW to the final component.

Change — route both checks through platform_compat.is_link_or_junction,
which this module already imports:

if platform_compat.is_link_or_junction(spill_dir) or not spill_dir.is_dir():  # cleanup
if platform_compat.is_link_or_junction(spill_dir):                            # write

That helper tries os.path.islink first and only then tests for a junction, so
symlink behaviour is byte-identical and each change strictly widens what the
guard refuses. Two production lines, plus comments recording which link kinds
are covered and why the downstream defences are not substitutes.

grep -n 'is_symlink()' src/kiro_crew/mcp_gateway/spill.py now returns only
prose — no live call site remains.

Deliberately not changed. platform_compat.first_linked_ancestor documents
an adjacent gap — a link in an ancestor of the path, e.g. a junctioned
config_dir(). That is outside the threat these comments model ("swapped the
spill dir, or planted a link inside it") and outside what was measured, so it is
named here rather than folded in.

Tests

  • TestSpillCleanup::test_cleanup_refuses_a_linked_spill_dir — plants a
    25h-old file in the link target; asserts cleanup returns 0 and that the
    file still exists. The second assertion is the load-bearing one: a count of 0
    alone would also be satisfied by a sweep that found nothing.
  • TestSpillToFile::test_spill_refuses_a_linked_spill_dir — sends an
    oversized tool result through maybe_spill_response; asserts the link target
    is still empty and that the original line is forwarded unmodified.
  • test_make_dir_link_yields_a_junction_on_windows — guards the guard.
    What a junction is is already pinned by
    test_junction_is_recognised_and_removable, so this asserts only the property
    that is pinned nowhere else and that the two tests above depend on: that this
    seam yields a junction rather than a symlink. Were make_dir_link ever to
    hand back a symlink on Windows, both would pass against the original guards
    and prove nothing.

Red-before / green-after, measured on Windows with the tests in place and
spill.py reverted to origin/main:

E  assert [WindowsPath('.../test-mcp-req-7-1757...json')] == []
   AssertionError: spilled a payload outside the data home
E  assert 1 == 0
FAILED ...::TestSpillToFile::test_spill_refuses_a_linked_spill_dir
FAILED ...::TestSpillCleanup::test_cleanup_refuses_a_linked_spill_dir
2 failed, 1 passed

After the fix: 292 passed, 1 skipped across test_mcp_gateway_oversize.py +
test_mcp_gateway_backend_coverage.py (the skip is the pre-existing
windows-expected-failures.txt entry, not new).

Platform honesty. make_dir_link creates a junction on Windows and a
symlink on POSIX. The original checks already refused symlinks, so on Linux CI
the two containment tests are no-regression checks rather than red-befores —
only Windows exercises the fix. The third test exists so that distinction is
pinned in the suite rather than living only in this description.

Gates run locally: flake8 clean, isort --check-only clean, mypy reports
nothing for spill.py, and scripts/check_black_formatting.py passes scoped to
origin/main...HEAD — both touched files were already in the 1166-file
known-unformatted baseline, so no new offender and no unrelated reformatting.

Manual verification

N/A — unit coverage sufficient: both behaviours are filesystem-level guards, and
the tests create a real junction and assert on a real deletion and a real write,
so there is no integration surface the automated tests cannot reach.

Related Issues

None. Found while auditing link-containment guards; no existing issue covers
this file.

Pattern harvest

Rule candidate: semgrep

Pattern: a link-containment guard that tests only is_symlink() /
os.path.islink() before acting on a path — a Windows junction is invisible to
both and passes as an ordinary directory, so the guard silently does not hold
there. Any such site that then walks, reads, hashes, writes or unlinks through
the path should go through platform_compat.is_link_or_junction.

Two corollaries this PR is direct evidence for:

  • Sweep the whole file, not the hit. The same spill_dir was guarded twice
    with the same blind spot; fixing only the site that surfaced first would have
    left the disclosure half live.
  • Depth does not save you. A per-entry S_ISREG screen and an
    O_EXCL/O_NOFOLLOW open both sat downstream of these guards and neither
    helped, because each is scoped to a component rather than to the directory the
    path resolves through.

The inverse is not a defect: shutil.rmtree refuses a junction on its own, so
an rmtree-based site is already safe.

Checklist

  • At most two commits (one is the norm), with a Conventional Commits title (feat|fix|docs|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

🤖 Generated with Claude Code

@leonlaiyc
leonlaiyc requested review from a team and pepmach September 6, 2026 09:25
@github-actions github-actions Bot added fork Pull request from a fork (external contributor) readiness: action required A blocking check or review needs attention readiness: checking Automated validation is still running and removed readiness: action required A blocking check or review needs attention labels Sep 6, 2026
@github-actions

github-actions Bot commented Sep 6, 2026 •

Copy link
Copy Markdown
Contributor

GPT 5.6 Review (fork) — 🔴 changes requested (blocking)

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

1 of 1 blocking finding(s) are security-class and were withheld from adjudication, so the blocking verdict stands.

BLOCKING -- src/kiro_crew/mcp_gateway/spill.py:65 -- Link checks remain vulnerable to a swap race (origin: validation)
if platform_compat.is_link_or_junction(spill_dir) or not spill_dir.is_dir():
if platform_compat.is_link_or_junction(spill_dir):
Writable spill dir swapped after check -> cleanup/write resolves through junction -> arbitrary file deletion or response disclosure.
Anchor: residual/security
Fix: Pin the real directory across each operation and use descriptor-relative access on POSIX.
[BLOCK-MERGE] 1ed5741
[GPT-REVIEWED] 1ed5741

Adjudication (Opus 4.8) — is blocking on each finding proportionate?

The adjudicable block is empty (0 findings). Only fenced finding F1 remains.

F1 — TOCTOU swap race on the spill directory. The diff hardens the check by adding junction detection (spill.py:61, spill.py:131 via is_link_or_junction), but the finding's residual is that the check and the use are separate operations: after the guard passes, the directory can be swapped for a link before iterdir()/unlink() (cleanup) or os.open() (write) resolves through it. The fix comment itself concedes O_NOFOLLOW constrains only the final path component, not the directory the path resolves through (spill.py:141-147), so the residual is genuine, not closed by this PR.

Harm is unbounded of the security kind: arbitrary file deletion (cleanup path) or disclosure of a full tool response — a payload that may carry secrets — into an attacker-chosen location (write path). To FLAG I would need to show the swap-and-win condition combination is so extreme a human would accept the residual risk. I cannot complete that record: an agent controlling its own execution timing can retry the race, and I cannot establish from code opened in this run that swapping a directory inside the data home is unreachable — that precondition is precisely the pre-existing filesystem state the residual concerns. When torn on an unbounded-harm fenced finding, the contract requires UPHOLD-FENCED.

[ADJUDICATION] 1ed5741249e56f65ec2c1c37d8d4532e4f64eaae total=0 uphold=0 downgrade=0
[GPT-ADJUDICATED] 1ed5741249e56f65ec2c1c37d8d4532e4f64eaae
[ADJUDICATION-FENCED] 1ed5741249e56f65ec2c1c37d8d4532e4f64eaae fenced=1 flagged=0
UPHOLD-FENCED F1 src/kiro_crew/mcp_gateway/spill.py:65 -- Genuine residual TOCTOU: the link/junction guard and the subsequent iterdir/open are separate operations, so a swap between them redirects deletion or secret-bearing writes; O_NOFOLLOW covers only the final component, and the swap precondition cannot be shown unreachable from code opened here.
[GPT-ADJUDICATED-FENCED] 1ed5741249e56f65ec2c1c37d8d4532e4f64eaae

@github-actions

github-actions Bot commented Sep 6, 2026 •

Copy link
Copy Markdown
Contributor

Opus 4.8 Review (fork) — ✅ no blocking findings

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

Review details

No findings.

[OPUS-REVIEWED] 1ed5741

@github-actions

github-actions Bot commented Sep 6, 2026 •

Copy link
Copy Markdown
Contributor

Design Review (Fable 5, fork) — ✅ PASS

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

All claims verified against the base tree: platform_compat is already imported in spill.py, is_link_or_junction exists with a 3.10/3.11 junction fallback and tests islink first (so symlink behavior is unchanged, the guard only widens), and make_dir_link is an existing conftest seam. The change is two guard lines routed through an existing helper, no pinned test is weakened, Windows red-before/green-after is documented, and the failure posture stays fail-open for the response path. The known adjacent gap (a linked ancestor, e.g. a junctioned config_dir()) is explicitly scoped out rather than silently missed.

Design-Verdict: PASS

Real cross-platform bypass of two existing containment guards, closed at the right layer with the helper built for exactly this, minimally and verifiably.

Suggestions

  • The PR names the ancestor-link gap (first_linked_ancestor on a junctioned config_dir()) but files nothing — open a tracking issue so the deferral outlives this PR description.

[DESIGN-REVIEWED] 1ed5741

@github-actions

github-actions Bot commented Sep 6, 2026 •

Copy link
Copy Markdown
Contributor

First Principles Review (Fable 5, fork) — 🟡 CONCERNS

Premise-level review of 1ed5741249e56f65ec2c1c37d8d4532e4f64eaae 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.

All verification done. The change reuses existing mechanisms, the defect is derived from a documented platform rule the repo itself pins in platform_compat.py, and both changed guards are the fix's two consequences of one cause. The one depth finding: the identical is_symlink()-only directory-guard pattern survives at other sites I read and verified. Final review:

First-Principles-Verdict: CONCERNS

The exact is_symlink()-only dir-guard this PR harvests as a pattern sits unfixed at kiro_prerequisite.py:1176 and wheel_engine.py:696.

Not justified as shipped

  • Item 5 — rides along: comment/docstring rewrite at both sites; harm-free, inventory only.

What this change ships

Intent: stop the gateway deleting or writing files through a junction planted as its spill directory on Windows — a FIX.

  1. Startup sweep now refuses a junctioned spill dir instead of deleting 24h-old files in its target — justified
  2. Oversized tool responses are no longer written through a junctioned spill dir; original line forwarded — justified
  3. Refusal log line now reads "symlink or junction" — rides along
  4. Two containment tests plus a Windows-only test pinning that make_dir_link yields a junction — justified
  5. Both sites' docstrings/comments rewritten to record junction coverage — rides along

Watch

  • Point patch with counted siblings. Grepped is_symlink\(\)|os\.path\.islink across src/kiro_crew (~150 hits); at least two are the same directory-level guard-then-operate shape with the same junction blind spot: kiro_prerequisite.py:1176,1185,1191 (auth staging root — credential material then written beneath it; Windows branch exists at line 1196) and platform/wheel_engine.py:696 (shadow venv dir subsequently removed). The description defers only the ancestor-link gap, not these.
    Clears when: those guards route through platform_compat.is_link_or_junction, or a linked issue records the repo-wide sweep the "Pattern harvest" proposes.

[FIRST-PRINCIPLES-REVIEWED] 1ed5741

@leonlaiyc
leonlaiyc force-pushed the fix/spill-cleanup-junction-containment branch from f7f70d4 to e03a62e Compare September 6, 2026 10:02
@github-actions github-actions Bot added readiness: action required A blocking check or review needs attention and removed readiness: checking Automated validation is still running labels Sep 6, 2026
@leonlaiyc leonlaiyc changed the title fix(mcp-gateway): refuse a junctioned spill dir in the 24h cleanup sweep fix(mcp-gateway): refuse a junctioned spill dir on both spill paths Sep 6, 2026
@github-actions github-actions Bot added readiness: checking Automated validation is still running readiness: action required A blocking check or review needs attention and removed readiness: action required A blocking check or review needs attention readiness: checking Automated validation is still running labels Sep 6, 2026
`spill.py` guards its spill directory in two places, and BOTH tested only
`spill_dir.is_symlink()`. A Windows junction is a directory reparse point,
not a symlink: `is_symlink()` answers False for one and `is_dir()` answers
True, so both guards admitted it and both operated through the link.

1. `cleanup_old_spill_files()` — the 24h sweep iterated the junction's
   TARGET and called `entry.unlink()` on every 24h-old regular file there.
   Its docstring names this exact threat: "an agent that swapped the spill
   dir ... could otherwise aim this sweep at an arbitrary directory and
   have the gateway delete 24h-old files there (confused deputy)". The
   per-entry `lstat`/`S_ISREG` screen does not help — it skips links INSIDE
   the directory, while here the directory itself is the link.

2. `maybe_spill_response()` — the write path wrote the spilled payload into
   the junction's target. Its comment states the stake: "an attacker-planted
   link would redirect the write outside the data home". What lands there is
   a full tool response, exactly the content that may carry secrets. The
   `O_EXCL`/`O_NOFOLLOW` open does not cover it: those constrain the FINAL
   component, not the directory the path resolves through, and
   `os.O_NOFOLLOW` does not exist on Windows — the only platform with
   junctions.

Both now go through `platform_compat.is_link_or_junction`, which the module
already imports. It tries `os.path.islink` first, so symlink behaviour is
unchanged and this strictly widens what each guard refuses.

Tests: `test_cleanup_refuses_a_linked_spill_dir` and
`test_spill_refuses_a_linked_spill_dir` build the link with
`conftest.make_dir_link`. Measured on Windows against the unpatched tree,
both fail — the sweep deletes the victim's file (`assert 1 == 0`) and the
write path leaves a spill file in the victim directory. Both pass after.
On POSIX `make_dir_link` yields a symlink, which the original checks already
refused, so there they are no-regression checks;
`test_make_dir_link_yields_a_junction_on_windows` pins the seam property
that makes them load-bearing on Windows without restating what
`test_junction_is_recognised_and_removable` already covers.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
@bolichen97
bolichen97 force-pushed the fix/spill-cleanup-junction-containment branch from e03a62e to 1ed5741 Compare September 8, 2026 11:13
@bolichen97

Copy link
Copy Markdown
Contributor

Rebased onto main 2b060c18 by a maintainer as part of the 2026-09-08 open-PR audit. New head: 1ed57412 (was e03a62e1).

Clean rebase, no conflicts. No content changes to the PR's diff.

Gates run locally on the changed files only: black --check (both files fail, but they are already listed in .github/black-baseline.txt and fail identically on main, so pre-existing), isort --check-only (pass), flake8 (pass), pytest test/test_mcp_gateway_oversize.py (25 passed, 1 skipped).

Please review the rebase result. Note that a maintainer push makes the maintainer the last pusher, so under the repo's last-push rule a second approver is needed. Reply here if anything looks wrong.

@github-actions github-actions Bot added readiness: checking Automated validation is still running readiness: action required A blocking check or review needs attention and removed readiness: action required A blocking check or review needs attention readiness: checking Automated validation is still running labels Sep 8, 2026
@dwu96 dwu96 added the needs-pr-triage PR scanner: awaiting automated triage label Sep 15, 2026
@chenmingwei23 chenmingwei23 added drive-to-green PR claimed by drive-to-green pipeline and removed needs-pr-triage PR scanner: awaiting automated triage labels Sep 15, 2026
@chenmingwei23

Copy link
Copy Markdown
Contributor

Kiro Crew [operator: chenmingwei23#de330d0c]

Triaged as solvable and claimed for the drive-to-green pipeline.

No conflict. Design PASS, Opus clean. Two blockers:

  1. GPT 5.6 Review has one BLOCKING finding: a TOCTOU swap race on the spill
    directory -- the path is validated and then operated on by name, so the
    directory can be swapped for a junction between check and use. GPT names the
    remedy: pin the real directory across each operation and use
    descriptor-relative access on POSIX. That is what will be implemented, with a
    test covering the swap window.
  2. Backend Lint and Type Check is CANCELLED on the stale merge ref and clears on a
    fresh head.

The First Principles CONCERNS about the same pattern at two other call sites is a
ride-along observation. It will be answered in a comment, not folded into this diff.

Content security scan passed with no findings.

@github-actions github-actions Bot added the merge conflict Branch has merge conflicts with its base — author must resolve before merge label Sep 30, 2026
@iamwhatever

Copy link
Copy Markdown
Contributor

Thank you for this, @leonlaiyc — a careful fix with a clearly-reasoned write-up and real red-before/green-after Windows evidence.

While this was open, main independently shipped the same fix. Commit 6d54165 ("make four is_symlink guards see a junction", #15310, merged 2026-09-30) now routes both spill.py guards through platform_compat.is_link_or_junction instead of is_symlink():

  • cleanup_old_spill_files() — spill.py:69
  • maybe_spill_response() — spill.py:138

Those lines match the two you proposed here, and no live is_symlink() call remains in the file — the exact outcome your PR aimed for. That same main advance is what put this PR into a CONFLICTING state.

Since the bug is already fixed on main the same way, this PR is superseded and I'm closing it. Your diagnosis stands on its own and was correct; thank you for digging into the Windows junction blind spot.

@iamwhatever iamwhatever closed this Oct 4, 2026
@github-actions github-actions Bot removed the readiness: action required A blocking check or review needs attention label Oct 4, 2026
@mbriones98 mbriones98 removed the drive-to-green PR claimed by drive-to-green pipeline label Oct 19, 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) merge conflict Branch has merge conflicts with its base — author must resolve before merge

Projects

None yet

Development

Successfully merging this pull request may close these issues.

6 participants