1use 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
19const 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#[derive(Clone, Debug, Deserialize, Eq, PartialEq, Serialize)]
39#[serde(default, deny_unknown_fields)]
40pub struct ShellPolicy {
41 pub default_timeout_secs: u64,
43 pub max_timeout_secs: u64,
45 pub max_capture_bytes: u64,
48 pub scrub_env: Vec<String>,
51 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 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
103pub(crate) struct ShellOutcome {
105 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 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 .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 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 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 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#[cfg(unix)]
231struct ProcessGroup(Option<rustix::process::Pid>);
232
233#[cfg(unix)]
234impl ProcessGroup {
235 fn new(child_id: Option<u32>) -> Self {
236 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 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
260struct 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 #[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
295async 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
324pub(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 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 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 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 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 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 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}