shep-daemon 0.18.2

The supervision engine behind shep: process spawning, restart policy, the log plane, watch and cron restarts, and the RPC server
Documentation
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
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
//! The Windows counterpart to `sys`: a job object per sheep
//!
//! Windows has no process groups, so where the unix arm spawns each sheep
//! with `process_group(0)`, here the sheep is assigned to a job object: a
//! kernel container its children inherit and which terminates as a unit.
//! A member cannot escape a job created without
//! `JOB_OBJECT_LIMIT_BREAKAWAY_OK`, so `kill_tree` reaches more of the tree
//! here than on unix, where a `setsid` grandchild escapes.
//!
//! `JOB_OBJECT_LIMIT_KILL_ON_JOB_CLOSE` is not set: the daemon holds the
//! handle, so it would take the whole flock down with the shepherd. On unix
//! a sheep outlives a killed shepherd, and the platforms stay aligned.
//!
//! Also the security descriptor behind the shepherd's own pipes, [`UserOnly`].

#![allow(unsafe_code)] // every unsafe site on this platform is in this file

use std::ffi::{OsStr, c_void};
use std::io;
use std::os::windows::io::{AsRawHandle as _, FromRawHandle as _, OwnedHandle, RawHandle};

use shep_core::transport::PipeInstances;
use tokio::net::windows::named_pipe::{NamedPipeServer, ServerOptions};
use windows_sys::Win32::Foundation::{
    CloseHandle, HANDLE, HANDLE_FLAG_INHERIT, LocalFree, SetHandleInformation,
};
use windows_sys::Win32::Security::Authorization::{
    ConvertSidToStringSidW, ConvertStringSecurityDescriptorToSecurityDescriptorW, SDDL_REVISION_1,
};
use windows_sys::Win32::Security::{
    GetTokenInformation, PSID, SECURITY_ATTRIBUTES, TOKEN_QUERY, TOKEN_USER, TokenUser,
};
use windows_sys::Win32::System::Console::{
    GetStdHandle, STD_ERROR_HANDLE, STD_INPUT_HANDLE, STD_OUTPUT_HANDLE,
};
use windows_sys::Win32::System::JobObjects::{
    AssignProcessToJobObject, CreateJobObjectW, JOBOBJECT_EXTENDED_LIMIT_INFORMATION,
    JobObjectExtendedLimitInformation, SetInformationJobObject, TerminateJobObject,
};
use windows_sys::Win32::System::Threading::{GetCurrentProcess, OpenProcessToken};

/// Marks this process's own stdio handles non-inheritable.
///
/// The Windows counterpart to `shep-cli`'s `seal_inherited_fds`.
/// `CreateProcess` with `bInheritHandles = TRUE`, which `std` passes whenever
/// any stdio is redirected, inherits every inheritable handle the parent
/// holds, not only the ones `std` prepared. A shepherd spawned from a shell
/// that gave `shep` a pipe for stdout would hold that pipe open for life, so
/// `shep start | Out-Null` never returns.
///
/// Called immediately before a spawn: it changes only the inherit flag, so
/// this process goes on using its own stdio. Best-effort, nothing to report.
pub fn seal_std_handles() {
    for id in [STD_INPUT_HANDLE, STD_OUTPUT_HANDLE, STD_ERROR_HANDLE] {
        // SAFETY: `GetStdHandle` takes one of the three documented standard
        // handle ids and returns a handle this process already owns, not a
        // new reference, so it must not be closed. Null or
        // `INVALID_HANDLE_VALUE` is filtered before use.
        let handle = unsafe { GetStdHandle(id) };
        if handle.is_null() || handle == windows_sys::Win32::Foundation::INVALID_HANDLE_VALUE {
            continue;
        }
        // SAFETY: `handle` is a live handle owned by this process, checked
        // just above. Clearing `HANDLE_FLAG_INHERIT` changes only whether a
        // future `CreateProcess` passes it on; it neither closes the handle
        // nor affects I/O through it. A failure leaves one spawn inheriting a
        // handle it should not, which is not worth refusing a start over.
        unsafe {
            let _ = SetHandleInformation(handle, HANDLE_FLAG_INHERIT, 0);
        }
    }
}

