Skip to content

fix(dashboard): audit steering's two silent descriptor-gate refusals - #11210

Merged
iamwhatever merged 1 commit into
mainfrom
fix/steering-audit-unread-8430
Sep 16, 2026
Merged

iamwhatever merged 1 commit into
mainfrom
fix/steering-audit-unread-8430

Conversation

@CrysisDeu

Copy link
Copy Markdown
Contributor

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):

  1. Listing head read (_head_meta): a bare None from safe_read_file_bytes_nolink now writes tool_invocation(tool_name="api_steering_list", tool_kind="steering", outcome="error", metadata={"path": ...}) before returning _empty_meta().
  2. Scoped read (_resolve_and_read_blocking → readfailed): api_steering_detail now audits that token as api_steering_read / outcome="error" / {"key": ...} instead of folding it into the not_found line 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 main at 6332e7eea before this change: grep log_tool_invocation steering.py → 2 hits (:995, :1157), neither on a refusal path; the readfailed path reached the :1157 closure only as not_found.

How

  • _audit_unread(tool_name, tool_kind, outcome, metadata) added module-local beside _sel(), same body and same best-effort try/except as prompts._audit_unread — an audit write can never fail the response.
  • Outcome is coarse on purpose: the gate judges and reads through ONE descriptor and answers a bare 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.
  • Module-local copy rather than a shared helper (the issue left this open): prompts.py and steering.py each already carry their own late-binding _sel() seam for the same reason, and lifting the wrapper into _shared.py would touch fix(security): read prompt paths through the descriptor gate #8249's module and the spec that names prompts._audit_unread for 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 answer None for one document only; asserts the refused entry is kept with description == "", the neighbour still has its description, and exactly one non-ok api_steering_list line with outcome == "error" / tool_kind == "steering" / path ending denied.md.
  • TestReadEndpoint::test_a_refused_scoped_read_is_audited_as_withheld — base: assert ['not_found'] == ['error']. Patches the gate to None; asserts 404 with body {"error": "not found"} (identical to an unknown key) and exactly one api_steering_read line with outcome == "error" and metadata == {"key": "user/a.md"}.

Also run locally: scripts/check_black_formatting.py (pass, diff-scoped), scripts/check_comment_history.py (pass), mypy on steering.py (clean), isort --check-only and flake8 on both changed files (clean).

Other

Backend-only (handler + test + spec); no frontend change, so no-screenshots applies. 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

@CrysisDeu
CrysisDeu requested review from a team and krishdhasmana September 16, 2026 05:44
@CrysisDeu CrysisDeu added the no-screenshots PR has no visual delta; screenshot gate exempt label Sep 16, 2026
@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 3355f2db7a842fdcc6a72d49a37cce1ba71f6db5 — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS/CONCERNS are advisory.

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

@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 3355f2db7a842fdcc6a72d49a37cce1ba71f6db5 and found no blocking issues.

This comment is updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] 3355f2d

False positive or not applicable? A repository writer can comment:
/ai-review override gpt 3355f2db7a842fdcc6a72d49a37cce1ba71f6db5: <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 3355f2db7a842fdcc6a72d49a37cce1ba71f6db5 — 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

_audit_unread ships as a verbatim second copy of an existing helper; the only alternative the description weighs is a shared module, not reuse.

Not justified as shipped

  • Item 3 — duplicate of src/kiro_crew/dashboard/handlers/prompts.py:318: grep _audit_unread under src/ finds 2 definitions (prompts.py:318, steering.py:147) with identical executable bodies; the description rejects only "lifting the wrapper into _shared.py", never reusing the existing symbol, and the two docstrings have already diverged.
    Subtraction: delete steering._audit_unread and import prompts._audit_unread — neither handler module imports the other today, and both _sel() seams resolve the same kiro_crew.dashboard.handlers.sel, so behaviour is identical.
    Clears when: the copy is deleted in favour of the existing symbol, or a concrete reason the direct import fails (an import cycle, a needed behaviour difference) is shown.

What this change ships

Inventory (5 items) — 4 justified

Intent: 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).

  1. A refused listing head read now leaves a SEL error line; the entry still lists with an empty description — justified
  2. A refused scoped read is now logged error instead of not_found; the 404 body is unchanged — justified
  3. steering.py gains its own _audit_unread wrapper — duplicate of src/kiro_crew/dashboard/handlers/prompts.py:318
  4. The steering-viewer spec states both audit lines in the same commit — justified
  5. Two new tests pin the audit lines and the unchanged response shapes — justified

[FIRST-PRINCIPLES-REVIEWED] 3355f2d

@github-actions

github-actions Bot commented Sep 16, 2026 •

Copy link
Copy Markdown
Contributor

Opus 4.8 Review — ✅ no blocking findings

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

Review details

No findings.

[OPUS-REVIEWED] 3355f2d

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

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

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
@CrysisDeu
CrysisDeu force-pushed the fix/steering-audit-unread-8430 branch from 9dc483a to 3355f2d Compare September 16, 2026 06:16
@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 enabled auto-merge (squash) September 16, 2026 08:06

@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.

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.

@iamwhatever
iamwhatever merged commit a9c1cb2 into main Sep 16, 2026
114 of 117 checks passed
@iamwhatever
iamwhatever deleted the fix/steering-audit-unread-8430 branch September 16, 2026 08:06
@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
…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
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(dashboard): audit steering's two silent descriptor-gate refusals

2 participants