Skip to content

fix(security): read literal echo/printf substitutions as argv in the ssh floor - #23303

Closed
JLargent42 wants to merge 1 commit into
mainfrom
fix/shell-normalizer-gaps
Closed

JLargent42 wants to merge 1 commit into
mainfrom
fix/shell-normalizer-gaps

Conversation

@JLargent42

@JLargent42 JLargent42 commented Oct 23, 2026 •

Copy link
Copy Markdown
Contributor

Problem / Motivation

Goal: The ssh self-target floor reads the literal output of an echo/printf substitution as the argv it becomes.

#21345 records four gaps in the reader in src/kiro_crew/security/ that the self-protection, git-publish, sandbox-escape-ssh-self and network-exposure floors share:

  1. A redirection glued to the verb (kirocrew restart>/tmp/log) was read so that the verb was dropped.
  2. The output of a literal $(echo …) in program position was not read as the argv it becomes, for the ssh-self floor.
  3. Arguments of a launcher in front of a data consumer (time grep …, sudo grep …) and of git grep were read as invocations, so ordinary searches were refused.
  4. Quoted heredoc bodies were read as commands, so a commit message written as git commit -m "$(cat <<'EOF' … EOF)" was refused.

This PR ships gap 2 only. Gaps 1, 3 and 4 are deferred to #23351 (see Not a goal).

Why it matters

Gap 2 lets a command shape through that the ssh-self floor exists to refuse.

Not a goal

What changed (motivation → approach → change)

The ssh-self floor spliced a literal substitution back as its first printed word only, so $(echo ssh localhost id) did not read as the command it runs.

  • _static_substitution_words (in argv_floor_self.py) rebuilds the whole output of a literal substitution: echo with its -n/-e/-E options consumed, or printf with one format operand and no % conversion. Like the shell, it strips only trailing newlines. Anything else returns None, and the existing one-word reader _static_substitution_output applies as before.
  • Output carrying quoting, operator, expansion or comment characters is never re-spliced.
  • The ssh-self floor (argv_floor_ssh.py) splices that output in, so a substitution in program position reads as the argv it expands to. A line where any such output holds a word starting with - is not spliced: the whole command keeps main's reading, so no option word reaches the floor's argv walk from a substitution.

argv_floor.py, __init__.py and _exports.py re-export the new helper on the package facade. The security spec (docs/system-specs/modules/security.md) records that glued redirections, launcher searches and quoted heredoc bodies keep main's reading until #23351.

Backwards compatibility

Compatible: gap 2 adds refusals for shapes the ssh-self floor already intends to refuse.

Removes nothing: no rule, row, config key or public function is removed.

Tests

  • test/test_denied_commands_security_ssh_self.py::TestSandboxEscapeSshSelf: literal substitution output naming this host is refused, and the same output naming another host stays allowed. Output that holds an option word is not spliced, and the shapes main refuses stay refused. A trailing space in the output still separates words. There is also a unit test of _static_substitution_words.
  • test/test_security_gate_liveness.py: the package line budget is raised with its reason recorded beside it.

Manual verification

N/A — unit coverage sufficient: every changed read is reached through is_denied, the entry point the tool-call gate uses.

Related Issues

Part of #21345

Sibling sweep

Swept: git grep -nE "_static_substitution_output|_splice_static_substitution" -- src/
Sibling: src/kiro_crew/security/argv_floor_self.py -- changed here
Sibling: src/kiro_crew/security/argv_floor_ssh.py -- changed here
Sibling: src/kiro_crew/security/rm_floor.py -- not affected -- reads its own segments; its gaps are in #21365

Pattern harvest

Rule candidate: review-prompt
Pattern: a security reader that narrows a refusal must fall back to the prior reading for every shape it does not fully model, with a guard test pairing each narrowed allow with the nearest shape that must stay refused

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

@JLargent42
JLargent42 requested review from a team and KiroCrewCaptain as code owners October 23, 2026 03:21
@JLargent42
JLargent42 requested a review from CrysisDeu October 23, 2026 03:21
@github-actions

github-actions Bot commented Oct 23, 2026 •

Copy link
Copy Markdown
Contributor

Sensitive Change Review

Sensitive files changed:

  • src/kiro_crew/security/__init__.py

  • src/kiro_crew/security/_exports.py

  • src/kiro_crew/security/argv_floor.py

  • src/kiro_crew/security/argv_floor_self.py

  • src/kiro_crew/security/argv_floor_ssh.py

  • @JLargent42 posted a complete reasoning template for 137b45e.

@JLargent42

Copy link
Copy Markdown
Contributor Author

Sensitive change review

  • Head commit: 0a500a8
  • What rule changed: the shared shell reader in security/shell_normalizer*.py and security/argv_floor_self.py / argv_floor_ssh.py, which the self-protection, git-publish, sandbox-escape-ssh-self and network-exposure argv floors read.
  • Before -> after (what was allowed/blocked, now): a self-protection verb with a redirection glued to it, and a literal echo/printf substitution naming this host in program position, were allowed and are now refused. A search tool behind a modelled launcher (time/sudo/nice/timeout/env/command/exec/nohup) or git grep without a pager option, and a quoted heredoc body fed only to data consumers, were refused and are now allowed. Everything the reader does not fully model keeps the prior reading.
  • Worst case if wrong (breaks commands / leaks secret / locks user out): a narrowing read too broadly would allow a command that names a protected verb but runs only a search tool; the reader falls back to the prior refusal for any launcher option, pager option, script-reading consumer (sed, awk), shell or evaluator in the frame. No secret or lockout path is touched.
  • Evidence checked (which sandbox result proves it): is_denied through test/test_denied_commands_security_shared_reader.py and TestSandboxEscapeSshSelf; 48 of the 336 cases fail with the prior source and all pass now, and the guard cases (unmodelled launcher options, permission verbs under a launcher, heredocs to a shell or piped to one, unquoted delimiters, non-literal prefixes, git grep -O) keep the prior verdict. A further 29-shape probe changed no verdict beyond the intended allows.
  • No regression:
    • Tools still work (which tools/commands were run, result): the shell_normalizer / argv_floor / is_denied suites (139 files): 9821 passed, 38 skipped; perm-verb, deny_gate and heredoc suites: 1779 passed; flake-pattern ratchet 60 passed.
    • Backward compatible (old config / old data / old callers still work, how checked): no rule rows, config keys or public functions removed; the new helpers are registered on the package facade and the facade guard tests pass.
    • Existing tests (which suites passed on this head): the suites above plus the scoped backend gate (one local-only failure from a missing pytest_split plugin in a file this diff does not touch); flake8, isort, black, mypy, docs-lint and semgrep clean.
  • How to undo: revert this one commit; no data or config migration.

@JLargent42

Copy link
Copy Markdown
Contributor Author

