Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
22 changes: 22 additions & 0 deletions docs/system-specs/modules/security.md
Original file line number Diff line number Diff line change
Expand Up @@ -1086,6 +1086,28 @@ Two mechanisms make "the split changed nothing for a caller" a tested claim rath
views in `deny_gate.py` and to `shell_normalizer._shell_payload_walk` (the
self-protection and git-publish floors), which add them to the frame's own payloads, so
`sh -c 2>/dev/null '<script>'` hides no script and the frame's exemptions still apply.
The walk reads the caller's own command line with single quotes as literal
(`_substitution_bodies(..., raw_source=True)`) only when that line is one simple
`git commit`/`git tag` or `gh pr|issue create|edit|comment` command
(`_is_message_flag_command`): its first word is literally `git` or `gh`, no global
option such as `git -c` comes before the subcommand, it holds no `;`, `&`, `|`,
`(`, `)`, `{`, `}` or newline outside quotes, and every word holding a
substitution opener (a backtick, `$(`, `<(`, `>(`) is the value of a message flag
(`-m`/`--message` for git; `-b`/`--body`/`-t`/`--title` for gh). Every opener must
also sit inside one bare single-quoted value: the value starts with `'` and ends
at its matching closing `'`, with no prefix, suffix or concatenation (including
after `=` or glued flag letters). The whole command text must contain no `$`
anywhere, so `$'...'`, `$[...]`, `$((...))`, `$(...)` and `${...}` do not qualify.
That text opens no nested frame, as in bash
(``gh pr edit 1 --body 'run `ssh x`'`` runs no ssh). Every other command, such as
`trap '...'`, `bash -c 'eval "$1"' _ '...'`, `git -c alias.x='!...'` or
`gh alias set`, gets the quote-blind openers for the whole text, because a later
program may run its single-quoted text as shell. So does a nested or decoded
payload (a `-c` script, an `eval` string, a
quoted assignment script), any text that holds a `#`, `<<`, `$`, a backslash or a
control byte (a newline, or a separator the ssh floor masked), and any text whose
quotes do not all close.
A catalog row still matches its raw text either way.
Within one `is_denied` call (`call_views.sharing_views`, which this module also serves
to its importers) both walks share one result per frame text, and `_shell_payload_walk`
and `argv_floor_self._quoted_assignment_scripts` keep theirs in the same memo, so every
Expand Down
1 change: 1 addition & 0 deletions src/kiro_crew/security/argv_floor.py
Original file line number Diff line number Diff line change
Expand Up @@ -302,6 +302,7 @@
_iter_shell_chars,
_matching_close_paren,
_nested_shell_payloads,
_only_single_quoted_openers,
_program_basename,
_push_option_matches,
_push_token_redirection,
Expand Down
22 changes: 15 additions & 7 deletions src/kiro_crew/security/argv_floor_self.py
Original file line number Diff line number Diff line change
Expand Up @@ -206,7 +206,9 @@ def _quoted_assignment_scripts(text_lower: str) -> "list[str]":
n = _shell_normalizer
found = [text_lower]
for text in found: # extended while it runs, so a script's own scripts count
for source in _shell_payload_sources(text) if "=" in text else ():
literal = text == text_lower
walk = _shell_payload_walk(text, literal_single_quotes=literal) if "=" in text else []
for source, _ in walk:
tokens = n._self_tokens(source, resolve=False) if "=" in source else []
for payload in n._nested_shell_payloads(tokens, allow_join=False):
script = _decode_printf_escapes(payload)
Expand All @@ -222,30 +224,36 @@ def _quoted_assignment_scripts(text_lower: str) -> "list[str]":
return found[1:]


def _self_frames(text_lower: str) -> "list[tuple[str, list[str]]]":
def _self_frames(
text_lower: str, literal_single_quotes: bool = True
) -> "list[tuple[str, list[str]]]":
"""The shared walk plus the walk of every quoted script in it that opens with an
assignment, read whole so the assignment resolves as it does when typed directly.
Once per text inside one ``sharing_views`` call, like the walk itself."""
from .shell_commands import _CALL_VIEWS # local: the facade serves every module name

