Python
"""Conservative read-only shell-command classifier for the session-scoped grant.
"Allow read-only commands for this session" (owner ask 2026-08-11, born of approval
fatigue in security-scan sessions: ~15 hand-approvals per run) auto-allows a command only
when THIS classifier accepts it. The contract:
- **Local filesystem reads only.** Network clients (curl/wget/ssh/nc) are deliberately
excluded even for GET — an auto-allowed network command is an exfiltration channel
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, 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, 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
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: the
session still runs under its permission mode, and the user granted the scope explicitly.
"""
from __future__ import annotations
import os
import re
import shlex
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).
# Any other variable may name a program the command then runs, so it rejects.
_SAFE_ENV = frozenset({
"LANG", "LANGUAGE", "LC_ALL", "LC_COLLATE", "LC_CTYPE", "LC_MESSAGES", "LC_NUMERIC",
"LC_TIME", "TZ", "NO_COLOR", "COLUMNS",
})
SHELLS = ("bash", "powershell")
# PowerShell evaluates or expands these even inside what looks like an argument:
# variables, sub-expressions and grouping, script blocks, array/hash literals, arrays of
# arguments, escapes, call / redirection / sequence operators. Fail closed on any of them.
_POWERSHELL_UNSAFE = frozenset("$`(){}[]@,;&<>")
# -- tokenizing -----------------------------------------------------------------------------
def _has_unquoted_expansion(command: str) -> bool:
"""A variable, subshell or brace expansion bash would apply before the command runs.
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 = None
escaped = False
brace = 0
prev = ""
for char in command:
if escaped:
escaped = False
prev = ""
continue
if char == "\\" and quote != "'":
escaped = True
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
def _stages(command: str) -> list[list[str]] | None:
"""Tokenize with operators surfaced; split into pipeline stages. None = reject."""
if not command or not command.strip():
return None
if any(ord(c) < 32 and c != "\t" for c in command):
return None # a line break starts another command; other controls are never needed
if _has_unquoted_expansion(command) or "$(" in command or "`" in command or "<(" in command or ">(" in command:
return None
lex = 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 it
try:
tokens = list(lex)
except ValueError:
return None # unbalanced quotes etc.
stages: list[list[str]] = [[]]
for tok in tokens:
if tok == "|":
stages.append([])
elif tok in {";", "&", "&&", "||", "|&"} or (tok and set(tok) <= {">", "<", "&", "0", "1", "2"} and any(c in tok for c in "<>&")):
return None # every operator except a plain pipe rejects (incl. 2>, &>, <<)
else:
stages[-1].append(tok)
if any(not s for s in stages):
return None # empty stage ("| cmd", "cmd |")
return stages
# -- 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 = 0
while i < 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 += 2
continue
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 += 1
continue
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
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),
"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 _find_targets(args: list[str]) -> list[str]:
"""Starting points of `find`, with its global options skipped (for any find command,
accepted or not).
`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
# 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
# -- 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 config` is not on the list: settings can hold credentials, so reading them asks.
_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
_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,
),
}
_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_leading(args: list[str]) -> tuple[list[str], int]:
"""The `-C DIR` operands among git's leading global flags, and where the subcommand
starts. The accepted global flags are `-C` 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."""
dirs: list[str] = []
i = 0
while i < len(args):
if args[i] == "-C" and i + 1 < len(args):
dirs.append(args[i + 1])
i += 2
elif args[i] in _GIT_GLOBAL_FLAGS:
i += 1
else:
break
return dirs, i
def _git_analyze(args: list[str]) -> list[str] | None:
targets, i = _git_leading(args)
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
# -- 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 = 0
while i < len(argv) and _ENV_ASSIGN.match(argv[i]):
if argv[i].split("=", 1)[0] not in _SAFE_ENV:
return None
i += 1
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 None # path-invoked binaries can be anything; bare names only
if head == "git":
return _git_analyze(args)
if head == "find":
return _find_analyze(args)
if head == "xxd":
return _xxd_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
# A recursive listing may follow a directory junction out of the folders. Later stages
# that only see names and sizes are fine; a stage that reads the listed files asks.
_PS_NAME_ONLY = frozenset({"select-object", "sort-object", "measure-object", "write-output"})
def _ps_recursive_listing(argv: list[str]) -> bool:
head = argv[0].lower()
if _PS_ALIASES.get(head, head) != "get-childitem":
return False
aliases = _PS_SPECS["get-childitem"].aliases
for tok in argv[1:]:
if tok.startswith("-") and len(tok) > 1:
name = tok[1:].partition(":")[0].lower()
if aliases.get(name, name) in ("recurse", "depth"):
return True
return False
def _powershell_pipeline_ok(stages: list[list[str]]) -> bool:
for i, stage in enumerate(stages):
if _ps_recursive_listing(stage):
later = (s[0].lower() for s in stages[i + 1 :])
return all(_PS_ALIASES.get(h, h) in _PS_NAME_ONLY for h in later)
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 targets
def _powershell_plain(command: str) -> bool:
"""A command PowerShell runs as written: no construct that evaluates or expands. (A
leading `.` or `&` that would run a script is rejected too: `&` here, and `.` because
it is not a read-only command.)"""
if any(c in _POWERSHELL_UNSAFE for c in command):
return False
return "--%" not in command.split()
def _powershell_paths(command: str) -> str:
"""PowerShell has no backslash escape: a backslash is a path separator. The tokenizer
below is bash-style, so hand it forward slashes, which PowerShell paths accept too."""
return command.replace(chr(92), "/")
# -- 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 None
command = str(command or "")
if shell == "powershell":
if not _powershell_plain(command):
return None
command = _powershell_paths(command)
stages = _stages(command)
if stages is None:
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
if not _powershell_pipeline_ok(stages):
return stages, [None] * len(stages)
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) ------------------------------------------------------------
# The classifier above decides what a command may DO. It says nothing about what the
# command may READ, so a session grant meant for "stop asking about my project files" also
# covered ~/.aws/credentials, ~/.ssh/id_rsa and OpenWorker's own secrets file. These
# helpers name the file operands so the caller can hold them to the session's roots — the
# 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, and
# since OPE-232 the same flag parse that accepts a command names its files.
# `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]?$")
def _flag_values(args: list[str]) -> list[str]:
"""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 {"-", "--"}:
continue
if "=" in tok:
value = tok.split("=", 1)[1]
elif ":" in tok:
value = tok.split(":", 1)[1]
elif not tok.startswith("--") and len(tok) > 2 and (
"/" in tok[2:] or "\\" in tok[2:] or tok[2:].startswith(("~", "."))
):
value = tok[2:]
else:
continue
if value and not _NUMERIC.match(value):
out.append(value)
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)
return _flag_values(args) + [t for t in args if not t.startswith("-") and not _NUMERIC.match(t)]
def git_repo_dirs(command: str, shell: str = "bash") -> list[str]:
"""The folder each git stage of an accepted command runs in: its `-C` operands joined,
or `.`. Empty when the command is not read-only. The engine checks the project's git
settings there before the grant covers the command (coworker/git_settings.py)."""
analyzed = _analyze(command, shell)
if analyzed is None or any(t is None for t in analyzed[1]):
return []
out: list[str] = []
for stage in analyzed[0]:
argv = stage if shell == "powershell" else _strip_env(stage)
if not argv:
continue
head = argv[0].lower() if shell == "powershell" else argv[0]
if head == "git":
dirs, _ = _git_leading(argv[1:])
out.append(os.path.join(*dirs) if dirs else ".")
return out
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.
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.
"""
analyzed = _analyze(command, shell)
if analyzed is None:
return []
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 out
# -- the Auto-Approve tier (OPE-234) ------------------------------------------------------------
# Stricter than the session grant above, because nothing asks the user or the reviewer
# afterwards. A command qualifies only as ONE line made of parts joined by `;`, `&&` or
# `||`, each a read-only command (the classifier above) or a `cd` that stays inside the
# folders, with every file it reads inside the folders as well. The shell persists across
# calls, so paths are judged from the shell's real current folder, which the caller passes.
# Extra rules, each failing closed: no environment-variable prefixes (some programs run
# what such a variable names), no brace expansion, no flag carrying a path (the target
# table above does not follow flag values), and wildcards are expanded here and every
# match checked, as the shell would expand them.
import glob as _glob
import os as _os
from pathlib import Path as _Path
from typing import Callable as _Callable
_MAX_PARTS = 20
_GLOB_CHARS = frozenset("*?[")
_HARMLESS_REDIRECTS = frozenset({"2>/dev/null", "2>&1"})
def _raw_tokens(text: str) -> list[str] | None:
"""Whitespace-separated tokens with their quotes kept; None on unbalanced quoting."""
tokens: list[str] = []
cur: list[str] = []
quote: str | None = None
escaped = False
for ch in text:
if escaped:
cur.append(ch)
escaped = False
elif ch == "\\" and quote != "'":
cur.append(ch)
escaped = True
elif quote:
cur.append(ch)
if ch == quote:
quote = None
elif ch in "'\"":
quote = ch
cur.append(ch)
elif ch in " \t":
if cur:
tokens.append("".join(cur))
cur = []
else:
cur.append(ch)
if quote or escaped:
return None
if cur:
tokens.append("".join(cur))
return tokens
def _unquoted(token: str) -> str:
"""The characters of a raw token the shell would see outside quotes."""
out: list[str] = []
quote: str | None = None
escaped = False
for ch in token:
if escaped:
escaped = False
elif ch == "\\" and quote != "'":
escaped = True
elif quote:
if ch == quote:
quote = None
elif ch in "'\"":
quote = ch
else:
out.append(ch)
return "".join(out)
def _split_sequence(command: str) -> list[str] | None:
"""Split on top-level `;`, `&&`, `||`, outside quotes. None on unbalanced quoting."""
parts: list[str] = []
buf: list[str] = []
quote: str | None = None
escaped = False
i = 0
while i < len(command):
ch = command[i]
if escaped:
buf.append(ch)
escaped = False
elif ch == "\\" and quote != "'":
buf.append(ch)
escaped = True
elif quote:
buf.append(ch)
if ch == quote:
quote = None
elif ch in "'\"":
quote = ch
buf.append(ch)
elif ch == ";":
parts.append("".join(buf))
buf = []
elif command.startswith("&&", i) or command.startswith("||", i):
parts.append("".join(buf))
buf = []
i += 1
else:
buf.append(ch)
i += 1
if quote or escaped:
return None
parts.append("".join(buf))
return [p.strip() for p in parts]
def _without_harmless_redirects(tokens: list[str]) -> list[str]:
out: list[str] = []
i = 0
while i < len(tokens):
tok = tokens[i]
if tok in _HARMLESS_REDIRECTS:
i += 1
continue
if tok == "2>" and i + 1 < len(tokens) and tokens[i + 1] == "/dev/null":
i += 2
continue
out.append(tok)
i += 1
return out
def _flag_carries_path(token: str) -> bool:
if not token.startswith("-") or token in {"-", "--"}:
return False
if token.startswith("--") and "=" in token:
value = token.split("=", 1)[1]
return "/" in value or "\\" in value or value.startswith(("~", "."))
return "/" in token or "\\" in token or "~" in token
_SETTINGS_PRINTERS = frozenset({"env", "printenv"})
def _bash_stage_words(command: str) -> list[list[str]]:
"""Each pipeline stage of a bash command with leading `NAME=value` words dropped; empty
when the command does not parse."""
stages = _stages(command)
if stages is None:
return []
out: list[list[str]] = []
for stage in stages:
i = 0
while i < len(stage) and _ENV_ASSIGN.match(stage[i]):
i += 1
if stage[i:]:
out.append(stage[i:])
return out
def prints_settings(command: str, shell: str = "bash") -> bool:
"""True when a stage prints the process environment or git's settings (`env`,
`printenv`, `git config`), which can hold credentials. The read-only session grant is
the user's own click and takes its own view; the Auto-Approve tier never clears these."""
if shell != "bash":
return False
for words in _bash_stage_words(command):
if words[0] in _SETTINGS_PRINTERS:
return True
if words[0] == "git" and _git_subcommand(words[1:]) == "config":
return True
return False
def _git_subcommand(args: list[str]) -> str:
"""The subcommand after git's leading global flags (`-C DIR` carries an operand)."""
i = 0
while i < len(args):
if args[i] == "-C":
i += 2
elif args[i].startswith("-"):
i += 1
else:
return args[i]
return ""
def git_revision_paths(command: str, shell: str = "bash") -> list[str]:
"""The path half of every `revision:path` operand of a git stage (`git show HEAD:.env`,
`git cat-file -p :.env`). Git prints the file at that revision, so the path deserves the
same secret-name check as a plain file operand."""
if shell != "bash":
return []
out: list[str] = []
for words in _bash_stage_words(command):
if words[0] != "git":
continue
for tok in words[1:]:
if tok.startswith("-") or ":" not in tok:
continue
rev, _, path = tok.partition(":")
if path and "://" not in tok and not (len(rev) == 1 and rev.isalpha() and path.startswith(("\\", "/"))):
out.append(path)
return out
def readonly_tier_check(
command: str,
*,
cwd: _Path,
inside: _Callable[[_Path], bool],
covers: _Callable[[str, _Path], "list[_Path] | None"],
) -> tuple[bool, str]:
"""(eligible, detail) for the Auto-Approve read-only tier. `cwd` is the shell's current
folder and `inside` says whether a path is inside the session's folders. `covers` is the
engine's shared read-only check, the same one behind the session grant: given one
command and the folder it runs from, it returns the paths the command reads, or None when
the command is not covered. Every rule the grant gains (flag lists, the project's git
settings, the secret-name rule) reaches the tier through it; this function only adds the
sequence handling and the extra fail-closed rules a reviewer-less clearance needs."""
command = str(command or "")
if not command.strip() or any(ord(c) < 32 and c != "\t" for c in command):
return False, "" # empty, or more than one line (each line is its own command)
parts = _split_sequence(command)
if parts is None or not parts or len(parts) > _MAX_PARTS or any(not p for p in parts):
return False, ""
here = _Path(cwd)
if not inside(here):
return False, ""
ran: list[str] = []
for part in parts:
raw = _raw_tokens(part)
if not raw:
return False, ""
raw = _without_harmless_redirects(raw)
if not raw:
return False, ""
if any(c in _unquoted(t) for t in raw for c in "{}"):
return False, "" # brace expansion makes words the checks cannot see
text = " ".join(raw)
stages = _stages(text)
if stages is None:
return False, ""
words = [w for stage in stages for w in stage]
if any(_ENV_ASSIGN.match(stage[0]) for stage in stages):
return False, ""
if any(_flag_carries_path(w) for w in words):
return False, ""
if words[0] == "cd":
if len(stages) != 1 or len(words) != 2 or words[1].startswith("-"):
return False, ""
if any(c in _GLOB_CHARS or c == "~" for c in _unquoted(raw[1])):
return False, ""
target = _Path(words[1])
here = (target if target.is_absolute() else here / target).resolve()
if not inside(here):
return False, ""
ran.append(f"cd {words[1]}")
continue
# The shared check: read-only as the shell runs it, every read (wildcards expanded)
# inside the folders, and whatever else the grant checks.
if covers(text, here) is None:
return False, ""
# A wildcard the shell would expand must be a file operand, and every match is
# checked by the shared check; a wildcard elsewhere (a pattern position) could
# become extra operands. The tier runs only on bash, so bash's operand table applies.
targets = read_targets(text, shell="bash")
globbed = {_unquoted(t) for t in raw if any(c in _GLOB_CHARS for c in _unquoted(t))}
if any(g not in targets for g in globbed):
return False, ""
ran.append(text)
return True, " ; ".join(ran)