/// An anonymous job object owning one sheep and everything it spawns.
///
/// Closed on drop. Dropping does not terminate the members: this module's
/// doc covers why `KILL_ON_JOB_CLOSE` is not set.
#[derive(Debug)]
pub(crate) struct Job(HANDLE);

// SAFETY: a job object HANDLE is plain data, not a thread-affine resource;
// Win32 permits any thread to call `AssignProcessToJobObject`,
// `TerminateJobObject` or `CloseHandle` on it. A `Job` moves into the
// per-sheep task that owns its `RunningProcess`.
unsafe impl Send for Job {}
// SAFETY: every Win32 call this module makes on the handle is itself
// thread-safe, and `Job` exposes no interior mutability.
unsafe impl Sync for Job {}

impl Job {
    /// Creates an anonymous job object.
    ///
    /// Anonymous (a null name): a named job is visible in the kernel object
    /// namespace, where another process could open it and terminate the sheep.
    ///
    /// # Errors
    ///
    /// Whatever the OS says if the job cannot be created or its limits set.
    pub(crate) fn create() -> io::Result<Self> {
        // SAFETY: both arguments are the documented "no security attributes,
        // no name" nulls. `CreateJobObjectW` returns a null handle on
        // failure, which is checked immediately below before the value is
        // stored or used.
        let handle = unsafe { CreateJobObjectW(core::ptr::null(), core::ptr::null()) };
        if handle.is_null() {
            return Err(io::Error::last_os_error());
        }
        let job = Self(handle);

        // Zeroed, then left zeroed: every limit flag stays off. Setting the
        // block explicitly makes adding a limit later a one-line edit at a
        // site that already handles its own errors.
        //
        // `JOB_OBJECT_LIMIT_BREAKAWAY_OK` and
        // `JOB_OBJECT_LIMIT_SILENT_BREAKAWAY_OK` are the two flags whose
        // absence is load-bearing: without them a member cannot escape the
        // job, which is what makes `kill_tree` complete.
        // SAFETY: `JOBOBJECT_EXTENDED_LIMIT_INFORMATION` is a plain Win32 POD
        // struct holding no reference, no `NonNull` and no range-restricted
        // enum, so all-zeroes is a valid inhabitant, and is the value wanted:
        // every limit flag off.
        let info: JOBOBJECT_EXTENDED_LIMIT_INFORMATION = unsafe { core::mem::zeroed() };
        // SAFETY: `job.0` is a live job handle, checked non-null above.
        // `JobObjectExtendedLimitInformation` is the class that pairs with
        // `JOBOBJECT_EXTENDED_LIMIT_INFORMATION`, and the pointer and length
        // describe a stack local that outlives the call.
        let ok = unsafe {
            SetInformationJobObject(
                job.0,
                JobObjectExtendedLimitInformation,
                core::ptr::from_ref(&info).cast(),
                u32::try_from(core::mem::size_of::<JOBOBJECT_EXTENDED_LIMIT_INFORMATION>())
                    .expect("the size of a fixed Win32 struct fits in u32"),
            )
        };
        if ok == 0 {
            return Err(io::Error::last_os_error());
        }
        Ok(job)
    }

