openmoat-core 0.5.7

//! Shell command classification (docs/ARCHITECTURE.md §3, docs/POLICY.md §3.1).
//!
//! A command line is lexed ([`crate::lexer`]), grouped into simple commands,
//! and each simple command is decomposed into [`AtomicAction`]s:
//!
//! | Source | Atomic action |
//! |---|---|
//! | the command itself | `Shell { argv }`; for `git`, without its global options (`git.rs`) |
//! | every pipeline / list suffix with ≥ 2 commands | `Pipeline { argv }` |
//! | a decoder stage piped into an interpreter reading stdin (`decoders.rs`) | canonical `Pipeline { <decoder> -d \| <interpreter> }` |
//! | leading `VAR=value`, `export`/`declare`/`set` assignments | `EnvSet` |
//! | `$VAR` / `${VAR}` references, `printenv NAME` | `EnvRead` |
//! | path-looking arguments, relative operands (`operands.rs`), `<` targets other than `/dev/null` and stdin, `source`/`.` files | `FsRead`, one per directory `cd` may have moved to (`cwd.rs`); also listed as a glob when unquoted `* ? [` make the shell expand it (`crate::expand`) |
//! | `>`/`>>`/`&>` targets other than `/dev/null` and the standard streams (`tables::STREAM_SINKS`), `tee`, destructive/destination args | `FsWrite` |
//! | URLs with any host, bare dotted names under a known TLD, IPv4 literals (`crate::host`) | `Net` |
//! | `$( … )`, backticks, `sh -c` (any option spelling, `invocation.rs`), `eval`, `xargs`, `sudo`, `env`, … | nested classification |
//! | `python -c`, `node -e`, `perl -e`, … payloads | URL/path scan of the payload |
//! | `find -exec/-execdir/-ok/-okdir` commands, `--output=FILE`, `gofmt -w` operands (`options.rs`) | nested classification, `FsWrite` |
//! | `watch`, `git rebase --exec`, `git submodule foreach`, `git bisect run`, `ssh -o ProxyCommand=`, `rsync -e` (`embedded.rs`) | nested classification |
//! | `file:` URLs (`curl file:///etc/passwd`) | `FsRead` |
//! | files `curl -F`/`-T`/`-d @` and `wget --post-file` send (`upload.rs`) | `FsRead` |
//! | `perl -i`/`ruby -i` operands, `patch` targets and `-o` (`in_place.rs`) | `FsWrite` |
//! | `xargs` input on the command line, `env -S 'cmd'` (`commands/wrappers.rs`) | nested classification |
//! | local git remotes, `git clone` destinations, `--upload-pack` (`git.rs`, `embedded.rs`) | `FsRead`, `FsWrite`, nested classification |
//! | `make --eval`, `-e`, `SHELL=`, `X!=cmd`, `$(shell …)` (`make.rs`) | `make <arg>` `Shell` atom + nested classification |
//! | text tool options (`text.rs`): `sort -o FILE`, `uniq in out`; an unknown option | `FsWrite`; `<program> @<option>` `Shell` atom |
//! | `sed` scripts (`sed/`): `r FILE`, `w FILE`; `e`, anything not understood | `FsRead`, `FsWrite`; `sed @<script>` `Shell` atom |
//! | `awk` programs (`awk.rs`) with `system`, `\|`, `getline`, `ENVIRON`, `ARGV`, `@`, `print … >` | `awk @<program>` `Shell` atom |
//!
//! Classification is conservative by design: when the input cannot be parsed
//! safely the result is [`ParseOutcome::Unparseable`], which the engine maps to
//! `ask`, never `allow`. A simple command (or a path in it) that cannot be
//! classified does not stop the others: their atoms are kept, so a `deny` among
//! them still wins over the `ask`. `<<<` here-strings and here-document bodies are data,
//! except that the substitutions and variables the shell expands in them are
//! classified and a shell or interpreter reading stdin runs them as its program.
//!
//! Module layout: `commands` groups tokens and classifies each simple command;
//! `tokens` recognises assignments and variable references inside one word;
//! `invocation` parses a shell's own options (`bash -lc`, `sh -ec`, `--login`);
//! `git` takes git's global options out of the command;
//! `operands` decides which plain arguments name files, and `copy` where a copy
//! or a move writes (`cp f ~/` writes `~/f`);
//! `decoders`, `make`, `options` and `embedded` handle constructs that hide a command or a
//! write (decoded pipelines, make arguments, `find -exec`, `--output=`, `watch 'cmd'`,
//! `git rebase --exec`, `ssh -o ProxyCommand=`);
//! `text` reads the options of text tools, whose values are data, not files,
//! and `sed` and `awk` their programs;
//! `tables` holds the program lists that drive all of them.

