Skip to content

fix(security): read snapshots and spec prefixes through the descriptor gate - #11227

Merged
iamwhatever merged 2 commits into
mainfrom
fix/descriptor-gate-reads-8429
Sep 17, 2026
Merged

iamwhatever merged 2 commits into
mainfrom
fix/descriptor-gate-reads-8429

Conversation

@CrysisDeu

@CrysisDeu CrysisDeu commented Sep 16, 2026 •

Copy link
Copy Markdown
Contributor

What

Two reads validated a file path and then re-opened it by name. Both now read through hooks.safe_read_file_bytes_nolink, the descriptor gate the prompt and skill readers already use, with each canonical path's own parent as within_root.

Site Before After
src/kiro_crew/dashboard/chat_runner.py::_safe_read_snapshot validate_file_path then Path.read_text gate read, max_bytes=4 * _MAX_SNAPSHOT + 4, allow_truncate=True, utf-8 decode with errors="replace", universal newlines
src/kiro_crew/taskrunner.py::_read_spec_prefix bare open() on the validated name gate read, max_bytes=4 * max_chars, allow_truncate=True, strict decode (tail held back only on a byte-cap cut), universal newlines, [:max_chars].strip()

Closes #8429

Why

validate_file_path judges the name. A hardlink alias shares its target's inode but carries its own innocent name: realpath yields the alias, is_symlink() is False, is_sensitive_path sees an ordinary file, and the bytes belong to whatever it aliases. st_nlink is the only signal and it is readable only on an open descriptor. The snapshot bytes are published into the dashboard diff chips; the spec prefix lands in the placeholder run's spec_content. This is the same class #8249 closed for the prompt/skill reads; these two sites were deliberately deferred out of that PR's scope.

How

  • The gate opens FIRST (platform_compat.open_file_no_reparse, refusing a link at the final component on every platform), fstats that one descriptor, refuses st_nlink > 1, a non-regular inode, and a sensitive or out-of-within_root real path, then reads the same descriptor. within_root = os.path.dirname(validated) is what carries the guarantee onto Windows, where O_NOFOLLOW does not exist.
  • Failure shapes are unchanged so neither endpoint becomes an oracle: _safe_read_snapshot returns None for every refusal exactly as it did for an unreadable file; _read_spec_prefix returns "" for a refusal, which is what its caller already substitutes for any read error (except Exception: early_content = ""). Invalid UTF-8 in a spec still raises (strict decode, as the text-mode read did) and the caller still maps it to "".
  • Byte caps replace unbounded reads. A UTF-8 code point is at most 4 bytes, so 4 * max_chars always yields at least max_chars characters, and 4 * _MAX_SNAPSHOT + 4 guarantees a file longer than the character cap decodes to MORE than _MAX_SNAPSHOT characters whether it was cut at the byte cap or read whole, so _truncate_snapshot's marker is appended exactly when the file exceeds the cap (pinned by test_truncates_a_large_multibyte_file_with_the_marker). The taskrunner decode is strict to EOF (an incomplete sequence at the end of a short file raises, as any malformed UTF-8 did in the text-mode read, and the caller maps it to ""); only a full-length result — the one case the byte cap itself may have cut mid code point — holds the dangling tail back with final=False, which loses nothing because every complete character before a cut at 4 * max_chars bytes already lies at or past index max_chars; newlines are normalized (\r\n, \r -> \n) as the replaced text-mode read did.
  • Both reads normalize \r\n / \r to \n, as the text-mode reads they replace did. For the snapshot this is load-bearing: the strReplace "before" comes from hooks.safe_read_file (text mode), so a CRLF "after" that kept its \r would render every unchanged line as modified in the diff chip (pinned by test_normalizes_newlines_like_the_text_mode_read_it_replaces in both test files).
  • chat_runner.py drops the by-name Path.is_file() pre-check; the gate's S_ISREG on the descriptor is the authoritative check.
  • Specs: docs/system-specs/modules/learn-cron-dashboard.md (file-change snapshot paragraph) and docs/system-specs/modules/taskrunner.md (background admission) describe the gated reads.

Tests

Repro admitted on the unmodified base (both hardlink-alias tests served the secret bytes; 7 failures total on base, all green after):

  • test/test_file_change_snapshots.py::TestSafeReadSnapshot — new: test_withholds_a_hardlink_alias_of_a_protected_file (HOME pinned to tmp_path, ~/.aws/credentials planted, is_sensitive_path asserted as precondition, alias under an innocent name -> None), test_withholds_a_symlink_to_a_protected_file, test_reads_through_the_descriptor_gate_not_by_name (Path.read_text raises if called), test_normalizes_newlines_like_the_text_mode_read_it_replaces, test_truncates_a_large_multibyte_file_with_the_marker; test_reads_with_explicit_utf8_encoding (which pinned the by-name Path.read_text call) replaced by test_reads_utf8_regardless_of_locale.
  • test/test_taskrunner_spec_prefix.py — new file: plain prefix, character (not byte) bound on multi-byte text, CRLF normalization, invalid UTF-8 still raises, an incomplete sequence at EOF still raises, a byte-cap cut mid code point is not an error, missing/directory/protected-name -> "", hardlink alias of a protected file -> "", symlink to a protected file -> "".
  • Ran by path with -n0: test/test_taskrunner.py test/test_taskrunner_coverage.py test/test_handlers_taskrunner_coverage.py test/test_file_change_snapshots.py test/test_taskrunner_spec_prefix.py test/test_chat_runner_coverage.py -> 891 passed.
  • Local gates: isort, flake8, black (diff-scoped script), mypy on both source files, check_subprocess_encoding.py, check_comment_history.py, docs_lint.py, check_lockdown_before_publish.py all pass.

