fix(sandbox): document unsafe blocks and enforce SAFETY comments with clippy

Every non-test unsafe block in openshell-sandbox now carries a
// SAFETY: comment stating its invariant, and
clippy::undocumented_unsafe_blocks is enabled at warn level in the
crate roots (lib, the sandbox bin, and the seccomp-perf bin), so the
CI clippy lanes with -D warnings fail the build on new undocumented
blocks. Test-only blocks are exempt through cfg_attr(test, allow) to
keep this change free of test-comment churn; the lint fires 89 times
on main and zero times after this change.

reset_child_signal_dispositions gains a # Safety section documenting
its caller contract (forked pre-exec child only), and the vsock
control stream reinterpreted as a UnixStream is documented in place:
the family-agnostic operations it relies on, the AF_UNIX members that
must never be called on it, and the dial-side twin of the same
reinterpretation.

Small mechanical edits were required so each comment sits on the line
directly above its unsafe block (the lint is line-anchored): nine
expressions hoisted into let bindings or nested ifs (five syscall
probes in main.rs, two F_SETFL guards in network_broker.rs, two in
boundary_server.rs), plus two reorderings (a timeout binding in
network_broker.rs, the SAFETY comment placement in seccomp_notify.rs).
Every movement preserves the original short-circuits and the errno
adjacency the probe helpers rely on, and four new tests pin those
properties: two run the self-protection probes against seccomp filters
(one lets the FIOSETOWN ioctl through to the kernel, so a probe that
reads another syscall's errno fails), and two cover the F_SETFL error
arms in connect_exact (an O_PATH descriptor for the transition
failure, a deny filter for the restore failure).

multiple_unsafe_ops_per_block is deliberately not enabled: it is
restriction-group and needs block splits at production sites owned by
#5180.

Closes #5188

Signed-off-by: Emilien Macchi <emacchi@redhat.com>

Author: EmilienM

crates/openshell-sandbox/src/bin/seccomp-perf.rs

@@ -3,6 +3,10 @@
 
 //! Microbenchmark entry point for the production seccomp network broker.
 
+// Crate-scoped: Cargo rejects mixing `[lints] workspace = true` with a
+// crate-specific lint table (see #5188).
+#![warn(clippy::undocumented_unsafe_blocks)]
+
 #[cfg(target_os = "linux")]
 use std::net::SocketAddr;
 

crates/openshell-sandbox/src/boundary_server.rs

@@ -4828,6 +4828,8 @@ mod linux {
                 .map_err(|_| {
                     io::Error::new(io::ErrorKind::InvalidInput, "sockaddr_vm exceeds socklen_t")
                 })?;
+            // SAFETY: socket() creates a fresh descriptor and takes only
+            // scalar arguments; the result is checked below before any use.
             let raw_fd = unsafe {
                 libc::socket(
                     libc::AF_VSOCK,
@@ -4838,6 +4840,8 @@ mod linux {
             if raw_fd < 0 {
                 return Err(io::Error::last_os_error());
             }
+            // SAFETY: raw_fd was checked non-negative above and is uniquely
+            // owned; this is its single wrap into an OwnedFd.
             let fd = unsafe { OwnedFd::from_raw_fd(raw_fd) };
             let address = libc::sockaddr_vm {
                 svm_family: family,
@@ -4846,6 +4850,8 @@ mod linux {
                 svm_cid: libc::VMADDR_CID_ANY,
                 svm_zero: [0; 4],
             };
+            // SAFETY: bind operates on the live OwnedFd with a fully
+            // initialized sockaddr_vm of the declared length.
             let result = unsafe {
                 libc::bind(
                     fd.as_raw_fd(),
@@ -4856,6 +4862,7 @@ mod linux {
             if result < 0 {
                 return Err(io::Error::last_os_error());
             }
+            // SAFETY: listen operates on the live, bound OwnedFd.
             if unsafe { libc::listen(fd.as_raw_fd(), 16) } < 0 {
                 return Err(io::Error::last_os_error());
             }
@@ -4879,6 +4886,9 @@ mod linux {
                     listener,
                     server_config,
                 } => {
+                    // SAFETY: accept4 takes the live listener descriptor with
+                    // SOCK_CLOEXEC and a valid null address buffer; the
+                    // returned descriptor is checked below before any use.
                     let raw_fd = unsafe {
                         libc::accept4(
                             listener.as_raw_fd(),
@@ -4890,8 +4900,11 @@ mod linux {
                     if raw_fd < 0 {
                         Err(io::Error::last_os_error())
                     } else {
+                        // SAFETY: raw_fd was checked non-negative above and
+                        // is uniquely owned; this is its single wrap.
+                        let stream = unsafe { File::from_raw_fd(raw_fd) };
                         Ok(ControlStream::PendingTls {
-                            stream: PlainControlStream::Vsock(unsafe { File::from_raw_fd(raw_fd) }),
+                            stream: PlainControlStream::Vsock(stream),
                             server_config: server_config.clone(),
                         })
                     }
@@ -5086,8 +5099,26 @@ mod linux {
         ) -> io::Result<openshell_isolation_interface::contract::BoundaryDuplexStream> {
             match self {
                 Self::Vsock(file) => {
-                    let stream =
-                        unsafe { std::os::unix::net::UnixStream::from_raw_fd(file.into_raw_fd()) };
+                    let raw_fd = file.into_raw_fd();
+                    // SAFETY: `into_raw_fd` handed over a valid, open,
+                    // solely-owned descriptor exactly once, so this is its
+                    // single re-wrap. The descriptor is an AF_VSOCK stream
+                    // reinterpreted as a Unix stream; the stream only ever
+                    // sees family-agnostic operations (fcntl, read/write,
+                    // epoll registration via `from_std`, and shutdown), which
+                    // behave the same on AF_VSOCK streams. `peer_addr`,
+                    // `local_addr`, and `peer_cred` must never be called on
+                    // it: they would fail at runtime on a vsock descriptor.
+                    // The surface is fenced by this private enum and by the
+                    // `Box<dyn DuplexStream>` erasure in `into_tokio`. The
+                    // dial side performs the same reinterpretation in the
+                    // `RuntimeInitiatedVsock` arm of `dial_supervisor`, but
+                    // files its vsock descriptors under the `Unix` variant
+                    // (not `Vsock`) and uses only `take_error()` (a
+                    // SOL_SOCKET getsockopt) and `writable()`, both
+                    // family-agnostic; the allowed-ops list above covers
+                    // this accept-side stream only.
+                    let stream = unsafe { std::os::unix::net::UnixStream::from_raw_fd(raw_fd) };
                     stream.set_nonblocking(true)?;
                     Ok(Box::new(tokio::net::UnixStream::from_std(stream)?))
                 }

crates/openshell-sandbox/src/lib.rs

@@ -3,6 +3,11 @@
 
 //! Capability-free in-workload sandbox boundary.
 
+// Crate-scoped: Cargo rejects mixing `[lints] workspace = true` with a
+// crate-specific lint table (see #5188).
+#![warn(clippy::undocumented_unsafe_blocks)]
+#![cfg_attr(test, allow(clippy::undocumented_unsafe_blocks))]
+
 pub mod binary_pins;
 #[cfg(target_os = "linux")]
 pub mod boundary_exec;

crates/openshell-sandbox/src/linux/seccomp_notify.rs

@@ -831,8 +831,6 @@ fn verify_notification_sizes() -> io::Result<()> {
 }
 
 fn ioctl_ptr(fd: RawFd, request: libc::c_ulong, argument: *mut libc::c_void) -> io::Result<i64> {
-    // SAFETY: every caller supplies the UAPI structure encoded into `request`,
-    // alive and writable for the ioctl duration.
     // `libc::ioctl` models the request as `c_ulong` for glibc and `c_int`
     // for musl. Linux UAPI request values fit both representations.
     #[cfg(target_env = "musl")]
@@ -841,6 +839,8 @@ fn ioctl_ptr(fd: RawFd, request: libc::c_ulong, argument: *mut libc::c_void) ->
     })?;
     #[cfg(target_env = "musl")]
     let request = libc::c_int::from_ne_bytes(request.to_ne_bytes());
+    // SAFETY: every caller supplies the UAPI structure encoded into `request`,
+    // alive and writable for the ioctl duration.
     let result = unsafe { libc::ioctl(fd, request, argument) };
     if result < 0 {
         Err(io::Error::last_os_error())