mod awk;
mod commands;
mod copy;
mod cwd;
mod database;
mod decoders;
mod embedded;
mod error;
pub(crate) mod git;
mod in_place;
mod invocation;
mod make;
mod operands;
mod options;
mod path_options;
pub(crate) mod push;
mod sed;
pub(crate) mod tables;
#[cfg(test)]
mod tests;
mod text;
pub(crate) mod tokens;
mod upload;

pub(crate) use error::ClassifyError;

use crate::action::AtomicAction;
use crate::lexer::Token;
use crate::paths;

/// Result of classifying a command line.
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum ParseOutcome {
    Parsed(Vec<AtomicAction>),
    /// Some part could not be classified (`reason`); `atoms` are the parts that
    /// were, still decided so that a `deny` among them is not lost. `asks` when
    /// the line could not be read in full or a classifier limit was reached
    /// ([`ClassifyError::asks`]).
    Unparseable {
        reason: String,
        atoms: Vec<AtomicAction>,
        asks: bool,
    },
}

/// Why part of an action could not be classified.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct Unparsed {
    pub reason: String,
    /// The engine asks, whatever the policy's catch-all says: the atoms of the
    /// rest of the line may be missing, so a deny among them must not become
    /// a `defer` (padding a command until the classifier gives up).
    pub asks: bool,
}

impl ParseOutcome {
    /// The atoms classified, and why the rest could not be, if anything was left.
    #[must_use]
    pub fn into_parts(self) -> (Vec<AtomicAction>, Option<Unparsed>) {
        match self {
            Self::Parsed(atoms) => (atoms, None),
            Self::Unparseable {
                reason,
                atoms,
                asks,
            } => (atoms, Some(Unparsed { reason, asks })),
        }
    }
}

/// The program of a command's argv, without its directory (`/usr/bin/curl` → `curl`).
pub(crate) fn program_name(argv: &[String]) -> &str {
    argv.first().map_or("", |p| tokens::basename(p))
}

/// Whether the command connects where its arguments say: a program of
/// [`tables::HOST_PROGRAMS`], or `git` with a subcommand that names a remote.
pub(crate) fn names_hosts(argv: &[String]) -> bool {
    let program = program_name(argv);
    tables::HOST_PROGRAMS.contains(&program) || (program == "git" && git::names_hosts(argv))
}

/// What `${project}` is in a shell word: the shell's variable `project`, not
/// the policy's project root. Unset it expands to nothing, which is what the
/// word is resolved with; set by the line it is substituted (`locals.rs`), and
/// otherwise its value is not known (`paths::has_unexpanded_variable`).
const WORD_PROJECT: Option<&str> = None;

/// Context needed to normalise paths inside a command. No I/O.
#[derive(Debug, Clone, Copy)]
pub struct ShellContext<'a> {
    pub home: &'a str,
    /// Every directory the command may be running in: the session's working
    /// directory, plus wherever an earlier `cd` may have moved (`cwd.rs`).
    /// `None` is a directory that cannot be known (`cd "$X"`, `cd -`).
    pub cwd: &'a [Option<String>],
}

impl ShellContext<'_> {
    /// Every canonical path a shell word may name: one per possible working
    /// directory for a relative word. An error when one of them is not known
    /// (`~-`, or a relative word after `cd "$X"`), which makes the command `ask`.
    pub(crate) fn paths(&self, word: &str) -> Result<Vec<String>, ClassifyError> {
        if let Some(path) = paths::resolve(word, self.home, WORD_PROJECT, None) {
            return Ok(vec![path]);
        }
        self.cwd
            .iter()
            .map(|cwd| {
                paths::resolve(word, self.home, WORD_PROJECT, cwd.as_deref())
                    .ok_or_else(|| ClassifyError::UnknownDirectory(word.to_owned()))
            })
            .collect()
    }

    /// The absolute forms of `word` that kept a `..` (`c/../x`), one per
    /// possible working directory: the engine resolves them where the OS would
    /// (`crate::realpath::physical`). Empty when `word` has no `..` or its
    /// directory is not known ([`Self::paths`] already reports that).
    pub(crate) fn traversals(&self, word: &str) -> Vec<String> {
        if let Some(path) = paths::traversal(word, self.home, WORD_PROJECT, None) {
            return vec![path];
        }
        self.cwd
            .iter()
            .filter_map(|cwd| paths::traversal(word, self.home, WORD_PROJECT, cwd.as_deref()))
            .collect()
    }
}