Local pre-push review (hand-written charters; the brief extractor reported a parity failure, so this is approximate to CI).

  • Opus charter: PASS (0 blocking, 0 advisory). The run ended before its full write-up; the verdict and the per-claim checks were recorded.
  • GPT charter: the run ended before a verdict after naming two candidates, both checked with a throwaway probe against main and this head: (a) a launcher in front of awk/sed reads the same as the bare program, which the prior reader already treats as data, so this is not a new allow; (b) an escaped double quote in a heredoc delimiter gives the same verdict on both sides.

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

github-actions Bot commented Oct 23, 2026 •

Copy link
Copy Markdown
Contributor

UX Review (Opus 5.5) — ⏭️ skipped

Revision 137b45e4d583ab9549f355e0023b7525c710ea96 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 commented Oct 23, 2026 •

Copy link
Copy Markdown
Contributor

Design Review (Opus 5.5) — ✅ PASS

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

Design-Verdict: PASS

No design-level concerns. The full-output splice falls back to main's one-word reading whenever it can't model the output, so it only adds refusals and widens no allow.

Notes

[DESIGN-REVIEWED] 137b45e

Description read

[DESCRIPTION-READ] 9936f59ec90587743f72be4468e60134325f4fc53ec13cfa9d7c73f78674d881

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

Copy link
Copy Markdown
Contributor

First Principles Review (Opus 5.5) — ✅ PASS

Premise-level review of 137b45e4d583ab9549f355e0023b7525c710ea96 — 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

The fix fits gap 2 of #21345 closely. The only extra is three spec paragraphs about gaps 1, 3 and 4, which this PR leaves unchanged.

Notes

What this change ships

Inventory (6 items) — 5 justified

Intent: stop an agent from reaching ssh to this host by hiding the command in the printed output of $(echo …)/printf. FIX.

  1. $(echo ssh localhost id), `printf 'ssh localhost'` and similar in program position are now refused — justified
  2. If any substitution on the line prints a word starting with -, nothing on the line is spliced and the line is read as on main — justified
  3. A trailing space in printed output ($(printf 'ssh ')localhost) now separates words — justified
  4. Security spec gains paragraphs on glued redirections, launcher searches and quoted heredocs, all unchanged — rides along, oversized
  5. New private reader _static_substitution_words (with _is_echo_option and _STATIC_OUTPUT_UNSAFE_CHARS), registered on the security facade — justified
  6. Security-package line budget raised by 86 — justified

[FIRST-PRINCIPLES-REVIEWED] 137b45e

Description read

[DESCRIPTION-READ] 826180eb844cd8ba8a47e0d64270f7499fb54481efd7bd334ab3224558fb3b9f

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

Copy link
Copy Markdown
Contributor

Opus 5.5 Review — 🔴 changes requested (blocking)

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

The ssh self-target floor now splits a multi-word substitution's output on the default IFS. Base refused IFS=,; ssh -l $(echo u far) localhost id; this head lets it through, and the agent can ssh into its own machine outside the sandbox.

BLOCKING — src/kiro_crew/security/argv_floor_ssh.py:979
words = _full_output(match) if splice_lines else None / if words is not None: / return words
Trigger: the agent runs IFS=,; ssh -l $(echo u far) localhost id (also ssh -p $(echo 22 far) localhost id). The path is is_denied → _is_ssh_to_self, where _FLAT_SUBSTITUTION_RE.sub(_splice_static_substitution, …) rewrites the text to ssh -l u far localhost id. The walk then reads far as the host and localhost as part of the remote command.
Outcome: is_denied returns None on head. On base 91d4998 the same command is refused with rule=sandbox-escape-ssh-self. With IFS set to ,, bash does not split u far, so the real argv is ssh -l "u far" localhost id. That connects to this host and escapes the sandbox.
Anchor: backend-security-controls
Fix: keep the multi-word reading deny-only. Walk both the line splice and the one-word _static_substitution_output splice, and deny if either one reaches a self-host. Or use the line splice only for a substitution in program position.

[BLOCK-MERGE] 137b45e
[OPUS-REVIEWED] 137b45e

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

False positive or not applicable? A repository writer can comment:
/ai-review override fable 137b45e4d583ab9549f355e0023b7525c710ea96 false-positive: <reason, 20 to 500 characters>

@github-actions

github-actions Bot commented Oct 23, 2026 •

Copy link
Copy Markdown
Contributor

GPT 6.1 Review — 🔴 changes requested (blocking)

GPT 6.1 found at least one blocking issue that must be resolved before merging 137b45e4d583ab9549f355e0023b7525c710ea96. Adjudication upheld 1 of 1 blocking finding(s); those must be resolved before merging.

This comment is updated in place on each push.

BLOCKING -- src/kiro_crew/security/argv_floor_self.py:461 -- Printf newline normalization invents an argv boundary

output = _decode_printf_escapes(args[0])
Trigger: ssh $(printf 'localhost\n').example.com id reaches is_denied → _is_ssh_to_self → this helper. Bash strips the trailing newline, producing destination localhost.example.com; the decoder instead produces localhost .
Outcome: The floor reads localhost as the destination and refuses a remote connection that the previous reader allows.
Anchor: defect
Fix: Return None for backslash-containing printf formats in the full-output helper, preserving the existing fallback until escapes can be decoded faithfully.
Sites: Backtick substitutions; program-position $(printf 'ssh localhost\n').example.com id; corresponding destination substitutions in sftp, scp, and rsync.

[BLOCK-MERGE] 137b45e
[GPT-REVIEWED] 137b45e

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

F1 (LOW harm). The bug is confirmed, but the fix is small and the bad code is new in this PR. _decode_printf_escapes turns \n into a space (shell_normalizer_escapes.py:16, :113). That makes the output.rstrip("\n") at argv_floor_self.py:465 do nothing, so localhost gets spliced in as whole words at argv_floor_ssh.py:968-985. The ssh floor then reads localhost as the destination.
The failure is a false denial: it blocks the command rather than letting something through, the user sees it, and they can work around it by typing the hostname directly. The command shape that triggers it is unusual.
The fix is one guard in a helper this PR adds (refuse formats containing escapes, or strip trailing newline escapes before decoding). It needs no new state and no coordination between modules, so it doesn't cost more than the harm it prevents.

[ADJUDICATION] 137b45e4d583ab9549f355e0023b7525c710ea96 total=1 uphold=1 downgrade=0
UPHOLD F1 src/kiro_crew/security/argv_floor_self.py:461 reason=harm-warrants-remedy
[GPT-ADJUDICATED] 137b45e4d583ab9549f355e0023b7525c710ea96

False positive or not applicable? A repository writer can comment:
/ai-review override gpt 137b45e4d583ab9549f355e0023b7525c710ea96 false-positive: <reason, 20 to 500 characters>

@github-actions

github-actions Bot commented Oct 23, 2026 •

Copy link
Copy Markdown
Contributor

Security Scope Review -- 🔴 BLOCK (blocking)

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

Verdict basis: a script-confirmed newly-refused operation.

