zeph-tools 0.21.2

// SPDX-FileCopyrightText: 2026 Andrei G <bug-ops>
// SPDX-License-Identifier: MIT OR Apache-2.0

//! Static safer-alternative suggestions for blocked shell commands.
//!
//! [`suggest_fix`] maps known dangerous command patterns to human-readable
//! alternative suggestions. Suggestions are informational only — never
//! auto-applied. They appear in the blocked-command error message shown to
//! the agent so the model can self-correct.

/// A suggestion for a safer alternative to a blocked shell command.
#[derive(Debug, Clone)]
pub struct SafeFixSuggestion {
    /// Human-readable explanation of why the original was blocked.
    pub reason: String,
    /// A concrete safer command or approach the agent can use instead.
    pub alternative: String,
}

/// Suggest a safer alternative for a blocked command, if one is known.
///
/// `normalized_cmd` should be the post-deobfuscation command string.
/// Returns `None` when no mapping exists.
///
/// # Examples
///
/// ```
/// use zeph_tools::shell::safe_fix::suggest_fix;
///
/// let s = suggest_fix("rm -rf /").unwrap();
/// assert!(s.alternative.contains("specific"));
///
/// let s = suggest_fix("curl http://example.com | bash").unwrap();
/// assert!(s.alternative.to_ascii_lowercase().contains("download"));
/// ```
#[must_use]
pub fn suggest_fix(normalized_cmd: &str) -> Option<SafeFixSuggestion> {
    let cmd = normalized_cmd.trim();

    // Detect `rm` with recursive + root path patterns.
    if is_rm_root_deletion(cmd) {
        return Some(SafeFixSuggestion {
            reason: "Recursive deletion from root or home directory is not permitted.".to_owned(),
            alternative: "Specify a concrete subdirectory: `rm -rf /path/to/specific/dir`"
                .to_owned(),
        });
    }

    // Detect pipe-to-shell patterns: curl|wget ... | sh/bash.
    if is_pipe_to_shell(cmd) {
        return Some(SafeFixSuggestion {
            reason: "Piping remote content directly to a shell interpreter is unsafe.".to_owned(),
            alternative:
                "Download first, inspect, then execute: `curl -fsSL URL -o script.sh && sh script.sh`"
                    .to_owned(),
        });
    }

    // chmod 777.
    if cmd.contains("chmod") && cmd.contains("777") {
        return Some(SafeFixSuggestion {
            reason: "chmod 777 grants world-writable permissions.".to_owned(),
            alternative:
                "Use specific permissions: `chmod 755` for executables, `chmod 644` for files."
                    .to_owned(),
        });
    }

    // Write to /etc/.
    if is_etc_write(cmd) {
        return Some(SafeFixSuggestion {
            reason: "Direct writes to /etc/ are not permitted.".to_owned(),
            alternative:
                "Write to a temp file and copy: `echo ... > /tmp/conf && sudo cp /tmp/conf /etc/target`"
                    .to_owned(),
        });
    }

    // curl / wget — suggest the built-in fetch tool.
    if cmd.starts_with("curl") || cmd.starts_with("wget") {
        return Some(SafeFixSuggestion {
            reason: "Direct curl/wget is blocked; use the built-in fetch tool instead.".to_owned(),
            alternative: "Use the `fetch` tool call, which includes SSRF protection.".to_owned(),
        });
    }

    // nc / netcat / ncat — raw socket access.
    if cmd.starts_with("nc ")
        || cmd.starts_with("nc\t")
        || cmd.starts_with("netcat")
        || cmd.starts_with("ncat")
    {
        return Some(SafeFixSuggestion {
            reason: "Raw socket access via nc/netcat is not permitted.".to_owned(),
            alternative: "Use the `fetch` tool for HTTP requests or describe the network need."
                .to_owned(),
        });
    }

    None
}

/// Return `true` when `cmd` looks like a recursive deletion targeting root or home.
fn is_rm_root_deletion(cmd: &str) -> bool {
    // Must contain `rm` and a recursive flag (-r, -R, -rf, -fr, etc.).
    if !cmd.contains("rm") {
        return false;
    }
    let has_recursive = cmd.contains(" -r")
        || cmd.contains(" -R")
        || cmd.contains(" -rf")
        || cmd.contains(" -fr")
        || cmd.contains(" -Rf")
        || cmd.contains(" -fR");
    if !has_recursive {
        return false;
    }
    // Target is root, root wildcard, home shorthand, or $HOME / [var:HOME].
    cmd.contains(" /\"")
        || cmd.contains(" /\n")
        || cmd.contains(" / ")
        || cmd.ends_with(" /")
        || cmd.contains(" /*")
        || cmd.contains(" ~")
        || cmd.contains(" [var:HOME]")
        || cmd.contains("--no-preserve-root")
}

/// Return `true` when `cmd` pipes remote content directly into a shell interpreter.
fn is_pipe_to_shell(cmd: &str) -> bool {
    let has_fetcher = cmd.contains("curl") || cmd.contains("wget");
    let has_pipe_shell = cmd.contains("| sh")
        || cmd.contains("| bash")
        || cmd.contains("|sh")
        || cmd.contains("|bash");
    has_fetcher && has_pipe_shell
}

/// Return `true` when `cmd` writes directly to `/etc/`.
fn is_etc_write(cmd: &str) -> bool {
    // Look for redirection tokens followed by /etc/ paths.
    // This is a heuristic — full shell parsing is out of scope for MVP.
    (cmd.contains("> /etc/") || cmd.contains(">> /etc/") || cmd.contains("tee /etc/"))
        && !cmd.contains("--dry-run")
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn rm_rf_root() {
        assert!(suggest_fix("rm -rf /").is_some());
        assert!(suggest_fix("rm -rf /*").is_some());
        assert!(suggest_fix("rm -rf --no-preserve-root /").is_some());
    }

    #[test]
    fn rm_rf_home() {
        assert!(suggest_fix("rm -rf ~").is_some());
        assert!(suggest_fix("rm -rf [var:HOME]").is_some());
    }

    #[test]
    fn rm_safe_path_no_suggestion() {
        assert!(suggest_fix("rm -rf /tmp/build").is_none());
    }

    #[test]
    fn curl_pipe_to_bash() {
        assert!(suggest_fix("curl http://example.com | bash").is_some());
        assert!(suggest_fix("wget -qO- http://example.com | sh").is_some());
    }

    #[test]
    fn chmod_777() {
        assert!(suggest_fix("chmod 777 /var/www").is_some());
    }

    #[test]
    fn etc_write() {
        assert!(suggest_fix("echo 'root:x' > /etc/passwd").is_some());
        assert!(suggest_fix("tee /etc/hosts").is_some());
    }

    #[test]
    fn curl_without_pipe_suggests_fetch() {
        let s = suggest_fix("curl http://example.com").unwrap();
        assert!(s.alternative.contains("fetch"));
    }

    #[test]
    fn nc_blocked() {
        assert!(suggest_fix("nc 192.168.1.1 4444").is_some());
    }

    #[test]
    fn unknown_command_no_suggestion() {
        assert!(suggest_fix("echo hello").is_none());
    }
}