fix(sandbox): support kernels < 5.19 via seccomp WAIT_KILLABLE_RECV fallback

[akram]

Summary

The capability-free sandbox hard-requires SECCOMP_FILTER_FLAG_WAIT_KILLABLE_RECV (Linux 5.19+) to install its notification listener. On older kernels (RHEL 9.x / 5.14, i.e. current OpenShift/RHCOS nodes) the seccomp() call returns EINVAL, the listener thread dies (notification launcher disappeared), and the supervisor fails confirmation — so the sandbox cannot start.

This makes the flag optional: attempt it, and gracefully fall back to a plain NEW_LISTENER when the kernel doesn't support it. Zero-cap containment is unchanged (the listener still mediates every syscall); the only thing lost on < 5.19 is the killable-receive semantics.

Related Issue

Fixes #3417

Changes

• openshell-isolation-interface install_listener: try WAIT_KILLABLE_RECV, and on EINVAL retry with a plain NEW_LISTENER. The resulting listener records wait_killable_recv = false.
• SandboxConfirmEvidence::validate(): stop gating launch on the cancellation evidence (which is exactly WAIT_KILLABLE_RECV), so confirmation succeeds on < 5.19. Updated the conformance test to assert rejection on a containment-critical primitive (new_listener) instead.

Testing

• Validated end-to-end on OpenShift / RHCOS RHEL 9.8 (kernel 5.14.0-687.35.1.el9_8): the capability-probe returns {"qualified":true, "seccomp_notification":true, "wait_killable_recv":false}, and a real sandbox created through the Kubernetes driver reaches Ready (workload + supervisor pods both Running). Before the change the same path failed with notification launcher disappeared.
• On kernels >= 5.19 behavior is unchanged (WAIT_KILLABLE_RECV is still used; wait_killable_recv = true).
• Built clean (musl release) in-cluster for the sandbox and supervisor images; conformance test updated. Unit/conformance suite runs in CI.

Checklist

• Conventional Commits + --signoff (DCO)
• Change scoped to the issue
• Degraded semantics on < 5.19 documented in code comments
• Maintainer review of the security-contract change (validate())

[copy-pr-bot]

This pull request requires additional validation before any workflows can run on NVIDIA's runners.

Pull request vetters can view their responsibilities here.

Contributors can view more details about this message here.

[mrunalp]

Findings