Security scope review -- adjudicated candidates

  • macos-latest (platform posix): 15 classified, 4 newly refused, 7 still allowed.
  • ubuntu-latest (platform posix): 15 classified, 4 newly refused, 7 still allowed.
  • windows-latest (platform windows): 4 classified, 1 newly refused, 2 still allowed.

Newly refused (confirmed by the real classifier at both refs)

  • $(echo ssh build.example.com uptime) (posix, leg macos-latest)
    • Who loses it: One token off the attack: an operator script builds the ssh line from a literal and runs it against the remote build host to check load before a deploy; only the host differs from the refused self-target shape.
    • Refused by: deny-rules -- Blocked by security policy: (?:\A|[;&|\n]|\$\()[\s"'(]*(?:[\w.:/\\-]*[/\\])?(?:ssh|scp|sftp|rsync)(?:\.exe)?\s+(?:\S*@)?(?:localhost|127\.\d{1,3}\.\d{1,3}\.\d{1,3}|\[?::1\]?|\$\(\s*hostname|\s*hostname|${?hostname}?)(?=[\s:'");&|#]|\Z)
      Matched structurally on the command's argv, not by the pat
  • $(echo ssh deploy@build.example.com systemctl status kiro-crew) (posix, leg macos-latest)
    • Who loses it: A maintainer's status query on the remote runner built from a literal echo; a far host with a user@ prefix, multi-word output now spliced as argv.
    • Refused by: deny-rules -- Blocked by security policy: (?:\A|[;&|\n]|\$\()[\s"'(]*(?:[\w.:/\\-]*[/\\])?(?:ssh|scp|sftp|rsync)(?:\.exe)?\s+(?:\S*@)?(?:localhost|127\.\d{1,3}\.\d{1,3}\.\d{1,3}|\[?::1\]?|\$\(\s*hostname|\s*hostname|${?hostname}?)(?=[\s:'");&|#]|\Z)
      Matched structurally on the command's argv, not by the pat
  • rsync $(echo dist/ build.example.com:/srv/app/) (posix, leg macos-latest)
    • Who loses it: A deploy step pushes the built dist directory to the remote app host with the src/dest pair from a literal; multi-word splice into rsync's any-position target walk.
    • Refused by: deny-rules -- Blocked by security policy: (?:\A|[;&|\n]|\$\()[\s"'(]*(?:[\w.:/\\-]*[/\\])?(?:ssh|scp|sftp|rsync)(?:\.exe)?\s+(?:\S*@)?(?:localhost|127\.\d{1,3}\.\d{1,3}\.\d{1,3}|\[?::1\]?|\$\(\s*hostname|\s*hostname|${?hostname}?)(?=[\s:'");&|#]|\Z)
      Matched structurally on the command's argv, not by the pat
  • logger -t kiro $(echo rsync localhost mirror finished) (posix, leg macos-latest)
    • Who loses it: A cron-run mirror script logs completion to syslog with an unquoted literal message; logger is the program, the ssh-family words are message data.
    • Refused by: deny-rules -- Blocked by security policy: (?:\A|[;&|\n]|\$\()[\s"'(]*(?:[\w.:/\\-]*[/\\])?(?:ssh|scp|sftp|rsync)(?:\.exe)?\s+(?:\S*@)?(?:localhost|127\.\d{1,3}\.\d{1,3}\.\d{1,3}|\[?::1\]?|\$\(\s*hostname|\s*hostname|${?hostname}?)(?=[\s:'");&|#]|\Z)
      Matched structurally on the command's argv, not by the pat
  • $(echo ssh build.example.com uptime) (posix, leg ubuntu-latest)
    • Who loses it: One token off the attack: an operator script builds the ssh line from a literal and runs it against the remote build host to check load before a deploy; only the host differs from the refused self-target shape.
    • Refused by: deny-rules -- Blocked by security policy: (?:\A|[;&|\n]|\$\()[\s"'(]*(?:[\w.:/\\-]*[/\\])?(?:ssh|scp|sftp|rsync)(?:\.exe)?\s+(?:\S*@)?(?:localhost|127\.\d{1,3}\.\d{1,3}\.\d{1,3}|\[?::1\]?|\$\(\s*hostname|\s*hostname|${?hostname}?)(?=[\s:'");&|#]|\Z)
      Matched structurally on the command's argv, not by the pat
  • $(echo ssh deploy@build.example.com systemctl status kiro-crew) (posix, leg ubuntu-latest)
    • Who loses it: A maintainer's status query on the remote runner built from a literal echo; a far host with a user@ prefix, multi-word output now spliced as argv.
    • Refused by: deny-rules -- Blocked by security policy: (?:\A|[;&|\n]|\$\()[\s"'(]*(?:[\w.:/\\-]*[/\\])?(?:ssh|scp|sftp|rsync)(?:\.exe)?\s+(?:\S*@)?(?:localhost|127\.\d{1,3}\.\d{1,3}\.\d{1,3}|\[?::1\]?|\$\(\s*hostname|\s*hostname|${?hostname}?)(?=[\s:'");&|#]|\Z)
      Matched structurally on the command's argv, not by the pat
  • rsync $(echo dist/ build.example.com:/srv/app/) (posix, leg ubuntu-latest)
    • Who loses it: A deploy step pushes the built dist directory to the remote app host with the src/dest pair from a literal; multi-word splice into rsync's any-position target walk.
    • Refused by: deny-rules -- Blocked by security policy: (?:\A|[;&|\n]|\$\()[\s"'(]*(?:[\w.:/\\-]*[/\\])?(?:ssh|scp|sftp|rsync)(?:\.exe)?\s+(?:\S*@)?(?:localhost|127\.\d{1,3}\.\d{1,3}\.\d{1,3}|\[?::1\]?|\$\(\s*hostname|\s*hostname|${?hostname}?)(?=[\s:'");&|#]|\Z)
      Matched structurally on the command's argv, not by the pat
  • logger -t kiro $(echo rsync localhost mirror finished) (posix, leg ubuntu-latest)
    • Who loses it: A cron-run mirror script logs completion to syslog with an unquoted literal message; logger is the program, the ssh-family words are message data.
    • Refused by: deny-rules -- Blocked by security policy: (?:\A|[;&|\n]|\$\()[\s"'(]*(?:[\w.:/\\-]*[/\\])?(?:ssh|scp|sftp|rsync)(?:\.exe)?\s+(?:\S*@)?(?:localhost|127\.\d{1,3}\.\d{1,3}\.\d{1,3}|\[?::1\]?|\$\(\s*hostname|\s*hostname|${?hostname}?)(?=[\s:'");&|#]|\Z)
      Matched structurally on the command's argv, not by the pat
  • $(echo ssh.exe build.example.com uptime) (windows, leg windows-latest)
    • Who loses it: The Windows spelling of the program-position splice: a PowerShell helper composes the OpenSSH client line for the remote build host; must stay allowed as the posix row does.
    • Refused by: deny-rules -- Blocked by security policy: (?:\A|[;&|\n]|\$\()[\s"'(]*(?:[\w.:/\\-]*[/\\])?(?:ssh|scp|sftp|rsync)(?:\.exe)?\s+(?:\S*@)?(?:localhost|127\.\d{1,3}\.\d{1,3}\.\d{1,3}|\[?::1\]?|\$\(\s*hostname|\s*hostname|${?hostname}?)(?=[\s:'");&|#]|\Z)
      Matched structurally on the command's argv, not by the pat

Each row above is an operation that the base ref ALLOWS and this change REFUSES. Narrow the rule at the tier named. Withdrawing a row is not the way to green: that is its own pull request, on its own merits.

Scope-Verdict: PASS

Reason: The change makes the ssh self-target floor read a literal echo/printf substitution as every word it prints, so a substitution in program position is read as the argv it expands to. That refuses only the hidden ssh localhost shape. Any line where one of those outputs holds a - word goes back to the old one-word reading. No regression has been confirmed yet. The verdict on the 19 candidates comes from the harness. The heredoc, launcher-search and glued-redirection notes in security.md change no code, so there was nothing there to adjudicate.

TIGHTENING: ssh self-target argv floor (_is_ssh_to_self in argv_floor_ssh.py), which now splices the whole output of a static substitution through the new _static_substitution_words -- it refuses an ssh-family command to this host hidden inside a literal substitution, quoting the hunk: "A body whose whole output is a literal line ($(echo ssh localhost id)) is spliced as every word it prints, so a program-position substitution reads as the argv it expands to".

ADJUDICATED: 19 candidates, 0 confirmed newly-refused

PLATFORM COVERAGE:

  • posix (15 rows): These cover the $(…) splice in three places:

    • program position: $(echo ssh build.example.com uptime), sudo $(echo systemctl restart sshd)
    • ssh's host and remote-command slots: ssh build.example.com $(echo curl localhost:8080/health)
    • the any-position target walk of scp and rsync: two-word operand outputs, with both local and remote destinations

    Five more rows (git commit -m, gh pr comment --body, echo, grep, logger) quote or pass the ssh and localhost words as plain arguments to programs that are not in the ssh family. One row has a - word in the output, which tests the no-splice branch.

  • windows (4 rows): These use the ssh.exe/scp.exe spellings with PowerShell $(…) subexpressions, in both program and operand position. The diff assumes .exe basename resolution, and its own test lists ssh.exe $(echo -o …).

  • Not probed:

    • Backtick bodies on Windows and cmd.exe spellings, which have no $(…) form.
    • Output containing \ (a Windows path). The unsafe-character set drops that output back to the old one-word reading, so no candidate could exercise the new splice there.

[SCOPE-REVIEWED] 137b45e

The confirmed rows, in the committed corpus's own shape
{
  "golden_paths": [
    {
      "kind": "shell",
      "command_or_flow": "$(echo ssh build.example.com uptime)",
      "platform": "posix",
      "reason": "One token off the attack: an operator script builds the ssh line from a literal and runs it against the remote build host to check load before a deploy; only the host differs from the refused self-target shape."
    },
    {
      "kind": "shell",
      "command_or_flow": "$(echo ssh deploy@build.example.com systemctl status kiro-crew)",
      "platform": "posix",
      "reason": "A maintainer's status query on the remote runner built from a literal echo; a far host with a user@ prefix, multi-word output now spliced as argv."
    },
    {
      "kind": "shell",
      "command_or_flow": "rsync $(echo dist/ build.example.com:/srv/app/)",
      "platform": "posix",
      "reason": "A deploy step pushes the built dist directory to the remote app host with the src/dest pair from a literal; multi-word splice into rsync's any-position target walk."
    },
    {
      "kind": "shell",
      "command_or_flow": "logger -t kiro $(echo rsync localhost mirror finished)",
      "platform": "posix",
      "reason": "A cron-run mirror script logs completion to syslog with an unquoted literal message; logger is the program, the ssh-family words are message data."
    },
    {
      "kind": "shell",
      "command_or_flow": "$(echo ssh.exe build.example.com uptime)",
      "platform": "windows",
      "reason": "The Windows spelling of the program-position splice: a PowerShell helper composes the OpenSSH client line for the remote build host; must stay allowed as the posix row does."
    }
  ]
}

@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 23, 2026
@JLargent42
JLargent42 force-pushed the fix/shell-normalizer-gaps branch from 0a500a8 to 9b58139 Compare October 23, 2026 04:08
@JLargent42

Copy link
Copy Markdown
Contributor Author

Sensitive change review

  • Head commit: 9b58139
  • What rule changed: the shared shell reader in security/shell_normalizer*.py and security/argv_floor_self.py / argv_floor_ssh.py, which the self-protection, git-publish, sandbox-escape-ssh-self and network-exposure argv floors read.
  • Before -> after (what was allowed/blocked, now): a self-protection verb with a redirection glued to it, and a literal echo/printf substitution naming this host in program position, were allowed and are now refused. A search tool behind a modelled launcher (time/sudo/nice/timeout/env/command/exec/nohup) or git grep without a pager option, and a quoted heredoc body fed only to data consumers in text with no backslash-newline, were refused and are now allowed. Everything the reader does not fully model keeps the prior reading.
  • Worst case if wrong (breaks commands / leaks secret / locks user out): a narrowing read too broadly would allow a command that names a protected verb; the reader falls back to the prior refusal for any launcher option, pager option, script-reading consumer (sed, awk), shell or evaluator in the frame, and for any heredoc text holding a backslash-newline. No secret or lockout path is touched.
  • Evidence checked (which sandbox result proves it): is_denied through test/test_denied_commands_security_shared_reader.py and TestSandboxEscapeSshSelf: the newly read shapes plus guard cases (unmodelled launcher options, permission verbs under a launcher, heredocs to a shell or piped to one, unquoted delimiters, non-literal prefixes, git grep -O, a body line ending in a backslash, including inside bash -c) that keep the prior refusal.
  • No regression:
    • Tools still work (which tools/commands were run, result): every test file matching shell_normalizer / argv_floor / is_denied / perm_verb / deny_gate / heredoc, plus the facade-mirror guards and the security package budget: 11349 passed, 38 skipped, 0 failed.
    • Backward compatible (old config / old data / old callers still work, how checked): no rule rows, config keys or public functions removed; strip_heredocs is keyword-only with the existing behaviour as its default; the new names are in the facade manifests and the facade guards pass.
    • Existing tests (which suites passed on this head): the suites above; flake8, isort, black, mypy, docs-lint and semgrep clean.
  • How to undo: revert this one commit; no data or config migration.

@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 Oct 23, 2026
@JLargent42

Copy link
Copy Markdown
Contributor Author
  • span=c65544f87915 Heredoc bodies are located after line continuations are folded

fixed in 9b58139: _self_tokens removes heredoc bodies only when the unfolded text holds no backslash-newline, and does so before folding; with one present, every line is read as a command. The self-protection floor, which joins continuations before building frames, passes strip_heredocs=False whenever the join changed the text.
Tests: TestQuotedHeredocBodyIsStdinData::test_a_body_a_program_can_run_is_still_read covers a body line ending in a backslash with a single-quoted delimiter, a backslash-escaped delimiter, both self-protection verbs, and the same shape inside a -c payload; all are refused, and red at the prior head.
self-added: yes
mechanism: heredoc-body strip in the shared reader

@JLargent42
JLargent42 force-pushed the fix/shell-normalizer-gaps branch from 9b58139 to 9361179 Compare October 23, 2026 04:38
@JLargent42

Copy link
Copy Markdown
Contributor Author
  • span=58f918e8fcd6 Incorrect delimiter dequoting

fixed in 9361179: _heredoc_delimiter returns None for a double-quoted delimiter part that holds a backslash, since bash removes a backslash there before \, ", $, a backtick or a newline and that reading is not modelled. _quoted_heredoc_bodies then places no body, so every line of the command is read as a command.
Tests: test_a_body_a_program_can_run_is_still_read covers the reported delimiter shape and an escaped-quote delimiter; both are refused and both were allowed at the prior head.
self-added: yes
mechanism: heredoc delimiter reader

@JLargent42

Copy link
Copy Markdown
Contributor Author

Sensitive change review

  • Head commit: 9361179
  • What rule changed: the shared shell reader in security/shell_normalizer*.py and security/argv_floor_self.py / argv_floor_ssh.py, which the self-protection, git-publish, sandbox-escape-ssh-self and network-exposure argv floors read.
  • Before -> after (what was allowed/blocked, now): a self-protection verb with a redirection glued to it, and a literal echo/printf substitution naming this host in program position, were allowed and are now refused. A search tool behind a modelled launcher or git grep without a pager option, and a quoted heredoc body fed only to data consumers (no backslash-newline, no backslash in a double-quoted delimiter), were refused and are now allowed. A ) inside heredoc data no longer closes a substitution. Everything the reader does not fully model keeps the prior reading.
  • Worst case if wrong (breaks commands / leaks secret / locks user out): a narrowing read too broadly would allow a command that names a protected verb; the reader falls back to the prior refusal for any launcher option, pager option, script-reading consumer (sed, awk), shell or evaluator in the frame, any heredoc it cannot place, and any heredoc text holding a backslash-newline. No secret or lockout path is touched.
  • Evidence checked (which sandbox result proves it): is_denied through test/test_denied_commands_security_shared_reader.py and TestSandboxEscapeSshSelf, including guard cases for every reviewer-reported heredoc shape (backslash-ended body line, backslash or escaped quote in a double-quoted delimiter, a ) line inside heredoc data within a substitution, quoted and unquoted), all refused.
  • No regression:
    • Tools still work (which tools/commands were run, result): every test file matching shell_normalizer / argv_floor / is_denied / perm_verb / deny_gate / heredoc, plus every facade guard and the security package budget: 15107 passed, 38 skipped, 0 failed before the budget update; the budget test passes after it.
    • Backward compatible (old config / old data / old callers still work, how checked): no rule rows, config keys or public functions removed; new keyword arguments default to the existing behaviour; facade guards pass.
    • Existing tests (which suites passed on this head): the suites above; flake8, isort, black, mypy, docs-lint and semgrep clean.
  • How to undo: revert this one commit; no data or config migration.

@JLargent42

Copy link
Copy Markdown
Contributor Author
  • span=58f918e8fcd6 Substitution span closes prematurely on heredoc data

fixed in 9361179: _substitution_bodies proves the closing paren over _heredoc_data_masked(...), which blanks each placed heredoc body (offsets kept); when the slice holds a << whose body cannot be placed, every ) is blanked, so no closer is proven and the whole remainder is read.
Tests: test_a_body_a_program_can_run_is_still_read covers a ) line inside a quoted heredoc inside "$(…)", inside a bare $(…) assignment, and inside an unquoted heredoc; all are refused, the first and third were allowed at the prior head. The commit-message shape git commit -m "$(cat <<EOF … EOF)" with a quoted delimiter stays allowed.
self-added: yes
mechanism: substitution span proof in the shared reader

@JLargent42

Copy link
Copy Markdown
Contributor Author
  • Newly refused on macos-latest: a remote-shell command whose port option comes from a literal echo substitution, to a dotted remote host

rebutted: the gap-2 splice makes the substitution read as the argv bash actually runs, which is the same command with the port option written out. Main already refuses that written-out command whenever the dotted host has no published resolver verdict yet (_resolved_host_verdict fails closed on a dotted first-contact name). Main allows the substitution spelling only because it reads the substitution as one opaque word, which is the gap #21345 records.
Probed locally with the resolver held at a miss: main denies the written-out command and allows the substitution; this head denies both. With the resolver answering "remote", both are allowed on main and on this head, which matches the ubuntu-latest result.
Not a defect: the macOS row is the existing first-contact resolver behaviour applied to the argv the command really has. A maintainer override for the scope lane at the current head is requested on that basis.

@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 23, 2026
@JLargent42
JLargent42 force-pushed the fix/shell-normalizer-gaps branch from 9361179 to ac72e4a Compare October 23, 2026 05:32
@JLargent42

JLargent42 commented Oct 23, 2026 •

Copy link
Copy Markdown
Contributor Author
  • span=5e784cc06287 shell_normalizer.py: a launched rg --pre preprocessor, and a folded substitution frame hiding a protected command

fixed in ac72e4a. Finding 1 (rg --pre): _data_consumer_command_disqualified withdraws the data-consumer exemption per command when any token is --pre/--pre=…; the preprocessor rg/ag/ack run on every searched file, so its argument is executable whether or not a wrapper launches it. --pre-glob only filters files and is not matched.
Finding 2 (folded substitution): _shell_payload_walk carries a per-frame strip flag. A substitution body is read from the folded source, so a backslash-newline bash keeps literal inside a quoted heredoc is already gone; when the fold changed the source, its substitution descendants are queued with heredoc stripping off and the body lines are read as commands.
Both findings are in shell_normalizer.py, so they share this one path-scoped span. Tests cover the launched/bare/glued rg --pre forms and a backslash-ended heredoc body line inside a substitution; all refused, all allowed at the prior head, and the legit commit-message heredoc stays allowed.
self-added: yes
mechanism: data-consumer --pre disqualifier + per-frame heredoc-strip flag

@JLargent42

Copy link
Copy Markdown
Contributor Author

Sensitive change review

  • Head commit: ac72e4a
  • What rule changed: the shared shell reader in security/shell_normalizer*.py, security/perm_verb_mention.py and security/argv_floor_self.py / argv_floor_ssh.py, which the self-protection, git-publish, sandbox-escape-ssh-self and network-exposure argv floors read.
  • Before -> after (what was allowed/blocked, now): the reader now refuses a self-protection verb with a glued redirection, a literal echo/printf substitution naming this host in program position, a launched second-operand writer (sudo uniq <verb> /etc/passwd), a search tool whose --pre preprocessor runs a protected verb, and a protected command hidden in a quoted heredoc body (double-quoted delimiter with a backslash, a ) inside heredoc data, or a backslash-ended body line inside a substitution). It now allows a search tool behind a modelled launcher or git grep without a pager option, and a quoted heredoc fed only to plain data consumers. Everything the reader does not fully model keeps the prior reading.
  • Worst case if wrong (breaks commands / leaks secret / locks user out): a narrowing read too broadly would allow a command naming a protected verb; the reader falls back to the prior refusal for any launcher option, pager/--pre option, script-reading consumer (sed, awk), second-operand writer, shell or evaluator in the frame, any heredoc it cannot place, any backslash in a double-quoted delimiter, and any backslash-newline in a frame. No secret or lockout path is touched.
  • Evidence checked (which sandbox result proves it): is_denied through test/test_denied_commands_security_shared_reader.py and TestSandboxEscapeSshSelf, with guard cases for every reviewer-reported shape across two CI review rounds, each refused and each allowed at the head it was reported on.
  • No regression:
    • Tools still work (which tools/commands were run, result): every test file matching shell_normalizer / argv_floor / is_denied / perm_verb / deny_gate / heredoc, plus every facade guard and the security package budget: 11362 passed, 38 skipped, 0 failed.
    • Backward compatible (old config / old data / old callers still work, how checked): no rule rows, config keys or public functions removed; new keyword arguments default to the existing behaviour; facade guards pass.
    • Existing tests (which suites passed on this head): the suites above; flake8, isort, black, mypy, docs-lint and semgrep clean; comment-history gate clean.
  • How to undo: revert this one commit; no data or config migration.

@JLargent42

Copy link
Copy Markdown
Contributor Author

Disposition for the confirmed rows on 1648f1d3. I believe this is not a narrowing of what the floor decides, so it is left for the maintainer, as the scope lane is.

  • span=an option-position substitution splice reads as its literal spelling, which the unclassified-host state refuses — ssh $(echo -p 2222) deploy@build.example.com '…' and ssh $(echo -t) build.example.com tmux attach (all three legs), ssh $(echo -L 8080:<loopback>:80) bastion.example.com -N (macOS) and ssh.exe $(echo -L 8080:<loopback>:80) bastion.example.com -N (Windows) were allowed on the base ref and refused on this head.

mechanism: on the base ref the ssh-self floor did not splice an option substitution, so the target after it was never classified, and the command went through for that reason alone. With gap 2 the splice turns each command into its literal spelling, and the literal spelling meets the same target-classification step every literal ssh command meets. While a new dotted name's lookup is still pending, the floor fails closed, and that is the refusal recorded here. I ran each row and its literal spelling through is_denied on this head and on main 46f09275. With the build.example.com names, which never classify locally, the literal spelling is refused on both main and this head, and the splice form matches it on this head. With a classified remote address (198.51.100.7) standing in for the target, every splice row and every literal spelling is allowed on both main and this head. That includes the -L row, whose loopback forward target is an option value, not the ssh destination.
request: a maintainer check of the rows against their literal spelling under the scope harness. If the literal spelling is refused there too, the row measures the classifier state, not this change.

@JLargent42

Copy link
Copy Markdown
Contributor Author

Fixed the second of two GPT findings on 8cde4fd210.

  • span=5e784cc06287 F2 preprocessor disqualifier fires on a non-preprocessor tool (downgraded, defect) — a literal preprocessor-option token anywhere (for example as a search-pattern operand of a plain line matcher) withdrew the data-consumer exemption and over-refused a read-only search.

self-added: yes.
mechanism: the withdrawal is now gated on one of the three search tools that actually define that preprocessor option being present among the tokens; for any other program the token is ordinary data. The real preprocessor threat (one of those three tools naming the product CLI as its preprocessor) stays refused; the plain-line-matcher search with that token as a pattern is allowed again.

Fixed in head 58b2c6c52a1b2341a5f6fff7fd83e2525223d80f; the lane re-runs there.

@JLargent42

Copy link
Copy Markdown
Contributor Author

Sensitive change review

  • Head commit: 617cfb2
  • What rule changed: no rule changed since the prior head 1648f1d. This head is a simplification of the shared shell reader's helpers. The three pattern constants it added (_ECHO_OPTION_RE, _NAMED_FD_PREFIX_RE, _LITERAL_WORD_RE) are replaced by string and set checks (_is_echo_option, _LITERAL_WORD_CHARS); the named-descriptor check is dropped because the literal-word check already returns empty for a {fd} prefix; and the two separator scans share one predicate, _is_command_separator, in place of _is_command_amp plus an inline ;|\n test. The package line budget is lowered to the recomputed total, 32,793.
  • Before -> after (what was allowed/blocked, now): unchanged on ASCII input. A differential check of the old and new helpers over 400,000 random words built from letters, digits, quotes, operators, braces and newlines found 0 differences. The only difference found is a non-ASCII word that case-insensitive [a-z] matched (U+212A): the new check does not read it as a literal word, so it is not kept as an operand.
  • Worst case if wrong (breaks commands / leaks secret / locks user out): a floor reads one operand differently for a word glued to a redirection; the differential check above and the floor suites bound that.
  • Evidence checked (which sandbox result proves it): the differential check above and the floor suites below on this head.
  • No regression:
    • Tools still work (which tools/commands were run, result): test_denied_commands_security_shared_reader.py, test_denied_commands_security_ssh_self.py, test_security_gate_liveness.py, test_facade_mirror_guards.py, test_facade_mirror.py and the denied-commands, argv-floor and shell-normalizer suites ran on this head with -n 2: 1,886 passed, 1 skipped; the deny-gate and denied-commands top-level suites: 284 passed.
    • Backward compatible (old config / old data / old callers still work, how checked): no public function, config key or rule changed; the renamed private helpers have no callers outside this PR's own code, checked with a repository search.
    • Existing tests (which suites passed on this head): the suites above, plus black (py310) through scripts/check_black_formatting.py, flake8, isort, mypy on the security package and the comment-history gate against origin/main.
  • How to undo: revert the commit; no data or config migration.

@JLargent42

Copy link
Copy Markdown
Contributor Author

Simplification pass on this head (617cfb2): the shared shell reader's three new pattern constants are replaced with string and set checks, the two glued-separator scans share one predicate, and a named-descriptor check the literal-word check already covered is removed. Source is 3 lines shorter and the package budget drops to 32,793. Old and new helpers agree on 400,000 random ASCII words; the targeted floor suites pass. No rule changed, and the open review findings on the prior head are unchanged by this commit.

@github-actions github-actions Bot added readiness: checking Automated validation is still running 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: action required A blocking check or review needs attention readiness: checking Automated validation is still running labels Oct 26, 2026
@JLargent42
JLargent42 force-pushed the fix/shell-normalizer-gaps branch from 617cfb2 to 8b8a6d1 Compare October 27, 2026 16:26
@JLargent42 JLargent42 changed the title fix(security): read glued redirects and literal substitutions in the shared shell reader fix(security): read literal echo/printf substitutions as argv in the ssh floor Oct 27, 2026
@github-actions github-actions Bot removed the merge conflict Branch has merge conflicts with its base — author must resolve before merge label Oct 27, 2026
@JLargent42

Copy link
Copy Markdown
Contributor Author

Sensitive change review

  • Head commit: 8b8a6d1
  • What rule changed: this head rebases onto current main and narrows the PR to gap 2, by operator decision. All of gap 1 is removed: _redirect_word_prefix, _glued_command_tail, _word_before_glued_separator and _is_command_separator, the edits to _self_cli_operands and _self_program_index, their facade entries, and test_denied_commands_security_shared_reader.py. shell_normalizer.py and shell_normalizer_walk.py are restored to main. What remains is _static_substitution_words in argv_floor_self.py, which the ssh self-target floor (argv_floor_ssh.py) uses to splice the full output of a literal echo/printf substitution. The package line budget is recomputed to 32,705 (main's 32,635 plus 70).
  • Before -> after (what was allowed/blocked, now): the self-protection floor reads exactly as on main. On the ssh self-target floor, a literal substitution whose printed words name this host ($(echo ssh localhost id)) is refused; the same output naming another host stays allowed; a substitution in an option position keeps reading through to the real host. Output carrying quoting, operator, expansion or comment characters falls back to main's one-word reader.
  • Worst case if wrong (breaks commands / leaks secret / locks user out): an ssh command using a literal echo/printf substitution is read differently from how the shell runs it, so it is refused or allowed in error. The guard cases in the ssh-self suite cover both directions.
  • Evidence checked (which sandbox result proves it): the floor suites below, run on this head.
  • No regression:
    • Tools still work (which tools/commands were run, result): pytest -n 2 over test_denied_commands_security*.py (12 files), test_argv_floor_*.py (3), test_facade_mirror_guards.py, test_facade_shared_checks.py, test_security_gate_liveness.py and test_blocked_commands_disclosure.py: 2,041 passed, 1 skipped. The top-level denied-commands and deny-gate suites (9 files): 504 passed.
    • Backward compatible (old config / old data / old callers still work, how checked): no public function, config key or rule changed. The removed private helpers were added by this PR and have no other callers (repository search).
    • Existing tests (which suites passed on this head): the suites above, plus black (py310) through scripts/check_black_formatting.py, flake8, isort, mypy on the security package, docs-lint, and the comment-history gate against origin/main.
  • How to undo: revert the commit; no data or config migration.

@JLargent42

Copy link
Copy Markdown
Contributor Author

Disposition for GPT F1 on 1648f1d3. Resolved by removal, not by a patch.

@JLargent42

Copy link
Copy Markdown
Contributor Author

Disposition for GPT F2 on 1648f1d3. It is not deferred: it is in the gap-2 code this PR still ships, and it is not fixed on head 8b8a6d19ae4a9eed0efe9b2d1583a6d0711a9546.

  • span=f59b205cadd9 F2 whitespace collapse drops a trailing argv boundary (argv_floor_self.py, _static_substitution_words). " ".join(output.split()) drops the trailing space of a printf format, so the spliced text joins it to the next word.

    Not a regression: main does not splice substitutions at all and allows the same shape, so this head refuses nothing less than main.
    Proposed fix (not applied on this head): strip only trailing newlines, as command substitution does, and keep internal and trailing spaces. The fix and its guard test wait on the owner's call.

@JLargent42

Copy link
Copy Markdown
Contributor Author

Disposition for the Opus glued-separator findings (rounds on 99b3e929 and 1648f1d3). Resolved by removal, not by a patch.

@JLargent42
JLargent42 force-pushed the fix/shell-normalizer-gaps branch from 8b8a6d1 to 6f1a06b Compare October 27, 2026 17:04
@JLargent42

Copy link
Copy Markdown
Contributor Author

Fixed the blocking finding on 8b8a6d19 in head 6f1a06b5855ccc66c18eeddcdcac3787451c3b09.

  • span=49f9306ff16b dash-led substitution output after a value-taking option was spliced as a second option (argv_floor_ssh.py). ssh -i $(echo -l) localhost id read as ssh -i -l localhost id, so the walk lost the host.

    self-added: yes. This PR's splice introduced it.
    fix: the splice now runs in a loop that sees the text built so far. When the output starts with - and the word before it starts with -, it keeps main's one-word reading, which leaves the original text in place. The previous word is read after its own splice, so this also covers a chained $(echo -i) $(echo -l).
    test: test_dash_output_after_an_option_is_that_options_value covers both trigger lines, plus the backtick, chained and scp forms. It fails without the fix.

@JLargent42

Copy link
Copy Markdown
Contributor Author

Fixed GPT F2 in head 6f1a06b5855ccc66c18eeddcdcac3787451c3b09.

  • span=f59b205cadd9 F2 whitespace collapse drops a trailing argv boundary (argv_floor_self.py, _static_substitution_words).

    fix: the output is now trimmed with rstrip("\n"), which is what command substitution strips. Interior and trailing spaces are kept, so $(printf 'ssh ')localhost id reads as ssh localhost id. Output that is empty or only whitespace still returns None.
    test: test_a_trailing_space_in_substitution_output_separates_words (printf and echo forms), and the unit test asserts that printf 'ssh ' yields "ssh ". Both fail without the fix.

@JLargent42

Copy link
Copy Markdown
Contributor Author

Sensitive change review

  • Head commit: 6f1a06b
  • What rule changed: two fixes to the ssh self-target floor's literal substitution reader, both from review of the prior head 8b8a6d1. (1) _is_ssh_to_self splices substitutions in a loop that sees the text already built. When a substitution's output starts with - and the word before it is option-shaped, it keeps main's one-word reading, because the shell passes that output as the option's value. (2) _static_substitution_words strips only trailing newlines, as command substitution does, instead of collapsing whitespace, so a trailing space still separates the output from text glued after it. The package line budget is recomputed to 32,719.
  • Before -> after (what was allowed/blocked, now): ssh -i $(echo -l) localhost id, ssh -l $(echo -l) 127.0.0.1 id and the backtick and scp forms were refused on main, allowed on 8b8a6d1, and are refused again. $(printf 'ssh ')localhost id and $(echo 'ssh ')localhost id were allowed on main and on 8b8a6d1, and are now refused. ssh -v $(echo -l) localhost id is allowed, as on main: the shell reads it as user localhost, host id.
  • Worst case if wrong (breaks commands / leaks secret / locks user out): an ssh command built with a literal echo/printf substitution is read differently from how the shell runs it, so it is refused or allowed in error. Every shape the fix touches falls back to main's reading.
  • Evidence checked (which sandbox result proves it): the new tests in test/test_denied_commands_security_ssh_self.py (test_dash_output_after_an_option_is_that_options_value, test_a_trailing_space_in_substitution_output_separates_words, and the _static_substitution_words unit test). With the src change reverted, 7 of the 8 selected tests fail; with it, all 8 pass.
  • No regression:
    • Tools still work (which tools/commands were run, result): pytest -n 2 -q over test_denied_commands_security*.py and test_argv_floor_*.py (14 files), test_facade_mirror_guards.py, test_facade_shared_checks.py, test_security_gate_liveness.py and test_blocked_commands_disclosure.py: 2,048 passed, 1 skipped. The top-level denied-commands and deny-gate suites (9 files): 504 passed.
    • Backward compatible (old config / old data / old callers still work, how checked): no public function, config key or rule changed.
    • Existing tests (which suites passed on this head): the suites above, plus black (py310) through scripts/check_black_formatting.py, flake8, isort, mypy on the security package, docs-lint, and the comment-history gate against origin/main.
  • How to undo: revert the commit; no data or config migration.

…ssh floor

The ssh self-target floor splices a literal `$(echo ...)` / `printf`
substitution back into the command text, so a substitution in program
position reads as the argv the shell builds from it.

`_static_substitution_words` returns every word the substitution prints:
`echo` with its -n/-e/-E options consumed, or `printf` with one format
operand and no `%` conversion. Like the shell, it strips only trailing
newlines. It returns None for anything else, and the existing one-word
reader applies. Output carrying quoting, operators, expansions or comments
is never re-spliced.

A line where any such output holds a word starting with `-` is not spliced
as a line. The whole command keeps the one-word reading, so no option word
reaches the walk from a substitution.

Glued redirections and separators in the self-protection floor (gap 1) are
deferred to #23351 with the shared tokenizer work; the spec records that.
The package line budget is recomputed to 32,721.
@JLargent42
JLargent42 force-pushed the fix/shell-normalizer-gaps branch from 6f1a06b to 137b45e Compare October 27, 2026 17:24
@JLargent42

Copy link
Copy Markdown
Contributor Author

Fixed the blocking finding on 6f1a06b5 in head 137b45e4d583ab9549f355e0023b7525c710ea96, by narrowing the splice at its root rather than with another shape guard.

  • span=4fda723f6f7e expanded option values can hide a self-host destination (argv_floor_ssh.py:972). ssh $(echo -i -l localhost) id was spliced to ssh -i -l localhost id, which the walk reads with localhost as the -l value. Main refuses it.

    self-added: yes. This PR's multi-word splice introduced it.
    fix (root narrowing): a line where any literal substitution's output holds a word starting with - is not spliced at all. The whole command keeps main's one-word reading. No option word ever enters the walk from a substitution, so the floor reads every option shape exactly as main does. The previous-word special case added on 6f1a06b5 is removed; the trailing-newline fix stays.
    test: test_substitution_output_with_an_option_word_is_not_spliced covers the reported line plus the -o -l, -J -l and -v -i -l variants and the option-value forms. The -i -l, -o -l and -v -i -l cases fail on 6f1a06b5, and all of them pass here. The multi-word splice still applies to output with no option word ($(echo ssh localhost id), $(printf 'ssh ')localhost id).

@JLargent42

Copy link
Copy Markdown
Contributor Author

Sensitive change review

  • Head commit: 137b45e
  • What rule changed: since the prior head 6f1a06b, the ssh self-target floor's literal substitution splice is narrowed at its root. A line where any literal echo/printf substitution's output holds a word starting with - is not spliced; the whole command keeps main's one-word reading. The previous-word check from the prior head is removed. _static_substitution_words still strips only trailing newlines. The package line budget is recomputed to 32,721.
  • Before -> after (what was allowed/blocked, now): ssh $(echo -i -l localhost) id, ssh $(echo -o -l localhost) id and ssh $(echo -v -i -l localhost) id were refused on main, allowed on 6f1a06b, and are refused again. A line with an option word in its substitution output reads exactly as on main, so chained forms such as ssh $(echo -i) $(echo -l) localhost id are allowed, as on main. The prior head refused those because it spliced them. $(echo ssh localhost id) and $(printf 'ssh ')localhost id are still refused, and output naming another host stays allowed.
  • Worst case if wrong (breaks commands / leaks secret / locks user out): a literal substitution without option words is read differently from how the shell runs it. Any line with an option word in a substitution's output falls back to main's reading.
  • Evidence checked (which sandbox result proves it): test_substitution_output_with_an_option_word_is_not_spliced in test/test_denied_commands_security_ssh_self.py (8 cases). Three of them fail on 6f1a06b, and all 8 pass on this head. A grep of the test tree found no allow test that depends on splicing an option word. The option-position allow cases (ssh $(echo -p 2222) build.example.com uptime and the like) now pass through main's reading, and one program-position deny case that needed such a splice (ssh $(echo -l root localhost)) is removed, since main allows it.
  • No regression:
    • Tools still work (which tools/commands were run, result): pytest -n 2 -q over test_denied_commands_security*.py and test_argv_floor_*.py (14 files), test_facade_mirror_guards.py, test_facade_shared_checks.py, test_security_gate_liveness.py and test_blocked_commands_disclosure.py: 2,050 passed, 1 skipped. The top-level denied-commands and deny-gate suites (9 files): 504 passed.
    • Backward compatible (old config / old data / old callers still work, how checked): no public function, config key or rule changed.
    • Existing tests (which suites passed on this head): the suites above, plus black (py310) through scripts/check_black_formatting.py, flake8, isort, mypy on the security package, docs-lint, and the comment-history gate against origin/main.
  • How to undo: revert the commit; no data or config migration.

@JLargent42

Copy link
Copy Markdown
Contributor Author

Disposition for the blocking Opus finding on 137b45e4. It is not patched on this PR.

@JLargent42

Copy link
Copy Markdown
Contributor Author

Disposition for the blocking GPT finding on 137b45e4. It is not patched on this PR.

@JLargent42

Copy link
Copy Markdown
Contributor Author

Closing this PR. All of its remaining work moves to #23351.

Gap 1 (glued redirects) was already deferred to #23351. The only thing left here was gap 2, the static-substitution splice in the ssh floor. Four review rounds in a row found a new bypass in that splice, each a different shell edge: dash-word options, option values, IFS splitting and printf newline handling. Patching each edge as it's found isn't converging, so the splice is better rebuilt once, on the shell tokenizer planned in #23351.

Everything this PR covered, plus every reviewer finding from the GPT and Opus rounds, is recorded on #23351, so nothing is lost. Main's behaviour is unchanged.

@JLargent42 JLargent42 closed this Oct 27, 2026
@github-actions github-actions Bot removed the readiness: action required A blocking check or review needs attention label Oct 27, 2026
@bolichen97
bolichen97 deleted the fix/shell-normalizer-gaps branch November 6, 2026 07:18
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant