/** * Conservative read-only classifier for shell commands an agent ran. * * Used to decide whether an owner turn changed anything. A command counts as * read-only only when every part of it is clearly read-only; anything unknown, * unparsable, or ambiguous counts as mutating. False "mutating" results only * cost a review; a false "read-only" would skip a needed one. */ export type BashCommandClass = 'read_only' | 'mutating'; type Token = | { kind: 'word'; value: string } | { kind: 'op'; value: string } | { kind: 'redirect'; target: string | null }; /** Redirect targets that write nothing. */ const HARMLESS_REDIRECT_TARGETS = new Set(['/dev/null', '&1', '&2', '-']); // Commands that never modify state, whatever their arguments. const ALWAYS_READ_ONLY = new Set([ ':', '[', '[[', 'basename', 'cat', 'cd', 'cksum', 'cmp', 'column', 'comm', 'cut', 'date', 'df', 'diff', 'dig', 'dirname', 'du', 'echo', 'egrep', 'expr', 'false', 'fgrep', 'file', 'fold', 'free', 'getent', 'grep', 'groups', 'head', 'hexdump', 'host', 'hostname', 'id', 'jq', 'less', 'ls', 'lsblk', 'lsof', 'md5sum', 'more', 'nl', 'nproc', 'nslookup', 'nvidia-smi', 'od', 'paste', 'pgrep', 'printf', 'ps', 'pwd', 'readlink', 'realpath', 'rev', 'rg', 'sha1sum', 'sha256sum', 'sha512sum', 'sleep', 'ss', 'stat', 'strings', 'tac', 'tail', 'test', 'tr', 'tree', 'true', 'type', 'uname', 'uniq', 'uptime', 'wc', 'whereis', 'which', 'whoami', 'xxd', ]); // Prefixes that run the following command; classify what they run. const COMMAND_WRAPPERS = new Set(['sudo', 'timeout', 'nice', 'time', 'env']); const GIT_READ_ONLY_SUBCOMMANDS = new Set([ 'blame', 'cat-file', 'describe', 'diff', 'grep', 'log', 'ls-files', 'ls-remote', 'ls-tree', 'merge-base', 'reflog', 'rev-list', 'rev-parse', 'shortlog', 'show', 'show-ref', 'status', 'whatchanged', ]); const SYSTEMCTL_READ_ONLY = new Set([ 'cat', 'is-active', 'is-enabled', 'is-failed', 'list-dependencies', 'list-timers', 'list-unit-files', 'list-units', 'show', 'status', ]); const DOCKER_READ_ONLY = new Set([ 'images', 'info', 'inspect', 'logs', 'port', 'ps', 'top', 'version', ]); const SQL_WRITE_PATTERN = /\b(?:insert|update|delete|drop|create|alter|replace|attach|detach|vacuum|reindex|begin|commit)\b|\.(?:import|restore|save|backup|output|once)\b|pragma\s+\w+\s*=/i; /** Split a command line into words, operators and redirects (quote-aware). */ function tokenize(command: string): Token[] | null { const tokens: Token[] = []; let current = ''; let hasCurrent = false; let pendingRedirect = false; const pushWord = () => { if (!hasCurrent) return; if (pendingRedirect) { tokens.push({ kind: 'redirect', target: current }); pendingRedirect = false; } else { tokens.push({ kind: 'word', value: current }); } current = ''; hasCurrent = false; }; const pushOp = (value: string) => { pushWord(); if (pendingRedirect) return false; tokens.push({ kind: 'op', value }); return true; }; for (let i = 0; i < command.length; i += 1) { const ch = command[i]; if (ch === "'") { const end = command.indexOf("'", i + 1); if (end < 0) return null; current += command.slice(i + 1, end); hasCurrent = true; i = end; continue; } if (ch === '"') { let j = i + 1; let value = ''; for (; j < command.length && command[j] !== '"'; j += 1) { if (command[j] === '\\' && j + 1 < command.length) { value += command[j + 1]; j += 1; continue; } // Command substitution inside double quotes still runs a command. if (command[j] === '`' || command.startsWith('$(', j)) return null; value += command[j]; } if (j >= command.length) return null; current += value; hasCurrent = true; i = j; continue; } if (ch === '\\' && i + 1 < command.length) { if (command[i + 1] !== '\n') { current += command[i + 1]; hasCurrent = true; } i += 1; continue; } if ( ch === '`' || command.startsWith('$(', i) || command.startsWith('<(', i) ) return null; if (ch === ' ' || ch === '\t') { pushWord(); continue; } if (ch === '\n' || ch === ';') { if (!pushOp(';')) return null; continue; } if (ch === '&') { if (command[i + 1] === '&') { if (!pushOp('&&')) return null; i += 1; continue; } if (command[i + 1] === '>') { // &> / &>> redirect stdout+stderr. pushWord(); pendingRedirect = true; i += command[i + 2] === '>' ? 2 : 1; continue; } // A trailing/background "&" — treat like a separator. if (!pushOp(';')) return null; continue; } if (ch === '|') { if (command[i + 1] === '|') { if (!pushOp('||')) return null; i += 1; continue; } if (!pushOp('|')) return null; continue; } if (ch === '>') { // An fd number glued to the operator ("2>") is part of the redirect. if (/^\d+$/.test(current)) { current = ''; hasCurrent = false; } pushWord(); pendingRedirect = true; if (command[i + 1] === '>' || command[i + 1] === '|') i += 1; if (command[i + 1] === '&') { // 2>&1 style: the target is the fd that follows. let j = i + 2; let fd = '&'; while (j < command.length && /[\d-]/.test(command[j])) { fd += command[j]; j += 1; } tokens.push({ kind: 'redirect', target: fd }); pendingRedirect = false; i = j - 1; } continue; } if (ch === '<') { // Input redirects and here-docs read only; the following word is input. pushWord(); if (command[i + 1] === '<') return null; // here-doc bodies are opaque continue; } if (ch === '(' || ch === ')' || ch === '{' || ch === '}') { if (!hasCurrent) return null; // subshells / groups current += ch; continue; } current += ch; hasCurrent = true; } pushWord(); if (pendingRedirect) tokens.push({ kind: 'redirect', target: null }); return tokens; } function hasFlag(args: string[], ...flags: string[]): boolean { return args.some((arg) => flags.some( (flag) => arg === flag || (flag.startsWith('--') && arg.startsWith(`${flag}=`)) || // Bundled short flags like "-iE" for "-i". (flag.length === 2 && flag.startsWith('-') && /^-[a-zA-Z]+$/.test(arg) && arg.includes(flag[1])), ), ); } function positional(args: string[]): string[] { return args.filter((arg) => !arg.startsWith('-')); } /** First non-option argument, skipping the values of options that take one. */ function firstPositional( args: string[], optionsWithValue: ReadonlySet, ): string | undefined { for (let i = 0; i < args.length; i += 1) { const arg = args[i]; if (!arg.startsWith('-')) return arg; if (optionsWithValue.has(arg)) i += 1; } return undefined; } const SYSTEMCTL_OPTIONS_WITH_VALUE = new Set([ '-p', '--property', '-n', '--lines', '-o', '--output', '-t', '--type', '-H', '--host', '-M', '--machine', '--state', ]); const COMPOSE_OPTIONS_WITH_VALUE = new Set([ '-f', '--file', '-p', '--project-name', '--project-directory', '--env-file', '--profile', ]); function isReadOnlyGit(args: string[]): boolean { const rest = [...args]; // Global options before the subcommand. while (rest.length > 0 && rest[0].startsWith('-')) { const option = rest.shift()!; if (option === '-c') return false; // config overrides can run hooks/aliases if (option === '-C') { rest.shift(); continue; } if (option !== '--no-pager' && option !== '-P') return false; } const [sub, ...subArgs] = rest; if (!sub) return true; if (GIT_READ_ONLY_SUBCOMMANDS.has(sub)) { if (sub === 'diff' && hasFlag(subArgs, '--output')) return false; return true; } if (sub === 'branch') { if ( hasFlag( subArgs, '-d', '-D', '-m', '-M', '-c', '-C', '-f', '-u', '--delete', '--move', '--copy', '--force', '--set-upstream-to', '--unset-upstream', '--edit-description', ) ) { return false; } // "git branch " creates a branch; only listing forms are read-only. const listing = hasFlag(subArgs, '--list', '-l', '--contains', '--merged'); return listing || positional(subArgs).length === 0; } if (sub === 'tag') { return hasFlag(subArgs, '-l', '--list') || subArgs.length === 0; } if (sub === 'remote') { return ( subArgs.length === 0 || (subArgs.length === 1 && subArgs[0] === '-v') || subArgs[0] === 'show' || subArgs[0] === 'get-url' ); } if (sub === 'stash') { return subArgs[0] === 'list' || subArgs[0] === 'show'; } if (sub === 'worktree') return subArgs[0] === 'list'; if (sub === 'config') { return hasFlag(subArgs, '--get', '--get-all', '--list', '-l'); } return false; } function isReadOnlySystemctl(args: string[]): boolean { const sub = firstPositional(args, SYSTEMCTL_OPTIONS_WITH_VALUE); return sub !== undefined && SYSTEMCTL_READ_ONLY.has(sub); } function isReadOnlyDocker(args: string[]): boolean { const rest = [...args]; while (rest.length > 0 && rest[0].startsWith('-')) { const option = rest.shift()!; if (option === '--context' || option === '-c' || option === '-H') { rest.shift(); } else if (!option.startsWith('--context=')) { return false; } } const [sub, ...subArgs] = rest; if (!sub) return false; if (DOCKER_READ_ONLY.has(sub)) return true; if (sub === 'stats') return hasFlag(subArgs, '--no-stream'); if (sub === 'context') return subArgs[0] === 'ls' || subArgs[0] === 'show'; if (sub === 'compose') { const composeSub = firstPositional(subArgs, COMPOSE_OPTIONS_WITH_VALUE); return ( composeSub === 'ps' || composeSub === 'logs' || composeSub === 'config' || composeSub === 'ls' ); } return false; } function isReadOnlyCurl(args: string[]): boolean { if ( hasFlag( args, '-d', '-F', '-T', '-o', '-O', '-K', '--data', '--data-raw', '--data-binary', '--data-urlencode', '--json', '--form', '--upload-file', '--output', '--remote-name', '--remote-name-all', '--config', '--cookie-jar', '-c', ) ) { return false; } for (let i = 0; i < args.length; i += 1) { const arg = args[i]; let method: string | undefined; if (arg === '-X' || arg === '--request') method = args[i + 1]; else if (arg.startsWith('--request=')) method = arg.slice(10); else if (/^-X[A-Za-z]+$/.test(arg)) method = arg.slice(2); if (method !== undefined && !/^(?:GET|HEAD|OPTIONS)$/i.test(method)) { return false; } } return true; } function isReadOnlyWget(args: string[]): boolean { if (hasFlag(args, '--post-data', '--post-file', '--method', '--body-data')) { return false; } if (hasFlag(args, '--spider')) return true; // Only "print to stdout" forms: -O - / -qO- / --output-document=-. return args.some( (arg, i) => ((arg === '-O' || arg === '--output-document') && args[i + 1] === '-') || /^-[a-zA-Z]*O-$/.test(arg) || arg === '--output-document=-', ); } function isReadOnlySqlite(args: string[]): boolean { const readonly = hasFlag(args, '-readonly', '--readonly') || args.some((arg) => /^file:.*[?&]mode=ro\b/.test(arg)); if (!readonly) return false; return !args.some((arg) => SQL_WRITE_PATTERN.test(arg)); } function isReadOnlyFind(args: string[]): boolean { return !args.some((arg) => /^-(?:delete|exec|execdir|ok|okdir|fprint|fprint0|fprintf|fls)$/.test(arg), ); } function isReadOnlySed(args: string[]): boolean { if (hasFlag(args, '-i', '--in-place')) return false; // The "w file" / "W file" commands write files. return !args.some((arg) => /(?:^|[;/}\s])[wW]\s+\S/.test(arg)); } function isReadOnlyGh(args: string[]): boolean { const [group, action, ...rest] = args; if (group === 'api') { const apiArgs = [action, ...rest].filter((a): a is string => !!a); if ( hasFlag(apiArgs, '-f', '-F', '--field', '--raw-field', '--input') || apiArgs.some((arg, i) => { const method = arg === '-X' || arg === '--method' ? apiArgs[i + 1] : arg.startsWith('--method=') ? arg.slice(9) : undefined; return method !== undefined && !/^GET$/i.test(method); }) ) { return false; } return true; } const readActions = new Set([ 'list', 'view', 'status', 'diff', 'checks', 'watch', ]); return ( ['pr', 'run', 'issue', 'release', 'repo', 'workflow'].includes(group) && readActions.has(action) ); } function isReadOnlyKill(args: string[]): boolean { // "kill -0 " only checks that the process exists; "kill -l" lists signals. return args[0] === '-0' || args[0] === '-l'; } /** Strip wrapper commands (sudo, timeout, env, ...) and variable assignments. */ function unwrapCommand(words: string[]): string[] { let rest = words; for (;;) { while (rest.length > 0 && /^[A-Za-z_][A-Za-z0-9_]*=/.test(rest[0])) { rest = rest.slice(1); } const [head, ...tail] = rest; if (!head || !COMMAND_WRAPPERS.has(head)) return rest; let next = tail; if (head === 'sudo') { while (next.length > 0 && next[0].startsWith('-')) { const option = next[0]; next = next.slice(1); if (option === '-u' || option === '-g') next = next.slice(1); } } else if (head === 'timeout') { while (next.length > 0 && next[0].startsWith('-')) { const option = next[0]; next = next.slice(1); if (option === '-s' || option === '-k') next = next.slice(1); } next = next.slice(1); // duration } else if (head === 'nice') { if (next[0] === '-n') next = next.slice(2); else if (next[0]?.startsWith('-')) next = next.slice(1); } else if (head === 'env') { while (next.length > 0 && next[0].startsWith('-')) next = next.slice(1); } else if (head === 'time') { while (next.length > 0 && next[0].startsWith('-')) next = next.slice(1); } if (next.length === 0) return head === 'env' ? ['env'] : []; rest = next; } } function isReadOnlySimpleCommand(words: string[]): boolean { const unwrapped = unwrapCommand(words); if (unwrapped.length === 0) return true; // bare assignment const [rawCommand, ...args] = unwrapped; const command = rawCommand.split('/').at(-1) ?? rawCommand; if (ALWAYS_READ_ONLY.has(command)) return true; switch (command) { case 'env': case 'printenv': return args.length === 0 || command === 'printenv'; case 'export': case 'unset': case 'local': case 'set': return true; // shell-local state only case 'git': return isReadOnlyGit(args); case 'systemctl': return isReadOnlySystemctl(args); case 'journalctl': return !hasFlag( args, '--rotate', '--flush', '--sync', '--vacuum-size', '--vacuum-time', '--vacuum-files', ); case 'docker': return isReadOnlyDocker(args); case 'curl': return isReadOnlyCurl(args); case 'wget': return isReadOnlyWget(args); case 'sqlite3': return isReadOnlySqlite(args); case 'find': return isReadOnlyFind(args); case 'sed': return isReadOnlySed(args); case 'sort': return !hasFlag(args, '-o', '--output'); case 'awk': case 'gawk': return !args.some((arg) => /\bsystem\s*\(|\bprint[^;]*>|getline/.test(arg), ); case 'gh': return isReadOnlyGh(args); case 'kill': return isReadOnlyKill(args); case 'crontab': return args.length === 1 && args[0] === '-l'; case 'tsc': return hasFlag(args, '--noEmit'); case 'ip': return ( args.length > 0 && ['addr', 'a', 'route', 'r', 'link', 'l', 'neigh'].includes(args[0]) && (args.length === 1 || args[1] === 'show' || args[1] === 'list') ); case 'ping': return hasFlag(args, '-c'); case 'top': return hasFlag(args, '-b'); default: return false; } } /** * Classify one shell command line. Read-only only when every pipeline segment * is a known read-only command and nothing is redirected into a file. */ export function classifyBashCommand(command: string): BashCommandClass { const trimmed = command.trim(); if (!trimmed) return 'read_only'; const tokens = tokenize(trimmed); if (!tokens) return 'mutating'; let words: string[] = []; const segments: string[][] = []; for (const token of tokens) { if (token.kind === 'redirect') { if (!token.target || !HARMLESS_REDIRECT_TARGETS.has(token.target)) { return 'mutating'; } continue; } if (token.kind === 'op') { if (words.length > 0) segments.push(words); words = []; continue; } words.push(token.value); } if (words.length > 0) segments.push(words); for (const segment of segments) { if (segment[0] === 'xargs') { // xargs runs the command that follows its own options. let rest = segment.slice(1); while (rest.length > 0 && rest[0].startsWith('-')) { const option = rest[0]; rest = rest.slice(1); if (/^-[IdEsLnP]$/.test(option)) rest = rest.slice(1); } if (rest.length === 0 || !isReadOnlySimpleCommand(rest)) { return 'mutating'; } continue; } if (!isReadOnlySimpleCommand(segment)) return 'mutating'; } return 'read_only'; }