Skip to content

refactor(security): compose the redaction pass pair through one helper - #17518

Closed
DeryFerd wants to merge 1 commit into
kirodotdev:mainfrom
DeryFerd:refactor/redaction-pair-helper-v2
Closed

DeryFerd wants to merge 1 commit into
kirodotdev:mainfrom
DeryFerd:refactor/redaction-pair-helper-v2

Conversation

@DeryFerd

@DeryFerd DeryFerd commented Oct 6, 2026

Copy link
Copy Markdown
Contributor

Problem / Motivation

Goal: Redacted dashboard output no longer depends on individual call sites running the credential and exfiltration-URL passes in the right order; one shared helper composes them, and a tree-wide test keeps it that way.

kiro_crew.security.redact and redact_with_findings already compose the two redaction passes in a fixed order, and the docstring records why the order matters: exfiltration URLs run first because that pass matches whole URLs, and a credential replaced ahead of one leaves a placeholder inside it, which the URL matcher then fails to recognize as the shape it exists to catch. Call sites that wire the two passes by hand inherit no such guarantee. The dashboard package sequenced the pair by hand in dozens of places, and a number of them had it backwards.

Why it matters

The credential goes either way; what the reversed order loses is suppression of the destination. redact_exfiltration_urls classifies a URL as suspicious partly by query length and replaces the entire URL when it fires, so once a credential inside that URL has been swapped for a placeholder, the exfil pass no longer recognizes the shape and the host survives the redaction untouched. The host is the half a reader acts on: it says which surface the content was about to leave for. The entropy and length heuristics also stop firing for that URL, so the loss is not limited to the credential shape that happened to match.

Every one of these sites is dashboard egress (audit rows, error text, file-search previews), so a reversed pair leaks exactly the detail an operator would use to judge the exposure while still reporting that a credential was redacted. The failure is quiet: the log looks redacted, and the destination is still in it.

A test that only checked the helper would not stop this class. The failure mode is a call site re-sequencing the pair, which any new handler can reintroduce, so the guard has to read the tree.

Not a goal

  • Migrating the hand-sequenced pairs outside the dashboard package. The scan finds 38 two-line pairs in 32 files plus one inline pair on the current tree; they are pinned in the baseline so the rule already holds, and a later sweep can migrate them a file at a time.
  • Changing what either pass matches. The credential patterns, the exfil heuristics, and streaming redaction behavior are untouched.
  • Adding a redaction entry point. This composes the two existing passes; no new capability ships.

What changed (motivation → approach → change)

The approach reuses the existing composer instead of inventing a new one: redact at sites that discard the per-pass warnings, redact_with_findings where the warning lists are consumed as a signal, which preserves both lists in the same fixed order.