    /// Assigns an already-spawned process to this job.
    ///
    /// Every process the assigned one creates is a member too, and that
    /// inheritance is what makes this the process-group substitute. A child
    /// that forks a grandchild between the spawn and the assignment leaves it
    /// outside the job; closing that window needs `CREATE_SUSPENDED`, which
    /// `std`'s `Command` cannot express.
    ///
    /// # Errors
    ///
    /// Whatever the OS says. `ERROR_ACCESS_DENIED` usually means shep itself
    /// runs in a job that does not permit breakaway.
    pub(crate) fn assign(&self, process: RawHandle) -> io::Result<()> {
        // SAFETY: `self.0` is a live job handle for as long as `self` lives,
        // and `process` is the caller's live child-process handle, borrowed
        // from a `tokio::process::Child` that outlives this call. Neither
        // handle is consumed.
        let ok = unsafe { AssignProcessToJobObject(self.0, process as HANDLE) };
        if ok == 0 {
            return Err(io::Error::last_os_error());
        }
        Ok(())
    }

    /// Terminates every process in the job.
    ///
    /// Unblockable, like the `SIGKILL` it stands in for. `exit_code` becomes
    /// the observed exit code of every member.
    ///
    /// # Errors
    ///
    /// Whatever the OS says. A job whose members have all exited is not an
    /// error: this succeeds and does nothing.
    pub(crate) fn terminate(&self, exit_code: u32) -> io::Result<()> {
        // SAFETY: `self.0` is a live job handle for as long as `self` lives.
        let ok = unsafe { TerminateJobObject(self.0, exit_code) };
        if ok == 0 {
            return Err(io::Error::last_os_error());
        }
        Ok(())
    }
}

impl Drop for Job {
    fn drop(&mut self) {
        // SAFETY: `self.0` was returned non-null by `CreateJobObjectW` and
        // nothing else in this module closes it; `Job` is neither `Copy` nor
        // `Clone`, so this runs exactly once. A failing `CloseHandle` in a
        // destructor has no caller to report to.
        unsafe {
            let _ = CloseHandle(self.0);
        }
    }
}

/// A security descriptor that admits the shepherd's own user and nobody else
///
/// A named pipe made with `CreateNamedPipe` and no descriptor gets the
/// default one, which grants `Everyone` read, and the single accept behind a
/// per-spawn pipe authenticates nobody. Created under this one, a pipe is
/// refused to every other account, administrators and `SYSTEM` included: the
/// DACL holds one ACE, `GENERIC_ALL` for the user the shepherd runs as, and is
/// protected, so nothing inherits into it.
///
/// It confines nothing on the same account. A dog runs as the operator and
/// can open any pipe the operator can; this keeps a different local account
/// from connecting first and reading a dog's or a sheep's frames (#350).
///
/// Built once per pipe and handed to [`shep_core::transport::Listener::bind_with`]
/// as its [`PipeInstances`], so the first instance and every replacement are
/// created under it.
pub(crate) struct UserOnly {
    /// A self-relative descriptor `LocalAlloc`ed by the converter, freed on drop.
    descriptor: *mut c_void,
}

// SAFETY: the descriptor is written once by the converter and only read after
// that, by `CreateNamedPipe`, which copies it. No Win32 call here mutates it,
// and a raw pointer to memory nothing else aliases is plain data.
unsafe impl Send for UserOnly {}
// SAFETY: shared access only reads the descriptor, as above.
unsafe impl Sync for UserOnly {}

impl core::fmt::Debug for UserOnly {
    fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
        f.debug_struct("UserOnly").finish_non_exhaustive()
    }
}

