1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
//! 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;
//! [`AppContainerProfile::ensure_path_access`] avoids writing when the access
//! is already present.
//! For code that needs stronger isolation, use a separate low-privilege
//! account.
//!
//! # Example
//!
//! ```no_run
//! # #[cfg(windows)]
//! # fn main() -> std::io::Result<()> {
//! 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));
//! # Ok(())
//! # }
//! # #[cfg(not(windows))]
//! # fn main() {}
//! ```
//!
//! # 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.
pub use ;
pub use ;
pub use ;
pub use ;
pub use ;
pub use ;
pub use ;
pub use ;
pub use ;
pub use PrimaryToken;
// Builds the README examples as doctests, so the front page cannot drift from
// the API.
;