shell_sanitize_rules/

env_expansion.rs

use shell_sanitize::{Rule, RuleResult, RuleViolation};

/// Rejects input containing environment variable expansion patterns.
///
/// Detects:
/// - `$NAME` (simple variable reference)
/// - `${NAME}` (braced variable reference)
/// - `%NAME%` (Windows-style variable reference)
///
/// # Intentionally allowed patterns
///
/// The following patterns are **not** flagged:
///
/// - **Positional parameters** (`$1`, `$2`, …) — These start with a digit
///   and are not environment variable names. They are common in pricing text
///   (e.g. `"$5 off"`) and typically cannot leak secrets.
/// - **Lone `$` at end of input** — Not a valid expansion.
///
/// If your use case requires blocking positional parameters as well,
/// combine this rule with [`ShellMetaRule`](crate::ShellMetaRule), which
/// rejects the `$` character itself.
///
/// # Rationale
///
/// Environment variable expansion can leak secrets or alter behavior:
/// ```text
/// $HOME/.ssh/id_rsa   → leaks home directory
/// ${SECRET_KEY}        → leaks credentials
/// %USERPROFILE%        → Windows equivalent
/// ```
pub struct EnvExpansionRule {
    /// Whether to check Windows-style `%VAR%` patterns.
    check_windows: bool,
}

impl Default for EnvExpansionRule {
    fn default() -> Self {
        Self {
            check_windows: true,
        }
    }
}

impl EnvExpansionRule {
    /// Create a POSIX-only rule (skip `%VAR%` detection).
    pub fn posix_only() -> Self {
        Self {
            check_windows: false,
        }
    }
}

impl Rule for EnvExpansionRule {
    fn name(&self) -> &'static str {
        "env_expansion"
    }

    fn check(&self, input: &str) -> RuleResult {
        let mut violations = Vec::new();

        check_dollar_patterns(self.name(), input, &mut violations);

        if self.check_windows {
            check_percent_patterns(self.name(), input, &mut violations);
        }

        if violations.is_empty() {
            Ok(())
        } else {
            Err(violations)
        }
    }
}

/// Detect `$NAME` and `${NAME}` patterns.
///
/// ASCII-only scan: all sentinel characters (`$`, `{`, `(`, `_`) are single-byte
/// ASCII, so byte indices used for `&input[..]` slicing are always valid UTF-8
/// char boundaries.
fn check_dollar_patterns(
    rule_name: &'static str,
    input: &str,
    violations: &mut Vec<RuleViolation>,
) {
    let bytes = input.as_bytes();
    let len = bytes.len();
    let mut i = 0;

    while i < len {
        if bytes[i] == b'$' && i + 1 < len {
            let next = bytes[i + 1];

            if next == b'{' {
                // ${...} pattern
                if let Some(end) = input[i + 2..].find('}') {
                    let var_name = &input[i + 2..i + 2 + end];
                    if !var_name.is_empty() {
                        violations.push(
                            RuleViolation::new(
                                rule_name,
                                format!("environment variable expansion ${{{}}} found", var_name),
                            )
                            .at(i)
                            .with_fragment(format!("${{{}}}", var_name)),
                        );
                    }
                    i = i + 2 + end + 1;
                    continue;
                }
            } else if next == b'(' {
                // $(...) command substitution — handled by ShellMetaRule via `$`
                // but we flag it here too for completeness.
                violations.push(
                    RuleViolation::new(rule_name, "command substitution $(...) found")
                        .at(i)
                        .with_fragment("$("),
                );
                i += 2;
                continue;
            } else if next.is_ascii_alphabetic() || next == b'_' {
                // $NAME pattern
                let start = i;
                let var_start = i + 1;
                let mut var_end = var_start + 1;
                while var_end < len
                    && (bytes[var_end].is_ascii_alphanumeric() || bytes[var_end] == b'_')
                {
                    var_end += 1;
                }
                let var_name = &input[var_start..var_end];
                violations.push(
                    RuleViolation::new(
                        rule_name,
                        format!("environment variable expansion ${} found", var_name),
                    )
                    .at(start)
                    .with_fragment(format!("${}", var_name)),
                );
                i = var_end;
                continue;
            }
        }
        i += 1;
    }
}

/// Detect `%NAME%` patterns (Windows).
///
/// ASCII-only scan: `%` is a single-byte ASCII character, so byte indices
/// are always valid UTF-8 char boundaries.
fn check_percent_patterns(
    rule_name: &'static str,
    input: &str,
    violations: &mut Vec<RuleViolation>,
) {
    let bytes = input.as_bytes();
    let len = bytes.len();
    let mut i = 0;

    while i < len {
        if bytes[i] == b'%' && i + 1 < len {
            // Look for closing %
            if let Some(end) = input[i + 1..].find('%') {
                let var_name = &input[i + 1..i + 1 + end];
                // Require at least one alphanumeric char (skip `%%` empty)
                if !var_name.is_empty()
                    && var_name
                        .bytes()
                        .all(|b| b.is_ascii_alphanumeric() || b == b'_')
                {
                    violations.push(
                        RuleViolation::new(
                            rule_name,
                            format!("Windows environment variable %{}% found", var_name),
                        )
                        .at(i)
                        .with_fragment(format!("%{}%", var_name)),
                    );
                    i = i + 1 + end + 1;
                    continue;
                }
            }
        }
        i += 1;
    }
}