Skip to main content

Crate win_custody

Crate win_custody 

Source
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. Launch passes an explicit PROC_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_job creates the child inside a kill-on-close Job, so it never exists outside the job and cannot outlive you, even when your process is killed.
  • Who it runs as. PrimaryToken lets 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. SecurityDescriptor turns SDDL into the access rules for the pipes (PipeServer), mutexes (NamedMutex), jobs and directory trees you share with the child, and PipeServer tells you the process ID of whoever connected.
  • What it can touch, if you ask. AppContainerProfile and Launch::app_container run 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§

AllowedAce
One ACCESS_ALLOWED_ACE, reduced to the fields policy checks read.
AppContainerProfile
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 Job enforces.
Launch
A child process to create, and everything it is allowed to receive.
NamedMutex
A named mutex created, or opened when it already exists, with a security descriptor you choose.
ObjectSecurityDescriptor
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.
OwnedSid
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).
PipeClient
A client connection to a local named pipe.
PipeServer
A single-instance, local-only byte pipe server.
PipeWait
How long a pipe operation may take, and whose exit ends it early.
PrimaryToken
A primary access token that crate::Launch::as_user can start a child with.
PrivilegeGuard
A privilege enabled in the process token for this value’s lifetime.
Process
An open process handle with a fixed rights set.
SecurityDescriptor
A security descriptor built from SDDL, for creating objects (crate::PipeServer, crate::NamedMutex, crate::Job) and for resetting the ACLs of a directory tree.
SessionProcess
One process as Terminal Services reports it.
SuspendedChild
A child created suspended. Dropping it without calling resume terminates it, so a launch that fails half-way never leaves a frozen process behind.
ValidatedDacl
A DACL whose every ACE was an in-bounds ACCESS_ALLOWED_ACE with a well-formed SID. Any other ACE type fails validation, so a policy that iterates this list has already excluded deny and audit entries.
ValidatedSid
A SID copied out of a descriptor after its structure was verified.

Enums§

AclValidationError
Why a descriptor’s bytes did not form the structure Windows claims.
AppContainerAccess
Filesystem rights granted by AppContainerProfile::grant_path.
MutexAcquisition
How a mutex wait ended.
PipeAccess
The access a PipeClient opens the pipe with.
PipeDirection
The direction data flows, seen from the server.
PipeError
A failure from a deadline-bound pipe operation.
ProcessAccess
The rights a Process handle carries.
SecurityAclError
A failure while reading part of a security descriptor.
WaitOutcome
How a wait on a kernel object ended.

Functions§

active_console_session_id
The session attached to the physical console, or None while 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 with Launch::stdout, Launch::stdin or Launch::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 group as 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 NUL device, which discards writes and reads as end-of-file.
process_session_id
The session the process with pid runs in.
read_to_end_bounded
Reads handle to end-of-stream, keeping at most maximum + 1 bytes 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 handle is signaled or timeout passes. None waits forever.