1. The fallback removes a documented security invariant. Before this PR, kernels without WAIT_KILLABLE_RECV failed closed. With the fallback, a workload can signal a notifying thread after ID_VALID but before process_vm_writev, allowing stale task-memory writes after the syscall
   resumes. The architecture explicitly makes the flag mandatory for this reason. Fallback (

   OpenShell/crates/openshell-isolation-interface/src/linux/seccomp_notify.rs

   Lines 333 to 344 in de00bfc

   	// WAIT_KILLABLE_RECV (Linux 5.19+) makes the supervisor's notification
   	// receive interruptible by a fatal signal. Kernels older than 5.19 (for
   	// example RHEL 9.x / 5.14 nodes) reject the flag with EINVAL. Rather than
   	// refusing to start there, fall back to a plain listener: the notification
   	// receive is then uninterruptible, but the sandbox is otherwise fully
   	// functional. The resulting listener records `wait_killable_recv = false`
   	// so callers can observe the degraded cancellation semantics.
   	match install_listener_with_flags(syscalls, true) {
   	Ok(listener) => Ok(listener),
   	Err(error) if error.raw_os_error() == Some(libc::EINVAL) => {
   	install_listener_with_flags(syscalls, false)
   	}

   ), write path
   (

   OpenShell/crates/openshell-sandbox/src/network_broker.rs

   Lines 1680 to 1685 in de00bfc

   	listener.validate_id(notification_id)?;
   	if copied != 0 {
   	task_memory::write_exact(tid, address, &bytes[..copied])?;
   	}
   	listener.validate_id(notification_id)?;
   	task_memory::write_exact(tid, length_address, &actual_length.to_ne_bytes())

   ), architecture invariant
   (

   OpenShell/architecture/sandbox.md

   Lines 172 to 174 in de00bfc

   	This sandbox runtime requires Linux 6.2 or newer for Landlock ABI v3 and treats
   	`SECCOMP_FILTER_FLAG_WAIT_KILLABLE_RECV` as mandatory so cancelled
   	notifications cannot race task-memory writes.

   ).

   The kernel documentation (https://github.com/torvalds/linux/blob/master/Documentation/userspace-api/seccomp_filter.rst) confirms that the flag suppresses non-fatal signals after userspace receives the notification. I would retain the launch gate until the pointer-writing paths
   have another cancellation-safe design.

2. The new comments describe the kernel semantics backwards. A plain listener is interruptible by non-fatal signals; WAIT_KILLABLE_RECV makes the notifying task ignore them after receipt. The comment currently says the fallback is “uninterruptible” and attributes the behavior to
   the supervisor’s receive operation. The unchanged architecture documentation also contradicts the new behavior.

Full transparent behavior on old kernels is difficult. The safest approach is an explicit legacy mode that forbids broker writes into workload memory.

Mode Behavior
━━━━━━━━━━━━━━━ ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Modern kernel Use WAIT_KILLABLE_RECV; retain full behavior
─────────────── ─────────────────────────────────────────────────────────────────
Legacy kernel Plain listener, but no task-memory output writes
─────────────── ─────────────────────────────────────────────────────────────────
Current PR Plain listener while retaining writes; unsafe cancellation race

Recommended changes:

1. Keep the EINVAL fallback, but record a Killable versus LegacyReadOnly listener mode.

2. Centralize task-memory writes behind a listener method that rejects them in legacy mode.

3. In legacy mode:

   • Support accept/accept4 only with null address arguments.
   • Reject mediated getpeername with EOPNOTSUPP, or allow native behavior where safe.
   • Reject sendmmsg paths requiring msg_len writes.
   • Continue supporting socket creation, connect, bind, listen, sendto, and sendmsg; these use copied inputs, scalar responses, or atomic ADDFD_SEND.

4. Change confirmation validation to accept either:

   • killable notifications with task-memory writes, or
   • legacy mode with task-memory writes disabled.

5. Add tests that deliberately install a plain listener—even on a modern kernel—and prove every output-write path fails closed.

6. Document the reduced syscall compatibility and emit the selected mode in qualification output.

The key invariant should be something like:

cancellation || task_memory_writes_disabled

rather than removing cancellation from validation unconditionally.

This would let outbound-oriented workloads run on RHEL 9 while preserving containment. Some server workloads may fail because common accept wrappers request the peer address. Full compatibility requires a distribution backport of WAIT_KILLABLE_RECV; userspace cannot atomically
combine arbitrary task-memory writes with a seccomp response. The kernel documentation (https://github.com/torvalds/linux/blob/master/Documentation/userspace-api/seccomp_filter.rst) explains why non-fatal signal suppression matters after notification receipt.

[johntmyers]

gator-agent

PR Review Status

Thanks @mrunalp. I independently checked the signal-cancellation concern against the kernel contract, the broker's accept/getpeername/sendmmsg output-write paths, and the architecture invariant; it is reachable on the proposed plain-listener fallback and remains blocking.

Action required: @akram, preserve cancellation safety for every task-memory output write and update the comments and architecture documentation to describe the selected legacy behavior accurately.

Blocking findings:

• GATOR-de00bfcc-01: plain-listener notification cancellation can race privileged writes into workload memory

Carried findings:

• None

Non-blocking suggestions:

• None

Gator metadata

• Validation: Project-valid focused fix for accepted issue #3417
• Docs: Missing; architecture/sandbox.md still says WAIT_KILLABLE_RECV is mandatory, and the new inline comments reverse the flag semantics
• Checks: DCO, vouch, and Trivy pass; Branch Checks and Helm Lint await current-head test dispatch
• E2E: test:e2e is required for sandbox lifecycle and seccomp enforcement behavior, but dispatch waits for blocking review feedback
• Head SHA: de00bfccfca2d284da266865a6e99c74e9284d02
• Base SHA: 8de26878f9324a822131ff6107861134843f1886
• Merge base SHA: 6d496f540a1a2e5c49687cddd68d56dc82cd5ebb
• Patch ID: 8efd98bbfd32d2ebec43ab50ae307293afde088e
• Gator payload: 9
• Review mode: initial
• Previous reviewed SHA: none
• Review budget exhausted: no
• Maintainer decision required: no
• Next state: gator:in-review

[akram]

thank you @mrunalp and @johntmyers , I'am addressing the change request in subsequent commits

[johntmyers]

gator-agent

Blocked

Thanks @akram. I saw your follow-up commit addressing the cancellation-safety request, including the legacy read-only listener mode and the updated architecture documentation. I cannot run the required delta review yet because GitHub reports that this head conflicts with main.

Next action: @akram, rebase or merge main, resolve the conflicts, and push the resulting head. Gator will then review the author-only delta against the open GATOR-de00bfcc-01 obligation.

Gator metadata

• Head SHA: dc85fde79de44297ccbd5794381512d90eaa13b0
• Gator payload: 9
• Next state: gator:blocked
• Blocked reason: merge_conflict

[elezar]

Under which conditions would cancellation and task_memory_writes_disabled not have different values?

[akram]

@elezar you're right: today task_memory_writes_disabled is just !cancellation, so the two are always opposite and the cancellation || task_memory_writes_disabled check is tautological.

Instead of dropping the field, I'd make it a real independent attestation. At qualification the sandbox installs a LegacyReadOnly listener and checks that its own broker guard (write_task_output) actually fails closed with EOPNOTSUPP, then reports that result. It becomes true only when the listener is legacy and the guard is verified, so if the guard ever regressed and started writing again, the field drops to false while cancellation is already false, and validate() rejects the boundary instead of admitting the race. The two can then genuinely diverge, and the invariant has teeth. It's ~20 lines in qualify_runtime (prototype on explore/seccomp-writes-disabled-selftest).

I can fix it in this PR, or in a follow-up PR if you'd rather land the current change first.

Since this touches the cancellation-safety contract you reviewed: @mrunalp @johntmyers, does the direction work for you? The alternative is collapsing to a single ListenerMode, which makes the unsafe state unrepresentable but leaves no confirmation cross-check. I'm leaning toward the attestation since it keeps validate() meaningful.

[github-actions]

Label test:e2e applied, but pull-request/3420 does not exist yet. A maintainer needs to comment /ok to test 2370e5059f9d144a65b25f0b515b9eddea929d90 to mirror this PR. Once the mirror exists, re-apply the label or re-run Branch E2E Checks from the Actions tab.

[johntmyers]

/ok to test 2370e50

[johntmyers]

gator-agent

PR Review Status

Thanks @akram. I reviewed the current head after your follow-up on the cancellation-safety request. The new legacy read-only listener mode routes sendmmsg length writes through the guarded output method and rejects accept/accept4 address output plus getpeername before task-memory access, so GATOR-de00bfcc-01 is resolved with no new code blockers.

Action required: Please document the kernel-before-5.19 LegacyReadOnly behavior and its EOPNOTSUPP limitations in the relevant public Fern docs under docs/ (for example, the OpenShift runtime guidance and support matrix). The architecture update alone does not satisfy the public documentation gate for this observable sandbox behavior.

Blocking findings:

• No blocking code findings remain.

Carried findings:

• GATOR-de00bfcc-01: resolved by the current head; the Gator-owned review thread is closed.

Gator metadata

• Validation: Project-valid fix for accepted issue Capability-free sandbox fails to start on kernels < 5.19 (RHEL 9.x / 5.14): seccomp WAIT_KILLABLE_RECV EINVAL #3417, with explicit maintainer direction to proceed.
• Docs: Public Fern docs are missing the legacy listener compatibility and syscall limitations.
• Checks: Current-head Branch Checks, Helm Lint, and E2E workflows are queued.
• E2E: test:e2e applied; /ok to test 2370e5059f9d144a65b25f0b515b9eddea929d90 posted; Branch E2E Checks queued.
• Head SHA: 2370e5059f9d144a65b25f0b515b9eddea929d90
• Base SHA: 8bd3dcc565f380ddfc464fc41b1faa936d72af3e
• Merge base SHA: 4b2cb7f007da2f701422daf394643b0fd9d4daef
• Patch ID: f37aa8ca1ee936368882526dbd8c95ff9f47ec37
• Gator payload: 9
• Review mode: follow_up
• Previous reviewed SHA: de00bfccfca2d284da266865a6e99c74e9284d02
• Review budget exhausted: no
• Maintainer decision required: no
• Next state: gator:in-review

[akram]

doc added @johntmyers

[johntmyers]

/ok to test 285085e

[github-actions]

Label test:e2e applied for 285085e. Open the existing run and click Re-run all jobs to execute with the label set. The run will execute the standard E2E suite after building the required gateway, sandbox, and supervisor images once. The matching required CI gate status on this PR will flip green automatically once the run finishes.