Python
fix(permissions): the read-only checker allows only reviewed flags (OPE-232)
Devika Verma6f2ef8bef01f
diff --git a/coworker/readonly.py b/coworker/readonly.pyindex 3f84d2fa..155e6b42 100644--- a/coworker/readonly.py+++ b/coworker/readonly.py@@ -6,18 +6,26 @@ when THIS classifier accepts it. The contract:- **Local filesystem reads only.** Network clients (curl/wget/ssh/nc) are deliberatelyexcluded even for GET — an auto-allowed network command is an exfiltration channel- under prompt injection. Interpreters (python/ruby/sh -c) and anything that can write,- execute, or mutate are excluded.+ under prompt injection. Interpreters (python/ruby/sh -c), pagers, and anything that can+ write, execute, or mutate are excluded.+- **Allowlisted flags** (OPE-232). Every accepted command lists the flags known only to+ change what is shown or which local files are read. Any other flag, including one+ nobody has reviewed, makes the command not read-only. The same holds for each git+ subcommand and each PowerShell cmdlet. sed, awk and jq programs are accepted only in a+ conservative subset.- **Pipelines are allowed** (`nl … | sed -n … | grep …`) — every stage must classify.- All other shell operators (;, &&, ||, &, redirections, substitutions) are rejected- outright.+ All other shell operators (;, &&, ||, &, redirections, substitutions, subshells,+ brace expansion) are rejected outright.- **Shell-aware** (OPE-232). The caller says which shell runs the command: `bash` (macOS,Linux) or `powershell` (Windows). For PowerShell only a plain command with literal- arguments is eligible; anything that can evaluate code or expand values rejects.+ arguments is eligible, and only the cmdlets listed below.- **One line.** A command spanning lines is several commands: rejected.- **Fail closed.** Unknown commands, unparseable input, path-invoked binaries, and any- doubtful flag reject. False negatives cost one manual approval; false positives cost- an unreviewed side effect — the asymmetry decides every edge case here.+ flag not on a list reject. False negatives cost one manual approval; false positives+ cost an unreviewed side effect — the asymmetry decides every edge case here.++The same parse that accepts a command names the files it reads (`read_targets`), so every+path an allowed flag carries is held to the session's folders.This is a user-elected convenience on top of the approval flow, not a sandbox: thesession still runs under its permission mode, and the user granted the scope explicitly.@@ -27,49 +35,8 @@ from __future__ import annotationsimport reimport shlex--# Commands that only read local state, with no writing flags to police. Several entries-# are not unconditionally read-only — see _FLAG_BAD below, which polices the flags that-# turn a listed command into a writer or an executor.-_SIMPLE_SAFE = {- "ls", "cat", "head", "tail", "wc", "nl", "sort", "uniq", "cut", "tr",- "grep", "egrep", "fgrep", "rg", "ugrep", "file", "stat", "du", "df",- "pwd", "echo", "printf", "which", "whoami", "id", "date", "uname",- "basename", "dirname", "realpath", "readlink", "jq", "column", "diff",- "comm", "strings", "md5sum", "shasum", "sha1sum", "sha256sum",- "hexdump", "xxd", "od", "true", "false", "yamllint", "actionlint",-}--# Git subcommands that only read. Note the per-subcommand guards below — several git-# "read" commands grow write/exec behavior through specific flags.-_GIT_SAFE = {- "status", "log", "show", "diff", "blame", "shortlog", "describe",- "rev-parse", "rev-list", "ls-files", "ls-tree", "grep", "cat-file",- "name-rev", "merge-base", "count-objects", "var", "check-ignore",-}--_GIT_BRANCH_FLAG_OK = {- "--show-current", "--list", "-a", "-r", "-v", "-vv", "--contains",- "--merged", "--no-merged", "--all",-}--_FIND_BAD = ("-delete", "-exec", "-execdir", "-ok", "-okdir", "-fprint", "-fls", "-fprintf")--# Several _SIMPLE_SAFE entries are not unconditionally read-only: one flag turns the-# command into a writer or an executor. The find family taught this lesson first-# (_FIND_BAD); the same policing now applies to every other command that grows-# write/exec behavior through a flag. Values are denied flags; a token matches when it-# equals the flag, carries an attached value (`-oout.txt`, `--output=out`), or — for-# short flags — hides inside a cluster (`sort -ro out`).-_FLAG_BAD: dict[str, tuple[str, ...]] = {- "sort": ("-o", "--output", "--compress-program", "--files0-from"),- "xxd": ("-r",), # reverse mode writes the decoded bytes to the `outfile` argument- "date": ("-s", "--set"), # sets the system clock- "file": ("-C", "--compile"), # compiles the magic database to magic.mgc- "rg": ("--pre", "--pre-glob", "--hostname-bin", "--pager"),- "ugrep": ("--pager",),- "du": ("--files0-from",),-}+from dataclasses import dataclass+from typing import Callable, Optional_ENV_ASSIGN = re.compile(r"^[A-Za-z_][A-Za-z0-9_]*=[^;&|<>`]*$")# Environment prefixes that only change formatting (locale, time zone, colour, width).@@ -85,35 +52,47 @@ SHELLS = ("bash", "powershell")# arguments, escapes, call / redirection / sequence operators. Fail closed on any of them._POWERSHELL_UNSAFE = frozenset("$`(){}[]@,;&<>")-# A sed script token that invokes the `w`/`W` (write-file) command. Two spellings:-# * at the start of a script command, optionally after an address —-# `w file`, `1,5w file`, `1wout.txt`, and after `;`/`{` in a multi-command script;-# * as a substitution flag, after the third delimiter — `s/a/b/w file`,-# `s/a/b/wout.txt`. Backreference-based so only a completed `s<d>pat<d>repl<d>` shape-# is considered, which keeps a pattern or replacement merely *starting* with `w`-# (`s/wide/X/`) out of the denials. Conservative either way: a false hit costs one-# manual approval.-_SED_WRITE = re.compile(r"(^|[;{])[0-9,$/ ]*[wW]|s(.).*?\2.*?\2.*?[wW]")-# awk programs can execute commands through pipe-redirection (`print x | "sh"`,-# `"cmd" | getline`) without containing `>` or `system(`.-_AWK_PIPE = re.compile(r"\|\s*getline|\|\s*[\"']")+# -- tokenizing -----------------------------------------------------------------------------++def _has_unquoted_expansion(command: str) -> bool:+ """A variable, subshell or brace expansion bash would apply before the command runs.-def _has_unquoted_shell_variable(command: str) -> bool:+ Single-quoted text is literal; `$` inside double quotes still expands. Brace expansion+ (`{a,b}`, `{1..3}`) turns one written word into several operands, so it rejects;+ braces without a comma or `..` (`stash@{0}`) are literal and pass.+ """quote: str | None = Noneescaped = False+ brace = 0+ prev = ""for char in command:if escaped:escaped = False- elif char == "\\" and quote != "'":+ prev = ""+ continue+ if char == "\\" and quote != "'":escaped = True- elif char == "'" and quote != '"':+ continue+ if char == "'" and quote != '"':quote = None if quote == "'" else "'"elif char == '"' and quote != "'":quote = None if quote == '"' else '"'elif char == "$" and quote != "'":return True+ elif quote is None:+ if char in "()":+ return True+ if char == "{":+ brace += 1+ elif char == "}":+ brace = max(0, brace - 1)+ elif char in " \t":+ brace = 0+ elif brace and (char == "," or (char == "." and prev == ".")):+ return True+ prev = char if quote is None else ""return False@@ -123,11 +102,11 @@ def _stages(command: str) -> list[list[str]] | None:return Noneif any(ord(c) < 32 and c != "\t" for c in command):return None # a line break starts another command; other controls are never needed- # Shell variables are expanded after this check; single-quoted '$' is literal.- if _has_unquoted_shell_variable(command) or "$(" in command or "`" in command or "<(" in command or ">(" in command:+ if _has_unquoted_expansion(command) or "$(" in command or "`" in command or "<(" in command or ">(" in command:return Nonelex = shlex.shlex(command, posix=True, punctuation_chars=True)lex.whitespace_split = True+ lex.commenters = "" # a `#` inside a word is part of the word, as the shell reads ittry:tokens = list(lex)except ValueError:@@ -145,133 +124,1204 @@ def _stages(command: str) -> list[list[str]] | None:return stages-def _git_ok(args: list[str]) -> bool:- # Global flags: only `-C <dir>` and `--no-pager` pass; `-c`/`--config-env` can set- # core.pager and similar exec hooks — rejected.+# -- the flag model -------------------------------------------------------------------------+# A flag either takes no value, takes one (attached: `-n5`, `--lines=5`; or the next+# token), or takes an optional value that must be attached (`--color`, `--color=never`).+# Value kinds: "num" must look like a count; "path" names a file the command reads and is+# returned as a read target; "text" is anything else (a pattern, a format, a field list).+#+# Where GNU and BSD disagree on whether a short flag takes a value, it is listed as taking+# none: the token after it then counts as an operand, which is a read target, so the+# disagreement can only add targets, never hide one.++_NUM = re.compile(r"^[+-]?[0-9]+[A-Za-z]*$")++Flags = list[tuple[str, Optional[str], Optional[str]]] # (name, value, kind)+++@dataclass(frozen=True, eq=False)+class _Spec:+ short: frozenset[str]+ short_val: dict[str, str]+ short_opt: frozenset[str]+ long: frozenset[str]+ long_val: dict[str, tuple[str, ...]]+ long_opt: frozenset[str]+ numeric: bool # `-20` is a count (head, tail, grep context)+ operands: str # "paths", "none", or "first" (a pattern/script/program, then paths)+ max_operands: Optional[int]+ pattern_flags: frozenset[str] # with any of these, "first" has no positional pattern+ check: Optional[Callable[[Flags, list[str]], bool]]+++def _spec(+ short: str = "",+ vals: str = "",+ sopt: str = "",+ long: str = "",+ lvals: str = "",+ lopt: str = "",+ *,+ numeric: bool = False,+ operands: str = "paths",+ max_operands: Optional[int] = None,+ pattern_flags: str = "",+ check: Optional[Callable[[Flags, list[str]], bool]] = None,+ common: bool = True,+) -> _Spec:+ """Build a spec from compact strings: `vals="n:num f:path"`, `lvals="arg:text,text"`."""++ def kinds(text: str) -> dict[str, tuple[str, ...]]:+ return {k: tuple(v.split(",")) for k, v in (item.split(":") for item in text.split())}++ longs = set(long.split()) | ({"help", "version"} if common else set())+ return _Spec(+ frozenset(short),+ {k: v[0] for k, v in kinds(vals).items()},+ frozenset(sopt),+ frozenset(longs),+ kinds(lvals),+ frozenset(lopt.split()),+ numeric,+ operands,+ max_operands,+ frozenset(pattern_flags.split()),+ check,+ )+++def _merge(base: _Spec, **extra: str) -> _Spec:+ """`base` plus more flags (same keyword strings as `_spec`); `drop` removes short flags+ of `base` first."""+ add = _spec(common=False, **{k: v for k, v in extra.items() if k != "drop"})+ drop = set(extra.get("drop", ""))+ return _Spec(+ (base.short - drop) | add.short,+ {**{k: v for k, v in base.short_val.items() if k not in drop}, **add.short_val},+ base.short_opt | add.short_opt,+ base.long | add.long,+ {**base.long_val, **add.long_val},+ base.long_opt | add.long_opt,+ base.numeric,+ base.operands,+ base.max_operands,+ base.pattern_flags,+ base.check,+ )+++def _value_ok(kind: str, value: str) -> bool:+ return kind != "num" or bool(_NUM.match(value))+++def _parse(spec: _Spec, args: list[str]) -> tuple[Flags, list[str]] | None:+ """Split `args` into flags and operands under `spec`. None = a flag is not allowed.++ Long flags must be spelled out: an abbreviation (`--out` for `--output`) is not on any+ list, so it rejects. A short-flag cluster (`-rn`, `-n5`) is read the way getopt reads+ it: letters until one that takes a value, which takes the rest of the token.+ """+ flags: Flags = []+ operands: list[str] = []i = 0while i < len(args):- if args[i] == "-C" and i + 1 < len(args):+ tok = args[i]+ i += 1+ if tok == "--":+ operands.extend(args[i:])+ break+ if not tok.startswith("-") or tok == "-":+ operands.append(tok)+ continue+ if tok.startswith("--"):+ name, eq, value = tok[2:].partition("=")+ if name in spec.long and not eq:+ flags.append((name, None, None))+ continue+ if name in spec.long_opt:+ flags.append((name, value if eq else None, "text"))+ continue+ kinds = spec.long_val.get(name)+ if kinds is None or (eq and len(kinds) > 1):+ return None+ values = [value] if eq else []+ while len(values) < len(kinds):+ if i >= len(args):+ break+ values.append(args[i])+ i += 1+ if len(values) < len(kinds):+ if kinds != ("commit",): # git's `--contains` may end the command bare+ return None+ flags.append((name, None, None))+ continue+ for kind, v in zip(kinds, values):+ if not _value_ok(kind, v):+ return None+ flags.append((name, v, kind))+ continue+ body = tok[1:]+ if spec.numeric and body.isdigit():+ flags.append(("", body, "num"))+ continue+ j = 0+ while j < len(body):+ c = body[j]+ j += 1+ if c in spec.short:+ flags.append((c, None, None))+ continue+ if c in spec.short_opt:+ flags.append((c, body[j:] or None, "text"))+ break+ kind = spec.short_val.get(c)+ if kind is None:+ return None+ value = body[j:]+ if not value:+ if i >= len(args):+ return None+ value = args[i]+ i += 1+ if not _value_ok(kind, value):+ return None+ flags.append((c, value, kind))+ break+ return flags, operands+++def _has(flags: Flags, *names: str) -> bool:+ return any(name in names for name, _, _ in flags)+++def _apply(spec: _Spec, args: list[str]) -> list[str] | None:+ """Read targets of a command under `spec`, or None when it is not read-only."""+ parsed = _parse(spec, args)+ if parsed is None:+ return None+ flags, operands = parsed+ if spec.max_operands is not None and len(operands) > spec.max_operands:+ return None+ if spec.check is not None and not spec.check(flags, operands):+ return None+ targets = [v for _, v, kind in flags if kind == "path" and v is not None]+ if spec.operands == "none":+ return targets+ if spec.operands == "first" and not _has(flags, *spec.pattern_flags):+ operands = operands[1:]+ return targets + operands+++# -- sed, awk and jq programs ----------------------------------------------------------------+# sed: addresses (line, `$`, `/regex/`, ranges, `first~step`, `addr,+N`), `!`, `{ }`, and+# the commands that only print, delete, quit or edit the pattern space: p d q Q = l P D n N+# g G h H x z F, `s///` with the flags g p i I m M and a number, and `y///`. Commands+# that read or write files, run programs, branch, or take free text (a i c) are not in it.++_SED_SIMPLE = frozenset("pdqQ=lPDnNgGhHxzF")+_SED_S_FLAGS = frozenset("gpiImM0123456789")+++def _sed_part(s: str, i: int, delim: str, regex: bool) -> int:+ """Index just past the closing `delim`, or -1. A bracket expression holding the+ delimiter is read differently by GNU and BSD sed, so it rejects."""+ n = len(s)+ while i < n:+ c = s[i]+ if c == "\\":i += 2continue- if args[i] == "--no-pager":+ if c == delim:+ return i + 1+ if regex and c == "[":+ j = i + 1+ if j < n and s[j] == "^":+ j += 1+ if j < n and s[j] == "]":+ j += 1+ while j < n and s[j] != "]":+ if s[j] == delim:+ return -1+ if s[j] == "[" and j + 1 < n and s[j + 1] in ":.=":+ end = s.find(s[j + 1] + "]", j + 2)+ if end < 0:+ return -1+ j = end + 2+ continue+ j += 1+ if j >= n:+ return -1+ i = j + 1+ continue+ i += 1+ return -1+++def _sed_address(s: str, i: int, second: bool = False) -> int:+ """Index past one address at `i` (`i` itself when there is none), or -1."""+ n = len(s)+ if i >= n:+ return i+ c = s[i]+ if second and c in "+~":+ j = i + 1+ while j < n and s[j].isdigit():+ j += 1+ return j if j > i + 1 else -1+ if c.isdigit():+ while i < n and s[i].isdigit():+ i += 1+ if i < n and s[i] == "~":+ j = i + 1+ while j < n and s[j].isdigit():+ j += 1+ return j if j > i + 1 else -1+ return i+ if c == "$":+ return i + 1+ if c == "/" or (c == "\\" and i + 1 < n and s[i + 1] not in "\\\n"):+ delim = "/" if c == "/" else s[i + 1]+ i = _sed_part(s, i + (1 if c == "/" else 2), delim, regex=True)+ if i < 0:+ return -1+ while i < n and s[i] in "IM":+ i += 1+ return i+ return i+++def _sed_script_ok(script: str) -> bool:+ s, n, i, depth = script, len(script), 0, 0+ while True:+ while i < n and s[i] in " \t;":i += 1+ if i >= n:+ return depth == 0+ start = i+ i = _sed_address(s, i)+ if i < 0:+ return False+ if i > start:+ while i < n and s[i] in " \t":+ i += 1+ if i < n and s[i] == ",":+ j = i + 1+ while j < n and s[j] in " \t":+ j += 1+ i = _sed_address(s, j, second=True)+ if i <= j:+ return False+ while i < n and s[i] in " \t":+ i += 1+ if i < n and s[i] == "!":+ i += 1+ while i < n and s[i] in " \t":+ i += 1+ if i >= n:+ return False # an address with no command+ c = s[i]+ i += 1+ if c == "{":+ depth += 1continue- break- if i >= len(args):+ if c == "}":+ depth -= 1+ if depth < 0 or i - 1 > start:+ return False+ elif c in "sy":+ if i >= n or s[i] in "\\\n":+ return False+ delim = s[i]+ i = _sed_part(s, i + 1, delim, regex=(c == "s"))+ if i < 0:+ return False+ i = _sed_part(s, i, delim, regex=False)+ if i < 0:+ return False+ if c == "s":+ while i < n and s[i] in _SED_S_FLAGS:+ i += 1+ elif c in _SED_SIMPLE:+ if c in "qQl":+ while i < n and (s[i].isdigit() or s[i] in " \t"):+ i += 1+ else:+ return False+ while i < n and s[i] in " \t":+ i += 1+ if i < n and s[i] not in ";}":+ return False+++def _sed_check(flags: Flags, operands: list[str]) -> bool:+ scripts = [v for name, v, _ in flags if name in ("e", "expression") and v is not None]+ if not scripts:+ scripts = operands[:1]+ return bool(scripts) and all(_sed_script_ok(t) for t in scripts)+++# awk: any program that prints, matches and computes. Rejected: output redirection and+# pipes (`>`, `>>`, `|`, `|&` — a `>` after a print statement starts is read as one),+# `getline`, `system`, the environment and process tables, rewriting ARGV/ARGC (which+# picks the files read), and gawk's `@` directives and indirect calls.+_AWK_BANNED = re.compile(r"\b(system|getline|ENVIRON|PROCINFO|ARGV|ARGC)\b|@")+++def _awk_program_ok(program: str) -> bool:+ if _AWK_BANNED.search(program):return False- sub, rest = args[i], args[i + 1 :]- if any(t.startswith("--output") for t in rest):- return False # git log/diff --output=<file> writes- if sub == "grep" and any(_flag_denied(t, ("-O", "--open-files-in-pager")) for t in rest):- return False # git grep -O<pager> executes the given program- if sub in _GIT_SAFE:- return True- if sub == "branch":- return all(t in _GIT_BRANCH_FLAG_OK or t.startswith(("--format=", "--sort=")) for t in rest)- if sub == "tag":- return bool(rest) and all(- t in {"-l", "--list", "-n", "--contains", "--merged"} or t.startswith("-n") for t in rest- )- if sub == "stash":- return bool(rest) and rest[0] in {"list", "show"}- if sub == "remote":- return not rest or rest[0] in {"-v", "show", "get-url"}- if sub == "config":- return any(t in {"--get", "--get-all", "--get-regexp", "--list", "-l"} for t in rest)- if sub == "reflog":- return not rest or rest[0] == "show"- return False+ if "|" in program.replace("||", ""):+ return False+ first_print = re.search(r"\bprint", program)+ return not (first_print and re.search(r">(?!=)", program[first_print.start():]))+++def _awk_check(_flags: Flags, operands: list[str]) -> bool:+ return bool(operands) and _awk_program_ok(operands[0])+++# jq filters cannot write or run anything; what is left out is reading modules from the+# library path and reading the environment.+_JQ_BANNED = re.compile(r"\b(import|include|env|ENV|modulemeta|get_search_list|get_prog_origin|get_jq_origin)\b")+++def _jq_check(_flags: Flags, operands: list[str]) -> bool:+ return not (operands and _JQ_BANNED.search(operands[0]))+++def _date_check(_flags: Flags, operands: list[str]) -> bool:+ return all(o.startswith("+") for o in operands) # any other operand sets the clock+++def _strings_check(_flags: Flags, operands: list[str]) -> bool:+ return not any(o.startswith("@") for o in operands) # `@file` is read as more options+++def _diff_check(flags: Flags, _operands: list[str]) -> bool:+ # A recursive diff follows symbolic links it meets inside the folders unless told not+ # to; the targets check only sees the operands named here.+ return not _has(flags, "r", "recursive") or _has(flags, "no-dereference")+++def _command_check(flags: Flags, _operands: list[str]) -> bool:+ return _has(flags, "v", "V") # only the lookup; `command NAME` runs NAME+++# -- the commands ----------------------------------------------------------------------------++_GREP = _spec(+ "EFGPiyvwxcLloqsbHhnTZzaIrU",+ "e:text f:path m:num A:num B:num C:num d:text D:text",+ long="extended-regexp fixed-strings basic-regexp perl-regexp ignore-case no-ignore-case "+ "invert-match word-regexp line-regexp count files-with-matches files-without-match "+ "only-matching quiet silent no-messages byte-offset with-filename no-filename "+ "line-number initial-tab null null-data text recursive line-buffered",+ lvals="regexp:text file:path max-count:num after-context:num before-context:num "+ "context:num label:text binary-files:text devices:text directories:text exclude:text "+ "exclude-dir:text include:text exclude-from:path",+ lopt="color colour",+ numeric=True,+ operands="first",+ pattern_flags="e f regexp file",+)++_SHA = _spec("btz", long="binary text zero tag")++_SPECS: dict[str, _Spec] = {+ "ls": _spec(+ "aAbBcCdDfFgGhHiIklmnNopqQrRsStTuUvwxXZ1eOP@",+ long="all almost-all author escape ignore-backups directory dired file-type full-time "+ "group-directories-first no-group human-readable si dereference-command-line "+ "dereference-command-line-symlink-to-dir inode kibibytes literal numeric-uid-gid "+ "hide-control-chars show-control-chars quote-name recursive reverse size context zero",+ lvals="block-size:text format:text hide:text indicator-style:text ignore:text "+ "quoting-style:text sort:text time:text time-style:text tabsize:num width:num",+ lopt="color classify hyperlink",+ ),+ "cat": _spec(+ "AbeEnstTuv",+ long="show-all number-nonblank show-ends number squeeze-blank show-tabs show-nonprinting",+ ),+ "head": _spec(+ "qvz", "n:num c:num",+ long="quiet silent verbose zero-terminated", lvals="lines:num bytes:num", numeric=True,+ ),+ "tail": _spec(+ "qvzr", "n:num c:num",+ long="quiet silent verbose zero-terminated", lvals="lines:num bytes:num", numeric=True,+ ),+ "wc": _spec("cmlLw", long="bytes chars lines max-line-length words", lvals="total:text"),+ "nl": _spec(+ "p", "b:text d:text f:text h:text i:num l:num n:text s:text v:num w:num",+ long="no-renumber",+ lvals="body-numbering:text section-delimiter:text footer-numbering:text "+ "header-numbering:text line-increment:num join-blank-lines:num number-format:text "+ "number-separator:text starting-line-number:num number-width:num",+ ),+ "sort": _spec(+ "bdfgihMnRrVcCmsuz", "k:text t:text S:text",+ long="ignore-leading-blanks dictionary-order ignore-case general-numeric-sort "+ "ignore-nonprinting month-sort human-numeric-sort numeric-sort random-sort reverse "+ "version-sort merge stable unique zero-terminated debug",+ lvals="key:text field-separator:text buffer-size:text parallel:num sort:text batch-size:num",+ lopt="check",+ ),+ "uniq": _spec(+ "cdDiuz", "f:num s:num w:num",+ long="count repeated ignore-case unique zero-terminated",+ lvals="skip-fields:num skip-chars:num check-chars:num",+ lopt="all-repeated group",+ max_operands=1, # a second operand is the output file+ ),+ "cut": _spec(+ "nsz", "b:text c:text d:text f:text",+ long="complement only-delimited zero-terminated",+ lvals="bytes:text characters:text delimiter:text fields:text output-delimiter:text",+ ),+ "tr": _spec(+ "cCdst", long="complement delete squeeze-repeats truncate-set1",+ operands="none", max_operands=2,+ ),+ "grep": _GREP,+ "egrep": _GREP,+ "fgrep": _GREP,+ "ugrep": _GREP,+ "rg": _spec(+ "acFHhiIlnNopqsSuUvwxbPV0",+ "A:num B:num C:num e:text f:path g:text m:num M:num r:text t:text T:text d:num E:text j:num",+ long="text count count-matches column files files-with-matches files-without-match "+ "fixed-strings hidden ignore-case invert-match json line-number no-line-number "+ "no-filename with-filename no-heading heading no-ignore no-ignore-vcs no-ignore-dot "+ "no-ignore-parent no-ignore-global no-ignore-exclude no-ignore-files no-messages "+ "only-matching pretty quiet case-sensitive smart-case stats type-list unrestricted "+ "multiline multiline-dotall word-regexp line-regexp null trim byte-offset pcre2 "+ "vimgrep no-config passthru crlf null-data one-file-system glob-case-insensitive "+ "line-buffered block-buffered no-unicode binary include-zero max-columns-preview "+ "sort-files no-require-git no-follow no-search-zip",+ lvals="after-context:num before-context:num context:num regexp:text file:path "+ "glob:text iglob:text max-count:num max-columns:num replace:text type:text "+ "type-not:text max-depth:num maxdepth:num encoding:text threads:num "+ "max-filesize:text ignore-file:path sort:text sortr:text type-add:text "+ "type-clear:text color:text colors:text context-separator:text "+ "field-match-separator:text field-context-separator:text path-separator:text "+ "engine:text",+ operands="first",+ pattern_flags="e f regexp file files type-list",+ ),+ "file": _spec(+ "bihLkrNnsE0", "F:text e:text P:text",+ long="brief mime mime-type mime-encoding dereference no-dereference keep-going raw "+ "no-pad no-buffer special-files print0 extension apple",+ lvals="separator:text exclude:text exclude-quiet:text parameter:text",+ ),+ "stat": _spec(+ "LftFnqrsxl", "c:text",+ long="dereference file-system terse", lvals="format:text printf:text cached:text",+ ),+ "du": _spec(+ "abcDHhklmPSsx0", "d:num B:text t:text X:path",+ long="all apparent-size bytes total dereference-args human-readable inodes count-links "+ "no-dereference null separate-dirs si summarize one-file-system",+ lvals="block-size:text max-depth:num threshold:text exclude:text exclude-from:path "+ "time-style:text",+ lopt="time",+ ),+ "df": _spec(+ "ahHiklPTt", "x:text B:text",+ long="all human-readable si inodes local portability print-type total no-sync",+ lvals="block-size:text type:text exclude-type:text", lopt="output",+ ),+ "pwd": _spec("LP", operands="none", max_operands=0),+ "echo": _spec("neE", operands="none", common=False),+ "printf": _spec(operands="none", common=False),+ "which": _spec("as", operands="none"),+ "whoami": _spec(max_operands=0),+ "id": _spec("ugGnrz", long="user group groups name real zero", operands="none"),+ "date": _spec(+ "uRj", "d:text", "I",+ long="utc universal rfc-email debug", lvals="date:text rfc-3339:text", lopt="iso-8601",+ operands="none", max_operands=1, check=_date_check,+ ),+ "uname": _spec(+ "asnrvmpio",+ long="all kernel-name nodename kernel-release kernel-version machine processor "+ "hardware-platform operating-system",+ max_operands=0,+ ),+ "basename": _spec("az", "s:text", long="multiple zero", lvals="suffix:text", operands="none"),+ "dirname": _spec("z", long="zero", operands="none"),+ "realpath": _spec(+ "emLPqsz",+ long="canonicalize-existing canonicalize-missing logical physical quiet strip "+ "no-symlinks zero",+ lvals="relative-to:path relative-base:path",+ ),+ "readlink": _spec(+ "femnqsvz",+ long="canonicalize canonicalize-existing canonicalize-missing no-newline quiet silent "+ "verbose zero",+ ),+ "true": _spec(max_operands=0, common=False),+ "false": _spec(max_operands=0, common=False),+ "env": _spec("0", long="null", max_operands=0), # bare `env` prints; operands run things+ "command": _spec("vVp", operands="none", check=_command_check, common=False),+ "column": _spec("tx", "c:num s:text o:text"),+ "diff": _spec(+ "abBcdeEfhHiNnpPqrsStTuwyZ",+ "U:num C:num W:num F:text I:text x:text X:path S:text L:text D:text",+ long="normal brief report-identical-files recursive new-file unidirectional-new-file "+ "text ignore-space-change ignore-all-space ignore-blank-lines ignore-case "+ "ignore-tab-expansion ignore-trailing-space strip-trailing-cr side-by-side "+ "left-column suppress-common-lines show-c-function expand-tabs initial-tab minimal "+ "speed-large-files no-dereference suppress-blank-empty ignore-file-name-case "+ "no-ignore-file-name-case ed rcs",+ lvals="width:num show-function-line:text label:text exclude:text exclude-from:path "+ "ignore-matching-lines:text starting-file:text from-file:path to-file:path "+ "tabsize:num ifdef:text horizon-lines:num line-format:text old-line-format:text "+ "new-line-format:text unchanged-line-format:text old-group-format:text "+ "new-group-format:text changed-group-format:text unchanged-group-format:text "+ "palette:text",+ lopt="unified context color",+ check=_diff_check,+ ),+ "comm": _spec(+ "123iz", long="check-order nocheck-order zero-terminated total",+ lvals="output-delimiter:text", max_operands=2,+ ),+ "strings": _spec(+ "afdow", "n:num t:text e:text s:text T:text",+ long="all print-file-name data include-all-whitespace",+ lvals="bytes:num radix:text encoding:text output-separator:text target:text unicode:text",+ numeric=True, check=_strings_check,+ ),+ "md5sum": _SHA,+ "sha1sum": _SHA,+ "sha224sum": _SHA,+ "sha256sum": _SHA,+ "sha384sum": _SHA,+ "sha512sum": _SHA,+ "b2sum": _merge(_SHA, vals="l:num", lvals="length:num"),+ "shasum": _spec("btU0", "a:text", long="binary text UNIVERSAL 01 tag", lvals="algorithm:text"),+ "cksum": _spec("", "a:text l:num o:text", long="base64 raw tag untagged", lvals="algorithm:text length:num"),+ "sum": _spec("rs", long="sysv"),+ "hexdump": _spec("bcCdoxv", "e:text n:num s:text"),+ "od": _spec(+ "abcdfilosxvDeFHILOXh", "A:text j:text N:text S:text t:text", "w",+ long="output-duplicates traditional",+ lvals="address-radix:text skip-bytes:text read-bytes:text format:text endian:text",+ lopt="strings width",+ ),+ "jq": _spec(+ "rjacnesSCMRhV",+ long="raw-output join-output ascii-output compact-output null-input exit-status slurp "+ "sort-keys color-output monochrome-output raw-input tab seq stream stream-errors "+ "raw-output0 unbuffered args jsonargs",+ lvals="indent:num arg:text,text argjson:text,text slurpfile:text,path rawfile:text,path",+ operands="first", check=_jq_check,+ ),+ "sed": _spec(+ "nErsuz", "e:text l:num",+ long="quiet silent regexp-extended separate unbuffered null-data posix debug sandbox",+ lvals="expression:text line-length:num",+ operands="first", pattern_flags="e expression", check=_sed_check,+ ),+ "yamllint": _spec(+ "s", "c:path d:text f:text",+ long="strict no-warnings list-files",+ lvals="config-file:path config-data:text format:text",+ ),+ # Added in OPE-232: common read-only tools, each with its own flag list.+ "tree": _spec(+ "adfxpsugDFqNQCAJXvtcUrnihS", "L:num P:text I:text H:text T:text",+ long="noreport prune matchdirs gitignore ignore-case dirsfirst filesfirst du si inodes "+ "device nolinks",+ lvals="charset:text filelimit:num timefmt:text sort:text",+ ),+ "cmp": _spec(+ "blsx", "i:text n:text",+ long="print-bytes verbose quiet silent", lvals="ignore-initial:text bytes:text",+ max_operands=4,+ ),+ "tac": _spec("br", "s:text", long="before regex", lvals="separator:text"),+ "rev": _spec(),+ "fold": _spec("bs", "w:num", long="bytes spaces", lvals="width:num"),+ "paste": _spec("sz", "d:text", long="serial zero-terminated", lvals="delimiters:text"),+ "join": _spec(+ "iz", "a:text e:text j:text o:text t:text v:text 1:text 2:text",+ long="ignore-case check-order nocheck-order header zero-terminated", max_operands=2,+ ),+ "expand": _spec("i", "t:text", long="initial", lvals="tabs:text"),+ "unexpand": _spec("a", "t:text", long="all first-only", lvals="tabs:text"),+ "seq": _spec("w", "f:text s:text t:text", long="equal-width", lvals="format:text separator:text", operands="none"),+ "nproc": _spec(long="all", lvals="ignore:num", max_operands=0),+}+for _awk in ("awk", "gawk", "mawk", "nawk"):+ _SPECS[_awk] = _spec(+ "", "F:text v:text", lvals="field-separator:text assign:text",+ operands="first", check=_awk_check,+ )+++# find(1): global options, starting points, then an expression of tests and actions. The+# allowed predicates select files or print to standard output; actions that delete, run+# programs, or write to a named file are not among them, nor are the options that follow+# symbolic links during the walk or read starting points from a file.+_FIND_GLOBAL_NO_VALUE = frozenset({"-H", "-L", "-P", "-E", "-X", "-d", "-s", "-x"})+_FIND_GLOBAL_OK = _FIND_GLOBAL_NO_VALUE - {"-L"}+_FIND_PRED0 = frozenset(+ "-print -print0 -ls -prune -quit -true -false -empty -readable -writable -executable "+ "-nouser -nogroup -depth -d -mount -xdev -noleaf -ignore_readdir_race "+ "-noignore_readdir_race -daystart -not -a -and -o -or -nowarn -warn ( ) ! ,".split()+)+_FIND_PRED1 = {+ **dict.fromkeys(+ "-name -iname -path -ipath -wholename -iwholename -regex -iregex -lname -ilname "+ "-regextype -type -xtype -size -perm -user -group -uid -gid -links -inum -mtime "+ "-mmin -atime -amin -ctime -cmin -used -maxdepth -mindepth -fstype -printf "+ "-context -Bmin -Btime -flags".split(),+ "text",+ ),+ **dict.fromkeys("-newer -anewer -cnewer -samefile -mnewer -Bnewer".split(), "path"),+}+_FIND_NEWER_XY = re.compile(r"^-newer[aBcm]([aBcmt])$")+++def _find_analyze(args: list[str]) -> list[str] | None:+ targets: list[str] = []+ i = 0+ while i < len(args):+ tok = args[i]+ if tok in _FIND_GLOBAL_OK or (tok.startswith("-O") and tok[2:].isdigit() and tok != "-O"):+ i += 1+ elif tok == "-D" and i + 1 < len(args):+ i += 2 # debug options, never a path+ elif tok == "-f" and i + 1 < len(args):+ targets.append(args[i + 1]) # BSD: -f names a starting point+ i += 2+ elif tok in _FIND_GLOBAL_NO_VALUE:+ return None+ else:+ break+ while i < len(args) and not args[i].startswith("-") and args[i] not in _FIND_PRED0:+ targets.append(args[i])+ i += 1+ while i < len(args):+ tok = args[i]+ i += 1+ if tok in _FIND_PRED0:+ continue+ xy = _FIND_NEWER_XY.match(tok)+ kind = ("text" if xy.group(1) == "t" else "path") if xy else _FIND_PRED1.get(tok)+ if kind is None or i >= len(args):+ return None+ if kind == "path":+ targets.append(args[i])+ i += 1+ return targets-def _flag_denied(token: str, denied: tuple[str, ...]) -> bool:- """True when `token` is one of `denied`, attaches a value, or hides in a cluster.+def _find_targets(args: list[str]) -> list[str]:+ """Starting points of `find`, with its global options skipped (for any find command,+ accepted or not).- `sort --output=out`, `sort -oout` and `sort -ro out` are all the same flag as `sort- -o out`; a plain token comparison would wave the first two through, and a prefix- check alone misses the cluster form. Long forms match `flag=` exactly (so a literal- such as `--output-delimiter` is not mistaken for `--output`); short forms match any- attached suffix, including inside a short-flag cluster.+ `find -L /etc -name shadow` reads /etc exactly like `find /etc -name shadow`, but+ treating every leading `-` token as the start of the predicates returned no targets+ for the prefixed form — so the session grant's root check passed vacuously."""- if not token.startswith("-") or token == "-" or token == "--":+ out: list[str] = []+ i = 0+ while i < len(args):+ tok = args[i]+ if tok in _FIND_GLOBAL_NO_VALUE or (tok.startswith("-O") and tok != "-O"):+ i += 1+ continue+ if tok == "-D" and i + 1 < len(args):+ i += 2 # debugopts, never a path+ continue+ if tok == "-f" and i + 1 < len(args):+ out.append(args[i + 1]) # BSD: -f names the starting point+ i += 2+ continue+ break+ # Starting points end at the first predicate (any other `-` token). With none, find+ # defaults to `.`, which is inside every session root.+ while i < len(args) and not args[i].startswith("-"):+ out.append(args[i])+ i += 1+ return out+++# xxd reads its options by their leading letters, so only these exact spellings pass. At+# most one operand: a second one is the output file.+_XXD_SWITCHES = frozenset(+ "-a -autoskip -b -bits -C -capitalize -E -EBCDIC -e -i -include -p -ps -postscript "+ "-plain -u -uppercase -d -h -help -v -version".split()+)+_XXD_VALUE = frozenset("-c -cols -g -groupsize -l -len -o -offset -s -seek -n -name".split())+_XXD_ATTACHED = re.compile(r"^-[cglo][0-9]+$|^-s[+-]?(0x)?[0-9a-fA-F]+$")+++def _xxd_analyze(args: list[str]) -> list[str] | None:+ operands: list[str] = []+ i = 0+ while i < len(args):+ tok = args[i]+ i += 1+ if tok == "--":+ operands.extend(args[i:])+ break+ if tok in _XXD_SWITCHES or _XXD_ATTACHED.match(tok):+ continue+ if tok in _XXD_VALUE:+ if i >= len(args):+ return None+ i += 1+ continue+ if tok.startswith("-") and tok != "-":+ return None+ operands.append(tok)+ return operands if len(operands) <= 1 else None+++# actionlint takes Go-style flags (`-flag`, `--flag`, `-flag=value`). The flags that pick+# an external linter program, or write a config file, are not on the list.+_ACTIONLINT_BOOL = frozenset({"oneline", "color", "no-color", "verbose", "debug", "version"})+_ACTIONLINT_VALUE = {"format": "text", "ignore": "text", "config-file": "path", "stdin-filename": "text"}+++def _actionlint_analyze(args: list[str]) -> list[str] | None:+ targets: list[str] = []+ i = 0+ while i < len(args):+ tok = args[i]+ i += 1+ if tok == "--":+ targets.extend(args[i:])+ break+ if not tok.startswith("-") or tok == "-":+ targets.append(tok)+ continue+ name, eq, value = tok.lstrip("-").partition("=")+ if name in _ACTIONLINT_BOOL:+ if eq and value not in ("true", "false"):+ return None+ continue+ kind = _ACTIONLINT_VALUE.get(name)+ if kind is None:+ return None+ if not eq:+ if i >= len(args):+ return None+ value = args[i]+ i += 1+ if kind == "path":+ targets.append(value)+ return targets+++# -- git ---------------------------------------------------------------------------------------+# Each read-only subcommand has its own flag list. Every positional operand is returned as+# a read target: most are revisions or pathspecs inside the repository, which resolve+# inside the folders, but `git diff` also compares plain files named on the command line.+# Pretty-format placeholders that verify signatures (`%G…`) run an external program, so a+# format containing them rejects; so do the flags that run diff or textconv drivers.++_GIT_GLOBAL_FLAGS = frozenset({+ "--no-pager", "-P", "--no-optional-locks", "--literal-pathspecs", "--glob-pathspecs",+ "--noglob-pathspecs", "--icase-pathspecs", "--no-replace-objects",+})+++def _git_format_check(flags: Flags, _operands: list[str]) -> bool:+ return not any(+ name in ("format", "pretty") and v is not None and "%G" in v for name, v, _ in flags+ )+++_GIT_REV = _spec(+ "pusRawzmcbtWEFPigqw", "n:num S:text G:text U:num l:num I:text", "MCBX",+ long="oneline graph no-decorate all abbrev-commit no-abbrev-commit relative-date reverse "+ "first-parent merges no-merges follow name-only name-status numstat shortstat summary "+ "patch no-patch full-diff left-right cherry-pick cherry-mark cherry boundary topo-order "+ "date-order author-date-order source parents children no-notes regexp-ignore-case "+ "extended-regexp fixed-strings perl-regexp basic-regexp all-match invert-grep "+ "ancestry-path simplify-by-decoration full-history dense sparse simplify-merges do-walk "+ "walk-reflogs expand-tabs no-expand-tabs no-color pickaxe-all pickaxe-regex no-renames "+ "ignore-all-space ignore-space-change ignore-blank-lines ignore-space-at-eol "+ "ignore-cr-at-eol function-context minimal patience histogram raw full-index binary "+ "no-prefix default-prefix cc combined-all-paths text check exit-code quiet "+ "compact-summary no-ext-diff no-textconv mailmap use-mailmap no-mailmap log-size "+ "show-linear-break clear-decorations show-pulls not cached staged merge-base no-index "+ "irreversible-delete single-worktree reflog no-relative",+ lvals="format:text date:text author:text committer:text grep:text since:text after:text "+ "until:text before:text max-count:num skip:num min-parents:num max-parents:num "+ "diff-filter:text unified:num src-prefix:text dst-prefix:text line-prefix:text "+ "stat-width:num stat-name-width:num stat-graph-width:num stat-count:num encoding:text "+ "word-diff-regex:text diff-algorithm:text decorate-refs:text decorate-refs-exclude:text "+ "exclude:text glob:text find-object:text since-as-filter:text inter-hunk-context:num "+ "anchored:text diff-merges:text ignore-matching-lines:text",+ lopt="decorate abbrev pretty stat dirstat dirstat-by-file color word-diff color-words "+ "find-renames find-copies relative no-walk branches tags remotes ignore-submodules "+ "submodule break-rewrites notes show-notes color-moved",+ numeric=True,+ check=_git_format_check,+ common=False,+)+++def _git_list_check(flags: Flags, operands: list[str]) -> bool:+ return not operands or _has(flags, "l", "list") # operands without --list create+++def _git_config_check(flags: Flags, operands: list[str]) -> bool:+ modes = [n for n, _, _ in flags if n in ("get", "get-all", "get-regexp", "get-urlmatch", "list", "l")]+ if not modes:+ if operands[:1] == ["list"]:+ return len(operands) == 1+ return operands[:1] == ["get"] and 2 <= len(operands) <= 3+ if len(modes) != 1:return False- for flag in denied:- if token == flag:- return True- if flag.startswith("--"):- if token.startswith(flag + "="):- return True- elif len(flag) == 2 and not token.startswith("--"):- # `-o` matches `-oout.txt` and any cluster containing `o` (`-ro`). False- # positives on unrelated letters are acceptable — they cost one approval.- body = token[1:]- if flag[1] in body:- return True- elif token.startswith(flag):- return True- return False+ return len(operands) == 0 if modes[0] in ("list", "l") else 1 <= len(operands) <= 2+++_GIT_SPECS: dict[str, _Spec] = {+ "log": _GIT_REV,+ "show": _GIT_REV,+ "diff": _GIT_REV,+ "rev-list": _merge(+ _GIT_REV,+ long="count objects objects-edge no-object-names left-only right-only timestamp header "+ "bisect bisect-vars bisect-all",+ lvals="max-age:text min-age:text",+ ),+ "shortlog": _merge(_GIT_REV, short="nsec", sopt="w", long="numbered summary email committer", lvals="group:text", drop="n"),+ "status": _spec(+ "sbvz", sopt="u",+ long="short branch long verbose show-stash ahead-behind no-ahead-behind renames "+ "no-renames no-column null",+ lopt="porcelain untracked-files ignored ignore-submodules column find-renames",+ common=False,+ ),+ "blame": _spec(+ "bclfnsepwt", "L:text", "MC",+ long="root show-stats reverse first-parent porcelain line-porcelain incremental "+ "score-debug show-name show-number show-email color-lines color-by-age minimal",+ lvals="date:text encoding:text ignore-rev:text", lopt="abbrev",+ common=False,+ ),+ "describe": _spec(+ long="all tags contains exact-match debug long always first-parent",+ lvals="abbrev:num candidates:num match:text exclude:text", lopt="dirty broken",+ common=False,+ ),+ "rev-parse": _spec(+ "q",+ long="verify quiet git-dir show-toplevel show-prefix show-cdup is-inside-work-tree "+ "is-inside-git-dir is-bare-repository is-shallow-repository absolute-git-dir "+ "git-common-dir symbolic symbolic-full-name all revs-only no-revs flags no-flags sq "+ "not show-object-format show-superproject-working-tree shared-index-path "+ "local-env-vars show-ref-format sq-quote",+ lvals="since:text after:text until:text before:text default:text glob:text "+ "exclude:text disambiguate:text git-path:text prefix:text",+ lopt="short abbrev-ref branches tags remotes",+ common=False,+ ),+ "ls-files": _spec(+ "cdmoiskutvfz", "x:text X:path",+ long="cached deleted modified others ignored stage unmerged killed directory "+ "no-empty-directory eol deduplicate exclude-standard error-unmatch full-name "+ "recurse-submodules debug sparse resolve-undo",+ lvals="exclude:text exclude-from:path exclude-per-directory:text with-tree:text format:text",+ lopt="abbrev",+ common=False,+ ),+ "ls-tree": _spec(+ "drtlz", long="long name-only name-status object-only full-name full-tree",+ lvals="format:text", lopt="abbrev", common=False,+ ),+ "grep": _spec(+ "aiIrwvhHEGPFnlLzocpWq", "e:text f:path m:num A:num B:num C:num",+ long="text no-textconv ignore-case recursive no-recursive word-regexp invert-match "+ "full-name extended-regexp basic-regexp perl-regexp fixed-strings line-number column "+ "files-with-matches name-only files-without-match null only-matching count no-color "+ "break heading show-function function-context and or not all-match quiet cached "+ "untracked no-index exclude-standard no-exclude-standard recurse-submodules",+ lvals="max-depth:num threads:num regexp:text file:path max-count:num "+ "after-context:num before-context:num context:num",+ lopt="color",+ numeric=True,+ common=False,+ ),+ "cat-file": _spec(+ "tsep", long="batch-all-objects buffer unordered allow-unknown-type follow-symlinks",+ lopt="batch batch-check", common=False,+ ),+ "name-rev": _spec(+ long="tags all annotate-stdin name-only no-undefined always",+ lvals="refs:text exclude:text", common=False,+ ),+ "merge-base": _spec("a", long="all octopus is-ancestor independent fork-point", common=False),+ "count-objects": _spec("vH", long="verbose human-readable", common=False),+ "var": _spec("l", common=False),+ "check-ignore": _spec("qvzn", long="quiet verbose stdin non-matching no-index", common=False),+ "branch": _spec(+ "arvli",+ long="show-current list all remotes verbose no-color no-column ignore-case omit-empty no-abbrev",+ lvals="contains:commit no-contains:commit merged:commit no-merged:commit "+ "points-at:commit format:text sort:text",+ lopt="color column abbrev",+ check=_git_list_check,+ common=False,+ ),+ "tag": _spec(+ "li", sopt="n",+ long="list ignore-case omit-empty no-column",+ lvals="contains:commit no-contains:commit merged:commit no-merged:commit "+ "points-at:commit sort:text format:text",+ lopt="color column",+ check=_git_list_check,+ common=False,+ ),+ "config": _spec(+ "lz", "f:path",+ long="get get-all get-regexp get-urlmatch list show-origin show-scope name-only null "+ "global system local worktree includes no-includes bool int bool-or-int path "+ "expiry-date all regexp",+ lvals="file:path blob:text type:text default:text url:text",+ check=_git_config_check,+ common=False,+ ),+}+_GIT_REMOTE_GET_URL = _spec(long="push all", max_operands=1, common=False)+_GIT_REMOTE_SHOW = _spec("n", check=lambda flags, _ops: _has(flags, "n"), common=False) # -n: no network+++def _git_analyze(args: list[str]) -> list[str] | None:+ # Global flags: `-C <dir>` and a few that only change how pathspecs and output read.+ # `-c`, `--config-env`, `--git-dir`, `--work-tree` and `--exec-path` are not on the list.+ targets: list[str] = []+ i = 0+ while i < len(args):+ if args[i] == "-C" and i + 1 < len(args):+ targets.append(args[i + 1])+ i += 2+ elif args[i] in _GIT_GLOBAL_FLAGS:+ i += 1+ else:+ break+ if i >= len(args):+ return None+ sub, rest = args[i], args[i + 1 :]+ if sub in ("--version", "version"):+ return targets if not rest else None+ found: list[str] | None+ if sub in _GIT_SPECS:+ found = _apply(_GIT_SPECS[sub], rest)+ elif sub == "stash":+ found = _apply(_GIT_REV, rest[1:]) if rest[:1] in (["list"], ["show"]) else None+ elif sub == "reflog":+ if rest[:1] in (["show"], ["list"]):+ rest = rest[1:]+ found = _apply(_GIT_REV, rest) if not rest or rest[0].startswith("-") or len(rest) == 1 else None+ elif sub == "remote":+ if not rest or rest in (["-v"], ["--verbose"]):+ found = []+ elif rest[0] == "get-url":+ found = _apply(_GIT_REMOTE_GET_URL, rest[1:])+ elif rest[0] == "show":+ found = _apply(_GIT_REMOTE_SHOW, rest[1:])+ else:+ found = None+ else:+ found = None+ return None if found is None else targets + found-def _stage_ok(argv: list[str]) -> bool:- # Leading VAR=value assignments (LC_ALL=C grep …): only formatting variables pass.+# -- bash stages -----------------------------------------------------------------------------+++def _strip_env(argv: list[str]) -> list[str] | None:+ """Drop leading `VAR=value` assignments; None when one is not a formatting variable."""i = 0while i < len(argv) and _ENV_ASSIGN.match(argv[i]):if argv[i].split("=", 1)[0] not in _SAFE_ENV:- return False+ return Nonei += 1- argv = argv[i:]- if not argv:- return False- head = argv[0]+ return argv[i:]+++def _bash_stage(argv: list[str]) -> list[str] | None:+ """Read targets of one pipeline stage, or None when it is not read-only."""+ stripped = _strip_env(argv)+ if not stripped:+ return None+ head, args = stripped[0], stripped[1:]if "/" in head:- return False # path-invoked binaries can be anything; bare names only- args = argv[1:]- if head in _SIMPLE_SAFE:- denied = _FLAG_BAD.get(head)- if denied and any(_flag_denied(t, denied) for t in args):- return False- if head == "xxd":- # Without -r, `xxd infile outfile` still writes the dump to outfile. Only- # reject when a second non-flag operand is present (`xxd a.txt b.txt`).- operands = [t for t in args if not t.startswith("-")]- return len(operands) < 2- return True- if head == "env":- return not args # bare `env` prints; `env CMD` executes- if head == "command":- return bool(args) and args[0] in {"-v", "-V"}+ return None # path-invoked binaries can be anything; bare names onlyif head == "git":- return _git_ok(args)- if head == "sed":- if any(_flag_denied(t, ("-i", "--in-place", "-f", "--file")) for t in args):- return False- # The script is the value of -e/--expression (separate or attached); when none is- # given, the first positional is the script and the rest are file operands.- scripts: list[str] = []- skip_next = False- for tok in args:- if skip_next:- scripts.append(tok)- skip_next = False- continue- if tok in {"-e", "--expression"}:- skip_next = True- elif tok.startswith("-e"):- scripts.append(tok[2:])- elif tok.startswith("--expression="):- scripts.append(tok.split("=", 1)[1])- if not scripts:- for tok in args:- if not tok.startswith("-"):- scripts.append(tok)- break- return not any(_SED_WRITE.search(t) for t in scripts)- if head in {"awk", "gawk", "mawk", "nawk"}:- if any(_flag_denied(t, ("-f", "--file")) for t in args):- return False- return not any(">" in t or "system" in t or _AWK_PIPE.search(t) for t in args)+ return _git_analyze(args)if head == "find":- return not any(_flag_denied(t, _FIND_BAD) for t in args)- return False+ return _find_analyze(args)+ if head == "xxd":+ return _xxd_analyze(args)+ if head == "actionlint":+ return _actionlint_analyze(args)+ spec = _SPECS.get(head)+ return _apply(spec, args) if spec is not None else None+++# -- PowerShell -------------------------------------------------------------------------------+# Only these cmdlets and aliases, with these parameters, are read-only; anything else gets+# a card (native programs other than git included). Parameter names are matched in full or+# by a listed alias, without case. Paths given to a provider other than the file system+# (`env:`, `HKLM:`, `Variable:`, `Cert:` …) are not file reads, so they reject.+++@dataclass(frozen=True, eq=False)+class _PSSpec:+ params: dict[str, Optional[str]] # name -> None (a switch) or a value kind+ aliases: dict[str, str]+ positional: tuple[str, ...]+ rest: Optional[str] = None # takes every remaining positional argument+++def _ps(params: str, positional: str = "", aliases: str = "", rest: Optional[str] = None) -> _PSSpec:+ table: dict[str, Optional[str]] = {}+ for item in params.split():+ name, _, kind = item.partition(":")+ table[name.lower()] = kind or None+ alias_map = {k.lower(): v.lower() for k, v in (a.split("=") for a in aliases.split())}+ return _PSSpec(table, alias_map, tuple(p.lower() for p in positional.split()), rest)+++_PS_PATH_ALIASES = "PSPath=LiteralPath LP=LiteralPath"+_PS_SPECS: dict[str, _PSSpec] = {+ "get-childitem": _ps(+ "Path:path LiteralPath:path Filter:text Include:text Exclude:text Recurse Depth:num "+ "Force Name File Directory Hidden ReadOnly System Attributes:text",+ "Path Filter",+ _PS_PATH_ALIASES + " s=Recurse r=Recurse ad=Directory d=Directory af=File ah=Hidden "+ "h=Hidden ar=ReadOnly as=System",+ ),+ "get-content": _ps(+ "Path:path LiteralPath:path TotalCount:num Tail:num Raw Encoding:text Delimiter:text "+ "ReadCount:num Force Filter:text Include:text Exclude:text AsByteStream",+ "Path",+ _PS_PATH_ALIASES + " First=TotalCount Head=TotalCount Last=Tail",+ ),+ "select-string": _ps(+ "Pattern:text Path:path LiteralPath:path SimpleMatch CaseSensitive Context:text "+ "AllMatches NotMatch List Quiet Raw NoEmphasis Encoding:text Include:text "+ "Exclude:text Culture:text",+ "Pattern Path",+ _PS_PATH_ALIASES,+ ),+ "measure-object": _ps(+ "Property:text Line Word Character IgnoreWhiteSpace Sum Average Maximum Minimum "+ "StandardDeviation AllStats",+ "Property",+ ),+ "get-location": _ps(""),+ "test-path": _ps(+ "Path:path LiteralPath:path PathType:text IsValid Filter:text Include:text "+ "Exclude:text NewerThan:text OlderThan:text",+ "Path",+ _PS_PATH_ALIASES + " Type=PathType",+ ),+ "resolve-path": _ps("Path:path LiteralPath:path Relative RelativeBasePath:path", "Path", _PS_PATH_ALIASES),+ "get-filehash": _ps("Path:path LiteralPath:path Algorithm:text", "Path", _PS_PATH_ALIASES),+ "sort-object": _ps("Property:text Descending Unique CaseSensitive Top:num Bottom:num Stable Culture:text", "Property"),+ "select-object": _ps(+ "Property:text ExcludeProperty:text ExpandProperty:text Unique First:num Last:num "+ "Skip:num SkipLast:num Index:num",+ "Property",+ ),+ "write-output": _ps("NoEnumerate", rest="text"),+}+_PS_ALIASES = {+ "ls": "get-childitem", "dir": "get-childitem", "gci": "get-childitem",+ "cat": "get-content", "type": "get-content", "gc": "get-content",+ "sls": "select-string", "measure": "measure-object",+ "pwd": "get-location", "gl": "get-location",+ "rvpa": "resolve-path", "sort": "sort-object", "select": "select-object",+ "echo": "write-output", "write": "write-output",+}+# Common parameters every cmdlet takes. The ones that store results in variables, and the+# error actions that stop for input, are not on the list.+_PS_COMMON = {"erroraction": "action", "ea": "action", "warningaction": "action", "wa": "action",+ "informationaction": "action", "infa": "action", "verbose": None, "vb": None,+ "debug": None, "db": None}+_PS_ACTIONS = frozenset({"silentlycontinue", "continue", "stop", "ignore"})+_PS_PROVIDER = re.compile(r"^[^/:]{2,}:|::")+++def _ps_value_ok(kind: Optional[str], value: str) -> bool:+ if kind == "num":+ return bool(re.match(r"^-?[0-9]+$", value))+ if kind == "action":+ return value.lower() in _PS_ACTIONS+ if kind == "path":+ return not _PS_PROVIDER.search(value)+ return True+++def _powershell_stage(argv: list[str]) -> list[str] | None:+ head, args = argv[0].lower(), argv[1:]+ if head == "git":+ return _git_analyze(args)+ spec = _PS_SPECS.get(_PS_ALIASES.get(head, head))+ if spec is None:+ return None+ targets: list[str] = []+ bound: set[str] = set()+ positionals: list[str] = []+ i = 0+ while i < len(args):+ tok = args[i]+ i += 1+ if tok == "--":+ positionals.extend(args[i:])+ break+ if not tok.startswith("-") or len(tok) == 1 or re.match(r"^-[0-9]", tok):+ positionals.append(tok)+ continue+ name, colon, value = tok[1:].partition(":")+ key = spec.aliases.get(name.lower(), name.lower())+ if key in spec.params:+ kind = spec.params[key]+ elif key in _PS_COMMON:+ kind = _PS_COMMON[key]+ else:+ return None+ if key in bound:+ return None+ bound.add(key)+ if kind is None:+ if colon:+ return None+ continue+ if not colon:+ if i >= len(args):+ return None+ value = args[i]+ i += 1+ if not _ps_value_ok(kind, value):+ return None+ if kind == "path":+ targets.append(value)+ slots = [p for p in spec.positional if p not in bound]+ for value in positionals:+ if slots:+ kind = spec.params[slots.pop(0)]+ elif spec.rest is not None:+ kind = spec.rest+ else:+ return None+ if not _ps_value_ok(kind, value):+ return None+ if kind == "path":+ targets.append(value)+ return targetsdef _powershell_plain(command: str) -> bool:@@ -289,22 +1339,34 @@ def _powershell_paths(command: str) -> str:return command.replace(chr(92), "/")-def is_readonly_command(command: str, shell: str = "bash") -> bool:- """True iff `command` is a single command or pure pipeline of local read-only stages,- as the given shell (`bash` or `powershell`) would run it."""+# -- entry points ------------------------------------------------------------------------------+++def _analyze(command: str, shell: str) -> tuple[list[list[str]], list[list[str] | None]] | None:+ """Pipeline stages and, per stage, its read targets (None: not read-only).+ None overall when the command does not even tokenize as a plain pipeline."""if shell not in SHELLS:- return False+ return Nonecommand = str(command or "")if shell == "powershell":if not _powershell_plain(command):- return False+ return Nonecommand = _powershell_paths(command)stages = _stages(command)if stages is None:- return False- if shell == "powershell" and any(_ENV_ASSIGN.match(s[0]) for s in stages):- return False # not an assignment in PowerShell: it would be a command name- return all(_stage_ok(s) for s in stages)+ return None+ if shell == "powershell":+ if any(_ENV_ASSIGN.match(s[0]) for s in stages):+ return None # not an assignment in PowerShell: it would be a command name+ return stages, [_powershell_stage(s) for s in stages]+ return stages, [_bash_stage(s) for s in stages]+++def is_readonly_command(command: str, shell: str = "bash") -> bool:+ """True iff `command` is a single command or pure pipeline of local read-only stages,+ as the given shell (`bash` or `powershell`) would run it."""+ analyzed = _analyze(command, shell)+ return analyzed is not None and all(t is not None for t in analyzed[1])# -- read targets (OPE-130) ------------------------------------------------------------@@ -315,63 +1377,15 @@ def is_readonly_command(command: str, shell: str = "bash") -> bool:# same shape as the fix for browser uploads in OPE-122.## Extracting read targets from arbitrary shell is not possible in general; it is tractable-# here only because the classifier has already narrowed the input to the verbs above.+# here only because the classifier has already narrowed the input to the verbs above, and+# since OPE-232 the same flag parse that accepts a command names its files.-# Operands are not paths: arguments are strings, charsets, or command names.-_NO_PATH_OPERANDS = {- "echo", "printf", "pwd", "whoami", "id", "date", "uname", "true", "false",- "which", "basename", "dirname", "tr", "command", "env",-}-# The FIRST non-flag operand is a pattern/program, not a path; the rest are files.-_PATTERN_FIRST = {"grep", "egrep", "fgrep", "rg", "ugrep", "jq", "awk", "gawk", "mawk", "nawk", "sed"}-# Flags whose VALUE is a path, for the commands that accept them.-_PATH_VALUE_FLAGS = {"-f", "--file", "--exclude-from", "--include-from"}-# `head -n 5`, `cut -f 1`, `sed -n 2p`: a bare number is some flag's count, never a file-# worth scoping. Dropping them keeps the target list honest without a per-flag table.+# `head -n 5`, `cut -f 1`: a bare number is a count, never a file worth scoping._NUMERIC = re.compile(r"^[0-9]+([,:.-][0-9]+)*[a-zA-Z]?$")-# find(1)'s global options precede the starting points, so unlike the predicates they-# must not end the path list. -H/-L/-P select symlink handling; -E/-X/-d/-s/-x are BSD-# spellings; -O carries its level attached. -D takes a value (GNU debug options) and-# -f takes the starting point itself.-_FIND_GLOBAL_NO_VALUE = frozenset({"-H", "-L", "-P", "-E", "-X", "-d", "-s", "-x"})---def _find_targets(args: list[str]) -> list[str]:- """Starting points of `find`, with its global options skipped.-- `find -L /etc -name shadow` reads /etc exactly like `find /etc -name shadow`, but- treating every leading `-` token as the start of the predicates returned no targets- for the prefixed form — so the session grant's root check passed vacuously.- """- out: list[str] = []- i = 0- while i < len(args):- tok = args[i]- if tok in _FIND_GLOBAL_NO_VALUE or (tok.startswith("-O") and tok != "-O"):- i += 1- continue- if tok == "-D" and i + 1 < len(args):- i += 2 # debugopts, never a path- continue- if tok == "-f" and i + 1 < len(args):- out.append(args[i + 1]) # BSD: -f names the starting point- i += 2- continue- break- # Starting points end at the first predicate (any other `-` token). With none, find- # defaults to `.`, which is inside every session root.- while i < len(args) and not args[i].startswith("-"):- out.append(args[i])- i += 1- return out-def _flag_values(args: list[str]) -> list[str]:- """Paths a flag carries in the same token (OPE-232): `--file=PATH`, PowerShell's- `-Path:PATH`, and a short flag with a path attached (`-f/etc/hosts`). Named as read- targets so they are held to the folders like any operand. Values that are not paths- (`--format=%H`) resolve inside the folder and cost nothing."""+ """Values carried inside flag tokens (`--file=PATH`, `-Path:PATH`, `-f/etc/hosts`)."""out: list[str] = []for tok in args:if not tok.startswith("-") or tok in {"-", "--"}:@@ -391,76 +1405,27 @@ def _flag_values(args: list[str]) -> list[str]:return out-def _stage_targets(argv: list[str]) -> list[str]:- """File operands of one accepted pipeline stage."""- i = 0- while i < len(argv) and _ENV_ASSIGN.match(argv[i]):- i += 1- argv = argv[i:]- if not argv:- return []- head, args = argv[0], argv[1:]- if head in _NO_PATH_OPERANDS:- return []-- if head == "git":- # Only `-C <dir>` escapes the working directory; everything else the classifier- # accepts reads the repo already in scope. Operands after `--` are pathspecs.- out: list[str] = _flag_values(args)- for j, tok in enumerate(args):- if tok == "-C" and j + 1 < len(args):- out.append(args[j + 1])- elif tok == "--":- out.extend(t for t in args[j + 1 :] if not t.startswith("-"))- break- return out-+def _fallback_targets(argv: list[str]) -> list[str]:+ """For a stage the classifier rejects: every operand-looking token, erring wide."""+ stripped = _strip_env(argv) or argv+ head, args = (stripped[0], stripped[1:]) if stripped else ("", [])if head == "find":- return _find_targets(args) + _flag_values(args)-- out = _flag_values(args)- skip_next = False- seen_operand = False- for tok in args:- if skip_next:- # `-f` is a pattern FILE for grep but a field NUMBER for cut; the numeric test- # separates them without needing a per-command flag table.- if not _NUMERIC.match(tok):- out.append(tok)- # `grep -f patterns.txt build.log`: the pattern came from the flag, so the- # first positional is already a FILE and must not be skipped as the pattern.- seen_operand = True- skip_next = False- continue- if tok.startswith("-"):- if tok in _PATH_VALUE_FLAGS:- skip_next = True- continue- if head in _PATTERN_FIRST and not seen_operand:- seen_operand = True # the pattern/script/filter, not a file- continue- seen_operand = True- if not _NUMERIC.match(tok):- out.append(tok)- return out+ return _find_targets(args)+ return _flag_values(args) + [t for t in args if not t.startswith("-") and not _NUMERIC.match(t)]def read_targets(command: str, shell: str = "bash") -> list[str]:"""Every file operand `command` would read, for scoping against the session's roots.Only meaningful for commands `is_readonly_command` accepts — it assumes that vetting.- Errs toward naming MORE operands: an extra one costs a manual approval, a missed one- is an unscoped read, and that asymmetry decides the edge cases here as it does above.-- Known limit: a path reached through a flag this table does not list is not returned.- The positional operands that carry the real exposure are covered.+ For those, every operand and every path an allowed flag carries is named. Errs toward+ naming MORE: an extra one costs a manual approval, a missed one is an unscoped read."""- if shell not in SHELLS:+ analyzed = _analyze(command, shell)+ if analyzed is None:return []- command = str(command or "")- if shell == "powershell":- command = _powershell_paths(command)- stages = _stages(command)- if stages is None:- return []- return [t for stage in stages for t in _stage_targets(stage)]+ stages, found = analyzed+ out: list[str] = []+ for stage, targets in zip(stages, found):+ out.extend(targets if targets is not None else _fallback_targets(stage))+ return outdiff --git a/tests/test_readonly_allowlist.py b/tests/test_readonly_allowlist.pynew file mode 100644index 00000000..50a12035--- /dev/null+++ b/tests/test_readonly_allowlist.py@@ -0,0 +1,477 @@+"""OPE-232: the read-only checker allows only the flags known to be harmless.++Every command the checker accepts has a list of the flags that only change what is+shown or which local files are read. Any other flag, including one nobody has reviewed+yet, makes the command not read-only, so it gets a card. The same holds for git+subcommands and for the PowerShell cmdlets the checker knows.++The small languages inside sed, awk and jq are accepted only in a conservative subset,+and every path a flag carries is a read target that the session's folders are checked+against.+"""++from __future__ import annotations++import pytest++from coworker.readonly import is_readonly_command, read_targets+++def ok(command: str, shell: str = "bash") -> bool:+ return is_readonly_command(command, shell=shell)+++# -- the flags agents really use keep passing -----------------------------------------------++ACCEPT = [+ # ls / cat / head / tail / wc+ "ls -la", "ls -lt src", "ls -ld src", "ls -R", "ls -1", "ls -lah --color=auto",+ "ls --time-style=+%s -l", "ls --time-style full-iso -l", "ls -S", "ls --sort=size",+ "cat -A x.c", "cat -n x.c", "cat -v x.c", "cat -An x.c",+ "head -20 x", "head -n 5 x", "head -n5 x", "head -c 100 x", "head -c 1K x", "head -n -5 x",+ "head --lines=5 x", "tail -3 x", "tail -n +5 x", "tail -c 64 x", "tail -n1 x",+ "wc -l x", "wc -c x", "wc -lw x", "wc --lines x",+ # grep and friends+ "grep -n foo x", "grep -rn foo src", "grep -v foo x", "grep -c foo x", "grep -h foo x",+ "grep -i foo x", "grep --include=*.py -rn foo src", "grep -A 5 foo x", "grep -A25 foo x",+ "grep -B2 foo x", "grep -C 3 foo x", "grep -E 'a|b' x", "grep -m1 foo x", "grep -l foo x",+ "grep -rln foo src", "grep -a foo x", "grep -o foo x", "grep -oE 'a+' x", "grep -aobE x y",+ "grep -e foo -e bar x", "grep -w foo x", "grep -x foo x", "grep -F 'a.b' x", "grep -5 foo x",+ "grep --color=never foo x", "grep --exclude-dir=.git -rn foo .", "grep -q foo x",+ "egrep 'a|b' x", "fgrep a.b x", "grep -rI foo src", "grep -L foo src/x",+ "rg --json TODO", "rg -n foo src", "rg -i foo", "rg --files src", "rg -g '*.py' foo",+ "rg -t py foo", "rg -C 2 foo", "rg -l foo", "rg --hidden foo", "rg -uu foo",+ "ugrep -n foo x",+ # text tools+ "sort -rn x", "sort -u x", "sort -n x", "sort -k2 x", "sort -k6,7 x", "sort -t- -k2 x",+ "sort -t , -k 1,1 x", "uniq -c", "uniq -d x", "cut -c60- x", "cut -d, -f1 x",+ "cut -f 1 x", "cut -c1-200 x", "tr -d '\\r'", "tr a-z A-Z", "nl -ba x", "nl x",+ "column -t x", "comm -12 a b", "diff -u a b", "diff -q a b", "diff --label a -u a b",+ "diff -U3 a b", "diff -rq --no-dereference a b", "strings -n 8 x", "strings x",+ "od -A x -t x1z -v x", "od -c x", "od -N 16 -j 4 x", "hexdump -C x", "xxd x",+ "xxd -p x", "xxd -l 64 x", "xxd -s 0x100 -l 64 x", "xxd -c16 x",+ "file x", "file -b x", "file --mime-type x", "stat x", "stat -c %s x",+ "du -sh .", "du -h -d 1 .", "df -h", "df -h .",+ "md5sum x", "sha256sum x", "shasum -a 256 x", "sha1sum x",+ # small utilities+ "pwd", "whoami", "id -u", "date", "date -u +%Y", "date -d @0 +%s", "uname -a",+ "basename a/b.c .c", "dirname a/b.c", "realpath x", "readlink -f x", "which -a git",+ "echo hello", "echo -n hi", "printf 'a: '", "true", "false", "env",+ "command -v semgrep", "command -V git",+ # git+ "git status", "git status --short", "git status -sb", "git status --porcelain",+ "git log --oneline -5", "git log --oneline", "git log -1", "git log -n 3",+ "git log --all --graph --oneline", "git log --format=%H -1", "git log --pretty=format:%s -3",+ "git log --grep=fix -i", "git log --since=2.weeks --until=yesterday",+ "git log --follow -- src/x.py", "git log -p -1", "git log --stat -3", "git log --find-object=abc",+ "git log --date=short --format='%ad %s'", "git log --author=me", "git log main..HEAD",+ "git diff", "git diff --stat", "git diff --cached", "git diff --name-only HEAD~1",+ "git diff main...HEAD", "git diff -U0 a b", "git diff --src-prefix=a/ --dst-prefix=b/",+ "git diff --no-index a b", "git diff --word-diff", "git diff -w",+ "git show", "git show --stat HEAD", "git show HEAD:src/x.py", "git show --format=%H -s",+ "git blame src/x.py", "git blame -L 10,20 src/x.py", "git shortlog -sn",+ "git describe --tags", "git rev-parse HEAD", "git rev-parse --abbrev-ref HEAD",+ "git rev-parse --show-toplevel", "git rev-parse --is-inside-work-tree",+ "git rev-list --count HEAD", "git ls-files", "git ls-files -m", "git ls-tree -r HEAD",+ "git grep -n foo", "git grep -c needle", "git grep --cached needle", "git grep -e a -e b",+ "git cat-file -p HEAD", "git cat-file -t HEAD", "git merge-base main HEAD",+ "git count-objects -v", "git check-ignore -v x", "git name-rev HEAD",+ "git branch", "git branch -a", "git branch -vv", "git branch --show-current",+ "git branch --contains abc", "git branch --list 'feat*'", "git branch -r --merged",+ "git tag", "git tag -l", "git tag -l 'v1*'", "git tag -n5 -l",+ "git stash list", "git stash show -p", "git remote", "git remote -v",+ "git remote get-url origin", "git config --get user.name", "git config --list",+ "git config -l", "git config get user.name", "git reflog", "git reflog show -5",+ "git --no-pager log -1", "git -C /tmp/repo log -1", "git --version",+]++[email protected]("command", ACCEPT)+def test_the_flags_agents_use_stay_read_only(command):+ assert ok(command), command+++# -- any other flag gets a card ---------------------------------------------------------------+# A sample per command: some write or run things, most are simply not on the list.++REJECT = [+ "ls -L", "ls --dereference", "ls --zzz", "ls -la --hyperlinkz",+ "cat -l x", "cat --zzz x",+ "head -f x", "head --zzz x", "tail -f x", "tail -F x", "tail --follow x", "tail --pid=1 x",+ "wc --files0-from=list", "wc -q x",+ "grep -R foo .", "grep --dereference-recursive foo .", "grep -S foo .", "grep -A foo x",+ "grep --zzz foo x", "grep -O foo x",+ "rg -z foo", "rg --search-zip foo", "rg --pre ./p foo", "rg --pre=./p foo",+ "rg -L foo", "rg --follow foo", "rg --hostname-bin=./p foo", "rg --zzz foo",+ "ugrep --pager foo", "ugrep -Q foo", "ugrep --filter=x foo", "ugrep --save-config",+ "sort -o out x", "sort -T /tmp x", "sort --compress-program=gzip x",+ "sort --random-source=x x", "sort --files0-from=x", "sort --out=x x",+ "uniq a b", "uniq -c a b", "cut --zzz x", "tr -x a b", "tr a b c",+ "nl --zzz x", "column -J x", "comm a b c",+ "diff -r a b", "diff --recursive a b", "diff -l a b", "diff --paginate a b", "diff --zzz a b",+ "strings @list", "strings -n 8 @list", "od --zzz x", "hexdump -f fmt x",+ "xxd -r x", "xxd -revert x", "xxd -R always x", "xxd a b", "xxd -ps a b",+ "file -z x", "file -Z x", "file -p x", "file -f list", "file -m magic x",+ "stat --zzz x", "du -L .", "du --dereference .", "du --files0-from=x",+ "df --sync", "md5sum -c sums", "sha256sum --check sums", "shasum -c sums",+ "pwd x", "whoami x", "date 0101", "date -s now", "date -f list", "date -r x",+ "uname -x", "basename --zzz x", "readlink --zzz x", "which --zzz git",+ "echo -x hi", "printf -v name x", "true x", "env -i ls", "env -u X ls", "env X=1",+ "command ls", "command -p ls", "id -A",+ # git+ "git log --output=x", "git log --ext-diff", "git log --textconv", "git log --show-signature",+ "git log --format=%G?", "git log --pretty=format:%GS", "git log -L 1,2:x.c", "git log -Ox",+ "git log --orderfile=x", "git log --zzz", "git log --onel",+ "git diff --ext-diff", "git diff --output=x", "git diff -Ox",+ "git show --show-signature", "git blame --contents x y", "git blame -S revs x",+ "git blame --ignore-revs-file=x y", "git grep -O foo", "git grep -Ox foo",+ "git grep --open-files-in-pager foo", "git grep --textconv foo",+ "git cat-file --filters HEAD:x", "git cat-file --textconv HEAD:x",+ "git branch new", "git branch -D x", "git branch -m a b", "git branch --set-upstream-to=x",+ "git tag v1", "git tag -d v1", "git tag -a v1 -m x", "git tag -v v1",+ "git stash", "git stash pop", "git stash drop", "git remote add x y", "git remote show origin",+ "git remote set-url origin x", "git config user.name x", "git config --unset x",+ "git config --edit", "git config --add a b", "git reflog expire --all", "git reflog delete x",+ "git -c core.pager=x log", "git --git-dir=x log", "git --work-tree=x status",+ "git --exec-path=x status", "git --help", "git fetch", "git checkout x", "git commit -m x",+ "git status --zzz", "git rev-parse --resolve-git-dir x",+]++[email protected]("command", REJECT)+def test_any_other_flag_gets_a_card(command):+ assert not ok(command), command+++# -- operands that would write or run something -----------------------------------------------+++ "command, expected",+ [+ ("xxd dump.bin", True),+ ("xxd dump.bin out.bin", False), # the second operand is an output file+ ("uniq data.txt", True),+ ("uniq data.txt out.txt", False), # likewise for uniq+ ("date +%s", True),+ ("date 202001010000", False), # an operand without `+` sets the clock+ ("tr a b", True),+ ("strings @options.txt", False), # an `@file` operand is read as more options+ ("command -v ls", True),+ ("command ls", False), # runs ls+ ("env", True),+ ("env ls", False), # runs ls+ ("printf '%s\\n' a b", True),+ ],+)+def test_operands_that_write_or_run_are_not_read_only(command, expected):+ assert ok(command) is expected, command+++# -- sed: print and plain substitution ---------------------------------------------------------+++ "script",+ [+ "320,345p", "1,20p;40,60p", "/=== Stage 1/,/=== Stage 2/p", "/^static int f(/,/^}/p",+ "/struct A/,/^};/p;/struct B/,/^};/p", "/x/,$p", "$p", "1~2p", "0,/re/p", "/a/,+3p",+ "s/a/b/", "s/a/b/g", "s|/src/x/||", "s/[0-9]*$//", "s/\\(hb_[a-z_]*\\) (.*/\\1/",+ "s/a/b/2", "s/a/b/gI", "s/==[0-9]*==//;s/0x[0-9a-f]*/ADDR/g", "y/abc/xyz/",+ "/x/d", "5q", "=", "/start/,/end/{p}", "/a/!d", "/^$/d",+ ],+)+def test_sed_print_and_substitution_are_accepted(script):+ assert ok(f"sed -n '{script}' data.txt"), script+++ "script",+ [+ "w out.txt", "1w out.txt", "s/a/b/w out.txt", "s/a/b/e", "e ls", "r /etc/hosts",+ "R x", "W x", "1r x", "/x/w y", "s/[/]/x/", "a text", "i text", "c text",+ ":a;N;ba", "1,5b", "t", "/x/{w y}", "/x/{p", "p}", "s/a/b", "s/a/b/q", "1,p",+ "s/a/b/;w x", "v", "l 5;w x", "#n",+ ],+)+def test_sed_scripts_outside_the_subset_get_a_card(script):+ assert not ok(f"sed -n '{script}' data.txt"), script+++def test_sed_checks_every_script_it_is_given():+ assert ok("sed -e 1p -e 's/a/b/' data.txt")+ assert not ok("sed -e 1p -e 'w x' data.txt")+ assert not ok("sed --expression='w x' data.txt")+ assert not ok("sed -i 's/a/b/' x")+ assert not ok("sed --in-place 's/a/b/' x")+ assert not ok("sed -f script.sed x")+ assert ok("sed --sandbox -n 1p x")+++# -- awk: printing, matching, arithmetic --------------------------------------------------------+++ "program",+ [+ "{print $1}", "{print $2, $3, $4}", "NR>1 {print}", "$3 >= 100 {print $1}",+ "{if ($1 > 5) print $1}",+ '{printf "%s:%s ", $1, $2} END {print ""}', '{printf "%d\\t%s\\n", $1+579, substr($0, index($0,$2))}',+ '/^f/{f=1} f{print NR": "$0} f&&/^}/{exit}', "/a/,/b/", "{s+=$1} END {print s}",+ "length($0) > 80", "{a[$1]++} END {for (k in a) print k, a[k]}", "$1 == \"x\" || $2 < 3",+ ],+)+def test_awk_programs_that_only_print_are_accepted(program):+ assert ok(f"awk '{program}' data.txt"), program+++ "program",+ [+ '{print > "out"}', '{print >> "out"}', '{print | "sort"}', '{print |& "x"}',+ '{print "a;b}" > "out"}', '{print /;/ > "out"}', '{printf("%s", $1) > "out"}',+ 'BEGIN{system("ls")}', 'BEGIN{"date" | getline d}', 'BEGIN{getline l < "/etc/hosts"}',+ "BEGIN{print ENVIRON[\"HOME\"]}", "BEGIN{print PROCINFO[\"pid\"]}",+ 'BEGIN{ARGV[1]="/etc/hosts"; ARGC=2} {print}', '@include "x"', "BEGIN{f=\"system\"; @f(\"ls\")}",+ ],+)+def test_awk_programs_that_redirect_or_run_get_a_card(program):+ assert not ok(f"awk '{program}' data.txt"), program+++def test_awk_flags():+ assert ok("awk -F'|' '{print $1}' data.txt")+ assert ok("awk -F, -v n=2 '{print $n}' data.txt")+ assert not ok("awk -f prog.awk data.txt")+ assert not ok("awk --file=prog.awk data.txt")+ assert not ok("gawk -l ext '{print}' x")+ assert not ok("gawk -e '{print}' x")+ assert not ok("gawk -o out '{print}' x")+ assert not ok("mawk -W exec x")+++# -- jq: filters, without modules or the environment ---------------------------------------------+++ "command, expected",+ [+ ("jq . data.json", True),+ ("jq -r '.items[] | .name' data.json", True),+ ("jq '.results | length' data.json", True),+ ("jq -c --arg k v '.[$k]' data.json", True),+ ("jq -s 'add' a.json b.json", True),+ ("jq -n '1+1'", True),+ ("jq --indent 4 . data.json", True),+ ("jq -n env", False), # the environment is not a local file+ ("jq -n '$ENV.HOME'", False),+ ("jq 'import \"x\" as x; .' data.json", False), # modules are read from elsewhere+ ("jq 'include \"x\"; .' data.json", False),+ ("jq -L dir . data.json", False),+ ("jq -f prog.jq data.json", False),+ ("jq --from-file prog.jq data.json", False),+ ("jq --zzz . data.json", False),+ ],+)+def test_jq(command, expected):+ assert ok(command) is expected, command+++# -- find: predicates that select and print ------------------------------------------------------+++ "command",+ [+ "find . -name '*.py'", "find . -type f -name x", "find src -path '*/test/*' -prune -o -print",+ "find . -newermt 2024-01-01", "find . -not -name x", "find . -maxdepth 2 -type d",+ "find . -printf '%p\\n'", "find . -newer build.log", "find . -iname x", "find . -size -900k",+ "find . -perm -u+x", "find . -user me", "find . -xdev -name x", "find . -mmin -5",+ "find . -print0", "find . \\( -name a -o -name b \\)", "find . ! -name x", "find -H . -name x",+ "find -D search src",+ ],+)+def test_find_predicates_that_only_select_are_accepted(command):+ assert ok(command), command+++ "command",+ [+ "find . -delete", "find . -exec ls {} ;", "find . -execdir ls ;", "find . -ok ls ;",+ "find . -fprint out", "find . -fprintf out %p", "find . -fls out", "find . -fprint0 out",+ "find . -files0-from list", "find -L . -name x", "find . -follow", "find . -zzz",+ "find . -name", "find . -name x extra",+ ],+)+def test_find_actions_that_write_or_run_get_a_card(command):+ assert not ok(command), command+++# -- commands added in OPE-232 -----------------------------------------------------------------+++ "command",+ [+ "tree", "tree -L 2", "tree -a -I node_modules src", "tree -d", "tree --gitignore",+ "cmp a b", "cmp -l a b", "sha512sum x", "sha224sum x", "sha384sum x", "b2sum x",+ "cksum x", "sum x", "tac x", "rev x", "fold -w 80 x", "paste -d, a b", "join a b",+ "expand -t 4 x", "unexpand -a x", "seq 10", "seq 1 2 10", "nproc",+ ],+)+def test_added_commands_are_read_only(command):+ assert ok(command), command+++ "command",+ [+ "tree -o out.txt", "tree -R", "tree -l", "tree --fromfile list", "sha512sum -c sums",+ "b2sum --check sums", "cksum --check sums", "cmp --zzz a b", "seq -f %s --zzz 1",+ "nproc x", "join a b c", "paste --zzz a",+ ],+)+def test_added_commands_keep_their_own_allowlist(command):+ assert not ok(command), command+++ "command",+ ["less x", "more x", "man ls", "python3 x.py", "sh x", "curl x", "nc x", "xargs ls", "ps aux", "sleep 1"],+)+def test_pagers_interpreters_network_and_runners_stay_out(command):+ assert not ok(command), command+++# -- shell parsing ---------------------------------------------------------------------------------+++ "command, expected",+ [+ ("cat {a,b}.txt", False), # brace expansion makes more operands than are written+ ("cat x{1..3}", False),+ ("cat '{a,b}'", True), # quoted: one literal file name+ ("git show stash@{0}", True), # not an expansion+ ("cat a#b", True),+ ],+)+def test_expansions_the_target_list_cannot_see(command, expected):+ assert ok(command) is expected, command+++def test_a_hash_inside_a_word_is_part_of_the_word():+ assert read_targets("cat a#b") == ["a#b"]+++# -- read targets: every allowed flag that carries a path ----------------------------------------+++ "command, path",+ [+ ("grep -f /x/pats foo src", "/x/pats"),+ ("grep --file /x/pats src", "/x/pats"),+ ("grep --exclude-from=/x/l -r foo .", "/x/l"),+ ("rg --ignore-file /x/i foo", "/x/i"),+ ("rg -f /x/pats", "/x/pats"),+ ("rg --files /x", "/x"), # with --files the first operand is a path, not a pattern+ ("diff --from-file=/x/a b", "/x/a"),+ ("diff --to-file /x/a b", "/x/a"),+ ("diff -X /x/l a b", "/x/l"),+ ("du -X /x/l .", "/x/l"),+ ("du --exclude-from=/x/l .", "/x/l"),+ ("realpath --relative-to=/x a", "/x"),+ ("jq --slurpfile v /x/f.json . d.json", "/x/f.json"),+ ("jq --rawfile v /x/f.txt . d.json", "/x/f.txt"),+ ("find . -newer /x/ref", "/x/ref"),+ ("find . -samefile /x/ref", "/x/ref"),+ ("find . -anewer /x/ref", "/x/ref"),+ ("find . -newermm /x/ref", "/x/ref"),+ ("yamllint -c /x/conf a.yml", "/x/conf"),+ ("git grep -f /x/pats", "/x/pats"),+ ("git ls-files -X /x/l", "/x/l"),+ ("git ls-files --exclude-from=/x/l", "/x/l"),+ ("git config --file /x/conf --list", "/x/conf"),+ ("git diff --no-index /x/a b", "/x/a"), # git diff reads plain files, too+ ("git -C /x log", "/x"),+ ],+)+def test_every_path_a_flag_carries_is_a_read_target(command, path):+ assert ok(command), command+ assert path in read_targets(command), (command, read_targets(command))+++def test_values_that_are_not_paths_are_not_targets():+ assert read_targets("grep --include=*.py -rn foo src") == ["src"]+ assert read_targets("sort -t , -k 2 data.csv") == ["data.csv"]+ assert read_targets("find . -name '*.py'") == ["."]+ assert read_targets("ls --time-style=+%s -l src") == ["src"]+++# -- PowerShell: its own commands and parameters ----------------------------------------------------+++PS_ACCEPT = [+ "Get-ChildItem", "Get-ChildItem -Recurse -Filter *.py", "ls -Recurse src", "dir src",+ "gci -File -Depth 2", "ls -Name", "Get-ChildItem -Path src -Include *.md -Recurse",+ "Get-Content README.md", "cat README.md", "type README.md", "gc README.md -TotalCount 20",+ "Get-Content -Path README.md -Tail 5", "cat README.md -Head 10", "Get-Content x -Raw",+ "Get-Content x -Encoding utf8", "Select-String -Pattern foo -Path src/*.py",+ "sls foo README.md", "Select-String foo README.md -CaseSensitive -Context 2",+ "cat README.md | Measure-Object -Line", "cat README.md | measure -Word",+ "Get-Location", "pwd", "Test-Path README.md", "Test-Path -Path src -PathType Container",+ "Resolve-Path README.md", "Get-FileHash README.md", "Get-FileHash -Algorithm SHA256 README.md",+ "cat README.md | sort", "cat README.md | Sort-Object -Unique", "ls | Select-Object -First 5",+ "echo hello", "Get-ChildItem -Recurse -ErrorAction SilentlyContinue",+ "git status", "git log --oneline -5", "git diff --stat",+]++[email protected]("command", PS_ACCEPT)+def test_powershell_read_only_commands(command):+ assert ok(command, "powershell"), command+++PS_REJECT = [+ "Get-Content x -Wait", "cat x -Stream s", "Get-ChildItem -FollowSymlink", "ls -la",+ "Get-Content x -OutVariable v", "ls -PipelineVariable p", "ls -ErrorVariable e",+ "ls -ErrorAction Break", "Get-ChildItem -Zzz", "Get-Content x y",+ "Remove-Item x", "rm x", "Set-Content x y", "Out-File x", "Invoke-Expression x", "iex x",+ "Start-Process x", "Invoke-WebRequest x", "curl x", "wget x", "Copy-Item a b",+ "grep foo x", "head -n 5 x", "tail x", "wc -l x", "sed -n 1p x", "find . -name x",+ "cat env:USERPROFILE", "Get-Content -Path Env:PATH", "ls HKLM:/Software", "cat Variable:x",+ "Get-ChildItem Registry::HKEY_LOCAL_MACHINE", "Get-ChildItem -Path Cert:/",+ "git log --output=x", "git branch new",+]++[email protected]("command", PS_REJECT)+def test_powershell_other_parameters_and_commands_get_a_card(command):+ assert not ok(command, "powershell"), command+++ "command, path",+ [+ ("Get-Content -Path C:\\x\\a.txt", "C:/x/a.txt"),+ ("Get-Content -LiteralPath C:\\x\\a.txt", "C:/x/a.txt"),+ ("cat C:\\x\\a.txt", "C:/x/a.txt"),+ ("ls -Path:C:\\x", "C:/x"),+ ("Select-String foo C:\\x\\a.txt", "C:/x/a.txt"),+ ("Select-String -Path C:\\x\\a.txt -Pattern foo", "C:/x/a.txt"),+ ("Test-Path C:\\x", "C:/x"),+ ("Resolve-Path C:\\x", "C:/x"),+ ("Get-FileHash C:\\x\\a.txt", "C:/x/a.txt"),+ ("git -C C:\\x log", "C:/x"),+ ],+)+def test_powershell_path_values_are_read_targets(command, path):+ assert ok(command, "powershell"), command+ assert path in read_targets(command, shell="powershell")+++def test_powershell_patterns_are_not_targets():+ assert read_targets("Select-String -Pattern C:\\x README.md", shell="powershell") == ["README.md"]+ assert read_targets("Get-ChildItem -Filter *.py src", shell="powershell") == ["src"]diff --git a/tests/test_readonly_grant.py b/tests/test_readonly_grant.pyindex 5f02fc92..0613e93c 100644--- a/tests/test_readonly_grant.py+++ b/tests/test_readonly_grant.py@@ -135,7 +135,7 @@ def test_classifier_rejects(cmd):def test_engine_grant_gates_on_classifier(tmp_path):- eng = PermissionEngine(workspace_root=tmp_path, mode=Mode.INTERACTIVE)+ eng = PermissionEngine(workspace_root=tmp_path, mode=Mode.INTERACTIVE, shell_kind="bash")class Meta:category = "shell"diff --git a/tests/test_readonly_scoping.py b/tests/test_readonly_scoping.pyindex 967e1af6..05f3d979 100644--- a/tests/test_readonly_scoping.py+++ b/tests/test_readonly_scoping.py@@ -18,11 +18,13 @@ from coworker.readonly import is_readonly_command, read_targets@pytest.fixture()def session(tmp_path):- """A session whose granted root is `repo/`, with the grant already clicked."""+ """A session whose granted root is `repo/`, with the grant already clicked. The commands+ below are bash commands, so the shell is bash on every platform (OPE-232: PowerShell+ has its own list)."""root = tmp_path / "repo"(root / "src").mkdir(parents=True)(root / "build.log").write_text("boom", encoding="utf-8")- engine = PermissionEngine(workspace_root=root, mode=Mode.INTERACTIVE)+ engine = PermissionEngine(workspace_root=root, mode=Mode.INTERACTIVE, shell_kind="bash")engine.allow_readonly_for_session()return engine@@ -78,8 +80,11 @@ def test_reads_outside_every_root_now_ask(session, command):def test_find_with_a_global_option_inside_the_root_still_runs(session):# The scoping must not undo the convenience: the prefixed form over an in-scope path# keeps auto-running, exactly like the unprefixed one.- assert runs(session, "find -L . -name '*.py'")- assert runs(session, "find -D search src"), command+ assert runs(session, "find -H . -name '*.py'")+ assert runs(session, "find -D search src")+ # OPE-232: -L follows symbolic links met during the walk, which the folder check+ # cannot see, so it asks.+ assert not runs(session, "find -L . -name '*.py'")def test_openworkers_own_secrets_are_no_longer_readable(session):@@ -123,6 +128,7 @@ def test_a_second_granted_root_is_in_scope(tmp_path):workspace_root=repo,mode=Mode.INTERACTIVE,roots=[RootDir(path=repo, writable=True), RootDir(path=notes, writable=False)],+ shell_kind="bash",)engine.allow_readonly_for_session()# Reading needs read access, not write access.