Other

Backend-only (no-screenshots): no UI change; the diff chips render the same content for every non-aliased file and None (no chip content) for a refused one, as before.

Not touched: the steering descriptor-gate refusal sites (sibling PR #11210 / #8430). #8249's prompt/skill sites are unchanged.

Minor behaviour differences, both deliberate: the snapshot read no longer pulls an arbitrarily large file into memory before truncating (bounded at 4 * _MAX_SNAPSHOT + 4 bytes); the spec prefix read is bounded at 4 * max_chars bytes instead of a text-mode read(max_chars).

Pattern harvest

Rule candidate: grep
Pattern: validate_file_path( followed within a few lines by open(, .read_text(, .read_bytes( or Path(...) on the validated value is a validate-then-reopen-by-name read; route it through safe_read_file_bytes_nolink with within_root = the canonical path's parent.

@CrysisDeu
CrysisDeu requested review from a team and buluoray September 16, 2026 06:51
@github-actions github-actions Bot added the readiness: checking Automated validation is still running label Sep 16, 2026
@github-actions

github-actions Bot commented Sep 16, 2026 •

Copy link
Copy Markdown
Contributor

Design Review (Fable 5) — ✅ PASS

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

Design-Verdict: PASS

Verify no supported workflow feeds legitimately hardlinked specs to start_background — the gate now silently degrades those to an empty spec_content, indistinguishable from an unreadable file.

[DESIGN-REVIEWED] c1e0dc4

@github-actions

github-actions Bot commented Sep 16, 2026 •

Copy link
Copy Markdown
Contributor

GPT 5.6 Review — ✅ no blocking findings

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

This comment is updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] c1e0dc4

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

@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 16, 2026
@github-actions

github-actions Bot commented Sep 16, 2026 •

Copy link
Copy Markdown
Contributor

Opus 4.8 Review — ✅ no blocking findings

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

Review details

I've independently verified the two implementation changes against the descriptor gate they call and the byte-cap/decode logic.

  • safe_read_file_bytes_nolink (hooks.py:2966) opens first, fstats the descriptor, rejects st_nlink > 1 / non-regular / out-of-root / sensitive, and with allow_truncate returns exactly read_limit bytes when the file exceeds it (data[:read_limit]) — so _read_spec_prefix's final=len(raw) < read_limit correctly finalizes only a whole-file read and holds back a byte-cap-cut tail.
  • The "held-back tail loses nothing" claim is sound: with read_limit = 4*max_chars and UTF-8 ≤ 4 bytes/char, any partial code point at read_limit bytes is preceded by ≥ max_chars complete chars, so text[:max_chars] never drops a real character.
  • Marker honesty in _safe_read_snapshot holds: 4*_MAX_SNAPSHOT+4 bytes decode to ≥ _MAX_SNAPSHOT+1 chars for any oversize file (worst case all-4-byte or CRLF), and exactly _MAX_SNAPSHOT for a file at the cap, so the marker appears iff the file exceeds the cap.
  • Both refusal shapes collapse to None/"" — no protected-path oracle — and both remain on worker threads. Newline normalization aligns the after-read with the text-mode before. No regression for legitimate single-link regular files.

Nothing survives to a grounded (a)/(b)/(c) defect.

No findings.

[OPUS-REVIEWED] c1e0dc4

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

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

@github-actions

github-actions Bot commented Sep 16, 2026 •

Copy link
Copy Markdown
Contributor

First Principles Review (Fable 5) — 🟡 CONCERNS

Premise-level review of c1e0dc464bcd3f772ba41e24d20fd9d6f1713c66 — 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 PR's own harvest rule still matches four ungated validate-then-reopen reads it never names — one, skills.py lazy load, publishes bytes into the turn.

Not justified as shipped

  • Item 1 — point patch (accepted-and-deferred): the description's remaining-work list is only "the steering descriptor-gate refusal sites (sibling PR fix(dashboard): audit steering's two silent descriptor-gate refusals #11210 / fix(dashboard): audit steering's two silent descriptor-gate refusals #8430)", but its own harvest pattern (validate_file_path( then a by-name read within a few lines — I grepped all 33 call sites) still matches 4 unnamed siblings: src/kiro_crew/skills.py:2874 (Path(resolved).read_text, skill body injected into the turn — the same harm class, despite "fix(security): read prompt paths through the descriptor gate #8249's prompt/skill sites are unchanged"), src/kiro_crew/slack/handler.py:1058, src/kiro_crew/dashboard/handlers/usage.py:1862, src/kiro_crew/dashboard/handlers/core.py:411 (FileResponse by name).
    Clears when: those four sites are gated or each is named as out of the class / tracked like the steering sites.
  • Item 3 — rides along: declared ("no longer pulls an arbitrarily large file into memory"); removes an unbounded read, no premise risk.

What this change ships

Inventory (7 items) — 5 justified

Intent: stop a hardlink alias of a protected file, planted under an innocent name, from leaking bytes into dashboard diff chips or a task's spec_content — a FIX.

  1. Diff chips withhold hardlink/symlink aliases of protected files — point patch: 4 counted siblings above
  2. Task placeholder spec prefix withholds aliases; refusal is the same empty prefix as any read error — justified
  3. Snapshot read bounded at 4 * _MAX_SNAPSHOT + 4 bytes instead of whole-file-then-truncate — rides along, declared
  4. Spec-prefix read bounded in bytes, same character bound as the text-mode read — justified
  5. By-name is_file() pre-check dropped; the descriptor's S_ISREG decides — justified
  6. Both module specs describe the gated reads in the same commit — justified
  7. Pin on the by-name read_text call replaced by a locale-independence pin, declared, guarantee preserved — justified

[FIRST-PRINCIPLES-REVIEWED] c1e0dc4

@CrysisDeu CrysisDeu added the no-screenshots PR has no visual delta; screenshot gate exempt label Sep 16, 2026
@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 Sep 16, 2026
@CrysisDeu
CrysisDeu force-pushed the fix/descriptor-gate-reads-8429 branch from 60b4999 to 959ed72 Compare September 16, 2026 07:06
@github-actions github-actions Bot added readiness: action required A blocking check or review needs attention readiness: checking Automated validation is still running and removed readiness: checking Automated validation is still running readiness: action required A blocking check or review needs attention labels Sep 16, 2026
@CrysisDeu
CrysisDeu force-pushed the fix/descriptor-gate-reads-8429 branch from 959ed72 to 55a5cfa Compare September 16, 2026 07:18
…r gate

Two reads validated a path with hooks.validate_file_path and then re-opened
it by NAME: chat_runner._safe_read_snapshot (Path.read_text feeding the
dashboard diff chips) and taskrunner._read_spec_prefix (a bare open() for
the placeholder's spec prefix). A hardlink alias shares its target's inode
under an innocent name, so every name-based check passes while the bytes
belong to whatever it aliases; only the opened descriptor's st_nlink reveals
it. Both now read through hooks.safe_read_file_bytes_nolink with each
canonical path's own parent as within_root, the same gate the prompt and
skill readers use. Failure shapes are unchanged: None for the snapshot,
an empty prefix for the spec.

Closes #8429
…cut it

A spec that ENDS mid code point is malformed; holding its tail back turned
the read error the caller maps to "" into a silently shorter prefix. The
decode is now finalized for any result shorter than the byte cap, and
the tail is held back only for a full-length result, the one case the cap
itself may have cut, where every complete character before the cut already
lies past max_chars. The gate import moves to the module import section.
@CrysisDeu
CrysisDeu force-pushed the fix/descriptor-gate-reads-8429 branch from 55a5cfa to c1e0dc4 Compare September 16, 2026 07:49
@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 16, 2026
@iamwhatever
iamwhatever merged commit 2f02c81 into main Sep 17, 2026
116 of 117 checks passed
@iamwhatever
iamwhatever deleted the fix/descriptor-gate-reads-8429 branch September 17, 2026 01:24
@github-actions github-actions Bot removed the readiness: passed Eligible automated validation passed for the current revision label Sep 17, 2026
amadsalmon pushed a commit to amadsalmon/KiroCrew that referenced this pull request Sep 22, 2026
…r gate (kirodotdev#11227)

* fix(security): read snapshots and spec prefixes through the descriptor gate

Two reads validated a path with hooks.validate_file_path and then re-opened
it by NAME: chat_runner._safe_read_snapshot (Path.read_text feeding the
dashboard diff chips) and taskrunner._read_spec_prefix (a bare open() for
the placeholder's spec prefix). A hardlink alias shares its target's inode
under an innocent name, so every name-based check passes while the bytes
belong to whatever it aliases; only the opened descriptor's st_nlink reveals
it. Both now read through hooks.safe_read_file_bytes_nolink with each
canonical path's own parent as within_root, the same gate the prompt and
skill readers use. Failure shapes are unchanged: None for the snapshot,
an empty prefix for the spec.

Closes kirodotdev#8429

* fix(taskrunner): finalize the spec-prefix decode unless the byte cap cut it

A spec that ENDS mid code point is malformed; holding its tail back turned
the read error the caller maps to "" into a silently shorter prefix. The
decode is now finalized for any result shorter than the byte cap, and
the tail is held back only for a full-length result, the one case the cap
itself may have cut, where every complete character before the cut already
lies past max_chars. The gate import moves to the module import section.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

no-screenshots PR has no visual delta; screenshot gate exempt

Projects

None yet

Development

Successfully merging this pull request may close these issues.

fix(security): route the last two validate-then-reopen-by-name reads through the descriptor gate

2 participants