Skip to content

fix(design-tweak): stop the preview HTML scan enumerating a junctioned tree - #8767

Merged
bolichen97 merged 1 commit into
kirodotdev:mainfrom
leonlaiyc:fix/design-tweak-preview-junction-scan
Sep 6, 2026
Merged

bolichen97 merged 1 commit into
kirodotdev:mainfrom
leonlaiyc:fix/design-tweak-preview-junction-scan

Conversation

@leonlaiyc

@leonlaiyc leonlaiyc commented Sep 5, 2026 •

Copy link
Copy Markdown
Contributor

Problem / Motivation

scan_html builds the list of previewable pages that Design Tweak's diagnostic
404 renders, so its walk discloses filenames. It deliberately tests for a
link before calling is_dir(), and the comment in the source says exactly why:

Check before is_dir(), which follows links. Diagnostic names are visible to
the preview page, so even listing a linked private directory would disclose
information.

The test it used was entry.is_symlink().

On Windows that does not report a directory junction — and a junction is
precisely a DIRECTORY link, so it fell straight through to the is_dir() arm of
the same loop. A docs junction pointing at a protected directory had the walk
enumerate that directory and print its HTML filenames on the 404 page.

Why it matters

This is the exact disclosure the guard exists to prevent, reachable on Windows.
Contents never leak — the listing does, which is what the sensitive-path floor
is there to withhold.

The platform asymmetry is what makes it worth fixing rather than shrugging at: a
symlink on Windows requires a privilege, a junction requires none. So the
symlink-only test withheld the listing in the case a Windows user mostly cannot
create, and allowed it in the case they can.

That asymmetry is also why the gap survived review. Every existing test in
TestHtmlScanDoesNotFollowSymlinks is marked @requires_symlinks, so the entire
class is skipped on Windows. The suite looked thorough and covered this walk on
POSIX only.

What changed (motivation → approach → change)

Symptom — a junctioned directory under a preview root is enumerated by
scan_html and its HTML filenames reach the diagnostic 404.

Root cause — the walk tested one link type instead of asking the platform
seam that knows about both. Because a junction is a directory, the miss does not
merely skip a check: it routes the entry into the "descend this directory"
branch.

Change — entry.is_symlink() becomes runtime.is_link_or_junction(entry).

Reached through runtime rather than by importing platform_compat into
preview_files, because that module's docstring makes server the boundary:

server is the composition root and security-policy owner. Helpers receive
that module as runtime and resolve mutable state and compatibility seams
at call time.

preview_files already reaches is_sensitive_path, _contained and
_is_project_secret that way, so this keeps one convention rather than adding a
second. server therefore gains is_link_or_junction in its platform_compat
import and in the existing _RUNTIME_COMPAT_IMPORTS tuple — the module's own
declared mechanism for "names intentionally present on the runtime module …
resolved late through the server-owned network, filesystem, clock, and platform
seams". That is what keeps the import honest to flake8 without a noqa.

This is also a documented repository rule, not only a local inference: the
cross-platform table in AGENTS.md carries the row

| Detect/remove a dir link | is_link_or_junction(path) / unlink_link_or_junction(path) | path.is_symlink() (misses a Windows junction) |

so the changed call site was on the NOT column of that table.

Two production files, one of them a single name added to an import list.

Tests

Added to the existing TestHtmlScanDoesNotFollowSymlinks class, so the junction
case sits beside the symlink cases it completes:

  • test_a_junctioned_directory_is_not_enumerated — the linked tree's HTML names
    must not appear, while the real page still does.
  • test_the_scan_consults_the_shared_link_helper — the walk must ASK the helper;
    the seam, not the outcome, is what is_symlink() got wrong.
  • test_a_real_windows_junction_is_not_enumerated — no stub, no elevation.
    Creates a genuine reparse point with _winapi.CreateJunction and asserts the
    protected directory's filename never reaches the listing.

The stubbed tests are needed because os.path.isjunction is 3.12+ and always
False off Windows; the real-junction test is what anchors them to actual platform
behaviour instead of to a mock of it.

Red-before against the unmodified main production files (Windows host,
-p no:randomly): 2 failed, and the real-junction one fails with

AssertionError: ['real.html', 'docs/private-notes.html']

— the disclosure itself, reproduced on a real junction with nothing mocked. (The
helper-spy test also fails there, with AttributeError, since main's server
has no such name to patch.)

Green-after: the whole file, 288 passed / 10 skipped.

Gates: repo black gate ✓, isort ✓, flake8 ✓ (including the F401 the import
would otherwise raise — resolved via the module's own compat tuple, not a
suppression), mypy ✓.

