Skip to content

Commit da46aba

Browse files
committed
feat(isolation): add conformant sidecar RFC 0012 backend
Refactor the supervisor so the Kubernetes sidecar topology is driven by a first-class RFC 0012 isolation backend instead of an inline conditional branch. The agent container's supervisor now resolves a `sidecar` backend from the driver-provided `TopologyDescriptor` and runs the standard `attach -> confirm -> start_agent` lifecycle, identically to the in-pod backend; the supervisor no longer branches on which backend it resolved. The agent container stays autonomous and spawns its own workload, so the backend wraps the existing agent/process path rather than inverting control. Network mediation continues to run in the separate network-sidecar container (framed as the RFC's network-mediation component), which hosts no local mediation ingress in the backend. Fail-closed hardening: - `attach` validates the descriptor payload at the trust boundary (empty for this topology), mirroring the in-pod backend. - `confirm` peeks the authoritative control link to the network container and refuses to advance if it is already closed, so the workload is never launched only to be torn down on the first `wait`. - The supervisor rejects a single process that enables both --mode=network and --mode=process under sidecar enforcement (never driver-produced) instead of silently holding open without spawning the workload. - `wait` races the workload against the control-closed signal and folds any wait error to a closed exit, dropping the workload handle to reap it. Add `SIDECAR_BACKEND_ID` and `TopologyDescriptor::sidecar()` to the contract crate, wire the driver to set the sidecar descriptor on the agent container, and update the sandbox architecture doc. Also fix pre-existing clippy lints in openshell-isolation surfaced by the workspace `-D warnings` gate. Signed-off-by: Jordan Ganoff <jordan.ganoff@docker.com>
1 parent ac3cd28 commit da46aba

6 files changed

Lines changed: 911 additions & 162 deletions

File tree

‎architecture/sandbox.md‎

Lines changed: 23 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -52,18 +52,29 @@ paths, such as proxy support files or GPU device paths when a GPU is present.
5252
## Isolation Backend
5353

