Repository navigation
fix(dashboard): audit steering's two silent descriptor-gate refusals - #11210
Conversation
Design Review (Fable 5) — ✅ PASSDesign-level review of Design-Verdict: PASS Verify SEL volume: each listing call re-audits every refused document, so a frequently refreshed dashboard tab writes one line per refusal per refresh. [DESIGN-REVIEWED] 3355f2d |
GPT 5.6 Review — ✅ no blocking findingsGPT 5.6 completed its review of This comment is updated in place on each push. Review detailsNo findings. False positive or not applicable? A repository writer can comment: |
First Principles Review (Fable 5) — 🟡 CONCERNSPremise-level review of First-Principles-Verdict: CONCERNS
Not justified as shipped
What this change shipsInventory (5 items) — 4 justifiedIntent: make the steering read-gate's two silent refusals visible in the operator's SEL log without changing either HTTP response — a FIX, with provenance (issue #8430, two added tests failing on base).
[FIRST-PRINCIPLES-REVIEWED] 3355f2d |
Opus 4.8 Review — ✅ no blocking findingsReviewed Verdict parsed from the review's SHA-scoped output markers for commit False positive or not applicable? A repository writer can comment: |
The steering handler reads every document through the descriptor gate, and the gate refuses correctly there -- but a refusal was swallowed into the same shape ordinary I/O trouble produces with no SEL line, so a refused steering read left no operator-visible trace: - listing head read (_head_meta): a bare None became _empty_meta() and nothing was recorded, so an entry listed with no description was byte-identical, in the response AND in the log, to one that has none; - scoped read (_resolve_and_read_blocking -> readfailed): the handler audited the refusal as not_found, the same line an unknown key writes. Both now write the coarse audit-on-refusal line the prompt/skill reads write (_audit_unread, mirrored module-local like _sel): tool_invocation, tool_kind=steering, outcome=error, with the path or key. The line records THAT bytes were withheld, never why -- the gate judges through one descriptor and answers a bare None, and re-stat-ing the path to recover a cause would be another by-name look at the input these reads exist to stop trusting. Best-effort: an audit write cannot fail the response. The HTTP answer is unchanged at both sites (empty description with the entry kept; the same 404 an unknown key answers), so neither endpoint becomes an oracle for which files the gate protects. Closes #8430
9dc483a to
3355f2d
Compare
iamwhatever
left a comment
There was a problem hiding this comment.
Tier 1 auto-approve: fix (3 files). Criteria: no conflict, no requested changes, security path denylist clean, design-doc gate clean, SAST annotations clean, security checklist all-NO, AI reviewers green. Category: two steering read-gate refusals were silent (an entry with an empty description, a bare 404), so a refused inode was indistinguishable from an absent one; adds a best-effort SEL tool_invocation line on each refusal path without changing the HTTP-visible shape, plus tests. Spec files changed as a ride-along (a minority of the diff on both file count and changed lines), not reviewed as a design decision: docs/system-specs/modules/steering-viewer.md.
…irodotdev#11210) The steering handler reads every document through the descriptor gate, and the gate refuses correctly there -- but a refusal was swallowed into the same shape ordinary I/O trouble produces with no SEL line, so a refused steering read left no operator-visible trace: - listing head read (_head_meta): a bare None became _empty_meta() and nothing was recorded, so an entry listed with no description was byte-identical, in the response AND in the log, to one that has none; - scoped read (_resolve_and_read_blocking -> readfailed): the handler audited the refusal as not_found, the same line an unknown key writes. Both now write the coarse audit-on-refusal line the prompt/skill reads write (_audit_unread, mirrored module-local like _sel): tool_invocation, tool_kind=steering, outcome=error, with the path or key. The line records THAT bytes were withheld, never why -- the gate judges through one descriptor and answers a bare None, and re-stat-ing the path to recover a cause would be another by-name look at the input these reads exist to stop trusting. Best-effort: an audit write cannot fail the response. The HTTP answer is unchanged at both sites (empty description with the entry kept; the same 404 an unknown key answers), so neither endpoint becomes an oracle for which files the gate protects. Closes kirodotdev#8430
What
Adds the coarse audit-on-refusal SEL line to the two steering descriptor-gate refusal paths in
src/kiro_crew/dashboard/handlers/steering.py, mirroring the rider #8249 added to the prompt/skill reads (prompts._audit_unread):_head_meta): a bareNonefromsafe_read_file_bytes_nolinknow writestool_invocation(tool_name="api_steering_list", tool_kind="steering", outcome="error", metadata={"path": ...})before returning_empty_meta()._resolve_and_read_blocking→readfailed):api_steering_detailnow audits that token asapi_steering_read/outcome="error"/{"key": ...}instead of folding it into thenot_foundline an unknown key writes.The HTTP answer is unchanged at both sites: the entry is kept with an empty description; the scoped read still answers the same
404 {"error": "not found"}an unknown key answers.Why
The gate already refuses correctly at both sites, so nothing leaks — but the refusal was swallowed into the shape ordinary I/O trouble produces with no distinct trace. An entry listed with no description was byte-identical, in the response AND in the SEL log, to a document that simply has none; a refused scoped read was logged as
not_found, i.e. a typo. #8249's own rationale is that the response shapes are deliberately indistinguishable so no endpoint becomes an oracle, which is exactly why the operator-side log has to carry the fact.Live count on
mainat6332e7eeabefore this change:grep log_tool_invocation steering.py→ 2 hits (:995,:1157), neither on a refusal path; thereadfailedpath reached the:1157closure only asnot_found.How
_audit_unread(tool_name, tool_kind, outcome, metadata)added module-local beside_sel(), same body and same best-efforttry/exceptasprompts._audit_unread— an audit write can never fail the response.None; re-stat-ing the path to recover a cause would be another by-name look at the input these reads exist to stop trusting. The line records THAT bytes were withheld, never why.prompts.pyandsteering.pyeach already carry their own late-binding_sel()seam for the same reason, and lifting the wrapper into_shared.pywould touch fix(security): read prompt paths through the descriptor gate #8249's module and the spec that namesprompts._audit_unreadfor a 12-line best-effort wrapper. Two identical copies are the cheaper thing to debug.docs/system-specs/modules/steering-viewer.md§Security Invariants updated to state both audit lines and the unchanged response shapes.Tests
test/test_steering_api.py, run by path with-n0: 134 passed (132 existing + 2 new). Both new tests fail on the unmodified base — repro admitted before the fix:TestListing::test_a_refused_head_read_leaves_an_audit_line— base:assert [] == ['error'](no line at all). Patches the module-scope gate to answerNonefor one document only; asserts the refused entry is kept withdescription == "", the neighbour still has its description, and exactly one non-okapi_steering_listline withoutcome == "error"/tool_kind == "steering"/ path endingdenied.md.TestReadEndpoint::test_a_refused_scoped_read_is_audited_as_withheld— base:assert ['not_found'] == ['error']. Patches the gate toNone; asserts404with body{"error": "not found"}(identical to an unknown key) and exactly oneapi_steering_readline withoutcome == "error"andmetadata == {"key": "user/a.md"}.Also run locally:
scripts/check_black_formatting.py(pass, diff-scoped),scripts/check_comment_history.py(pass),mypyonsteering.py(clean),isort --check-onlyandflake8on both changed files (clean).Other
Backend-only (handler + test + spec); no frontend change, so
no-screenshotsapplies. Refusal shapes in the HTTP response are unchanged by design; only the audit line is added.Pattern harvest
Rule candidate: prepare-pr
Pattern: when a fix adds an audit-on-refusal rider to one handler's gated reads, grep every other handler calling the same gate (
safe_read_file_bytes_nolink) for refusal branches (is None,readfailed,_empty_meta()) that still return a plain fallback with no SEL line, and either extend them in the same PR or file a deferred-finding per module.Closes #8430