Expand description
Take custody of Windows child processes.
A parent that launches helpers on Windows has to decide four things for every child, plus a fifth when it does not trust the child. The Win32 defaults get each of them wrong for a service or a launcher:
- What it inherits.
Launchpasses an explicitPROC_THREAD_ATTRIBUTE_HANDLE_LIST, so the child receives exactly the handles you name and nothing else that happens to be inheritable in your process. The standard library cannot do this on stable Rust. - How long it lives.
Launch::spawn_in_jobcreates the child inside a kill-on-closeJob, so it never exists outside the job and cannot outlive you, even when your process is killed. - Who it runs as.
PrimaryTokenlets a service start the child in another session, as the logged-on user or as itself on that user’s desktop. - Who can reach it.
SecurityDescriptorturns SDDL into the access rules for the pipes (PipeServer), mutexes (NamedMutex), jobs and directory trees you share with the child, andPipeServertells you the process ID of whoever connected. - What it can touch, if you ask.
AppContainerProfileandLaunch::app_containerrun the child in an AppContainer with the capabilities you name and the paths you grant. This is opt-in.
§Sandboxing is opt-in
A Launch without Launch::app_container confines nothing. It does
not limit what a child can do with the rights its token already has: a job
object ties the child’s lifetime and resource use to yours, but does not
stop the child from reading files, writing the registry or opening network
connections.
With Launch::app_container, the child runs in a plain AppContainer, not
a Less Privileged AppContainer (LPAC). It keeps everything Windows grants
to ALL APPLICATION PACKAGES, and the launch cannot be combined with
Launch::as_user. Access given with AppContainerProfile::grant_path
is written into the files’ ACLs and outlives the process and the profile.
For code that needs stronger isolation, use a separate low-privilege
account.
§Example
use std::time::Duration;
use win_custody::{Job, JobLimits, Launch, WaitOutcome};
let job = Job::create(&JobLimits::new().kill_on_close(true))?;
let child = Launch::new(r"C:\Windows\System32\cmd.exe")
.args(["/d", "/c", "exit 7"])
.spawn_in_job(&job)?;
assert_eq!(child.wait(Some(Duration::from_secs(10)))?, WaitOutcome::Signaled);
assert_eq!(child.exit_code()?, Some(7));§Where the unsafe lives
unsafe_code is denied for the crate. Only the modules that call Win32
opt back in, each at its top, and every unsafe block there carries a
SAFETY: comment naming the invariant it relies on. Raw handles,
pointers and buffer lengths never cross the public API: handles come and
go as std::os::windows::io::OwnedHandle and
std::os::windows::io::BorrowedHandle, and buffers Windows fills are
bounds-checked before they are read.
On targets other than Windows the crate compiles to nothing.
Structs§
- Allowed
Ace - One
ACCESS_ALLOWED_ACE, reduced to the fields policy checks read. - AppContainer
Profile - A named AppContainer profile and the capabilities assigned to its child processes. Profile data persists in Windows after this value is dropped.
- Job
- An anonymous job object whose limits are in force before the first process can join it.
- JobLimits
- The limits a
Jobenforces. - Launch
- A child process to create, and everything it is allowed to receive.
- Named
Mutex - A named mutex created, or opened when it already exists, with a security descriptor you choose.
- Object
Security Descriptor - The security descriptor of an existing object, with accessors that validate its parts before exposing them. Use it to verify that a pipe, file or directory carries the ACL you expect.
- Owned
Sid - A SID converted from its string form, kept both as the Windows allocation (for APIs that need a pointer) and as validated bytes (for comparison).
- Pipe
Client - A client connection to a local named pipe.
- Pipe
Server - A single-instance, local-only byte pipe server.
- Pipe
Wait - How long a pipe operation may take, and whose exit ends it early.
- Primary
Token - A primary access token that
crate::Launch::as_usercan start a child with. - Privilege
Guard - A privilege enabled in the process token for this value’s lifetime.
- Process
- An open process handle with a fixed rights set.
- Security
Descriptor - A security descriptor built from SDDL, for creating objects
(
crate::PipeServer,crate::NamedMutex,crate::Job) and for resetting the ACLs of a directory tree. - Session
Process - One process as Terminal Services reports it.
- Suspended
Child - A child created suspended. Dropping it without calling
resumeterminates it, so a launch that fails half-way never leaves a frozen process behind. - Validated
Dacl - A DACL whose every ACE was an in-bounds
ACCESS_ALLOWED_ACEwith a well-formed SID. Any other ACE type fails validation, so a policy that iterates this list has already excluded deny and audit entries. - Validated
Sid - A SID copied out of a descriptor after its structure was verified.
Enums§
- AclValidation
Error - Why a descriptor’s bytes did not form the structure Windows claims.
- AppContainer
Access - Filesystem rights granted by
AppContainerProfile::grant_path. - Mutex
Acquisition - How a mutex wait ended.
- Pipe
Access - The access a
PipeClientopens the pipe with. - Pipe
Direction - The direction data flows, seen from the server.
- Pipe
Error - A failure from a deadline-bound pipe operation.
- Process
Access - The rights a
Processhandle carries. - Security
AclError - A failure while reading part of a security descriptor.
- Wait
Outcome - How a wait on a kernel object ended.
Functions§
- active_
console_ session_ id - The session attached to the physical console, or
Nonewhile the console is between sessions (during a user switch, for example). - anonymous_
pipe - An anonymous pipe as
(read, write). Neither end is inheritable; give an end to a child withLaunch::stdout,Launch::stdinorLaunch::inherit. - current_
session_ id - The session the calling process runs in.
- current_
token_ is_ member_ of - Whether the calling thread’s token (or the process token, when the thread
is not impersonating) has
groupas an enabled group. - current_
user_ sid_ string - The calling process’s user SID in string form, such as
S-1-5-18. - is_
elevated - Whether the calling process runs with an elevated (full administrator) token.
- null_
device - A read/write handle to the
NULdevice, which discards writes and reads as end-of-file. - process_
session_ id - The session the process with
pidruns in. - read_
to_ end_ bounded - Reads
handleto end-of-stream, keeping at mostmaximum + 1bytes so a caller can tell “exactly the bound” from “over the bound”. A broken pipe counts as end-of-stream. - session_
processes - Every process on the local machine with its session, copied out of the Terminal Services buffer before it is freed.
- wait
- Waits until the object behind
handleis signaled ortimeoutpasses.Nonewaits forever.