memo = _CALL_VIEWS.get()
key = ("self_frames", text_lower)
key = ("self_frames", text_lower, literal_single_quotes)
frames = None if memo is None else memo.get(key)
if frames is None:
frames = _shell_payload_walk(text_lower)
frames = _shell_payload_walk(text_lower, literal_single_quotes=literal_single_quotes)
seen = {source for source, _tokens in frames}
for script in _quoted_assignment_scripts(text_lower):
fresh = [frame for frame in _shell_payload_walk(script) if frame[0] not in seen]
fresh = [
frame
for frame in _shell_payload_walk(script, literal_single_quotes=False)
if frame[0] not in seen
]
seen.update(frame[0] for frame in fresh)
frames += fresh
if memo is not None:
memo[key] = frames
return [(source, list(tokens)) for source, tokens in frames]


def _self_token_frames(text_lower: str) -> "list[list[str]]":
def _self_token_frames(text_lower: str, literal_single_quotes: bool = True) -> "list[list[str]]":
"""The command's own argv plus the argv of every nested shell payload."""
return [tokens for _source, tokens in _self_frames(text_lower)]
return [tokens for _source, tokens in _self_frames(text_lower, literal_single_quotes)]


def _shell_payload_sources(text_lower: str) -> "list[str]":
Expand Down
12 changes: 9 additions & 3 deletions src/kiro_crew/security/argv_floor_ssh.py
Original file line number Diff line number Diff line change
Expand Up @@ -38,6 +38,7 @@
_data_consumer_exempt,
_decode_shell_quoted_literals,
_ends_argv,
_only_single_quoted_openers,
_program_basename,
_resolve_param_defaults,
_strip_redirect,
Expand Down Expand Up @@ -950,10 +951,11 @@ def _function_call_binds_self(text: str) -> bool:
def _reaches_self_over_ssh(text_lower: str) -> bool:
""":func:`_is_ssh_to_self` on *text_lower* and on each quoted assignment script in it,
read whole: the separator mask would turn a script's own separators into data."""
return any(map(_is_ssh_to_self, [text_lower, *_quoted_assignment_scripts(text_lower)]))
scripts = _quoted_assignment_scripts(text_lower)
return _is_ssh_to_self(text_lower, own_line=True) or any(map(_is_ssh_to_self, scripts))


def _is_ssh_to_self(text_lower: str) -> bool:
def _is_ssh_to_self(text_lower: str, *, own_line: bool = False) -> bool:
"""True if *text_lower* opens an ssh/scp/sftp/rsync channel to THIS host.

Structural for the same reason the other floors are: the target hides
Expand Down Expand Up @@ -998,6 +1000,10 @@ def _is_ssh_to_self(text_lower: str) -> bool:
the shell-builtin export spellings (``declare -x``/``typeset -x``), which
are not leading-assignment syntax and so are not modeled by the walk.
"""
# Single quotes read as literal only in the caller's own line, and only when it
# has no live substitution opener before the splices below rewrite it: a spliced
# static output (``x'y``) could otherwise pair into quotes around a live one.
literal = own_line and _only_single_quoted_openers(text_lower)
# Collapse empty expansions in the SOURCE so the gate and tokenization both
# read the spliced-out spelling (``s$()sh localhost`` -> ``ssh localhost``).
text_lower = _EMPTY_EXPANSION_RE.sub("", text_lower)
Expand Down Expand Up @@ -1069,7 +1075,7 @@ def _splice_static_substitution(match: "re.Match[str]") -> str:
# frames (a copy staged in a wrapper payload reaches its siblings); a
# copy staged in an EARLIER command line is the documented residual.
bound_program_verbs: "dict[str, str]" = {}
for tokens in _self_token_frames(text_lower):
for tokens in _self_token_frames(text_lower, literal):
programs = _argv_programs(tokens)
# A leading ``RSYNC_RSH=<cmd>`` environment assignment selects rsync's
# remote shell exactly like ``-e``/``--rsh``, but rides BEFORE the verb
Expand Down
22 changes: 16 additions & 6 deletions src/kiro_crew/security/shell_normalizer.py
Original file line number Diff line number Diff line change
Expand Up @@ -95,6 +95,7 @@
_is_shell_variable_reference,
_iter_shell_chars,
_matching_close_paren,
_only_single_quoted_openers,
_opens_comment,
_prev_word,
_push_option_matches,
Expand Down Expand Up @@ -1583,22 +1584,26 @@ def _c_script(start: int, avoid: "int | None") -> None:
# ``${a[@]}`` / ``${a[*]}`` / ``$a[@]`` -- the whole array as separate words.