Concretely:

  • Every hand-sequenced pair in the dashboard package now composes through the shared helper. That includes six credential-first pairs which had come back inside the split file_api/ and messaging_api/ submodules (two in file_api/grep.py's _grep_hit, four in messaging_api/proactive_send.py), plus the pairs in handlers/messaging.py, handlers/updates.py, dashboard/state.py, and chat_runner.py.
  • handlers/files.py and handlers/updates.py no longer import either raw pass; files.py composes through the context-aware redact shim it already had.
  • test/test_redaction_pair_order.py is new. It first asserts the behavior the order decides, on the helper itself: the canonical order suppresses the destination, the reversed order leaves a live URL standing, and the two orders agree when no URL carries a credential. It then pins a tree-wide baseline of hand-sequenced pairs, and the baseline is shrink-only: a pair that gets migrated must be pruned from the baseline in the same commit, and a new hand-sequenced pair anywhere under src/ fails the test. On the current tree the baseline holds 38 two-line pairs in 32 files plus one inline pair, all outside the dashboard package.
  • The scan is AST-based, so a comment or a string literal quoting the pattern cannot satisfy it, and it resolves every spelling the tree uses: bare names, qualified chains, and import aliases through modules that re-export the passes, while refusing a same-named method on an unrelated object. Targets and arguments are compared by source, so a subscripted target such as entry["path"] counts.
  • Two existing tests assert the seams this change moves, so both follow the migrated call: files.py composes through the shim, and state._log_task_exception calls redact, which is the symbol a failing-redactor test patches.
  • docs/system-specs/modules/security.md is updated in the same commit to record the composition rule and the pin test.

Backwards compatibility

Compatible: no exported symbol is added, renamed, or removed. redact_credentials and redact_exfiltration_urls keep their signatures and remain the public passes; callers outside the dashboard package are untouched.

Removes nothing: the two passes stay importable and in use across the tree. Only call composition inside the dashboard package, two now-unneeded import bindings, and one new test module change.

Tests

  • test/test_redaction_pair_order.py (new): the order-decides assertions on the helper, the shrink-only tree-wide baseline, and soundness probes for every spelling the scanner resolves (bare, qualified, aliased, and subscripted targets; pairs nested in branches and handlers; independent redactions that must not be flagged).
  • test/test_cse_2026_08_07_fixes.py and test/test_heartbeat_prompt_deliver.py follow the migrated seams.
  • Locally, the three files above pass (100 tests) and flake8, mypy src/kiro_crew, isort --check-only, and the black gate are clean on the branch. CI runs the full suite.

Manual verification

N/A — unit coverage sufficient. The change is call composition, and the new tests exercise the exact property at stake (the order decides the output) against the real passes; the tree-wide scan is itself executed by the suite rather than trusted.

Related Issues

Supersedes #11501, the earlier PR of this refactor, which I closed to rebase it. The dashboard has since been split into the file_api/ and messaging_api/ submodules, and that split carried six credential-first pairs back into the tree; this converts them and re-takes the pinned baseline counts on the current tree.

Checklist

  • At most two commits (one is the norm), with a Conventional Commits title (feat|fix|docs|style|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)
  • No secrets, credentials, or internal references in the diff

Contribution License Agreement

Contributions are accepted under the project's Apache-2.0 license. This change adds no new third-party dependency, so THIRD-PARTY-NOTICES needs no update.

@DeryFerd
DeryFerd requested a review from a team as a code owner October 6, 2026 20:20
@DeryFerd
DeryFerd requested a review from chenmingwei23 October 6, 2026 20:20
@github-actions github-actions Bot added fork Pull request from a fork (external contributor) readiness: checking Automated validation is still running labels Oct 6, 2026
@github-actions

github-actions Bot commented Oct 7, 2026 •

Copy link
Copy Markdown
Contributor

Design Review (Opus 5.5, fork) — ✅ PASS

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

Design-Verdict: PASS

Before merge, fix the counts in security.md and the test docstring ("37 reversed… 47 pairs in 36 files"): the actual baseline holds 38 pairs in 32 files.

Suggestions

  • Remove the pair counts from docs/system-specs/modules/security.md and point to _PINNED_TWO_LINE instead. The baseline can only shrink, so any count written in prose goes stale with each migration, and this one is already wrong.
  • Before calling ast.parse on a file, check that its text contains both pass names. Every spelling the scanner resolves includes those literal names, so the result is identical, and the test no longer parses all ~1600 files on every CI run (it currently takes about 2 minutes and needs a 600 s timeout).
  • The test module docstring says import aliases are "deliberately NOT resolved", but _alias_targets/_resolves_to_security do resolve them. Change the docstring to match the code, because it is the guide a future reader follows when the gate goes red.

[DESIGN-REVIEWED] 80fd8d9

Description read

[DESCRIPTION-READ] 1162f2464092cfd8a60ee11dc6e4933fd202a15bead6d0039bf76a59b9b61c64

That sha256 names everything this verdict read: the PR description, plus the 1 evidence file(s) the workflow collected from it and handed this review. It covers that evidence because the media strip replaces every attachment URL with the same placeholder, so an edit swapping one attachment for another would leave the description's captured text identical while what this review judged changed. Recompute it with .github/scripts/pr-description-capture.sh over the same inputs; if it differs, the description or that evidence changed after this verdict was formed and any finding drawn from either is unproven.

@github-actions

github-actions Bot commented Oct 7, 2026 •

Copy link
Copy Markdown
Contributor

First Principles Review (Opus 5.5, fork) — 🟡 CONCERNS

Premise-level review of 80fd8d978978cf12cce5a26a40dbe477bffeef09 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.

First-Principles-Verdict: CONCERNS

grep.py keeps its hand-written pass pair, although the description says it was migrated, and two prose copies of the site counts are already wrong.

Not justified as shipped

  • Item 2 — duplicate of redact (src/kiro_crew/dashboard/file_api/grep.py:50): the description says "two in file_api/grep.py's _grep_hit" now go through the shared helper. The diff only swaps the order (safe, _ = redact_exfiltration_urls(preview...) / redact_credentials(safe)), even though redact is already imported in that file.
    Subtraction: replace both reordered pairs in _grep_hit with redact(...).
    Clears when: _grep_hit holds no hand-written pass pair.
  • Item 6 — oversized: security.md and the new test's module docstring say "37 reversed sites … 47 pairs in 36 files". _PINNED_TWO_LINE holds 38 pairs in 32 files. The docstring also says an import alias "is deliberately NOT resolved", but _alias_targets does resolve aliases.
    Subtraction: delete the hard-coded counts and the alias sentence from both places; the baseline dict is the count.
    Clears when: the prose carries no count that can drift from the dict.
  • Item 3 — undeclared: websocket_hub keeps a hand-written pass pair, now in the correct order, because its passes come from injected providers. The description never mentions this file.

What this change ships

Inventory (8 items) — 5 justified

Intent: stop dashboard redaction leaving the destination URL visible when the two passes run in the wrong order. This is a FIX, although the title says refactor.

  1. Dashboard redaction sites (audit rows, error text, notices) now hide the destination URL — justified
  2. grep.py preview and label pairs are reordered but not migrated — duplicate of redact (grep.py:50)
  3. Browser-event redaction in websocket_hub is reordered inline — undeclared
  4. A new tree-wide test rejects any new reversed pair under src/ — justified
  5. 38 pairs outside the dashboard are pinned in a shrink-only baseline — justified
  6. Site counts are restated in the spec and the test docstring — oversized: stale, contradicts the baseline
  7. Two tests now patch or assert the migrated call — justified
  8. Imports of the raw passes that are no longer needed are dropped — justified

[FIRST-PRINCIPLES-REVIEWED] 80fd8d9

Description read

[DESCRIPTION-READ] a0bfe85bbbab2536e5484707ced393476d68fa8f99e4dbb8b640cfd67c492ec9

That sha256 names the PR description this verdict read. Recompute it with .github/scripts/pr-description-capture.sh; if it differs, the description changed after this verdict was formed and any finding drawn from the description is unproven.

@github-actions

github-actions Bot commented Oct 7, 2026 •

Copy link
Copy Markdown
Contributor

Opus 5.5 Review (fork) — ✅ no blocking findings

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

Review details

No blocking issues; one advisory finding on new in-function imports.

FINDING — src/kiro_crew/dashboard/messaging_api/proactive_send.py:512 — _redact_all, api_delete_message and api_update_message each gain a new in-function from kiro_crew.security import redact # noqa: F811 with no # circular import justification, which breaks the top-level-imports rule (non-blocking). This module reads its redactors from the facade's globals, so these local imports make the module resolve redact differently from how it resolves its other redactors → Fix: add redact to the module's TYPE_CHECKING facade import list and use the facade binding that messaging.py now exports, instead of the local imports.

[OPUS-REVIEWED] 80fd8d9

@github-actions

github-actions Bot commented Oct 7, 2026 •

Copy link
Copy Markdown
Contributor

GPT 6.1 Review (fork) — ✅ no blocking findings

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

Review details

FINDING -- src/kiro_crew/dashboard/messaging_api/proactive_send.py:62 -- Function-local from kiro_crew.security import redact hides runtime dependencies, violating top-level-imports -> Fix: remove the three newly added local imports and use the facade’s module-level redact binding.
[GPT-REVIEWED] 80fd8d9

@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 Oct 7, 2026
@DeryFerd
DeryFerd force-pushed the refactor/redaction-pair-helper-v2 branch 3 times, most recently from 56d765a to 49b0d1c Compare October 7, 2026 08:03
@github-actions github-actions Bot added readiness: checking Automated validation is still running readiness: action required A blocking check or review needs attention and removed readiness: action required A blocking check or review needs attention readiness: checking Automated validation is still running labels Oct 7, 2026
@DeryFerd
DeryFerd force-pushed the refactor/redaction-pair-helper-v2 branch from 49b0d1c to f6d4175 Compare October 7, 2026 09:19
@github-actions github-actions Bot added readiness: checking Automated validation is still running readiness: action required A blocking check or review needs attention and removed readiness: action required A blocking check or review needs attention readiness: checking Automated validation is still running labels Oct 7, 2026
The credential and exfiltration-URL passes must run in a fixed order, and
`kiro_crew.security.redact` already composes them that way. Its docstring
gives the reason: exfiltration URLs run FIRST because that pass matches
whole URLs, and a credential replaced ahead of it leaves a placeholder
inside one, which the URL matcher then fails to recognise as the shape it
is there to catch. The credential goes either way; what the reversed order
loses is suppression of the destination, which is the half a reader acts
on.

Call sites hand-sequenced the pair anyway. The dashboard package's pairs
now compose through `redact` (or `redact_with_findings` where the warning
lists are used as a signal, which preserves both lists in the same order),
with one deliberate exception: `file_api/grep.py`'s `_grep_hit` keeps the
two raw passes, reordered into the canonical sequence, because the facade
composition contract requires the grep row to read the facade-bound pass
bindings and take only its preview ceiling from the facade. The four
credential-first pairs the `messaging_api/` split had re-introduced are
converted, and `handlers/updates.py` no longer imports either raw pass;
`handlers/files.py` keeps its facade bindings while its own body composes
through `redact`.

`test/test_redaction_pair_order.py` is new. It asserts the behaviour the
order decides on the helper itself, then pins a tree-wide baseline of
hand-sequenced pairs (shrink-only: a paid-off entry that is not pruned
fails, and a new hand-sequenced pair anywhere under src/ fails). The scan
resolves every spelling the tree uses and reads the AST, so a comment or
string literal quoting the pattern cannot count. On today's tree the
baseline holds 38 two-line pairs in 32 files plus one inline pair, all
outside the dashboard package; they are pinned rather than migrated, so
the rule holds from today and the sweep reviews separately.

Two existing tests assert the seams this change moves, so both follow the
migrated call: `files.py` composes through the context-aware `redact`
shim, and `state._log_task_exception` calls `redact`, which is the symbol
a failing-redactor test patches.
@DeryFerd
DeryFerd force-pushed the refactor/redaction-pair-helper-v2 branch from f6d4175 to 80fd8d9 Compare October 7, 2026 10:06
@github-actions github-actions Bot added readiness: checking Automated validation is still running readiness: passed Eligible automated validation passed for the current revision and removed readiness: action required A blocking check or review needs attention readiness: checking Automated validation is still running labels Oct 7, 2026
@iamwhatever

Copy link
Copy Markdown
Contributor

Reviewed, not approving (crew-pr-reviewer). This refactors how the redaction passes are composed across several sinks. Redaction is security code, so it needs a security owner.

@github-actions github-actions Bot added the merge conflict Branch has merge conflicts with its base — author must resolve before merge label Oct 11, 2026
@DeryFerd DeryFerd closed this Oct 18, 2026
@github-actions github-actions Bot removed the readiness: passed Eligible automated validation passed for the current revision label Oct 18, 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) merge conflict Branch has merge conflicts with its base — author must resolve before merge

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants