shell_sanitize_rules/

presets.rs

//! Ready-made sanitizer configurations for common threat models.
//!
//! Each preset returns a fully configured [`Sanitizer`] with rules
//! matched to a specific use case. Choose based on **how the validated
//! value will be consumed**:
//!
//! | Preset | Target context | Rules |
//! |--------|---------------|-------|
//! | [`command_arg`] | `Command::new().arg()` | ControlChar |
//! | [`shell_command`] | `sh -c`, SSH, popen | ShellMeta + ControlChar + EnvExpansion + Glob |
//! | [`file_path`] | Upload dest, include | PathTraversal + ControlChar |
//! | [`file_path_absolute`] | Config file, absolute OK | PathTraversal(allow_abs) + ControlChar |
//! | [`strict`] | SSH remote path ops, max protection | All 5 rules |
//!
//! # AI agent use case
//!
//! When an LLM generates tool calls (e.g. Claude Code, Copilot, Devin),
//! treat the **data arguments** as untrusted input — indirect prompt
//! injection can manipulate what the AI produces.
//!
//! ## What this crate CAN validate
//!
//! **Path arguments** from structured tool calls — this is the primary
//! value for AI agents:
//!
//! ```text
//! AI: { tool: "read_file", path: "../../etc/shadow" }
//!                                 ^^^^^^^^^^^^^^^^
//!                                 file_path() catches this
//!
//! AI: { tool: "write_file", path: "/etc/crontab" }
//!                                 ^^^^^^^^^^^^^
//!                                 file_path() catches this
//! ```
//!
//! **Individual arguments** when the framework provides structured
//! tool calls:
//!
//! ```text
//! AI: { tool: "git_clone", url: "https://evil.com; rm -rf /" }
//!                                ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
//!                                shell_command() catches the `;`
//! ```
//!
//! **Template slots** when a trusted template is filled with AI data:
//!
//! ```text
//! Template (hardcoded):  "rsync -avz {} {}"
//! Slot 1 (file_path):    validated_src
//! Slot 2 (shell_command): validated_dest
//! ```
//!
//! ## What this crate CANNOT validate
//!
//! **Free-form bash command strings** — the AI generates the entire
//! command, not just arguments:
//!
//! ```text
//! AI: Bash("git diff HEAD~3")           ← legitimate
//! AI: Bash("git diff HEAD~3; rm -rf /") ← injection
//!
//! Sanitizing the full string would break the legitimate command.
//! This requires: sandbox, container isolation, command allowlist.
//! ```
//!
//! ## Preset selection for AI tool calls
//!
//! | AI tool type | Preset | Example |
//! |-------------|--------|---------|
//! | File read/write | [`file_path`] | `read("src/lib.rs")` |
//! | Config file | [`file_path_absolute`] | `read("/etc/app/config.toml")` |
//! | Shell arg slot | [`shell_command`] | `ssh("deploy {tag}")` |
//! | `Command::new().arg()` | [`command_arg`] | `git.arg(branch_name)` |
//! | Unknown context | [`strict`] | any mixed-use value |
//! | Free-form bash | *out of scope* | `Bash("cd repo && make")` |
//!
//! # Known limitations
//!
//! These presets do **not** defend against:
//!
//! - **Free-form command strings** — use sandbox/container isolation.
//! - **Argument injection** (`--upload-pack=evil`) — a flag prefixed with
//!   `--` is valid shell text. Use `--` separators or command-specific
//!   validation.
//! - **URL-encoded bypasses** (`%2e%2e`) — decode input before sanitizing.
//! - **Semantic attacks** — a path like `safe/but/wrong/file.txt` passes
//!   all rules but may still be the wrong file.

use shell_sanitize::{FilePath, Sanitizer, ShellArg};

use crate::{ControlCharRule, EnvExpansionRule, GlobRule, PathTraversalRule, ShellMetaRule};

/// Minimal validation for [`Command::new().arg()`][std::process::Command]
/// contexts.
///
/// Even without shell involvement, control characters can cause:
/// - NUL-byte truncation in C-backed APIs
/// - ANSI escape sequence injection in terminal output
/// - Newline injection in log files
///
/// # Rules
///
/// - [`ControlCharRule`]
///
/// # Example
///
/// ```
/// use shell_sanitize_rules::presets;
///
/// let s = presets::command_arg();
/// assert!(s.sanitize("safe-argument").is_ok());
/// assert!(s.sanitize("has\0null").is_err());
/// ```
pub fn command_arg() -> Sanitizer<ShellArg> {
    Sanitizer::builder()
        .add_rule(ControlCharRule::default())
        .build()
}

/// Sanitizer for values interpolated into shell command strings.
///
/// Use when the value will be evaluated by a shell: `sh -c "..."`,
/// SSH remote commands, `docker exec ... sh -c "..."`, CI/CD `run:`
/// blocks, or legacy `system()`/`popen()` calls.
///
/// # Rules
///
/// - [`ShellMetaRule`] — `;`, `|`, `&`, `$`, backtick, `()`, `{}`, `<>`, etc.
/// - [`ControlCharRule`] — NUL, newline, ANSI escapes
/// - [`EnvExpansionRule`] — `$HOME`, `${SECRET}`, `%USERPROFILE%`
/// - [`GlobRule`] — `*`, `?`, `[`, `]`, `{`, `}`
///
/// # Example
///
/// ```
/// use shell_sanitize_rules::presets;
///
/// let s = presets::shell_command();
///
/// // Safe argument
/// assert!(s.sanitize("my-branch-name").is_ok());
///
/// // Shell injection
/// assert!(s.sanitize("branch; rm -rf /").is_err());
///
/// // Prompt injection → env variable exfiltration
/// assert!(s.sanitize("$AWS_SECRET_ACCESS_KEY").is_err());
/// ```
pub fn shell_command() -> Sanitizer<ShellArg> {
    Sanitizer::builder()
        .add_rule(ShellMetaRule::default())
        .add_rule(ControlCharRule::default())
        .add_rule(EnvExpansionRule::default())
        .add_rule(GlobRule::default())
        .build()
}

/// Sanitizer for relative file paths.
///
/// Use for upload destinations, template includes, plugin paths, or
/// any path that must stay within a base directory. Rejects absolute
/// paths and `..` traversal.
///
/// # Rules
///
/// - [`PathTraversalRule`] — `..`, absolute paths, drive letters
/// - [`ControlCharRule`] — NUL, newline, ANSI escapes
///
/// # Example
///
/// ```
/// use shell_sanitize_rules::presets;
///
/// let s = presets::file_path();
///
/// // Relative path within allowed directory
/// assert!(s.sanitize("uploads/photo.jpg").is_ok());
///
/// // Traversal attack
/// assert!(s.sanitize("../../etc/passwd").is_err());
///
/// // Absolute path escape
/// assert!(s.sanitize("/etc/shadow").is_err());
/// ```
pub fn file_path() -> Sanitizer<FilePath> {
    Sanitizer::builder()
        .add_rule(PathTraversalRule::default())
        .add_rule(ControlCharRule::default())
        .build()
}

/// Sanitizer for file paths where absolute paths are acceptable.
///
/// Use for user-specified config files, log destinations, or paths
/// where the caller explicitly allows absolute paths but still needs
/// to block `..` traversal.
///
/// # Rules
///
/// - [`PathTraversalRule`] (absolute allowed) — `..` only
/// - [`ControlCharRule`] — NUL, newline, ANSI escapes
///
/// # Example
///
/// ```
/// use shell_sanitize_rules::presets;
///
/// let s = presets::file_path_absolute();
///
/// // Absolute path is allowed
/// assert!(s.sanitize("/etc/myapp/config.toml").is_ok());
///
/// // Traversal still blocked
/// assert!(s.sanitize("/etc/myapp/../../shadow").is_err());
/// ```
pub fn file_path_absolute() -> Sanitizer<FilePath> {
    Sanitizer::builder()
        .add_rule(PathTraversalRule::allow_absolute())
        .add_rule(ControlCharRule::default())
        .build()
}

/// Maximum-protection sanitizer with all rules enabled.
///
/// Use for the most dangerous contexts: SSH remote path operations,
/// values that serve as both shell arguments and file paths, or any
/// situation where the consumption context is unknown or mixed.
///
/// # Rules
///
/// All five built-in rules:
/// - [`ControlCharRule`]
/// - [`ShellMetaRule`]
/// - [`PathTraversalRule`]
/// - [`GlobRule`]
/// - [`EnvExpansionRule`]
///
/// # Example
///
/// ```
/// use shell_sanitize_rules::presets;
///
/// let s = presets::strict();
///
/// // Must pass every rule
/// assert!(s.sanitize("safe-filename.txt").is_ok());
///
/// // Fails on any violation
/// assert!(s.sanitize("../../etc/passwd").is_err());
/// assert!(s.sanitize("file; rm -rf /").is_err());
/// assert!(s.sanitize("$HOME/.ssh/id_rsa").is_err());
/// ```
pub fn strict() -> Sanitizer<ShellArg> {
    Sanitizer::builder()
        .add_rules(crate::default_shell_rules())
        .build()
}