def _shell_payload_walk(text_lower: str) -> "list[tuple[str, list[str]]]":
def _shell_payload_walk(
text_lower: str, *, literal_single_quotes: bool = True
) -> "list[tuple[str, list[str]]]":
""":func:`_shell_payload_walk_uncached`, once per text inside one ``sharing_views``
call; each caller gets fresh lists, so one that edits its argv cannot reach the next."""
from .shell_commands import _CALL_VIEWS # circular import: the reader imports this module

memo = _CALL_VIEWS.get()
if memo is None:
return _shell_payload_walk_uncached(text_lower)
key = ("payload_walk", text_lower) # the redirect views' keys are plain str
return _shell_payload_walk_uncached(text_lower, literal_single_quotes)
key = ("payload_walk", text_lower, literal_single_quotes) # redirect views' keys are str
frames = memo.get(key)
if frames is None:
frames = memo[key] = _shell_payload_walk_uncached(text_lower)
frames = memo[key] = _shell_payload_walk_uncached(text_lower, literal_single_quotes)
return [(source, list(tokens)) for source, tokens in frames]


def _shell_payload_walk_uncached(text_lower: str) -> "list[tuple[str, list[str]]]":
def _shell_payload_walk_uncached(
text_lower: str, literal_single_quotes: bool = True
) -> "list[tuple[str, list[str]]]":
"""``(source, argv)`` for *text_lower* and every nested shell payload in it.

``bash -c "kirocrew token"`` tokenizes to ``['bash', '-c', 'kirocrew token']``
Expand Down Expand Up @@ -1655,7 +1660,12 @@ class rather than one spelling of it.
from .shell_commands import redirect_hidden_payloads # the reader imports this module

nested = list(nested) + redirect_hidden_payloads(source)
for payload in nested + _substitution_bodies(_fold_line_continuations(source)):
# Single-quoted text is literal only in the caller's own command line: a
# nested or decoded payload is read quote-blind.
literal = literal_single_quotes and source == text_lower # payloads are shorter
for payload in nested + _substitution_bodies(
_fold_line_continuations(source), raw_source=literal
):
# Descend through EVERY literal payload, to any depth. Termination is
# structural, not a cap: a payload is carried inside one token of its
# parent, so it is strictly shorter than the parent's source text.
Expand Down
106 changes: 80 additions & 26 deletions src/kiro_crew/security/shell_normalizer_walk.py
Original file line number Diff line number Diff line change
Expand Up @@ -244,33 +244,87 @@ def _ends_argv(token: str) -> bool:
return "|" in token or ";" in token


def _substitution_bodies(text: str) -> "list[str]":
"""The body of each command substitution in *text*.

``$(...)`` is scanned with paren nesting so a nested substitution closing
first does not truncate the outer body; backticks are taken pairwise. Only
the BODY is returned -- a bare ``kill`` must not be attributed a name that
merely appears in a LATER, unrelated command of the same line.

The nesting walk is QUOTE-AWARE, through the same
:func:`_matching_close_paren` span the git-publish boundary walk uses. A
private, quote-unaware copy of it truncates the body at a QUOTED ``)``, and
that loses the nested command entirely rather than merely mis-sizing the span:
``git push origin my-feature > >(X=')' git push origin main)`` extracts the
body ``X='``, so the nested publish of a protected branch is never scanned
and ``is_denied`` returns None for a command bash executes. An UNPROVEN span
yields the whole remainder, which is the fail-closed direction -- scanning
text that is not really in the body can only add findings.

Quoting was not the whole of it. That span helper counted a ``)`` that shell
COMMAND GRAMMAR also puts there as an ordinary character, and two such
spellings were measured allowing a payload this module still refuses:
a ``#`` comment (``$(: # )`` closes on a later line) and a ``case`` pattern
(``$(case x in x) printf token;; esac)``). Both truncated the body before the
verb, so the value assembled from it was never recognised. The closer for the
BACKTICK form reads the same state machine now too, so the two spellings
cannot disagree.
_SUBSTITUTION_OPENERS = ("<(", ">(", "$(", "`")


def _only_single_quoted_openers(text: str) -> bool:
"""True when every quote in *text* closes and every substitution opener in it sits
inside single quotes (``'...'`` or ``$'...'``), so bash opens no substitution."""
state = 0
for step in _iter_shell_chars(text):
state = step.state
if step.state == 1: # inside '...' or $'...', the opening quote included
continue
for at in range(step.offset, step.offset + len(step.text)):
if text.startswith(_SUBSTITUTION_OPENERS, at):
return False
return state == 0


