Skip to main content

arabica_runner/
shell.rs

1//! The `shell` tool: one `sh -c` command, bounded in time and output, whose
2//! processes do not outlive the call.
3//!
4//! Shell is the one local tool that cannot be confined to the workspace root.
5//! Everything here limits what a single call can cost or leak. None of it makes
6//! shell safe to run without a permission decision; that decision belongs to
7//! the host, which should ask the user before every call.
8
9use std::path::{Path, PathBuf};
10use std::sync::atomic::{AtomicU64, Ordering};
11
12use serde::{Deserialize, Serialize};
13
14use crate::RunnerError;
15use crate::output::truncate_output;
16
17static CAPTURE_SEQUENCE: AtomicU64 = AtomicU64::new(0);
18
19/// `_`-separated name segments that mark an environment variable as a secret.
20const CREDENTIAL_SEGMENTS: &[&str] = &[
21    "KEY",
22    "APIKEY",
23    "TOKEN",
24    "SECRET",
25    "PASSWORD",
26    "PASSWD",
27    "CREDENTIAL",
28    "CREDENTIALS",
29    "AUTHORIZATION",
30    "BEARER",
31    "ACCESSKEY",
32    "PAT",
33    "SIGNING",
34    "PRIVATEKEY",
35];
36
37/// Limits for the `shell` tool.
38#[derive(Clone, Debug, Deserialize, Eq, PartialEq, Serialize)]
39#[serde(default, deny_unknown_fields)]
40pub struct ShellPolicy {
41    /// Seconds a command may run when the call does not choose.
42    pub default_timeout_secs: u64,
43    /// Upper bound on any timeout the model requests.
44    pub max_timeout_secs: u64,
45    /// Bytes kept from each captured stream. The middle of a larger stream is
46    /// dropped before the model-facing result is truncated again.
47    pub max_capture_bytes: u64,
48    /// Exact variable names removed from the child environment in addition to
49    /// the credential pattern, for example a provider's `api_key_env`.
50    pub scrub_env: Vec<String>,
51    /// Exact variable names exempt from the credential pattern.
52    pub allow_env: Vec<String>,
53}
54
55impl Default for ShellPolicy {
56    fn default() -> Self {
57        Self {
58            default_timeout_secs: 120,
59            max_timeout_secs: 600,
60            max_capture_bytes: 256 * 1024,
61            scrub_env: Vec::new(),
62            allow_env: Vec::new(),
63        }
64    }
65}
66
67impl ShellPolicy {
68    /// Whether a variable is removed from the child environment.
69    ///
70    /// Anything a command can read, the model can read and send to its
71    /// provider: `env` is one command away. Credentials are therefore removed
72    /// by name pattern rather than listed one by one, because a real
73    /// environment holds more of them than any list anticipates. Matching whole
74    /// `_`-separated segments avoids false positives such as `MONKEY` or
75    /// `KEYCHAIN_PATH`, and leaves `SSH_AUTH_SOCK` usable for git.
76    pub fn scrubs(&self, name: &str) -> bool {
77        if self.allow_env.iter().any(|allowed| allowed == name) {
78            return false;
79        }
80        if self.scrub_env.iter().any(|scrubbed| scrubbed == name) {
81            return true;
82        }
83        name.to_ascii_uppercase()
84            .split('_')
85            .any(|segment| CREDENTIAL_SEGMENTS.contains(&segment))
86    }
87
88    pub(crate) fn validate(&self) -> Result<(), RunnerError> {
89        if self.default_timeout_secs == 0 || self.max_timeout_secs < self.default_timeout_secs {
90            return Err(RunnerError::new(
91                "shell timeouts must satisfy 1 <= default_timeout_secs <= max_timeout_secs",
92            ));
93        }
94        if self.max_capture_bytes < 2 {
95            return Err(RunnerError::new(
96                "shell.max_capture_bytes must be at least 2",
97            ));
98        }
99        Ok(())
100    }
101}
102
103/// What one shell call produced.
104pub(crate) struct ShellOutcome {
105    /// Model-facing result: status line plus both streams, truncated.
106    pub content: String,
107    pub is_error: bool,
108    pub stdout: String,
109    pub stderr: String,
110}
111
112#[cfg(unix)]
113pub(crate) async fn run(
114    root: &Path,
115    policy: &ShellPolicy,
116    arguments: &serde_json::Value,
117) -> Result<ShellOutcome, RunnerError> {
118    let command = arguments
119        .get("command")
120        .and_then(serde_json::Value::as_str)
121        .ok_or_else(|| RunnerError::new("shell.command must be a string"))?;
122    if command.trim().is_empty() {
123        return Err(RunnerError::new("shell.command must not be empty"));
124    }
125    if let Some(reason) = is_catastrophic_command(command) {
126        return Err(RunnerError::new(format!(
127            "shell command blocked by security sandbox: {reason}"
128        )));
129    }
130    let timeout_secs = arguments
131        .get("timeout_sec")
132        .and_then(serde_json::Value::as_u64)
133        .unwrap_or(policy.default_timeout_secs)
134        .clamp(1, policy.max_timeout_secs);
135
136    // Streams go to files, not pipes: a pipe the parent is not draining fills
137    // and blocks the child, and a command that prints a lot must not deadlock.
138    let capture = CaptureDir::create()?;
139    let stdout_path = capture.path().join("stdout");
140    let stderr_path = capture.path().join("stderr");
141    let open = |path: &Path| {
142        std::fs::File::create(path)
143            .map_err(|error| RunnerError::new(format!("shell capture file unavailable: {error}")))
144    };
145    let mut child_command = tokio::process::Command::new("sh");
146    child_command
147        .arg("-c")
148        .arg(command)
149        .current_dir(root)
150        .stdin(std::process::Stdio::null())
151        .stdout(open(&stdout_path)?)
152        .stderr(open(&stderr_path)?)
153        // A new process group lets one signal reach everything the command
154        // starts, including background jobs that outlive `sh` itself.
155        .process_group(0)
156        .kill_on_drop(true)
157        .env("GIT_TERMINAL_PROMPT", "0")
158        .env("PAGER", "cat")
159        .env("GIT_PAGER", "cat");
160    for (name, _) in std::env::vars_os() {
161        if let Some(name) = name.to_str()
162            && policy.scrubs(name)
163        {
164            child_command.env_remove(name);
165        }
166    }
167
168    let mut child = child_command
169        .spawn()
170        .map_err(|error| RunnerError::new(format!("shell failed to start: {error}")))?;
171    // Declared after `child`, so on an early return or a dropped future the
172    // group is killed before `kill_on_drop` reaps the direct child.
173    let mut group = ProcessGroup::new(child.id());
174    let waited =
175        tokio::time::timeout(std::time::Duration::from_secs(timeout_secs), child.wait()).await;
176    // Kill the group whether or not the direct child exited: a call's
177    // processes must not outlive it. After a normal exit the group is usually
178    // already empty, and the kill is a harmless no-op.
179    group.kill();
180    let (exit_code, timed_out) = match waited {
181        Ok(Ok(status)) => (status.code(), false),
182        Ok(Err(error)) => return Err(RunnerError::new(format!("shell wait failed: {error}"))),
183        Err(_) => {
184            // The group kill above should already have ended `sh`. Kill the
185            // direct child explicitly as well: if the group kill failed, for
186            // instance because the child id was unavailable, waiting alone
187            // would block until the command finished on its own and the
188            // timeout would enforce nothing.
189            let _ = child.start_kill();
190            let _ = child.wait().await;
191            (None, true)
192        }
193    };
194
195    let stdout = read_bounded(&stdout_path, policy.max_capture_bytes).await?;
196    let stderr = read_bounded(&stderr_path, policy.max_capture_bytes).await?;
197    let mut content = match (timed_out, exit_code) {
198        (true, _) => format!(
199            "timed out after {timeout_secs}s; the command and every process it started were killed"
200        ),
201        (false, Some(code)) => format!("exit code {code}"),
202        (false, None) => "terminated by a signal".to_owned(),
203    };
204    if !stdout.is_empty() {
205        content.push_str("\nstdout:\n");
206        content.push_str(&stdout);
207    }
208    if !stderr.is_empty() {
209        content.push_str("\nstderr:\n");
210        content.push_str(&stderr);
211    }
212    Ok(ShellOutcome {
213        content: truncate_output(content),
214        is_error: timed_out || exit_code != Some(0),
215        stdout,
216        stderr,
217    })
218}
219
220#[cfg(not(unix))]
221pub(crate) async fn run(
222    _root: &Path,
223    _policy: &ShellPolicy,
224    _arguments: &serde_json::Value,
225) -> Result<ShellOutcome, RunnerError> {
226    Err(RunnerError::new("shell is only supported on unix hosts"))
227}
228
229/// The process group a shell call started, killed on drop.
230#[cfg(unix)]
231struct ProcessGroup(Option<rustix::process::Pid>);
232
233#[cfg(unix)]
234impl ProcessGroup {
235    fn new(child_id: Option<u32>) -> Self {
236        // `process_group(0)` makes the child the leader of a new group whose
237        // id equals the child's pid.
238        Self(
239            child_id
240                .and_then(|id| i32::try_from(id).ok())
241                .and_then(rustix::process::Pid::from_raw),
242        )
243    }
244
245    fn kill(&mut self) {
246        if let Some(group) = self.0.take() {
247            // ESRCH means the group is already gone, which is the goal.
248            let _ = rustix::process::kill_process_group(group, rustix::process::Signal::KILL);
249        }
250    }
251}
252
253#[cfg(unix)]
254impl Drop for ProcessGroup {
255    fn drop(&mut self) {
256        self.kill();
257    }
258}
259
260/// A private directory for one call's captured output, removed on drop.
261struct CaptureDir(PathBuf);
262
263impl CaptureDir {
264    fn create() -> Result<Self, RunnerError> {
265        let path = std::env::temp_dir().join(format!(
266            "structure-shell-{}-{}",
267            std::process::id(),
268            CAPTURE_SEQUENCE.fetch_add(1, Ordering::Relaxed)
269        ));
270        let mut builder = std::fs::DirBuilder::new();
271        // Created with 0700 in one step, so no other user can open the
272        // capture files between creation and a later permission change.
273        #[cfg(unix)]
274        {
275            use std::os::unix::fs::DirBuilderExt;
276            builder.mode(0o700);
277        }
278        builder.create(&path).map_err(|error| {
279            RunnerError::new(format!("shell capture directory unavailable: {error}"))
280        })?;
281        Ok(Self(path))
282    }
283
284    fn path(&self) -> &Path {
285        &self.0
286    }
287}
288
289impl Drop for CaptureDir {
290    fn drop(&mut self) {
291        let _ = std::fs::remove_dir_all(&self.0);
292    }
293}
294
295/// Read a captured stream without loading an arbitrarily large file.
296async fn read_bounded(path: &Path, max_bytes: u64) -> Result<String, RunnerError> {
297    use tokio::io::{AsyncReadExt, AsyncSeekExt};
298
299    let unavailable =
300        |error: std::io::Error| RunnerError::new(format!("shell output unavailable: {error}"));
301    let mut file = tokio::fs::File::open(path).await.map_err(unavailable)?;
302    let size = file.metadata().await.map_err(unavailable)?.len();
303    if size <= max_bytes {
304        let mut bytes = Vec::new();
305        file.read_to_end(&mut bytes).await.map_err(unavailable)?;
306        return Ok(String::from_utf8_lossy(&bytes).into_owned());
307    }
308    let half = max_bytes / 2;
309    let mut head = vec![0; usize::try_from(half).unwrap_or(usize::MAX)];
310    file.read_exact(&mut head).await.map_err(unavailable)?;
311    file.seek(std::io::SeekFrom::Start(size - half))
312        .await
313        .map_err(unavailable)?;
314    let mut tail = vec![0; usize::try_from(half).unwrap_or(usize::MAX)];
315    file.read_exact(&mut tail).await.map_err(unavailable)?;
316    Ok(format!(
317        "{}\n...[{} bytes omitted]...\n{}",
318        String::from_utf8_lossy(&head),
319        size - 2 * half,
320        String::from_utf8_lossy(&tail)
321    ))
322}
323
324/// Checks whether a shell command is catastrophic to the host or environment.
325pub(crate) fn is_catastrophic_command(command: &str) -> Option<&'static str> {
326    let trimmed = command.trim();
327    if trimmed.is_empty() {
328        return None;
329    }
330
331    // 1. Fork bomb detection (e.g. :(){ :|:& };:)
332    let stripped_ws: String = trimmed.chars().filter(|c| !c.is_whitespace()).collect();
333    if stripped_ws.contains(":(){:|:&};:") || stripped_ws.contains(":(){:|:&};") {
334        return Some("fork bomb detected");
335    }
336
337    // 2. Chained command detection (quote-aware splitting)
338    for part in split_command_chain(trimmed) {
339        let part = part.trim();
340        if part.is_empty() {
341            continue;
342        }
343
344        let tokens = tokenize_args(part);
345        if tokens.is_empty() {
346            continue;
347        }
348
349        // Skip command wrappers like sudo, doas, env
350        let mut idx = 0;
351        while idx < tokens.len() {
352            let t = tokens[idx].as_str();
353            if t == "sudo" || t == "doas" || t == "env" || (t.starts_with('-') && idx == 0) {
354                idx += 1;
355            } else {
356                break;
357            }
358        }
359        if idx >= tokens.len() {
360            continue;
361        }
362
363        let cmd_name = tokens[idx].as_str();
364        let args = &tokens[idx + 1..];
365
366        // 3. Destructive recursive removal of filesystem root
367        if cmd_name == "rm" {
368            let has_recursive = args.iter().any(|arg| {
369                if arg == "-r" || arg == "-R" || arg == "--recursive" {
370                    return true;
371                }
372                if arg.starts_with('-') && !arg.starts_with("--") {
373                    return arg.contains('r') || arg.contains('R');
374                }
375                false
376            });
377
378            if has_recursive {
379                for arg in args {
380                    if arg == "/"
381                        || arg == "/*"
382                        || arg == "/."
383                        || arg == "/.."
384                        || arg == "/.*"
385                        || arg == "--no-preserve-root"
386                    {
387                        return Some(
388                            "destructive recursive deletion of filesystem root is blocked",
389                        );
390                    }
391                }
392            }
393        }
394
395        // 4. Raw block device destruction (mkfs, dd)
396        if cmd_name.starts_with("mkfs") {
397            for arg in args {
398                if is_raw_block_device(arg) {
399                    return Some("formatting raw system disk device is blocked");
400                }
401            }
402        }
403
404        if cmd_name == "dd" {
405            for arg in args {
406                if let Some(target) = arg.strip_prefix("of=")
407                    && is_raw_block_device(target)
408                {
409                    return Some("direct overwrite of raw system disk device is blocked");
410                }
411            }
412        }
413
414        // 5. System root permission destruction (chmod -R, chown -R on /)
415        if cmd_name == "chmod" || cmd_name == "chown" {
416            let has_recursive = args.iter().any(|arg| arg == "-R" || arg == "--recursive");
417            if has_recursive {
418                for arg in args {
419                    if arg == "/" || arg == "/*" {
420                        return Some(
421                            "recursive permission destruction of filesystem root is blocked",
422                        );
423                    }
424                }
425            }
426        }
427    }
428
429    None
430}
431
432fn is_raw_block_device(path: &str) -> bool {
433    let p = path.trim();
434    p.starts_with("/dev/sd")
435        || p.starts_with("/dev/nvme")
436        || p.starts_with("/dev/vd")
437        || p.starts_with("/dev/hd")
438        || p.starts_with("/dev/disk")
439}
440
441fn split_command_chain(command: &str) -> Vec<String> {
442    let mut parts = Vec::new();
443    let mut current = String::new();
444    let mut in_single = false;
445    let mut in_double = false;
446    let mut chars = command.chars().peekable();
447
448    while let Some(c) = chars.next() {
449        match c {
450            '\'' if !in_double => {
451                in_single = !in_single;
452                current.push(c);
453            }
454            '"' if !in_single => {
455                in_double = !in_double;
456                current.push(c);
457            }
458            ';' if !in_single && !in_double => {
459                parts.push(std::mem::take(&mut current));
460            }
461            '&' | '|' if !in_single && !in_double => {
462                if chars.peek() == Some(&c) {
463                    chars.next();
464                }
465                parts.push(std::mem::take(&mut current));
466            }
467            _ => {
468                current.push(c);
469            }
470        }
471    }
472    if !current.trim().is_empty() {
473        parts.push(current);
474    }
475    parts
476}
477
478fn tokenize_args(segment: &str) -> Vec<String> {
479    let mut tokens = Vec::new();
480    let mut current = String::new();
481    let mut in_single = false;
482    let mut in_double = false;
483
484    for c in segment.chars() {
485        match c {
486            '\'' if !in_double => {
487                in_single = !in_single;
488            }
489            '"' if !in_single => {
490                in_double = !in_double;
491            }
492            c if c.is_whitespace() && !in_single && !in_double => {
493                if !current.is_empty() {
494                    tokens.push(std::mem::take(&mut current));
495                }
496            }
497            _ => {
498                current.push(c);
499            }
500        }
501    }
502    if !current.is_empty() {
503        tokens.push(current);
504    }
505    tokens
506}
507
508#[cfg(test)]
509mod tests {
510    use super::*;
511
512    #[test]
513    fn catastrophic_commands_are_blocked() {
514        for blocked in [
515            "rm -rf /",
516            "rm -fr /",
517            "rm -r -f /",
518            "rm -rf /*",
519            "rm -rf /.*",
520            "sudo rm -rf /",
521            "doas rm -rf /",
522            "rm --recursive --no-preserve-root /",
523            ":(){ :|:& };:",
524            ":(){:|:&};:",
525            "mkfs.ext4 /dev/sda1",
526            "mkfs /dev/nvme0n1p1",
527            "dd if=/dev/zero of=/dev/sda bs=1M",
528            "chmod -R 777 /",
529            "chown -R root:root /",
530            "echo hello; rm -rf /",
531            "cd /tmp && rm -rf /",
532            "true || rm -rf /",
533        ] {
534            assert!(
535                is_catastrophic_command(blocked).is_some(),
536                "must block catastrophic command: {blocked}"
537            );
538        }
539    }
540
541    #[test]
542    fn safe_commands_are_allowed() {
543        for safe in [
544            "cargo build",
545            "rm -rf target/",
546            "rm -rf /tmp/scratch",
547            "rm file.txt",
548            "echo 'rm -rf /'",
549            "echo \"rm -rf /\"",
550            "cat /dev/null",
551            "dd if=/dev/zero of=test.img bs=1M count=10",
552            "chmod 644 /tmp/file.txt",
553            "git clean -fdx",
554        ] {
555            assert!(
556                is_catastrophic_command(safe).is_none(),
557                "must allow safe command: {safe}"
558            );
559        }
560    }
561}