Skip to content

fix(security): scan a double-quoted command substitution and skip heredoc bodies in the span walk - #22938

Closed
cruisercohen wants to merge 1 commit into
mainfrom
fix/publish-floor-dq-command-substitution
Closed

cruisercohen wants to merge 1 commit into
mainfrom
fix/publish-floor-dq-command-substitution

Conversation

@cruisercohen

@cruisercohen cruisercohen commented Oct 21, 2026 •

Copy link
Copy Markdown
Contributor

Problem / Motivation

Goal: Close a publicly-surfaced gap where a git push wrapped in a command substitution could reach the git-publish floor without being scanned.

The floor scans the body of every command substitution so a wrapped git push is still checked. Two quote-context shapes slipped that scan on released code:

  • a $(...) / backtick substitution opened inside double quotes — echo "$(bash -c 'git push')" — whose body was mis-sized, so the wrapped command was dropped from what the floor scanned;
  • a heredoc body inside a substitution, where a ) on a body line was mistaken for the span closer, ending the span early and dropping the command after it.

Why it matters

The git-publish floor is the sole enforcement for pushes. A push that reaches it unscanned is one the floor cannot decide on, so these shapes let a push through that bash actually runs. The gap is in released span-walk code, so it affects current users until fixed.

Not a goal

  • Does not change any deny rule, threshold, or pass — detection is only widened, never a decision.
  • Does not touch the self-protection or rm floors beyond their shared use of the span helper (whose contract is preserved and regression-tested).
  • Does not address << used as an arithmetic left shift: that direction makes a span run long (the fail-closed direction), not short, so it hides no command; it can be tightened separately if wanted.

What changed (motivation → approach → change)

Root cause: the span walk in shell_normalizer_walk.py computed a substitution's body span while mis-handling quote context, so a data ) (one inside double quotes, or inside a heredoc body) was read as the real closer and the launcher after it was dropped from the scanned body.

Approach: make the span computation quote-aware the way bash parses the text, mirroring the self-protection floor's own substitution walk, and add it as an additive pass so no existing reading is removed.

Change:

  • _double_quoted_substitution_bodies recomputes the body span of a $(...) / backtick substitution opened inside double quotes from a fresh, neutral quote context, so its clean body is scanned.
  • _matching_close_paren skips a heredoc body (cat <<E … E), so a ) inside it no longer closes the span early. A <<< here-string has no body and is left alone — including at the interior < of the <<< run, so the span is unchanged for here-strings.
  • The package line-budget pin is raised to the exact measured total.

Backwards compatibility

Compatible: no legitimate command stops working. A differential of the real classifier (scripts/deny_diff.py --base origin/main --head HEAD) over the golden corpus shows 0 regressions and 0 loosenings on posix and windows; the only behaviour change is the intended new refusals of the wrapped-push shapes above. The change adds scan targets and lengthens spans only (the fail-closed direction), and the shared span helper keeps its "a span runs long, never short" contract.

Removes nothing: no path, record, key, or public function is hidden, deleted, or renamed; the diff only widens detection.

Tests

  • test_push_branch_gate_parser.py::TestDoubleQuotedSubstitutionAndHeredocSpan (9): failing-first rows for the double-quoted $(...) form, the backtick form, and a heredoc-bodied subshell before the push — each proven red before the fix and green after — plus unit assertions on the recomputed span bounds, a regression row that a <<< here-string is not mistaken for a heredoc at its interior <, and benign / single-quoted (literal) rows that stay allowed.
  • A differential deny-diff over the golden and a focused probe corpus on posix and windows: 0 regressions, 0 loosenings, exactly the intended new refusals.
  • test_security_gate_liveness.py including the package line-budget gate passes on this head.

Manual verification

N/A — unit and differential coverage are sufficient; this is a parser-level change with no UI or external surface.

Related Issues

N/A — fixes a publicly-surfaced span-walk gap on released code; no separate tracking issue is linked.

Pattern harvest

Rule candidate: review-prompt. Pattern: a paren/span counter over shell text that is not quote-and-heredoc-aware reads a data ) (quoted, escaped, or inside a heredoc body) as a real closer and truncates the scanned span — the fail-short direction that can hide a later command. Any new walk over shell text should reuse the shared quote/heredoc-aware _matching_close_paren rather than counting ) itself.

Checklist

  • At most two commits (one is the norm), with a Conventional Commits title
  • Existing tests pass and new tests added for new functionality
  • Self-review completed; code follows project style guidelines
  • Documentation updated (if applicable) — N/A
  • No secrets, credentials, or internal references in the diff

