Skip to main content

win_custody/
lib.rs

1//! Take custody of Windows child processes.
2//!
3//! A parent that launches helpers on Windows has to decide four things for
4//! every child, plus a fifth when it does not trust the child. The Win32
5//! defaults get each of them wrong for a service or a launcher:
6//!
7//! * **What it inherits.** [`Launch`] passes an explicit
8//!   `PROC_THREAD_ATTRIBUTE_HANDLE_LIST`, so the child receives exactly the
9//!   handles you name and nothing else that happens to be inheritable in your
10//!   process. The standard library cannot do this on stable Rust.
11//! * **How long it lives.** [`Launch::spawn_in_job`] creates the child inside
12//!   a kill-on-close [`Job`], so it never exists outside the job and cannot
13//!   outlive you, even when your process is killed.
14//! * **Who it runs as.** [`PrimaryToken`] lets a service start the child in
15//!   another session, as the logged-on user or as itself on that user's
16//!   desktop.
17//! * **Who can reach it.** [`SecurityDescriptor`] turns SDDL into the access
18//!   rules for the pipes ([`PipeServer`]), mutexes ([`NamedMutex`]), jobs and
19//!   directory trees you share with the child, and [`PipeServer`] tells you the
20//!   process ID of whoever connected.
21//! * **What it can touch, if you ask.** [`AppContainerProfile`] and
22//!   [`Launch::app_container`] run the child in an AppContainer with the
23//!   capabilities you name and the paths you grant. This is opt-in.
24//!
25//! # Sandboxing is opt-in
26//!
27//! A [`Launch`] without [`Launch::app_container`] confines nothing. It does
28//! not limit what a child can do with the rights its token already has: a job
29//! object ties the child's lifetime and resource use to yours, but does not
30//! stop the child from reading files, writing the registry or opening network
31//! connections.
32//!
33//! With [`Launch::app_container`], the child runs in a plain AppContainer, not
34//! a Less Privileged AppContainer (LPAC). It keeps everything Windows grants
35//! to `ALL APPLICATION PACKAGES`, and the launch cannot be combined with
36//! [`Launch::as_user`]. Access given with [`AppContainerProfile::grant_path`]
37//! is written into the files' ACLs and outlives the process and the profile.
38//! For code that needs stronger isolation, use a separate low-privilege
39//! account.
40//!
41//! # Example
42//!
43//! ```no_run
44//! # #[cfg(windows)]
45//! # fn main() -> std::io::Result<()> {
46//! use std::time::Duration;
47//! use win_custody::{Job, JobLimits, Launch, WaitOutcome};
48//!
49//! let job = Job::create(&JobLimits::new().kill_on_close(true))?;
50//! let child = Launch::new(r"C:\Windows\System32\cmd.exe")
51//!     .args(["/d", "/c", "exit 7"])
52//!     .spawn_in_job(&job)?;
53//! assert_eq!(child.wait(Some(Duration::from_secs(10)))?, WaitOutcome::Signaled);
54//! assert_eq!(child.exit_code()?, Some(7));
55//! # Ok(())
56//! # }
57//! # #[cfg(not(windows))]
58//! # fn main() {}
59//! ```
60//!
61//! # Where the `unsafe` lives
62//!
63//! `unsafe_code` is denied for the crate. Only the modules that call Win32
64//! opt back in, each at its top, and every `unsafe` block there carries a
65//! `SAFETY:` comment naming the invariant it relies on. Raw handles,
66//! pointers and buffer lengths never cross the public API: handles come and
67//! go as [`std::os::windows::io::OwnedHandle`] and
68//! [`std::os::windows::io::BorrowedHandle`], and buffers Windows fills are
69//! bounds-checked before they are read.
70//!
71//! On targets other than Windows the crate compiles to nothing.
72#![cfg(windows)]
73
74mod app_container;
75mod bounded_read;
76mod event;
77mod handle;
78mod job;
79mod launch;
80mod mutex;
81mod pipe;
82mod process;
83mod security;
84mod session;
85mod token;
86mod wide;
87
88pub use app_container::{AppContainerAccess, AppContainerProfile};
89pub use handle::{wait, WaitOutcome};
90pub use job::{Job, JobLimits};
91pub use launch::{anonymous_pipe, null_device, read_to_end_bounded, Launch, SuspendedChild};
92pub use mutex::{MutexAcquisition, NamedMutex};
93pub use pipe::{PipeAccess, PipeClient, PipeDirection, PipeError, PipeServer, PipeWait};
94pub use process::{is_elevated, Process, ProcessAccess};
95pub use security::{
96    current_token_is_member_of, current_user_sid_string, AclValidationError, AllowedAce,
97    ObjectSecurityDescriptor, OwnedSid, PrivilegeGuard, SecurityAclError, SecurityDescriptor,
98    ValidatedDacl, ValidatedSid,
99};
100pub use session::{
101    active_console_session_id, current_session_id, process_session_id, session_processes,
102    SessionProcess,
103};
104pub use token::PrimaryToken;
105
106// Builds the README examples as doctests, so the front page cannot drift from
107// the API.
108#[cfg(doctest)]
109#[doc = include_str!("../README.md")]
110struct ReadmeDoctests;