Skip to content

fix: make the remaining is_symlink() guards see Windows junctions - #11136

Merged
iamwhatever merged 1 commit into
mainfrom
fix/junction-guard-audit-10737
Sep 16, 2026
Merged

iamwhatever merged 1 commit into
mainfrom
fix/junction-guard-audit-10737

Conversation

@CrysisDeu

@CrysisDeu CrysisDeu commented Sep 15, 2026 •

Copy link
Copy Markdown
Contributor

What

Audit of the is_symlink()-based link guards that PR #9062's First Principles Review lane deferred to #10737: seed.py, deploy/__init__.py, and pod/runtime.py. Every guard that can meet a Windows directory junction now uses a junction-aware oracle; the one site that cannot is annotated so the next audit does not re-count it.

Why

A directory junction is what platform_compat.symlink_or_junction (and any unelevated Windows writer) produces, because a directory symlink there needs SeCreateSymbolicLinkPrivilege. A junction answers False to is_symlink(), and when dangling also to exists() / is_file() / is_dir(). So each guard below was blind to exactly the link shape that can occur on Windows:

Site Junction can come from What the old guard did on Windows
seed.py dangling-$KIROCREW_HOME guard symlink_or_junction / any Windows writer publishing the home dangling junction fell through every exists()-gated guard into the raw copytree FileExistsError the guard exists to prevent
deploy/__init__.py link migration apps/bridges.py publishes <home>/skills/<name> via symlink_or_junction; a deploy skill shares that namespace live junction reached the exists() branch, rmtree_force refused it (stdlib rmtree does not descend a junction root), gateway startup aborted with "could not remove"; dangling one crashed copytree
pod/runtime.py orphan_homes planted under pod_root (the guard's own threat model; on unelevated Windows a junction is the only link a same-user writer can plant) listed the planted alias as an orphan
pod/runtime.py cleanup_home pre-check, _rmtree_bounded, post-check same alias resolved to the live sibling, passed containment, rmtree refused it silently, the full 10-attempt retry window spun, and the sibling's files were reported as "something is still writing there" instead of naming the link
pod/runtime.py write_pod_config create-only guard planted at config.json live junction read as "already configured" (pod boots with a directory where its config should be); dangling one let the create-only write land on the surviving entry

Annotated, not converted: stop_pod's systemd drop-in is_symlink() is Linux-only; junctions do not exist there.

How

  • seed.py: pinned_fs.is_reparse_point(dst) and not dst.exists() -- the same oracle the sibling populated/empty-link guardrails in that function already use, so one function keeps one oracle. Message now says "dangling symlink or junction"; the guardrail constant is unchanged.
  • deploy/__init__.py: is_link_or_junction(link) -> unlink_link_or_junction(link) (removes the link, never its target). Link-first so a dangling entry is still handled.
  • pod/runtime.py: the five is_symlink() reads in the orphan / reclaim / config-seed path route through platform_compat.is_link_or_junction. Messages say "symlink or junction" / "symbolic link or junction"; existing match="symbolic link" / "symlink" in out assertions still hold.

Pattern harvest

Not generalizable: as a lint rule -- see the semgrep evaluation below. The reusable pattern is the test recipe (real shape via symlink_or_junction + simulated junction via the OS oracle), which this PR applies at every site.

Semgrep rule (proposed in #9062's Pattern harvest): evaluated, declined

The proposal was a same-module rule: symlink_or_junction writer + is_symlink reader in one file. Measured against this audit, the writer and the reader are in different modules at every site: apps/bridges.py writes, deploy/__init__.py reads; frontend.py writes, pod/provision.py read (#9062); seed.py and pod/runtime.py have no product writer at all (the link is user- or attacker-planted). The rule would have matched 0 of 3 sites here and 1 of 3 in #9062. A module-agnostic "any is_symlink() / os.path.islink" rule has the recall but not the precision: 166 such calls across 78 modules in src/kiro_crew today (vs 142 is_link_or_junction calls), most of them legitimate on POSIX-only paths, so it would ship with a 166-entry allowlist that every new POSIX-only guard has to grow. Neither is worth adding; this PR's pinning tests are the guard.

Tests

Per converted site, two tests, following the pattern #9062 established:

  1. Real shape -- built with the product's own platform_compat.symlink_or_junction, so each platform exercises what it actually produces: a symlink on POSIX (already handled, passes on base), a junction on an unelevated Windows shard (red on base).
  2. Simulated junction shape -- so the POSIX shards pin the guard too. A junction cannot be created on POSIX, so the OS-level junction oracle (platform_compat._ISJUNCTION, or pinned_fs.is_reparse_point for seed.py) is taught to recognise one real directory / one absent path, while every pathlib predicate keeps its true answer (is_symlink() False, is_dir()/exists() as a live or dangling junction would answer). is_link_or_junction / unlink_link_or_junction run their real logic over it. These tests are red on base on every platform.

Mutation check (source reverted, tests kept): 10 failed, 6 passed -- the 10 are the simulated-shape tests plus the message assertions; the 6 are the real-shape tests that on this POSIX host produce a symlink the old guards already handled (they go red only on the Windows shards). Source re-applied: all green.

Ran by path with -n0 on Python 3.12:

  • test/test_seed.py, test/test_readonly_source_skill_install.py, test/test_deploy_round15_fixes.py: 84 passed
  • test/test_pod.py: 461 passed, 1 skipped

test_deploy_round15_fixes.py::test_symlink_migration_replaces_with_copy was a source-text pin on link.is_symlink() / link.unlink(); it now pins the junction-aware pair and asserts the old spelling is gone.

isort / flake8 / black / mypy clean on the seven changed files.

Other

Closes #10737

@CrysisDeu
CrysisDeu requested review from a team and smeyffret September 15, 2026 23:54
@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: checking Automated validation is still running labels Sep 15, 2026
@github-actions

github-actions Bot commented Sep 15, 2026 •

Copy link
Copy Markdown
Contributor

Design Review (Fable 5) — ✅ PASS

Design-level review of b04b770d1ee70b8da2c66436b20ebf4e0214adb1 — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS/CONCERNS are advisory.

Design-Verdict: PASS

Confirm the Windows CI shard runs the new real-shape tests green — the mutation check quoted was POSIX-only, so Windows behavior rests on that shard.

[DESIGN-REVIEWED] b04b770

@github-actions

github-actions Bot commented Sep 15, 2026 •

Copy link
Copy Markdown
Contributor

First Principles Review (Fable 5) — ✅ PASS

Premise-level review of b04b770d1ee70b8da2c66436b20ebf4e0214adb1 — 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: PASS

Confirm the real-shape tests actually go red-on-base on a Windows shard — the author's mutation check ran only on a POSIX host.

What this change ships

Inventory (9 items) — 9 justified

Intent: FIX — close #10737, the deferred audit making the remaining is_symlink() guards recognise Windows directory junctions, the only link an unelevated Windows writer can plant.

  1. Seed on a dangling junction at $KIROCREW_HOME fails with the guardrail message, not raw FileExistsError — justified
  2. Gateway startup survives an app-published junction at a deploy-skill name: detached, replaced with a managed copy — justified
  3. A planted junction alias under pod_root is no longer listed as an orphan (link test now lstat-first) — justified
  4. pod down on a junction alias refuses immediately, naming the link, instead of spinning retries and blaming "still writing" — justified
  5. A mid-delete junction swap stops the retry window at once and is named as the link — justified
  6. Pod config seeding refuses a junction at config.json instead of reading it as "already configured" — justified
  7. stop_pod drop-in is_symlink() annotated Linux-only so the next audit skips it (comment only) — justified
  8. Source-text test pin rewritten to the junction-aware pair, old spelling asserted gone — justified
  9. black-baseline.txt drops the graduated test file (with black's reformat riding along) — justified

Evidence checked: Closes #10737 links the deferred audit; is_link_or_junction / unlink_link_or_junction / _ISJUNCTION exist in platform_compat.py:4457/4503/4433 and seed.py's sibling guardrails already use pinned_fs.is_reparse_point (lines 728, 741) — the change reuses existing mechanisms, adds no new surface. Zero unconverted is_symlink() guards remain in the three touched modules (grepped is_symlink|islink; only the annotated Linux-only site at runtime.py:1472). The pin rewrite is declared with evidence the old spelling was junction-blind. The baseline prune is mandated by check_black_formatting.py (graduated entries error until removed). Other-site siblings are covered by declared open PRs #8973/#9021/#9034.

[FIRST-PRINCIPLES-REVIEWED] b04b770

@github-actions

github-actions Bot commented Sep 15, 2026 •

Copy link
Copy Markdown
Contributor

Opus 4.8 Review — ✅ no blocking findings

Reviewed b04b770d1ee70b8da2c66436b20ebf4e0214adb1 — this comment is updated in place on each push.

Review details

The PR uniformly widens is_symlink()-based guards to junction-aware checks (is_link_or_junction / pinned_fs.is_reparse_point), and I've verified the helpers: is_reparse_point and is_link_or_junction both return True for plain POSIX symlinks (via os.path.islink first), so no POSIX regression; the seed dangling guard and its sibling guardrails now use the same oracle consistently; unlink_link_or_junction removes the link/junction without following it; and orphan_homes correctly re-orders the lstat-based link test before is_dir(). Every conversion preserves refuse/return semantics and tightens rather than weakens the link guards.

No findings.

[OPUS-REVIEWED] b04b770

Verdict parsed from the review's SHA-scoped output markers for commit b04b770d1ee70b8da2c66436b20ebf4e0214adb1.

False positive or not applicable? A repository writer can comment:
/ai-review override fable b04b770d1ee70b8da2c66436b20ebf4e0214adb1: <one-sentence reason>

@github-actions

github-actions Bot commented Sep 15, 2026 •

Copy link
Copy Markdown
Contributor

GPT 5.6 Review — ✅ no blocking findings

GPT 5.6 completed its review of b04b770d1ee70b8da2c66436b20ebf4e0214adb1 and found no blocking issues.

This comment is updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] b04b770

False positive or not applicable? A repository writer can comment:
/ai-review override gpt b04b770d1ee70b8da2c66436b20ebf4e0214adb1: <one-sentence reason>

@CrysisDeu
CrysisDeu force-pushed the fix/junction-guard-audit-10737 branch from 463b66b to b56a010 Compare September 16, 2026 00:03
@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 16, 2026
Audit of the is_symlink()-based link guards that PR #9062's First
Principles Review lane deferred (issue #10737). A directory junction --
the shape platform_compat.symlink_or_junction and any unelevated Windows
writer produce -- answers False to is_symlink(), and when dangling also to
exists()/is_file()/is_dir(), so each of these guards was blind to exactly
the link that can occur on Windows.

Converted (junction-aware oracle, one pinning test per site built with the
product's own link helper plus a simulated-junction test so POSIX shards
pin it too):

- seed.py dangling-$KIROCREW_HOME guard: now pinned_fs.is_reparse_point,
  the oracle the sibling guardrails in the same function already use. A
  dangling junction fell through every exists()-gated guard into the raw
  copytree FileExistsError the guard exists to prevent.
- deploy/__init__.py link migration: is_link_or_junction /
  unlink_link_or_junction. <home>/skills/<name> is also published by
  apps/bridges.py through symlink_or_junction, so a live junction reached
  the exists() branch where rmtree_force refused it and gateway startup
  aborted; a dangling one crashed copytree.
- pod/runtime.py orphan_homes, cleanup_home (pre- and post-check),
  _rmtree_bounded, write_pod_config: is_link_or_junction. On unelevated
  Windows a junction is the only link a same-user writer can plant under
  pod_root, so the planted alias was listed as an orphan, resolved to its
  live sibling, passed containment, and its refusal was reported as
  "something is still writing there" after the full retry window.

Annotated, not converted: stop_pod's systemd drop-in check is Linux-only.

Semgrep rule proposed in #9062 (symlink_or_junction writer + is_symlink
reader in one module): evaluated and declined -- the writer and reader
live in different modules at every site in this audit (bridges.py vs
deploy, frontend.py vs pod/provision.py, or no product writer at all), so
the rule would have matched none of them, while a module-agnostic
is_symlink() rule would need a 166-site allowlist.

Closes #10737
@CrysisDeu
CrysisDeu force-pushed the fix/junction-guard-audit-10737 branch from b56a010 to b04b770 Compare September 16, 2026 00:55
@github-actions github-actions Bot added readiness: checking Automated validation is still running readiness: action required A blocking check or review needs attention readiness: passed Eligible automated validation passed for the current revision and removed readiness: action required A blocking check or review needs attention readiness: checking Automated validation is still running labels Sep 16, 2026

@iamwhatever iamwhatever left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Approved after a full read of the diff on the current head: the change matches the linked issue and body, every load-bearing claim was spot-checked against main, tests pin the behaviour, all review lanes are clean and nothing is left undisposed on this head.

@iamwhatever
iamwhatever enabled auto-merge (squash) September 16, 2026 05:22
@iamwhatever
iamwhatever merged commit f1d304c into main Sep 16, 2026
115 of 120 checks passed
@iamwhatever
iamwhatever deleted the fix/junction-guard-audit-10737 branch September 16, 2026 05:23
@github-actions github-actions Bot removed the readiness: passed Eligible automated validation passed for the current revision label Sep 16, 2026
amadsalmon pushed a commit to amadsalmon/KiroCrew that referenced this pull request Sep 22, 2026
…rodotdev#11136)

Audit of the is_symlink()-based link guards that PR kirodotdev#9062's First
Principles Review lane deferred (issue kirodotdev#10737). A directory junction --
the shape platform_compat.symlink_or_junction and any unelevated Windows
writer produce -- answers False to is_symlink(), and when dangling also to
exists()/is_file()/is_dir(), so each of these guards was blind to exactly
the link that can occur on Windows.

Converted (junction-aware oracle, one pinning test per site built with the
product's own link helper plus a simulated-junction test so POSIX shards
pin it too):

- seed.py dangling-$KIROCREW_HOME guard: now pinned_fs.is_reparse_point,
  the oracle the sibling guardrails in the same function already use. A
  dangling junction fell through every exists()-gated guard into the raw
  copytree FileExistsError the guard exists to prevent.
- deploy/__init__.py link migration: is_link_or_junction /
  unlink_link_or_junction. <home>/skills/<name> is also published by
  apps/bridges.py through symlink_or_junction, so a live junction reached
  the exists() branch where rmtree_force refused it and gateway startup
  aborted; a dangling one crashed copytree.
- pod/runtime.py orphan_homes, cleanup_home (pre- and post-check),
  _rmtree_bounded, write_pod_config: is_link_or_junction. On unelevated
  Windows a junction is the only link a same-user writer can plant under
  pod_root, so the planted alias was listed as an orphan, resolved to its
  live sibling, passed containment, and its refusal was reported as
  "something is still writing there" after the full retry window.

Annotated, not converted: stop_pod's systemd drop-in check is Linux-only.

Semgrep rule proposed in kirodotdev#9062 (symlink_or_junction writer + is_symlink
reader in one module): evaluated and declined -- the writer and reader
live in different modules at every site in this audit (bridges.py vs
deploy, frontend.py vs pod/provision.py, or no product writer at all), so
the rule would have matched none of them, while a module-agnostic
is_symlink() rule would need a 166-site allowlist.

Closes kirodotdev#10737
bolichen97 pushed a commit that referenced this pull request Sep 30, 2026
) (#15310)

A Windows directory JUNCTION is a reparse point that Path.is_symlink()
and os.path.islink() both answer False for while is_dir() answers True,
and it is the only directory link an unprivileged Windows writer can
plant. Four link guards still tested is_symlink() (or a bare is_dir()),
so each failed OPEN for a junction while reading green on POSIX, where
the same plant is a symlink the old predicate catches. All four move to
platform_compat.is_link_or_junction, the repository's mandated predicate.

- portability.apply_import_zip: the replace-mode skills/auto strip
  guarded shutil.rmtree with a bare is_dir(), so a junction planted at
  skills/auto in the extraction tree aimed the delete OUTSIDE the
  archive. The LINK is now unlinked with unlink_link_or_junction (never
  its target); only a real directory reaches rmtree.
- connections.mint._is_reapable_spec: a junction at a mint-spec name was
  read as our own spec and unlinked, removing a directory link into a
  target this module does not own.
- connections.warm._warm_spec_is_foreign: a junction at a warm-spec name
  read as a free path (is_symlink() and, when dangling, exists() both
  False), so the writer replaced it and the sweep unlinked it.
- mcp_gateway.spill cleanup_old_spill_files / maybe_spill_response: a
  junction at the spill dir was followed, so the sweep deleted 24h-old
  files under its target (confused-deputy delete outside the data home).

Tests stage a real junction through conftest.make_dir_link (a junction
on Windows, a directory symlink on POSIX) and assert the guard refuses
it without touching the link's target, matching #11136 / #14327.

The four now match test_link_screen_hold_pin's discovery condition
(is_link_or_junction screen + a by-name resolve), so link_screen_sites.py
is regenerated. All four are the NO-HOLD kind: each refuses every link
and never traverses one.

The issue's fourth named site -- the deploy staging walk -- already
carries the fix on main (#14327, _stage_tree_safe), so it is not
re-touched here.

Fixes #12379
Fixes #10492

Co-authored-by: kirocrew-agent <agent@kirocrew.local>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Audit remaining is_symlink() guards for the Windows junction blind spot (seed.py, deploy, pod/runtime)

2 participants