@github-actions

github-actions Bot commented Oct 21, 2026 •

Copy link
Copy Markdown
Contributor

Sensitive Change Review

Sensitive files changed:

  • src/kiro_crew/security/shell_normalizer_walk.py

  • @cruisercohen posted a complete reasoning template for 7d9ee2c.

@github-actions

github-actions Bot commented Oct 21, 2026 •

Copy link
Copy Markdown
Contributor

UX Review (Opus 5.5) — ⏭️ skipped

Revision 7d9ee2c5c09102e85382c5844a50c3e074db2d53 touches no user-facing surface (no changes under website/ or committed screenshots), so the UX review was skipped. Does not block merge.

@github-actions github-actions Bot added the readiness: checking Automated validation is still running label Oct 21, 2026
@github-actions

github-actions Bot commented Oct 21, 2026 •

Copy link
Copy Markdown
Contributor

Design Review (Opus 5.5) — ✅ PASS

Design-level review of 7d9ee2c5c09102e85382c5844a50c3e074db2d53 — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS does not.

Design-Verdict: PASS

Nothing blocks: both changes only add text for the publish-floor scan to check, and a heredoc that is never closed makes the span run long, which scans more, never less.

Notes

  • The double-quote fix runs a second walk and adds its bodies to the first walk's output, instead of fixing how the first walk tracks quotes. So two walks now feed the same scanner. A later change to one walk can make them disagree without any warning.
  • _heredoc_operator also matches << inside arithmetic, as in $((x<<2)), and treats 2 as a delimiter. The span then runs on to the end. That is safe, but other callers of _matching_close_paren lose a proven span on those inputs.

[DESIGN-REVIEWED] 7d9ee2c

Description read

[DESCRIPTION-READ] d67760b5542d9363258c7408c728e77e39e139e1798087c4c3645ae044bc7c6a

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 21, 2026 •

Copy link
Copy Markdown
Contributor

First Principles Review (Opus 5.5) — ✅ PASS

Premise-level review of 7d9ee2c5c09102e85382c5844a50c3e074db2d53 — 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 does not.

First-Principles-Verdict: PASS

Both items fix a defect that tests added in this PR show failing on base. The double-quote item adds a second walk rather than correcting the one call that causes the bug.

Notes

  • Item 1 — symptom-level: the cause is the single call _matching_close_paren(text, i + 2) (shell_normalizer_walk.py:297), which carries the outer quote state into the span. It is the only call of that shape (grepped _matching_close_paren\([a-z_]+, [a-z_]+ \+ 2\): 1 hit). The fix instead adds a 56-line second walk over the whole text. Subtraction: delete _double_quoted_substitution_bodies and prove the $( span from the slice at neutral state on line 297 (_matching_close_paren(text[i + 2 :], 0)). This is the same idiom argv_floor_self.py:589 uses.
  • Item 2 — oversized: _heredoc_operator is a third reader of heredoc delimiters beside _heredoc_marker (shell_normalizer_redirects.py:520). Its docstring says it is "Shared … so the two cannot disagree about where a heredoc body starts and ends", and the new reader has its own <</<<</<<- rules. Subtraction: shrink the <</<<</<<- check to a call to _heredoc_marker, keeping only the dequoting of the delimiter.

What this change ships

Inventory (4 items) — 2 justified

Intent: a push wrapped in a double-quoted substitution, or placed after a heredoc body, is still checked by the publish floor. FIX.

  1. Substitutions opened inside double quotes (echo "$(bash -c 'git push')") now have their bodies scanned — symptom-level
  2. A ) inside a heredoc body no longer ends a substitution span early; this applies to every caller of the shared span helper (rm, self-protection and git floors) — oversized
  3. A <<< here-string is not mistaken for a heredoc anywhere in the run — justified
  4. The security package line budget rises from 32,097 to 32,272 — justified

[FIRST-PRINCIPLES-REVIEWED] 7d9ee2c

Description read

[DESCRIPTION-READ] 3a8c97496038ab9aa620126a6027b5ccd18eb3450eeecb309558b35905943ca1

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 21, 2026 •

Copy link
Copy Markdown
Contributor

Opus 5.5 Review — 🔴 changes requested (blocking)

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

A heredoc parser this PR adds reads an arithmetic << shift as a heredoc operator. That stops the PR's own double-quoted-substitution pass from closing its span, so a bare push it was written to catch is still allowed.

