//! Bounded Windows child process trees. No authorization is conferred here. //! The caller must commit the verified grant/attempt consumption before run. //! Job and handle lists are applied atomically by CreateProcessW (Windows 10+). use anyhow::{Context, Result, ensure}; use std::{ ffi::{OsStr, OsString}, mem::{size_of, size_of_val, zeroed}, os::windows::io::{AsRawHandle, FromRawHandle, OwnedHandle}, path::Path, ptr, sync::atomic::{AtomicBool, Ordering}, time::{Duration, Instant}, }; use windows_sys::Win32::{ Foundation::{ ERROR_BROKEN_PIPE, GetLastError, HANDLE, HANDLE_FLAG_INHERIT, STILL_ACTIVE, SetHandleInformation, }, Security::SECURITY_ATTRIBUTES, Storage::FileSystem::ReadFile, System::{ JobObjects::*, Pipes::{CreatePipe, PeekNamedPipe}, Threading::*, }, }; pub struct Output { pub stdout: Vec, pub stderr: Vec, pub exit_code: Option, pub truncated: bool, /// A killed process can already have affected the machine: never retry it. pub interrupted: bool, pub cancelled: bool, } /// Windows CRT quoting, not shell escaping. PowerShell receives -File followed /// by individual arguments; none are evaluated as a generated command string. pub fn quote(arg: &OsStr) -> Result> { use std::os::windows::ffi::OsStrExt; let input: Vec = arg.encode_wide().collect(); ensure!(!input.contains(&0), "ARGUMENT_NUL"); let mut out = vec![b'"' as u16]; let mut slashes = 0; for ch in input { if ch == b'\\' as u16 { slashes += 1; continue; } out.extend(std::iter::repeat_n( b'\\' as u16, slashes * if ch == b'"' as u16 { 2 } else { 1 }, )); if ch == b'"' as u16 { out.push(b'\\' as u16); } out.push(ch); slashes = 0; } out.extend(std::iter::repeat_n(b'\\' as u16, slashes * 2)); out.push(b'"' as u16); Ok(out) } fn owned(raw: HANDLE) -> Result { ensure!(!raw.is_null() && raw != -1isize as HANDLE, "PROCESS_HANDLE"); // SAFETY: successful creating API transfers this unique, live handle. Ok(unsafe { OwnedHandle::from_raw_handle(raw) }) } fn pipe() -> Result<(OwnedHandle, OwnedHandle)> { let mut read = ptr::null_mut(); let mut write = ptr::null_mut(); let security = SECURITY_ATTRIBUTES { nLength: size_of::() as u32, lpSecurityDescriptor: ptr::null_mut(), bInheritHandle: 1, }; // SAFETY: initialized output pointers and fixed-size security descriptor. ensure!( unsafe { CreatePipe(&mut read, &mut write, &security, 8192) } != 0, "PROCESS_PIPE" ); let read = owned(read)?; let write = owned(write)?; ensure!( unsafe { SetHandleInformation(read.as_raw_handle(), HANDLE_FLAG_INHERIT, 0) } != 0, "PIPE_READ_NOT_INHERITED" ); Ok((read, write)) } struct Attributes { storage: Vec, } impl Attributes { fn new() -> Result { let mut bytes = 0; unsafe { InitializeProcThreadAttributeList(ptr::null_mut(), 2, 0, &mut bytes); } ensure!(bytes > 0 && bytes < 65536, "PROCESS_ATTRIBUTES_SIZE"); let mut storage = vec![0usize; bytes.div_ceil(size_of::())]; ensure!( unsafe { InitializeProcThreadAttributeList(storage.as_mut_ptr().cast(), 2, 0, &mut bytes) } != 0, "PROCESS_ATTRIBUTES" ); Ok(Self { storage }) } fn pointer(&mut self) -> LPPROC_THREAD_ATTRIBUTE_LIST { self.storage.as_mut_ptr().cast() } fn set(&mut self, attribute: u32, handles: &[HANDLE]) -> Result<()> { ensure!( unsafe { UpdateProcThreadAttribute( self.pointer(), 0, attribute as usize, handles.as_ptr().cast(), std::mem::size_of_val(handles), ptr::null_mut(), ptr::null(), ) } != 0, "PROCESS_ATTRIBUTE_BINDING" ); Ok(()) } } impl Drop for Attributes { fn drop(&mut self) { unsafe { DeleteProcThreadAttributeList(self.pointer()); } } } fn drain( pipe: &OwnedHandle, output: &mut Vec, remaining: &mut usize, truncated: &mut bool, ) -> Result<()> { // One bounded read per stream/iteration avoids starvation by a noisy child. let mut available = 0; if unsafe { PeekNamedPipe( pipe.as_raw_handle(), ptr::null_mut(), 0, ptr::null_mut(), &mut available, ptr::null_mut(), ) } == 0 { ensure!( unsafe { GetLastError() } == ERROR_BROKEN_PIPE, "PROCESS_PIPE_PEEK" ); return Ok(()); } if available == 0 { return Ok(()); } let mut buffer = [0u8; 16384]; let mut read = 0; ensure!( unsafe { ReadFile( pipe.as_raw_handle(), buffer.as_mut_ptr(), available.min(buffer.len() as u32), &mut read, ptr::null_mut(), ) } != 0, "PROCESS_PIPE_READ" ); let keep = (*remaining).min(read as usize); output.extend_from_slice(&buffer[..keep]); *remaining -= keep; *truncated |= keep < read as usize; Ok(()) } pub fn run( executable: &Path, arguments: &[OsString], cwd: &Path, seconds: u32, max_bytes: usize, cancel: &AtomicBool, ) -> Result { run_observed( executable, arguments, cwd, Duration::from_secs(seconds.into()), max_bytes, cancel, || Ok(()), ) } pub(crate) fn run_observed( executable: &Path, arguments: &[OsString], cwd: &Path, timeout: Duration, max_bytes: usize, cancel: &AtomicBool, mut observe: impl FnMut() -> Result<()>, ) -> Result { ensure!( executable.is_absolute() && cwd.is_absolute() && !timeout.is_zero() && max_bytes <= 512 * 1024, "PROCESS_LIMITS" ); let (stdout, out_write) = pipe()?; let (stderr, err_write) = pipe()?; let (stdin, in_write) = pipe()?; // The child reads immediate EOF. Only its read handle is inheritable. ensure!( unsafe { SetHandleInformation( stdin.as_raw_handle(), HANDLE_FLAG_INHERIT, HANDLE_FLAG_INHERIT, ) } != 0, "STDIN_INHERITANCE" ); drop(in_write); let job = owned(unsafe { CreateJobObjectW(ptr::null(), ptr::null()) })?; let mut limits: JOBOBJECT_EXTENDED_LIMIT_INFORMATION = unsafe { zeroed() }; limits.BasicLimitInformation.LimitFlags = JOB_OBJECT_LIMIT_KILL_ON_JOB_CLOSE; ensure!( unsafe { SetInformationJobObject( job.as_raw_handle(), JobObjectExtendedLimitInformation, ptr::addr_of!(limits).cast(), size_of_val(&limits) as u32, ) } != 0, "PROCESS_JOB_LIMITS" ); let jobs = [job.as_raw_handle()]; let inherited = [ stdin.as_raw_handle(), out_write.as_raw_handle(), err_write.as_raw_handle(), ]; let mut attributes = Attributes::new()?; attributes.set(PROC_THREAD_ATTRIBUTE_JOB_LIST, &jobs)?; attributes.set(PROC_THREAD_ATTRIBUTE_HANDLE_LIST, &inherited)?; let mut startup: STARTUPINFOEXW = unsafe { zeroed() }; startup.StartupInfo.cb = size_of::() as u32; startup.StartupInfo.dwFlags = STARTF_USESTDHANDLES; startup.StartupInfo.hStdInput = stdin.as_raw_handle(); startup.StartupInfo.hStdOutput = out_write.as_raw_handle(); startup.StartupInfo.hStdError = err_write.as_raw_handle(); startup.lpAttributeList = attributes.pointer(); let mut command = quote(executable.as_os_str())?; for arg in arguments { command.push(b' ' as u16); command.extend(quote(arg)?); } ensure!(command.len() < 32766, "PROCESS_ARGUMENT_LIMIT"); command.push(0); let application = crate::native::wide(executable); let directory = crate::native::wide(cwd); let mut system_buffer = [0u16; 32768]; let system_length = unsafe { windows_sys::Win32::System::SystemInformation::GetSystemWindowsDirectoryW( system_buffer.as_mut_ptr(), system_buffer.len() as u32, ) } as usize; ensure!( system_length > 0 && system_length < system_buffer.len(), "SYSTEM_ROOT" ); let system = std::path::PathBuf::from(String::from_utf16(&system_buffer[..system_length])?); // Minimal environment: no inherited tokens, proxy secrets, device paths, // PSModulePath overrides, user profile or caller-controlled executable PATH. let mut environment = Vec::new(); let system_text = system .to_str() .ok_or_else(|| anyhow::anyhow!("SYSTEM_DIRECTORY_ENCODING"))?; ensure!( system_text.as_bytes().get(1) == Some(&b':') && system_text.as_bytes()[0].is_ascii_alphabetic(), "SYSTEM_DRIVE_REQUIRED" ); let system_drive = &system_text[..2]; for value in [ format!("SystemDrive={system_drive}"), format!("PATH={}\\System32;{}", system.display(), system.display()), format!("SystemRoot={}", system.display()), format!("TEMP={}", cwd.display()), format!("TMP={}", cwd.display()), format!("windir={}", system.display()), ] { environment.extend(crate::native::wide(value)); } environment.push(0); let mut process: PROCESS_INFORMATION = unsafe { zeroed() }; observe()?; ensure!( !cancel.load(Ordering::SeqCst), "PROCESS_CANCELLED_BEFORE_START" ); let created = unsafe { CreateProcessW( application.as_ptr(), command.as_mut_ptr(), ptr::null(), ptr::null(), 1, EXTENDED_STARTUPINFO_PRESENT | CREATE_NO_WINDOW | CREATE_UNICODE_ENVIRONMENT, environment.as_ptr().cast(), directory.as_ptr(), &startup.StartupInfo, &mut process, ) }; if created == 0 { return Err(std::io::Error::last_os_error()).context("PROCESS_CREATION_REFUSED"); } let process_handle = owned(process.hProcess)?; let _thread = owned(process.hThread)?; // Handles not explicitly listed (including job, DB and keys) are never inherited. drop(attributes); drop(stdin); drop(out_write); drop(err_write); let result = (|| -> Result { let mut result = Output { stdout: Vec::new(), stderr: Vec::new(), exit_code: None, truncated: false, interrupted: false, cancelled: false, }; let began = Instant::now(); let mut remaining = max_bytes; loop { drain( &stdout, &mut result.stdout, &mut remaining, &mut result.truncated, )?; drain( &stderr, &mut result.stderr, &mut remaining, &mut result.truncated, )?; let mut accounting: JOBOBJECT_BASIC_ACCOUNTING_INFORMATION = unsafe { zeroed() }; ensure!( unsafe { QueryInformationJobObject( job.as_raw_handle(), JobObjectBasicAccountingInformation, ptr::addr_of_mut!(accounting).cast(), size_of_val(&accounting) as u32, ptr::null_mut(), ) } != 0, "PROCESS_TREE_STATE" ); if accounting.ActiveProcesses == 0 { break; } let fenced = observe().is_err(); if !result.interrupted && (began.elapsed() >= timeout || cancel.load(Ordering::SeqCst) || fenced) { result.cancelled = cancel.load(Ordering::SeqCst) || fenced; result.interrupted = true; ensure!( unsafe { TerminateJobObject(job.as_raw_handle(), 1) } != 0, "PROCESS_TREE_TERMINATION" ); // This wait proves termination, not absence of effects. ensure!( unsafe { WaitForSingleObject(process_handle.as_raw_handle(), 5000) } == 0, "PROCESS_TERMINATION_UNCONFIRMED" ); // Keep this JobObject/process handle owner until *all* assigned // processes are observed inactive. Waiting for the leader alone // cannot release the helper lane or heal an interrupted outcome. } std::thread::sleep(Duration::from_millis(5)); } // No writer can outlive job destruction. Drain the bounded OS pipe buffers. for _ in 0..8 { drain( &stdout, &mut result.stdout, &mut remaining, &mut result.truncated, )?; drain( &stderr, &mut result.stderr, &mut remaining, &mut result.truncated, )?; } let mut code = 0; ensure!( unsafe { GetExitCodeProcess(process_handle.as_raw_handle(), &mut code) } != 0 && code != STILL_ACTIVE as u32, "PROCESS_EXIT_UNCONFIRMED" ); result.exit_code = Some(code as i32); Ok(result) })(); if result.is_err() { // Keep exact owned handles and the caller's helper lane on any observer // or I/O error. Termination/leader exit alone cannot prove the whole // assigned tree inactive; never drop ownership and admit replacement. unsafe { TerminateJobObject(job.as_raw_handle(), 1); } loop { let mut accounting: JOBOBJECT_BASIC_ACCOUNTING_INFORMATION = unsafe { zeroed() }; let ok = unsafe { QueryInformationJobObject( job.as_raw_handle(), JobObjectBasicAccountingInformation, ptr::addr_of_mut!(accounting).cast(), size_of_val(&accounting) as u32, ptr::null_mut(), ) }; if ok != 0 && accounting.ActiveProcesses == 0 { break; } std::thread::sleep(Duration::from_millis(50)); } } result } #[cfg(test)] mod tests { use super::*; #[test] fn arguments_never_become_shell_code_and_trailing_slashes_are_quoted() { assert_eq!( String::from_utf16("e(OsStr::new("a b\\")).unwrap()).unwrap(), "\"a b\\\\\"" ); assert_eq!( String::from_utf16("e(OsStr::new("a\"b")).unwrap()).unwrap(), "\"a\\\"b\"" ); assert_eq!( String::from_utf16("e(OsStr::new("$(Get-Content x); & y")).unwrap()).unwrap(), "\"$(Get-Content x); & y\"" ); assert!(quote(OsStr::new("a\0b")).is_err()); } }