One note on evidence, since it nearly went the other way: an early full-file run
on this branch showed two TestStaticPreviewServer timeouts that a pristine-main
run did not. Repeating the full run twice more gave 288 passed in ~8s, matching
main's ~8s; the 41s outlier coincided with an unrelated repository-wide scan
competing for I/O on the same machine. Recorded rather than omitted, because a
single differing run is not attribution either way.

Manual verification

N/A — unit coverage sufficient. The regression creates a real Windows junction
and drives the actual walk, so the platform behaviour is executed rather than
described; a manual repro would be the same three commands with less precision.

Related Issues

No linked issue. Found by auditing surviving is_symlink() guards against
platform_compat.is_link_or_junction after #8165 (fix(diagnostics): reject a junctioned log dir, not just a symlinked one) merged.

Scope is this one walk. Other is_symlink() sites each need their own threat
analysis before they are worth changing — #8165's review made exactly that point
— so they are not bundled here.

Pattern harvest

Rule candidate: semgrep

Pattern: is_symlink() / os.path.islink() used as a refusal immediately before
an is_dir() branch. On Windows the predicate misses a directory junction, and
because a junction is a directory the missed entry does not fall through
harmlessly — it lands in the descend-this-directory arm, so a guard that reads as
fail-safe becomes fail-open on exactly one platform. A rule can flag the
islink-then-isdir shape in a walk and require the reparse-aware helper.

Secondary review prompt: a test class whose every member is skipped on a platform
is evidence that platform is unverified, not that it is covered — worth
reading as a signal when the code under test is platform-sensitive.

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) — the in-source comment now states which link types are covered and why
  • No secrets, credentials, or internal references in the diff

Contribution License Agreement

🤖 Generated with Claude Code

…d tree

`scan_html` feeds the diagnostic 404 that lists previewable pages, so its walk
discloses filenames. It skipped links before calling `is_dir()` precisely
because `is_dir()` follows them -- the comment says so: "even listing a linked
private directory would disclose information".

It asked `entry.is_symlink()`, which does NOT report a Windows directory
junction. A junction IS a directory, so it fell straight through to the
`is_dir()` arm and the walk enumerated the linked tree: `docs` junctioned at a
protected directory put that directory's HTML filenames on the 404 page.

Route it through the runtime's `is_link_or_junction`, matching how this module
already reaches its other policy seams (`is_sensitive_path`, `_contained`)
rather than importing one directly -- `server` is the documented
security-policy owner and compatibility-seam boundary for these helpers.

The platform asymmetry is the point: a symlink on Windows needs a privilege, a
junction needs none. So the guard withheld the listing exactly where a user
cannot plant the link and allowed it where they can. Every existing test in
`TestHtmlScanDoesNotFollowSymlinks` is `@requires_symlinks` and therefore
skipped on Windows, which is how the gap survived.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
@leonlaiyc
leonlaiyc requested review from a team and krishdhasmana September 5, 2026 15:05
@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 5, 2026
@github-actions

github-actions Bot commented Sep 5, 2026

Copy link
Copy Markdown
Contributor

GPT 5.6 Review (fork) — ✅ no blocking findings

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

Review details

No findings.
[GPT-REVIEWED] 4dfa534

@github-actions

github-actions Bot commented Sep 5, 2026

Copy link
Copy Markdown
Contributor

Design Review (Fable 5, fork) — ✅ PASS

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

The change is a two-line predicate swap routed through the module's documented runtime seam, backed by the repo's own platform_compat shim table (which explicitly names is_link_or_junction over path.is_symlink() for exactly this Windows-junction miss). The base code confirms the description end-to-end: the walk did fall through to the is_dir() descend arm, the fix asks the shared platform helper, POSIX behavior is unchanged, and the scoping-out of other is_symlink() sites is explicitly justified. No contract, schema, or reversibility issues.

Design-Verdict: PASS

A real Windows-only disclosure closed at its root cause via the repo's own platform seam, minimal diff, anchored by a real-junction regression test.

[DESIGN-REVIEWED] 4dfa534

@github-actions

github-actions Bot commented Sep 5, 2026

Copy link
Copy Markdown
Contributor

Opus 4.8 Review (fork) — ✅ no blocking findings

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

Review details

No findings.

[OPUS-REVIEWED] 4dfa534

@github-actions

github-actions Bot commented Sep 5, 2026

Copy link
Copy Markdown
Contributor

First Principles Review (Fable 5, fork) — ✅ PASS

Premise-level review of 4dfa5345f55a915cffcf88fc8bea132077afea52 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.