5454
The supervisor does not build the boundary inline. It drives an **isolation
55-
backend** (RFC 0012) through one runtime contract (`ensure_boundary` → `bind`
56-
→ `boundary_ready` → `start_agent`), so the same supervisor code runs wherever
57-
the boundary sits. Today only the in-pod backend exists: it builds the boundary
58-
in the same process that operates it, over the existing primitives (network
59-
namespace, proxy, the pre-exec Landlock/seccomp ceiling, procfs identity).
60-
61-
The contract covers the full isolation envelope. `ensure_boundary` establishes
62-
the network namespace; `start_agent` establishes filesystem (Landlock) and
63-
syscall (seccomp) at process entry; `identity` resolves the connecting binary
64-
from procfs at runtime. The lifecycle handles are unforgeable type-state
65-
tokens, so the order (and thus "no workload runs before the boundary is
66-
ready") holds by construction rather than by convention.
55+
backend** (RFC 0012) through one runtime contract (`attach` → `confirm` →
56+
`start_agent`, over the `Bound`/`Ready`/`Running` type-state), so the same
57+
supervisor code runs wherever the boundary sits. The supervisor selects the
58+
backend from the driver-provided `TopologyDescriptor` and never branches on
59+
which one it resolved. Two backends exist:
60+
61+
- **in-pod** — builds and operates the boundary in the same process, over the
62+
existing primitives (network namespace, proxy, the pre-exec Landlock/seccomp
63+
ceiling, procfs identity).
64+
- **sidecar** (Kubernetes) — the agent container's supervisor runs this backend
65+
to operate the workload; network mediation runs in a separate network-sidecar
66+
container the backend coordinates (the agent container holds no gateway
67+
credentials and receives its policy over a peer-cred-authenticated control
68+
socket). The agent stays autonomous — it spawns its own workload — so the
69+
backend wraps that path rather than inverting control.
70+
71+
`attach` binds the trusted sandbox context and establishes standing enforcement;
72+
`confirm` verifies it (fail-closed); `start_agent` establishes the per-process
73+
launch-time controls (Landlock/seccomp) before the first untrusted instruction;
74+
identity resolves the connecting binary from procfs at runtime. The lifecycle
75+
handles are unforgeable type-state tokens, so the order (and thus "no workload
76+
runs before the boundary is ready") holds by construction rather than by
77+
convention.
6778

6879
## Network and Inference
6980

‎crates/openshell-driver-kubernetes/src/driver.rs‎

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1996,6 +1996,16 @@ fn apply_supervisor_sidecar_topology(
19961996
openshell_core::sandbox_env::SIDECAR_CONTROL_SOCKET,
19971997
SIDECAR_CONTROL_SOCKET,
19981998
);
1999+
// RFC 0012: the agent container's supervisor resolves the sidecar
2000+
// backend, so override the default in-pod descriptor set by
2001+
// `apply_required_env`. (The network sidecar container keeps the
2002+
// in-pod default; it runs the mediation component, not a backend, so
2003+
// its descriptor is never resolved.)
2004+
upsert_env(
2005+
env,
2006+
openshell_core::sandbox_env::TOPOLOGY_DESCRIPTOR,
2007+
&openshell_isolation::contract::TopologyDescriptor::sidecar().to_env_value(),
2008+
);
19992009
upsert_env(
20002010
env,
20012011
openshell_core::sandbox_env::PROXY_TLS_DIR,
@@ -4255,6 +4265,13 @@ mod tests {
42554265
rendered_env(agent, openshell_core::sandbox_env::SIDECAR_CONTROL_SOCKET),
42564266
Some(SIDECAR_CONTROL_SOCKET)
42574267
);
4268+
// RFC 0012: the agent container resolves the sidecar backend.
4269+
let sidecar_descriptor =
4270+
openshell_isolation::contract::TopologyDescriptor::sidecar().to_env_value();
4271+
assert_eq!(
4272+
rendered_env(agent, openshell_core::sandbox_env::TOPOLOGY_DESCRIPTOR),
4273+
Some(sidecar_descriptor.as_str())
4274+
);
42584275
assert_eq!(rendered_env(agent, "OPENSHELL_SUPERVISOR_READY_FILE"), None);
42594276
assert_eq!(rendered_env(agent, "OPENSHELL_ENTRYPOINT_PID_FILE"), None);
42604277
assert_eq!(
@@ -4288,6 +4305,16 @@ mod tests {
42884305
sidecar["command"],
42894306
serde_json::json!([SUPERVISOR_IMAGE_BINARY_PATH, "--mode=network"])
42904307
);
4308+
// The network sidecar container runs the mediation component, not a
4309+
// backend, so it keeps the default in-pod descriptor (never resolved).
4310+
assert_eq!(
4311+
rendered_env(sidecar, openshell_core::sandbox_env::TOPOLOGY_DESCRIPTOR),
4312+
Some(
4313+
openshell_isolation::contract::TopologyDescriptor::in_pod()
4314+
.to_env_value()
4315+
.as_str()
4316+
)
4317+
);
42914318
assert_eq!(sidecar["securityContext"]["runAsUser"], 0);
42924319
assert_eq!(sidecar["securityContext"]["runAsGroup"], 1500);
42934320
assert_eq!(sidecar["securityContext"]["runAsNonRoot"], false);

‎crates/openshell-isolation/src/contract.rs‎

Lines changed: 35 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -52,6 +52,16 @@ pub const CONTRACT_VERSION: u32 = 1;
5252
/// `openshell-sandbox`.
5353
pub const IN_POD_BACKEND_ID: &str = "in-pod";
5454

55+
/// The well-known backend id of the Kubernetes sidecar topology.
56+
///
57+
/// Selected for the agent container, whose supervisor runs this backend to
58+
/// operate the workload; network mediation runs in a separate network-sidecar
59+
/// container that the backend coordinates. A distinct topology from `in-pod`.
60+
/// Lives in the contract crate because compute drivers create the
61+
/// [`TopologyDescriptor`] naming it; the implementation lives in
62+
/// `openshell-sandbox`.
63+
pub const SIDECAR_BACKEND_ID: &str = "sidecar";
64+
5565
// ============================================================================
5666
// Errors
5767
// ============================================================================
@@ -190,6 +200,19 @@ impl TopologyDescriptor {
190200
}
191201
}
192202

203+
/// The descriptor for the Kubernetes sidecar topology's agent container: the
204+
/// supervisor there resolves the sidecar backend. The payload is empty; the
205+
/// backend reads its operational data (control socket, expected peer) from
206+
/// the driver-controlled environment for now.
207+
#[must_use]
208+
pub fn sidecar() -> Self {
209+
Self {
210+
contract_version: CONTRACT_VERSION,
211+
backend_id: SIDECAR_BACKEND_ID.to_string(),
212+
payload: Vec::new(),
213+
}
214+
}
215+
193216
/// Serialize for the driver-controlled environment transport
194217
/// (`OPENSHELL_TOPOLOGY_DESCRIPTOR`): `<version>:<backend_id>:<hex payload>`.
195218
/// Other transports deliver the same envelope with equivalent integrity.
@@ -251,7 +274,7 @@ fn hex_encode(bytes: &[u8]) -> String {
251274
}
252275

253276
fn hex_decode(hex: &str) -> Option<Vec<u8>> {
254-
if !hex.is_ascii() || hex.len() % 2 != 0 {
277+
if !hex.is_ascii() || !hex.len().is_multiple_of(2) {
255278
return None;
256279
}
257280
(0..hex.len())
@@ -444,9 +467,11 @@ pub trait BoundBoundary: Send {
444467
async fn confirm(self: Box<Self>) -> Result<Box<dyn ReadyBoundary>, BackendError>;
445468
}
446469

447-
/// Ready: mediation is initialized, standing enforcement is confirmed, and the
448-
/// backend is prepared to ensure the admitted launch-time controls are in force
449-
/// before untrusted execution. Only agent activation is possible from here.
470+
/// Ready: mediation is initialized and standing enforcement is confirmed.
471+
///
472+
/// The backend is prepared to ensure the admitted launch-time controls are in
473+
/// force before untrusted execution. Only agent activation is possible from
474+
/// here.
450475
#[async_trait]
451476
pub trait ReadyBoundary: Send {
452477
/// Make the admitted agent runnable behind the boundary and return its
@@ -459,10 +484,11 @@ pub trait ReadyBoundary: Send {
459484
async fn start_agent(self: Box<Self>) -> Result<Box<dyn RunningBoundary>, BackendError>;
460485
}
461486

462-
/// Running: the agent is runnable behind the boundary and the returned agent
463-
/// handle owns the complete workload tree. Exec and forwarding are available.
464-
/// All interface accessors return owned `Arc`s so a consumer can retain them
465-
/// past any later state consumption.
487+
/// Running: the agent is runnable behind the boundary.
488+
///
489+
/// The returned agent handle owns the complete workload tree. Exec and
490+
/// forwarding are available. All interface accessors return owned `Arc`s so a
491+
/// consumer can retain them past any later state consumption.
466492
pub trait RunningBoundary: Send + Sync {
467493
/// The agent process handle (owns the complete workload tree).
468494
fn agent(&self) -> Arc<dyn BoundaryProcess>;
@@ -558,6 +584,7 @@ pub struct ExecSpec {
558584
}
559585

560586
/// In-boundary process entry, consumed by the SSH server and supervisor session.
587+
///
561588
/// Like `start_agent`, every exec ensures the applicable launch-time controls
562589
/// are in force before the new process executes its first untrusted instruction
563590
/// and preserves the provisioned execution environment.

‎crates/openshell-isolation/src/lib.rs‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -26,7 +26,7 @@
2626
//! # Ordering is a security property
2727
//!
2828
//! The lifecycle states run in order: attach -> Bound -> confirm -> Ready ->
29-
//! start_agent -> Running. Nothing untrusted runs inside the boundary until it
29+
//! `start_agent` -> Running. Nothing untrusted runs inside the boundary until it
3030
//! is confirmed ready. This is enforced *by construction*: each transition
3131
//! consumes the prior state by value, and no state type has a public
3232
//! constructor, so the supervisor cannot skip a stage or run a workload before

0 commit comments

Comments
 (0)