/// Maximum nesting of `$( … )`, `sh -c`, `eval` and wrapper commands.
pub const MAX_DEPTH: u8 = 4;
/// Upper bound on atomic actions per command line, to bound work on hostile input.
pub const MAX_ATOMS: usize = 2048;
/// Upper bound on the directories one command line may be running in after `cd`.
pub const MAX_DIRS: usize = 16;

/// Classify a shell command string into atomic actions.
#[cfg(test)]
#[must_use]
pub fn classify(command: &str, ctx: &ShellContext<'_>) -> ParseOutcome {
    classify_globs(command, ctx).0
}

/// Classify a shell command string into atomic actions, and list the reads
/// and writes among them whose path is a glob the shell expands
/// (`crate::expand`), each with whether a last component starting with `.`
/// may name `.` and `..` ([`Sink::refuse_dot_dirs`]).
#[must_use]
pub fn classify_globs(
    command: &str,
    ctx: &ShellContext<'_>,
) -> (ParseOutcome, Vec<(AtomicAction, bool)>) {
    let mut sink = Sink::default();
    let mut stopped = commands::classify_into(command, ctx, &mut sink, 0).err();
    // `cat${IFS}~/.ssh/id_rsa`: the shell splits words where `$IFS` expands. The
    // line is classified a second time with it read as a space, and both sets of
    // actions count, so the split never loosens the verdict.
    let split = command.replace("${IFS}", " ").replace("$IFS", " ");
    if split != command {
        let again = commands::classify_into(&split, ctx, &mut sink, 0).err();
        stopped = stopped.or(again);
    }
    let asks = sink.asks || stopped.as_ref().is_some_and(ClassifyError::asks);
    let outcome = match sink.skipped.or(stopped) {
        Some(e) => ParseOutcome::Unparseable {
            reason: e.to_string(),
            atoms: sink.atoms,
            asks,
        },
        None if sink.atoms.is_empty() => ParseOutcome::Unparseable {
            reason: "no command found".to_owned(),
            atoms: Vec::new(),
            asks: false,
        },
        None => ParseOutcome::Parsed(sink.atoms),
    };
    (outcome, sink.globs)
}

/// All lowercase letters, digits and `_`, with one letter at least: a shell
/// variable by convention, not an environment variable.
pub(crate) fn is_lowercase(name: &str) -> bool {
    name.bytes().any(|b| b.is_ascii_lowercase())
        && name
            .bytes()
            .all(|b| b.is_ascii_lowercase() || b.is_ascii_digit() || b == b'_')
}

/// Accumulates atomic actions with de-duplication and a hard size bound.
///
/// Every classifier function writes through a `&mut Sink`, never a bare
/// `Vec`, so no code path can exceed [`MAX_ATOMS`].
#[derive(Debug, Default)]
pub(crate) struct Sink {
    atoms: Vec<AtomicAction>,
    /// The first part classification went past without understanding it.
    skipped: Option<ClassifyError>,
    /// Whether any part skipped was one that asks ([`ClassifyError::asks`]).
    asks: bool,
    /// Words of the command line, nested commands included, that the shell
    /// expands as globs ([`crate::lexer::Word::glob`]).
    glob_words: Vec<String>,
    /// Read and write atoms whose path is one of those globs: the engine
    /// evaluates every file it matches as well as the literal path.
    globs: Vec<(AtomicAction, bool)>,
    /// The command being classified refuses `.` and `..` as operands (`rm`,
    /// `rmdir`), so a glob of its own does not name them.
    no_dot_dirs: bool,
    /// Words of the command line with a `$` the shell expands (not one from
    /// single quotes): a path taken from one is not known as written.
    dollar_words: Vec<String>,
    /// Shell variables an earlier command of the line set on its own (`x=1;`,
    /// `for x in`, `export X=1`), with the nesting depth and the values they may
    /// hold, when those are known text. Such a variable is substituted where it
    /// is used, whatever its case; reading a lowercase one is no environment
    /// read, while an uppercase name, by convention an environment variable,
    /// keeps its `env.read`. A child shell (`sh -c`) does not see them.
    locals: Vec<(String, u8, Option<Vec<String>>)>,
    /// The nesting depth of the simple command being classified.
    depth: u8,
    /// Commands that publish commits (`push.rs`).
    pushes: Vec<push::Push>,
}