impl UserOnly {
    /// Builds the descriptor for the user this process runs as.
    ///
    /// # Errors
    ///
    /// Whatever the OS says if the process token cannot be read or the
    /// descriptor cannot be built from the user's SID.
    pub(crate) fn current_user() -> io::Result<Self> {
        let sid = current_user_sid()?;
        // `D:P` is a protected DACL, `A` an allow, `GA` generic-all. Narrower
        // rights would refuse the shepherd its own next instance: creating
        // one needs `FILE_CREATE_PIPE_INSTANCE`, which is in generic-all.
        let mut sddl: Vec<u16> = "D:P(A;;GA;;;".encode_utf16().collect();
        sddl.extend_from_slice(&sid);
        sddl.extend(")\0".encode_utf16());

        let mut descriptor: *mut c_void = core::ptr::null_mut();
        // SAFETY: `sddl` is a NUL-terminated UTF-16 string that outlives the
        // call, and `descriptor` is a live local for the out pointer. The
        // size out parameter is documented optional and passed null. On
        // success the descriptor is `LocalAlloc`ed and handed to `Self`,
        // which frees it; on failure nothing was allocated.
        let ok = unsafe {
            ConvertStringSecurityDescriptorToSecurityDescriptorW(
                sddl.as_ptr(),
                SDDL_REVISION_1,
                &raw mut descriptor,
                core::ptr::null_mut(),
            )
        };
        if ok == 0 {
            return Err(io::Error::last_os_error());
        }
        Ok(Self { descriptor })
    }
}

impl PipeInstances for UserOnly {
    fn create(&self, options: &ServerOptions, addr: &OsStr) -> io::Result<NamedPipeServer> {
        let mut attributes = SECURITY_ATTRIBUTES {
            nLength: u32::try_from(core::mem::size_of::<SECURITY_ATTRIBUTES>())
                .expect("the size of a fixed Win32 struct fits in u32"),
            lpSecurityDescriptor: self.descriptor,
            // The handle stays out of the child: it is the shepherd's end.
            bInheritHandle: 0,
        };
        // SAFETY: `attributes` is a fully initialised `SECURITY_ATTRIBUTES`
        // on this stack frame, so the pointer is valid for the whole call,
        // and its descriptor pointer is the live allocation `self` owns.
        // `CreateNamedPipeW` copies what it needs and keeps neither pointer.
        unsafe { options.create_with_security_attributes_raw(addr, (&raw mut attributes).cast()) }
    }
}

impl Drop for UserOnly {
    fn drop(&mut self) {
        // SAFETY: `descriptor` was allocated by the converter, which
        // documents `LocalFree` as its release, and nothing else frees it:
        // `UserOnly` is neither `Copy` nor `Clone`, so this runs once. A
        // failing free in a destructor has no caller to report to.
        unsafe {
            let _ = LocalFree(self.descriptor);
        }
    }
}

/// The string form of the SID of the user this process runs as, as UTF-16
/// without a terminator.
fn current_user_sid() -> io::Result<Vec<u16>> {
    let mut token: HANDLE = core::ptr::null_mut();
    // SAFETY: `GetCurrentProcess` returns a pseudo-handle that needs no
    // closing, and `token` is a live local for the out pointer. Success hands
    // back a real handle that this process owns.
    let opened = unsafe { OpenProcessToken(GetCurrentProcess(), TOKEN_QUERY, &raw mut token) };
    if opened == 0 {
        return Err(io::Error::last_os_error());
    }
    // SAFETY: `token` is a handle `OpenProcessToken` just returned and
    // nothing else owns, so `OwnedHandle` closes it exactly once.
    let token = unsafe { OwnedHandle::from_raw_handle(token) };

    let mut needed = 0_u32;
    // SAFETY: a null buffer of length zero is the documented way to ask for
    // the size, and `needed` is a live local. The call is expected to fail
    // with `ERROR_INSUFFICIENT_BUFFER`; only `needed` is read after it.
    unsafe {
        GetTokenInformation(
            token.as_raw_handle(),
            TokenUser,
            core::ptr::null_mut(),
            0,
            &raw mut needed,
        );
    }
    if needed == 0 {
        return Err(io::Error::last_os_error());
    }
    // `u64`s so the buffer is aligned for the `TOKEN_USER` read below.
    let mut buffer = vec![0_u64; usize::try_from(needed).unwrap_or(0).div_ceil(8)];
    // SAFETY: `buffer` is at least `needed` bytes, which is the length passed,
    // and `token` is a live token handle opened with `TOKEN_QUERY`.
    let filled = unsafe {
        GetTokenInformation(
            token.as_raw_handle(),
            TokenUser,
            buffer.as_mut_ptr().cast(),
            needed,
            &raw mut needed,
        )
    };
    if filled == 0 {
        return Err(io::Error::last_os_error());
    }
    // SAFETY: the call above filled `buffer` with a `TOKEN_USER` for the
    // `TokenUser` class, and the buffer is 8-byte aligned. Its `Sid` points
    // into the same buffer, which outlives every use below.
    let sid = unsafe { (*buffer.as_ptr().cast::<TOKEN_USER>()).User.Sid };

    // SAFETY: `sid` points into `buffer`, which is alive until this function
    // returns, and the call above filled it with a valid SID.
    unsafe { sid_to_wide(sid) }
}