BLOCKING — src/kiro_crew/security/shell_normalizer_walk.py:1052
parsed = _heredoc_operator(text, off) / pending_heredocs.append((parsed[0], parsed[1]))
Trigger: is_denied("echo \"$(echo $((1<<2))\nbash -c 'git push')\"") goes through _substitution_bodies → _double_quoted_substitution_bodies → _matching_close_paren(text[off + 2 :], 0). There the << of $((1<<2)) reaches _heredoc_operator, which queues delimiter 2. At the newline, _skip_heredoc_bodies finds no line equal to 2 and runs to the end of the text. The slice returns (34, False) at HEAD; on base, with no heredoc logic, it returns (34, True).
Outcome: the span is unproven, so the pass appends the whole remainder with its trailing )". is_denied returns None (ALLOW) for a command bash really runs (bash -c $'echo "$(echo $((1<<2))\necho RAN)"' prints 4, then RAN). The publish floor therefore lets a push through that the new pass alone would have denied.
Anchor: residual/security
Fix: in _matching_close_paren, don't look for heredoc operators inside an arithmetic context. Track depth past each $(( / (( opener, and call _heredoc_operator only while that depth is zero.

[OPUS-REVIEWED] 7d9ee2c
[BLOCK-MERGE] 7d9ee2c

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

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

@github-actions

github-actions Bot commented Oct 21, 2026 •

Copy link
Copy Markdown
Contributor

GPT 6.1 Review — ✅ no blocking findings (all downgraded on adjudication)

GPT 6.1 flagged blocking issues on 7d9ee2c5c09102e85382c5844a50c3e074db2d53; Opus 5.5 adjudication downgraded every one of them. Downgraded: the remedy each one needs is disproportionate to the harm it prevents. Adjudication downgraded all 1 blocking finding(s): the remedy each one requires is disproportionate to the harm it prevents.

This comment is updated in place on each push.

Review details

BLOCKING -- src/kiro_crew/security/shell_normalizer_walk.py:343 -- Literal text is newly classified as an executable substitution

if not escaped and step.state == 2 and ch == "$" and text.startswith("$(", off):
Trigger: Shell-tool inputs cat <<'E'\n"$(bash -c 'git push')"\nE, echo hi # "$(bash -c 'git push')", and echo "$$(bash -c 'git push')" reach this condition through is_denied → _shell_payload_sources → _shell_payload_walk → _substitution_bodies.
Outcome: All three are allowed by the base but refused by HEAD as git-publish-push-bare, although Bash executes no push. Literal-output and documentation commands therefore stop working.
Anchor: defect
Fix: Exclude comments and quoted heredoc bodies from the added walk, and recognize paired $$ parameters rather than treating their second dollar as a substitution opener.

[BLOCK-MERGE-DOWNGRADED] 7d9ee2c
[GPT-REVIEWED] 7d9ee2c

Adjudication (Opus 5.5) — is blocking on each finding proportionate?