impl Sink {
    /// Classify the next simple command at `depth`.
    pub(crate) fn enter(&mut self, depth: u8) {
        self.depth = depth;
        self.no_dot_dirs = false;
    }

    /// The command being classified is `program`: `rm` and `rmdir` refuse to
    /// remove `.` and `..` (POSIX), so `rm -rf .*` does not reach the parent.
    pub(crate) fn refuse_dot_dirs(&mut self, program: &str) {
        self.no_dot_dirs = matches!(program, "rm" | "rmdir");
    }

    /// `name`, set by a command of its own, is a shell variable from here on, if
    /// it is all lowercase: environment variables, secrets among them, are by
    /// convention uppercase, and deny rules name them so.
    pub(crate) fn note_local(&mut self, name: &str, values: Option<Vec<String>>) {
        // a later assignment replaces the earlier one
        self.locals
            .retain(|(n, d, _)| !(n == name && *d == self.depth));
        self.locals.push((name.to_owned(), self.depth, values));
    }

    /// The variables at `depth` whose values are all known.
    pub(crate) fn known_locals(&self, depth: u8) -> Vec<(String, Vec<String>)> {
        self.locals
            .iter()
            .filter(|(_, d, _)| *d == depth)
            .filter_map(|(n, _, v)| Some((n.clone(), v.clone()?)))
            .collect()
    }

    pub(crate) fn push(&mut self, atom: AtomicAction) -> Result<(), ClassifyError> {
        if let AtomicAction::EnvRead { name } = &atom
            && is_lowercase(name)
            && self
                .locals
                .iter()
                .any(|(n, d, v)| n == name && *d == self.depth && v.is_some())
        {
            return Ok(());
        }
        if self.atoms.contains(&atom) {
            return Ok(());
        }
        if self.atoms.len() >= MAX_ATOMS {
            return Err(ClassifyError::TooManyActions);
        }
        self.atoms.push(atom);
        Ok(())
    }

    /// Note a part that could not be classified and carry on with the rest:
    /// the command still asks, and what else it does is still decided.
    pub(crate) fn skip(&mut self, error: ClassifyError) {
        self.asks |= error.asks();
        self.skipped.get_or_insert(error);
    }

    /// Whether `word` uses `HOME`, `PWD` or `project` after the line gave it a
    /// value that is not known (`project=$(cat f)`, `read HOME`): path
    /// resolution reads those names as the real home, working directory and
    /// project, which the shell no longer does.
    fn overrides_a_known_name(&self, word: &str) -> bool {
        ["HOME", "PWD", "project"].iter().any(|name| {
            let refers = word.contains(&format!("${{{name}}}"))
                || word.match_indices(&format!("${name}")).any(|(at, _)| {
                    !word[at + 1 + name.len()..]
                        .starts_with(|c: char| c.is_ascii_alphanumeric() || c == '_')
                });
            refers
                && self
                    .locals
                    .iter()
                    .any(|(n, d, v)| n == name && *d == self.depth && v.is_none())
        })
    }

    /// Every path `word` may name, or none when one of them is not known (skipped).
    fn paths(&mut self, ctx: &ShellContext<'_>, word: &str) -> Vec<String> {
        // `cat $d/id_rsa`: the literal path is still checked, so a deny on it wins,
        // but the file the shell opens is not known
        if (paths::has_unexpanded_variable(word) || self.overrides_a_known_name(word))
            && self.dollar_words.iter().any(|w| w.contains(word))
        {
            // `@unknown-path <word>`: a rule can ask for a secret's file name in a
            // directory OpenMoat cannot place (`secret-names`)
            let atom = AtomicAction::Shell {
                argv: vec!["@unknown-path".to_owned(), word.to_owned()],
            };
            if let Err(full) = self.push(atom) {
                self.skip(full);
            }
            self.skip(ClassifyError::UnknownValue(word.to_owned()));
        }
        ctx.paths(word).unwrap_or_else(|e| {
            // Another user's home cannot be placed, and it may hold that user's
            // secrets: `@other-home <word>`, which the `other-home` rule asks for.
            if paths::other_user_home(word, ctx.home) {
                let atom = AtomicAction::Shell {
                    argv: vec!["@other-home".to_owned(), word.to_owned()],
                };
                if let Err(full) = self.push(atom) {
                    self.skip(full);
                }
            }
            self.skip(e);
            Vec::new()
        })
    }