#: The message flags whose single-quoted value the program stores as text and never
#: runs, per ``(first word, subcommand words)``.
_MESSAGE_FLAGS: "dict[tuple[str, ...], tuple[str, ...]]" = {
("git", "commit"): ("-m", "--message"),
("git", "tag"): ("-m", "--message"),
**{
("gh", group, verb): ("-b", "--body", "-t", "--title")
for group in ("pr", "issue")
for verb in ("create", "edit", "comment")
},
}


def _is_message_flag_command(text: str) -> bool:
"""True when *text* is ONE simple ``git commit|tag`` or ``gh pr|issue
create|edit|comment`` command, its first word literally ``git``/``gh`` with no
global option before the subcommand, and every word holding a substitution
opener is the value of a message flag (``-m V``, ``-mV``, ``--message V``,
``--message=V``; ``--body``/``-b``/``--title``/``-t`` for gh), with that value
exactly one bare single-quoted word."""
if any(step.active and step.char in ";&|(){}\n" for step in _iter_shell_chars(text)):
return False
words = _split_shell_words(text)
flags = _MESSAGE_FLAGS.get(tuple(words[:2])) or _MESSAGE_FLAGS.get(tuple(words[:3]))
if flags is None:
return False
i = 3 if words[0] == "gh" else 2
while i < len(words):
word = words[i]
if word in flags:
i += 1 # the next word is the flag's value
word = words[i] if i < len(words) else ""
else:
for flag in flags:
prefix = flag + "=" if flag.startswith("--") else flag
if word.startswith(prefix):
word = word[len(prefix) :]
break
else:
if any(opener in word for opener in _SUBSTITUTION_OPENERS):
return False
if any(opener in word for opener in _SUBSTITUTION_OPENERS) and not (
word.startswith("'") and word.endswith("'") and word.count("'") == 2
):
return False
i += 1
return True


def _substitution_bodies(text: str, *, raw_source: bool = False) -> "list[str]":
"""Return substitution bodies, not the unrelated commands after their closers.

Shared closers track quotes, nesting, comments and case arms; an unproven span
yields the whole remainder. In *raw_source*, a message-flag command
(:func:`_is_message_flag_command`) whose every opener sits inside single quotes
has no bodies, as in bash. That holds only for text with no ``$`` anywhere,
no ``#``, ``<<``, backslash or control byte (a newline, or a sentinel a caller
masked in) and whose every quote closes. Any other text, including text with a
live opener anywhere, gets the quote-blind openers for the whole text.
"""
if raw_source and not any(m in text for m in ("#", "<<", "$", "\\")):
if not any(ch < " " for ch in text) and _only_single_quoted_openers(text):
if _is_message_flag_command(text):
return []
bodies: list[str] = []
i = 0
while i < len(text):
Expand Down
8 changes: 8 additions & 0 deletions test/security_line_budget/ssh-self-quoted-message-flags.txt
Original file line number Diff line number Diff line change
@@ -0,0 +1,8 @@
+79
The payload walk reads the caller's own command line with single quotes as literal
when it is one simple `git commit|tag -m` or `gh pr|issue create|edit|comment
--body|--title` command whose every substitution opener sits inside one bare
single-quoted message value (`_only_single_quoted_openers`,
`_is_message_flag_command`), so `gh pr edit 1 --body 'run `ssh x`'` opens no nested
command. Text with a live opener, a `$`, `#`, `<<`, a backslash, a control byte or an
unclosed quote keeps the quote-blind reading.
1 change: 1 addition & 0 deletions test/test_argv_rules.py
Original file line number Diff line number Diff line change
Expand Up @@ -138,6 +138,7 @@ def test_ssh_batchmode_is_not_refused(monkeypatch):
f"echo $({_CM} 600 /etc/shadow)",
f"cat <({_CM} 600 /etc/shadow)",
f"echo `{_CM} 600 /etc/shadow`",
f'echo "`{_CM} 600 /etc/shadow`"',
f"echo \"$(bash -c '{_CM} 600 /etc/shadow')\"",
f"sh <<EOF\n{_CM} 600 /etc/shadow\nEOF",
f"echo '{_CM} 600 /etc/shadow' | bash",
Expand Down
Loading
Loading