F1 — Harm is LOW. The failure needs three things, all confirmed:

  • A $( opener sitting in double-quote state (shell_normalizer_walk.py:343).
  • A body that matches a publish rule. Every such body reaches the deny scan through shell_normalizer.py:1469.
  • That text being literal (a quoted heredoc, a comment, or $$).

What happens is a visible refusal that fails closed; it is not silent and never loosens the floor. The agent can re-spell the literal text and retry. The pre-existing byte-literal scan at shell_normalizer_walk.py:293-305 has no comment or heredoc awareness either, so base already refuses the unquoted forms of the same literal heredoc and comment inputs. The new walk only adds the double-quoted variant of a false-denial class that base already accepts. The real fix would thread heredoc-pending state (_skip_heredoc_bodies, :941), comment detection and $$ pairing into a second security walk. That means new state and branches in a security-critical walk, and future readers would carry them permanently, all to close a sliver of a class the primary scan leaves open by design. That cost is larger than a rare, recoverable false denial.

[ADJUDICATION] 7d9ee2c5c09102e85382c5844a50c3e074db2d53 total=1 uphold=0 downgrade=1
DOWNGRADE F1 src/kiro_crew/security/shell_normalizer_walk.py:343 reason=disproportionate-remedy
[GPT-ADJUDICATED] 7d9ee2c5c09102e85382c5844a50c3e074db2d53

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

@github-actions github-actions Bot added the merge conflict Branch has merge conflicts with its base — author must resolve before merge label Oct 21, 2026
@github-actions

github-actions Bot commented Oct 21, 2026 •

Copy link
Copy Markdown
Contributor

Security Scope Review -- ✅ PASS

Which legitimate operations does 7d9ee2c5c09102e85382c5844a50c3e074db2d53 newly refuse? Updated in place on each push. A script-confirmed regression blocks; the model proposes candidates and never decides a refusal.

Verdict basis: adjudicated, zero confirmed regressions.

Security scope review -- adjudicated candidates

  • macos-latest (platform posix): 20 classified, 0 newly refused, 16 still allowed.
  • ubuntu-latest (platform posix): 20 classified, 0 newly refused, 16 still allowed.
  • windows-latest (platform windows): 20 classified, 0 newly refused, 16 still allowed.

No candidate flipped from allowed to refused.

Scope-Verdict: PASS

Reason: The change gives the existing scan more text to read in two ways. It adds a second pass that pulls out the body of every $(...) or backtick substitution opened inside double quotes. It also makes the span helper skip heredoc bodies, so the bodies it extracts now get the full argv/exfil/rule scan. I wrote 25 boundary candidates around both changes, and the harness gave me no confirmed newly-refused row. One path is not adjudicated: the rm floor calls the span helper directly, and only the full gate's verdict covers it (see UNADJUDICATED).

TIGHTENING: Substitution-body extraction in shell_normalizer_walk._substitution_bodies (added bodies.extend(_double_quoted_substitution_bodies(text)), gated on step.state == 2 and ch == "$" and text.startswith("$(", off) and the backtick twin), plus heredoc-body skipping in _matching_close_paren (if ch == "\n" and pending_heredocs: pos = _skip_heredoc_bodies(...)). -- The one threat it refuses is a bare publish that bash runs from a double-quoted substitution, or from just after a heredoc whose body holds a ): "a bare git push reached through echo "$(bash -c 'git push')" was never scanned and the publish floor allowed a push bash runs".

ADJUDICATED: 25 candidates, 0 confirmed newly-refused