    /// Remember the words of `tokens` the shell expands as globs, and those
    /// with a `$` it expands.
    pub(crate) fn note_globs(&mut self, tokens: &[Token]) {
        for token in tokens {
            if let Token::Word(w) = token {
                if w.glob && !self.glob_words.contains(&w.text) {
                    self.glob_words.push(w.text.clone());
                }
                self.note_dollar_word(w);
            }
        }
    }

    /// Remember `word` when the shell expands a `$` or a command substitution in it.
    pub(crate) fn note_dollar_word(&mut self, word: &crate::lexer::Word) {
        let expands = !word.substitutions.is_empty()
            || word
                .text
                .match_indices('$')
                .any(|(pos, _)| !word.literal.iter().any(|span| span.contains(&pos)));
        if expands && !self.dollar_words.contains(&word.text) {
            self.dollar_words.push(word.text.clone());
        }
    }

    /// An `FsRead` for every path `word` may name.
    pub(crate) fn read(&mut self, ctx: &ShellContext<'_>, word: &str) -> Result<(), ClassifyError> {
        self.fs(ctx, word, |path| AtomicAction::FsRead { path })
    }

    /// An `FsWrite` for every path `word` may name.
    pub(crate) fn write(
        &mut self,
        ctx: &ShellContext<'_>,
        word: &str,
    ) -> Result<(), ClassifyError> {
        self.fs(ctx, word, |path| AtomicAction::FsWrite { path })
    }

    /// An `FsRead` for every path a `<` redirection from `word` may name,
    /// except the empty source and standard input (`tables::STREAM_SOURCES`).
    pub(crate) fn redirect_read(
        &mut self,
        ctx: &ShellContext<'_>,
        word: &str,
    ) -> Result<(), ClassifyError> {
        self.redirect(ctx, word, tables::STREAM_SOURCES, |path| {
            AtomicAction::FsRead { path }
        })
    }

    /// An `FsWrite` for every path a `>` redirection to `word` may name,
    /// except the data sink and standard output and error (`tables::STREAM_SINKS`).
    pub(crate) fn redirect_write(
        &mut self,
        ctx: &ShellContext<'_>,
        word: &str,
    ) -> Result<(), ClassifyError> {
        self.redirect(ctx, word, tables::STREAM_SINKS, |path| {
            AtomicAction::FsWrite { path }
        })
    }

    /// `fs` for a redirection target, skipped when it resolves to one of
    /// `streams`. A glob is never skipped: the shell may expand it to a file.
    fn redirect(
        &mut self,
        ctx: &ShellContext<'_>,
        word: &str,
        streams: &[&str],
        atom: fn(String) -> AtomicAction,
    ) -> Result<(), ClassifyError> {
        let stream = !word.contains(['*', '?', '['])
            && ctx
                .paths(word)
                .is_ok_and(|paths| paths.iter().all(|p| streams.contains(&p.as_str())));
        if stream {
            return Ok(());
        }
        self.fs(ctx, word, atom)
    }

    /// An atom for every path `word` may name, also kept as a glob when `word`
    /// is, or ends, a word the shell expands (`@file` and `--out=FILE` keep
    /// the glob of their word). An operand with the text of a glob elsewhere
    /// in the command line is expanded too: stricter, never looser.
    fn fs(
        &mut self,
        ctx: &ShellContext<'_>,
        word: &str,
        atom: fn(String) -> AtomicAction,
    ) -> Result<(), ClassifyError> {
        let glob =
            word.contains(['*', '?', '[']) && self.glob_words.iter().any(|w| w.ends_with(word));
        // a `..` is also kept, to be followed where the OS goes (through a symlink)
        let traversals = ctx.traversals(word);
        for path in self.paths(ctx, word).into_iter().chain(traversals) {
            let atom = atom(path);
            let entry = (atom.clone(), !self.no_dot_dirs);
            if glob && !self.globs.contains(&entry) {
                self.globs.push(entry);
            }
            self.push(atom)?;
        }
        Ok(())
    }
}