Repository navigation
fix(design-tweak): stop the preview HTML scan enumerating a junctioned tree - #8767
Conversation
…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>
GPT 5.6 Review (fork) — ✅ no blocking findingsReviewed Review detailsNo findings. |
Design Review (Fable 5, fork) — ✅ PASSDesign-level review of The change is a two-line predicate swap routed through the module's documented 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 |
Opus 4.8 Review (fork) — ✅ no blocking findingsReviewed |
First Principles Review (Fable 5, fork) — ✅ PASSPremise-level review of The base tree confirms everything material: the vulnerable 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 shipsIntent: stop the Design Tweak preview's 404 page listing filenames from a junction-linked directory on Windows. This is a FIX.
Watch
[FIRST-PRINCIPLES-REVIEWED] 4dfa534 |
bolichen97
left a comment
There was a problem hiding this comment.
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).
Problem / Motivation
scan_htmlbuilds the list of previewable pages that Design Tweak's diagnostic404 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: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 ofthe same loop. A
docsjunction pointing at a protected directory had the walkenumerate 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
TestHtmlScanDoesNotFollowSymlinksis marked@requires_symlinks, so the entireclass 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_htmland 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()becomesruntime.is_link_or_junction(entry).Reached through
runtimerather than by importingplatform_compatintopreview_files, because that module's docstring makesserverthe boundary:preview_filesalready reachesis_sensitive_path,_containedand_is_project_secretthat way, so this keeps one convention rather than adding asecond.
servertherefore gainsis_link_or_junctionin itsplatform_compatimport and in the existing
_RUNTIME_COMPAT_IMPORTStuple — the module's owndeclared 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.mdcarries 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
TestHtmlScanDoesNotFollowSymlinksclass, so the junctioncase sits beside the symlink cases it completes:
test_a_junctioned_directory_is_not_enumerated— the linked tree's HTML namesmust 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.CreateJunctionand asserts theprotected directory's filename never reaches the listing.
The stubbed tests are needed because
os.path.isjunctionis 3.12+ and alwaysFalse 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
mainproduction files (Windows host,-p no:randomly): 2 failed, and the real-junction one fails with— the disclosure itself, reproduced on a real junction with nothing mocked. (The
helper-spy test also fails there, with
AttributeError, sincemain'sserverhas 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
TestStaticPreviewServertimeouts that a pristine-mainrun 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 scancompeting 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 againstplatform_compat.is_link_or_junctionafter #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 threatanalysis before they are worth changing — #8165's review made exactly that point
— so they are not bundled here.
Pattern harvest
Rule candidate:
semgrepPattern:
is_symlink()/os.path.islink()used as a refusal immediately beforean
is_dir()branch. On Windows the predicate misses a directory junction, andbecause 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-isdirshape 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
feat|fix|docs|refactor|perf|test|chore|ci|build|revert: ...)Contribution License Agreement
🤖 Generated with Claude Code