PLATFORM COVERAGE: The diff assumes the bash tokenizer: double-quote state 2, $( and backtick as substitution openers, <</<<-/<<< heredoc syntax. It makes no assumption about paths, separators or executable names.

  • any (16 rows): neutral bash spellings. These include the scoped/dry-run/branch-computed pushes, the standard heredoc-in-"$(...)" flows for git commit -m and gh pr create/gh pr comment (with backticks, apostrophes and ) in the body), the <<< here-string next to a quoted substitution, an arithmetic << shift, and the backtick spelling.

  • posix (5 rows): rows that carry posix paths or bash/nproc/date +%s. This covers the rm floor's "$( branch and the bash -c wrapper with a read-only verb.

  • windows (4 rows): PowerShell spellings the bash-shaped walk now misreads:

    • "$(...)" subexpressions (Write-Host, Get-Content -Raw .\commit-message.txt, Get-Date under a C:\Users\... path).
    • The PowerShell backtick escape (`n in a commit message). The new backtick arm treats it as a substitution opener.

    This covers the one platform-specific assumption the change brings in: that ` and "$( inside double quotes mean what bash says they mean.

  • Not probed: I did not write a cmd.exe spelling. cmd has no $(/backtick substitution, so the new pass has nothing to match there.

UNADJUDICATED: rm_floor calls _shell._matching_close_paren(body, 0) directly on the "$( branch (src/kiro_crew/security/rm_floor.py:59-62). That means the heredoc-skip change also moves the rm floor's segment boundaries. Only the full composite verdict for rm -rf "$(git rev-parse --show-toplevel)/build" covers this path; no row isolates the floor itself. I would also have submitted a heredoc-fed rm operand (rm -f "$(cat <<'EOF' / /tmp/kc-probe.txt / EOF / )") and an rm on a path with an arithmetic << before a newline. I don't think either is a common enough real operation to spend a slot on. As a possible narrowing (argued, not confirmed): _heredoc_operator queues a delimiter for an arithmetic left shift ($((1<<4))). If a newline follows before the closer, _skip_heredoc_bodies consumes to the end of the text, and the span fails closed to the whole remainder. That only adds scanned text, so it could add a refusal on a multi-line script that uses << arithmetic, but nothing here demonstrates one.

[SCOPE-REVIEWED] 7d9ee2c

@cruisercohen
cruisercohen force-pushed the fix/publish-floor-dq-command-substitution branch from 2b73171 to 7d9ee2c Compare October 21, 2026 23:44
@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 merge conflict Branch has merge conflicts with its base — author must resolve before merge labels Oct 21, 2026
@cruisercohen

Copy link
Copy Markdown
Contributor Author

Sensitive change review

  • Head commit: 7d9ee2c
  • What rule changed: No deny rule, threshold, or pass changed. Two quote-context corrections to the git-publish floor's substitution span walk in shell_normalizer_walk.py: (1) a $(...) / backtick substitution opened inside double quotes now has its body span recomputed from a fresh, neutral quote context, the way bash parses it; (2) _matching_close_paren skips a heredoc body (cat <<E ... E) so a ) inside it is not mistaken for the span closer, while a <<< here-string is left alone.
  • Before -> after (what was allowed/blocked, now): Before, a git push wrapped in echo "$(bash -c 'git push')" (or the backtick form), or placed after a heredoc body inside a substitution, reached the publish floor with the wrapped command dropped from the scanned body, so it was allowed; after, those shapes are carried into the existing scan and refused. Benign and single-quoted (literal, non-executing) substitutions are unchanged-allowed.
  • Worst case if wrong (breaks commands / leaks secret / locks user out): The change only widens what the scan sees (detection-only), so the worst case is an over-refusal of a benign command that merely looks like one of these shapes. The differential below shows zero such over-refusals.
  • Evidence checked (which sandbox result proves it): scripts/deny_diff.py --base origin/main --head HEAD over the golden corpus and a focused probe corpus, on posix and windows: 0 regressions, 0 loosenings, and exactly the 4 intended new refusals. The failing-first rows are proven red on the pre-fix head and green here.
  • No regression:
    • Tools still work (which tools/commands were run, result): deny_diff golden corpus (the legitimate commands that must stay allowed) shows 0 regressions on posix and windows; benign double-quoted, single-quoted and here-string rows stay allowed in the test class.
    • Backward compatible (old config / old data / old callers still work, how checked): No config, data, or public API changed. The shared span helper _matching_close_paren keeps its "a span runs long, never short" contract — verified by a regression test on the <<< here-string run and by the deny_diff showing no loosening for the rm and self-protection callers.
    • Existing tests (which suites passed on this head): test_push_branch_gate_parser.py::TestDoubleQuotedSubstitutionAndHeredocSpan (9) and test_security_gate_liveness.py including the line-budget gate pass on this head; the broader backend security suites pass in CI.
  • How to undo: revert the single commit on this branch; the change is isolated to shell_normalizer_walk.py plus its two test files and the line-budget pin.

@cruisercohen

Copy link
Copy Markdown
Contributor Author

The blocking <<< here-string finding is fixed on 7d9ee2c5c09102e85382c5844a50c3e074db2d53.

  • _heredoc_operator now returns None for a < whose preceding character is also <, so the interior < of a <<< run is no longer read as a << heredoc operator. _matching_close_paren therefore runs the span through to its real closer for a here-string placed before the payload — the same span it produced before this change — so the wrapped command is scanned again. The shared helper keeps its "a span runs long, never short" contract for the rm and self-protection callers as well.
  • Added a regression test (test_a_herestring_is_not_mistaken_for_a_heredoc_mid_run): the here-string repro is refused, _heredoc_operator("<<<x", 1) is None at the interior positions, and _matching_close_paren on the <<< run asserts the full span.
  • The package line-budget pin is now exact with no slack — set to the measured package total.
  • On the note about << as an arithmetic left shift: that direction makes the span run long (the fail-closed direction), not short, so it does not hide a command. Happy to tighten it in a follow-up if you'd prefer.

@github-actions github-actions Bot added readiness: action required A blocking check or review needs attention merge conflict Branch has merge conflicts with its base — author must resolve before merge and removed readiness: checking Automated validation is still running labels Oct 21, 2026
@iamwhatever

Copy link
Copy Markdown
Contributor

Stale-PR cleanup check, 2026-11-17: this fix is still needed. I applied this PR's new tests in test/test_push_branch_gate_parser.py onto main at a72d85d without the source change. test_a_double_quoted_substitution_that_runs_is_scanned and test_a_heredoc_body_paren_cannot_close_the_span_early still fail there. Main has since rewritten the span walk (#36437, #36903, #32115), so this draft needs a rebase onto that code by @cruisercohen, then a fresh Sensitive Change sign-off and an answer to the open Opus finding. It is left as is until then.

@cruisercohen

Copy link
Copy Markdown
Contributor Author

Closing unmerged, following the maintainers' 2026-11-08 decision to stop patching shell spellings in the command-text checks (#21682 (comment)). The branch is kept if anyone wants it later.

@github-actions github-actions Bot removed the readiness: action required A blocking check or review needs attention label Nov 20, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

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