/// The string form of `sid`, as UTF-16 without a terminator.
///
/// # Safety
///
/// `sid` must point at a valid SID that stays alive for the call.
unsafe fn sid_to_wide(sid: PSID) -> io::Result<Vec<u16>> {
    let mut text: *mut u16 = core::ptr::null_mut();
    // SAFETY: `sid` is valid by this function's contract, and `text` is a
    // live local for the out pointer. Success hands back a `LocalAlloc`ed
    // NUL-terminated string that is freed below.
    let converted = unsafe { ConvertSidToStringSidW(sid, &raw mut text) };
    if converted == 0 {
        return Err(io::Error::last_os_error());
    }
    let mut len = 0;
    // SAFETY: `text` is NUL-terminated, so the scan stops at the terminator,
    // and every index read is before or at it.
    while unsafe { *text.add(len) } != 0 {
        len += 1;
    }
    // SAFETY: `text` holds `len` initialised `u16`s, read before the free.
    let wide = unsafe { core::slice::from_raw_parts(text, len) }.to_vec();
    // SAFETY: `text` came from `ConvertSidToStringSidW`, which documents
    // `LocalFree` as its release, and `wide` is a copy, so nothing reads it
    // after.
    unsafe {
        let _ = LocalFree(text.cast());
    }
    Ok(wide)
}

#[cfg(test)]
mod pipe_security_tests;

#[cfg(test)]
mod tests {
    use super::*;

    /// fails if a job cannot be created and terminated on this machine.
    ///
    /// An empty job is the case worth pinning: `kill_tree` runs against a
    /// sheep that may already have exited, so no members must read as success.
    #[test]
    fn an_empty_job_is_created_and_terminated_without_error() {
        let job = Job::create().expect("a job object must be creatable");
        job.terminate(1)
            .expect("terminating a job with no members must succeed");
    }

    /// fails if a real child assigned to a job survives `terminate`.
    ///
    /// The child would otherwise outrun the test, so an exit can only be the
    /// termination.
    #[tokio::test]
    async fn a_child_assigned_to_a_job_is_killed_by_terminate() {
        let job = Job::create().unwrap();
        // `ping`, not `timeout /t`: `timeout.exe` refuses a non-console stdin
        // and exits in milliseconds, so it would assert nothing here.
        let mut child = tokio::process::Command::new("cmd")
            .args(["/C", "ping", "-n", "600", "127.0.0.1"])
            .stdout(std::process::Stdio::null())
            .stderr(std::process::Stdio::null())
            .stdin(std::process::Stdio::null())
            .spawn()
            .expect("cmd must be spawnable on Windows");

        let handle = child
            .raw_handle()
            .expect("a just-spawned child has a raw handle");
        job.assign(handle).expect("assignment must succeed");

        job.terminate(9).unwrap();

        let status = tokio::time::timeout(std::time::Duration::from_secs(10), child.wait())
            .await
            .expect("a terminated job member must not outlive its job")
            .unwrap();
        assert!(
            !status.success(),
            "a job-terminated child must not report success"
        );
    }
}