The base tree confirms everything material: the vulnerable entry.is_symlink() sits at preview_files.py:272 under exactly the comment the description quotes; platform_compat.is_link_or_junction (platform_compat.py:3464) is the documented shim-table replacement AGENTS.md mandates over is_symlink(); server.py's _RUNTIME_COMPAT_IMPORTS tuple is the module's existing late-resolution mechanism the new name joins; and every existing test in TestHtmlScanDoesNotFollowSymlinks is indeed @requires_symlinks-gated. The one structurally identical sibling I could verify (design_critique/backend/routes.py:356 — an islink prune inside a walk that would descend a junction) has a different harm (digest coverage, not disclosure), and the author declared the deferral with a cited prior review.

First-Principles-Verdict: PASS

One-line mechanism fix at the documented platform seam, closing a real Windows-only disclosure the description reproduces; nothing rides along.

What this change ships

Intent: stop the Design Tweak preview's 404 page listing filenames from a junction-linked directory on Windows. This is a FIX.

  1. A junctioned directory under a preview root is no longer enumerated on the diagnostic 404 — justified (reproduced disclosure; AGENTS.md shim table mandates is_link_or_junction over is_symlink()).
  2. The walk asks the shared platform link helper through the server's runtime seam — justified (module's own documented convention; _RUNTIME_COMPAT_IMPORTS is the existing mechanism, not new surface).
  3. Three regression tests, one on a real Windows junction — justified, declared.
  4. Expanded in-source comment naming both link types — declared.

Watch

  • Counted siblings of the islink-before-descend walk shape remain (grep is_symlink()|os.path.islink( in src/kiro_crew: ~130 hits; the verified same-shape walk is design_critique/backend/routes.py:356, where a junction survives the prune into the descend arm). The author defers them per fix(diagnostics): reject a junctioned log dir, not just a symlinked one #8165's per-site threat-analysis ruling — accepted-and-deferred, not a demand.

[FIRST-PRINCIPLES-REVIEWED] 4dfa534

@github-actions github-actions Bot added readiness: action required A blocking check or review needs attention readiness: checking Automated validation is still running readiness: passed Eligible automated validation passed for the current revision and removed readiness: checking Automated validation is still running readiness: action required A blocking check or review needs attention labels Sep 5, 2026

@bolichen97 bolichen97 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 strict Tech Lead review.

Correctness. The changed call site is literally on the NOT column of AGENTS.md's cross-platform table (Detect/remove a dir link -> is_link_or_junction(path), NOT path.is_symlink() which "misses a Windows junction"). Verified the mechanism end to end: scan_html's walk iterates directory.iterdir(), so entry is a pathlib.Path and satisfies is_link_or_junction(path: str | os.PathLike); runtime is scan_html's own parameter and is in walk's closure; server._scan_html delegates with the module as runtime, and is_link_or_junction is added both to the platform_compat import and to _RUNTIME_COMPAT_IMPORTS, which is the module's existing late-resolution mechanism rather than a noqa.

No POSIX regression. is_link_or_junction tests os.path.islink first, which is what Path.is_symlink() already did; the junction arm is os.path.isjunction (3.12+) or _is_junction_fallback, and the fallback reads st_file_attributes / st_reparse_tag, both Windows-only os.stat_result fields, so it is False off Windows. POSIX behaviour is byte-for-byte the prior semantics.

Threat model. The guard sits before is_dir() precisely because is_dir() follows links, and a junction IS a directory, so the missed predicate did not fail closed - it routed the entry into the descend arm and enumerated the linked tree onto a page whose filenames are user-visible. The platform asymmetry is the real severity argument: a Windows symlink needs a privilege, a junction needs none, so the old test withheld the listing in the case a user mostly cannot create and allowed it in the case they can. TestHtmlScanDoesNotFollowSymlinks being entirely @requires_symlinks-gated is why this survived review, and the PR's own note that an all-skipped class is evidence of an UNVERIFIED platform rather than a covered one is the right lesson.

Tests. test_a_real_windows_junction_is_not_enumerated creates a genuine reparse point via _winapi.CreateJunction with no stub and no elevation, and it ran green on the Windows backend shards - that is what anchors the two stubbed tests. The helper-spy test correctly asserts the seam is consulted rather than only the outcome.

Scope. Minimal: 3 files, +76/-1, one commit, one predicate swap plus one name on an import list. Deferring the remaining is_symlink() sites to their own per-site threat analysis follows #8165's review ruling, so nothing rides along.

Gates. All checks green on 4dfa534; all four AI review lanes PASS with zero blocking findings; SAST 0 annotations; the single Focus Cue Gate annotation is a notice about 5 pre-existing elements the change does not touch. Not subject to the ux-review-required ruleset (no website/src/** or website/electron/** changes).

@bolichen97
bolichen97 merged commit e9be355 into kirodotdev:main Sep 6, 2026
75 checks passed
@github-actions github-actions Bot removed the readiness: passed Eligible automated validation passed for the current revision label Sep 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.

2 participants