Skip to content

Commit 11ba67a

Browse files
committed
fix(compute): explain root/unresolved USER identity rejection
Creating a sandbox from an image whose OCI USER resolves to root (for example `USER root`, or a non-root user listed in group 0 via the image's /etc/group) failed with an opaque, internal-sounding message: IdentityResolutionFailed: descriptor error: workload identity must not contain UID or GID zero It named neither the image nor the offending component, leaked the internal `descriptor error:` prefix, and offered no remediation. The Docker and Podman identity resolvers now emit an actionable error before the identity constructor rejects the zero value. The message names the image, says which component is zero (user, primary group, or a supplementary group), where the value came from (the image's USER, its /etc/passwd or /etc/group, or the policy), and how to proceed (use a non-root image, or set process.run_as_user and process.run_as_group). A new shared helper, `root_identity_rejection_message`, keeps the wording consistent across both drivers and is unit-tested without a Docker/Podman daemon. This is a diagnostics and documentation change only. Root is still rejected by `ResolvedWorkloadIdentity::new`, and an image with no USER and no policy identity still resolves to 1000:1000; no UID/GID mapping, isolation, or trust behavior is changed. Also correct `runtimes.mdx`, which claimed images without a USER must set both policy identity fields; it now matches `default-policy.mdx` and the code (no USER falls back to UID/GID 1000, and a root USER is rejected unless the policy sets a non-root identity). Addresses the error-message and docs acceptance criteria of NVIDIA#4030. The CLI "print the failure once" criterion is deferred pending maintainer clarification (elezar) on whether "once" covers the final visible output or every terminal write including transient spinner frames. Signed-off-by: Udaya Tejas <[email protected]>
1 parent fa2d381 commit 11ba67a

5 files changed

Lines changed: 294 additions & 5 deletions

File tree

‎crates/openshell-driver-docker/src/lib.rs‎

Lines changed: 36 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -61,7 +61,9 @@ use openshell_core::{
6161
AppArmorProfile, Error, ImagePullPolicy, NetworkSupervisorTrustBundle, Result as CoreResult,
6262
UpstreamProxyConfig,
6363
};
64-
use openshell_isolation_interface::contract::ResolvedWorkloadIdentity;
64+
use openshell_isolation_interface::contract::{
65+
IdentityComponentOrigin, ResolvedWorkloadIdentity, root_identity_rejection_message,
66+
};
6567
use openshell_sandbox_backend::boundary_protocol::{
6668
BoundaryConfig, GatewayVerificationKey, SandboxRuntimeDescriptor, SandboxTlsClientConfig,
6769
SandboxTlsServerConfig, generate_sandbox_tls_material,
@@ -750,6 +752,39 @@ fn resolve_docker_identity_from_accounts(
750752
} else {
751753
"image"
752754
};
755+
// Where each numeric component came from, for an actionable rejection
756+
// message. This does not change which identity is resolved or enforced.
757+
let uid_origin = if requested_user.is_empty() {
758+
IdentityComponentOrigin::ImageUser
759+
} else {
760+
IdentityComponentOrigin::Policy
761+
};
762+
let gid_origin = if !requested_group.is_empty() {
763+
IdentityComponentOrigin::Policy
764+
} else if !group_selector.is_empty() {
765+
// The group came from the image's `USER` in its `user:group` form.
766+
IdentityComponentOrigin::ImageUser
767+
} else {
768+
// The group was inherited from the user's `/etc/passwd` entry.
769+
IdentityComponentOrigin::ImagePasswd
770+
};
771+
let image_reference = sandbox
772+
.spec
773+
.as_ref()
774+
.and_then(|spec| spec.template.as_ref())
775+
.map(|template| template.image.trim())
776+
.filter(|reference| !reference.is_empty())
777+
.unwrap_or(image.id.as_str());
778+
if let Some(message) = root_identity_rejection_message(
779+
image_reference,
780+
uid,
781+
uid_origin,
782+
gid,
783+
gid_origin,
784+
&supplementary_gids,
785+
) {
786+
return Err(Status::failed_precondition(message));
787+
}
753788
ResolvedWorkloadIdentity::new(
754789
uid,
755790
gid,

‎crates/openshell-driver-docker/src/tests.rs‎

Lines changed: 57 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1870,7 +1870,63 @@ fn docker_identity_resolution_honors_policy_selectors_and_rejects_root() {
18701870
b"root:x:0:\n",
18711871
)
18721872
.unwrap_err();
1873-
assert!(error.message().contains("UID or GID zero"));
1873+
let message = error.message();
1874+
assert!(!message.contains("descriptor error"));
1875+
assert!(message.contains("resolves to a root workload"));
1876+
assert!(message.contains("the policy's `process.run_as_user`"));
1877+
assert!(message.contains("nvcr.io/nvidia/base/ubuntu:24.04"));
1878+
}
1879+
1880+
#[test]
1881+
fn docker_identity_resolution_rejects_image_user_root_with_actionable_error() {
1882+
// An off-the-shelf image that declares `USER root` and no policy identity.
1883+
let sandbox = test_sandbox();
1884+
let image = DockerImageMetadata {
1885+
id: "sha256:image".to_string(),
1886+
user: "root".to_string(),
1887+
working_dir: "/root".to_string(),
1888+
volumes: Vec::new(),
1889+
};
1890+
let error = resolve_docker_identity_from_accounts(
1891+
&sandbox,
1892+
&image,
1893+
b"root:x:0:0:root:/root:/bin/sh\n",
1894+
b"root:x:0:\n",
1895+
)
1896+
.unwrap_err();
1897+
let message = error.message();
1898+
// Names the image, blames the image USER, and gives a remediation path.
1899+
assert!(message.contains("nvcr.io/nvidia/base/ubuntu:24.04"));
1900+
assert!(message.contains("the image's `USER`"));
1901+
assert!(message.contains("UID 0"));
1902+
assert!(message.contains("non-root"));
1903+
assert!(message.contains("process.run_as_user"));
1904+
// The internal `descriptor error:` prefix must not leak to users.
1905+
assert!(!message.contains("descriptor error"));
1906+
}
1907+
1908+
#[test]
1909+
fn docker_identity_resolution_rejects_supplementary_group_zero_from_etc_group() {
1910+
// A non-root user whose /etc/group membership puts it in group 0.
1911+
let sandbox = test_sandbox();
1912+
let image = DockerImageMetadata {
1913+
id: "sha256:image".to_string(),
1914+
user: "agent".to_string(),
1915+
working_dir: "/sandbox".to_string(),
1916+
volumes: Vec::new(),
1917+
};
1918+
let error = resolve_docker_identity_from_accounts(
1919+
&sandbox,
1920+
&image,
1921+
b"root:x:0:0:root:/root:/bin/sh\nagent:x:10001:10002::/sandbox:/bin/sh\n",
1922+
b"root:x:0:agent\nagent:x:10002:\n",
1923+
)
1924+
.unwrap_err();
1925+
let message = error.message();
1926+
assert!(message.contains("group 0 (root)"));
1927+
assert!(message.contains("/etc/group"));
1928+
assert!(message.contains("run_as_group"));
1929+
assert!(!message.contains("descriptor error"));
18741930
}
18751931

18761932
#[test]

‎crates/openshell-driver-podman/src/isolation.rs‎

Lines changed: 45 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -10,7 +10,10 @@ use std::path::PathBuf;
1010

1111
use openshell_core::ComputeDriverError;
1212
use openshell_core::proto::compute::v1::DriverSandbox;
13-
use openshell_isolation_interface::contract::{ProvisioningEvidence, ResolvedWorkloadIdentity};
13+
use openshell_isolation_interface::contract::{
14+
IdentityComponentOrigin, ProvisioningEvidence, ResolvedWorkloadIdentity,
15+
root_identity_rejection_message,
16+
};
1417
use openshell_sandbox_backend::ALLOW_EXTRA_SUPPLEMENTARY_GROUPS_RESOURCE_CLAIM;
1518
use openshell_sandbox_backend::boundary_protocol::{
1619
BoundaryConfig, BoundaryListener, GatewayVerificationKey, SandboxRuntimeDescriptor,
@@ -170,6 +173,39 @@ pub fn resolve_identity(
170173
} else {
171174
"policy"
172175
};
176+
// Where each numeric component came from, for an actionable rejection
177+
// message. This does not change which identity is resolved or enforced.
178+
let uid_origin = if requested_user.is_empty() {
179+
IdentityComponentOrigin::ImageUser
180+
} else {
181+
IdentityComponentOrigin::Policy
182+
};
183+
let gid_origin = if !requested_group.is_empty() {
184+
IdentityComponentOrigin::Policy
185+
} else if !group.is_empty() {
186+
// The group came from the image's `USER` in its `user:group` form.
187+
IdentityComponentOrigin::ImageUser
188+
} else {
189+
// The group was inherited from the user's `/etc/passwd` entry.
190+
IdentityComponentOrigin::ImagePasswd
191+
};
192+
let image_reference = sandbox
193+
.spec
194+
.as_ref()
195+
.and_then(|spec| spec.template.as_ref())
196+
.map(|template| template.image.trim())
197+
.filter(|reference| !reference.is_empty())
198+
.unwrap_or(image_id);
199+
if let Some(message) = root_identity_rejection_message(
200+
image_reference,
201+
uid,
202+
uid_origin,
203+
gid,
204+
gid_origin,
205+
&supplemental,
206+
) {
207+
return Err(invalid(message));
208+
}
173209
ResolvedWorkloadIdentity::new(uid, gid, supplemental, source.into(), image_id.into())
174210
.map_err(invalid)
175211
}
@@ -491,7 +527,14 @@ mod tests {
491527
assert_eq!((identity.uid, identity.gid), (1000, 1001));
492528
assert_eq!(identity.supplementary_gids, vec![2000]);
493529
assert_eq!(identity.resource_digest, "sha256:pinned");
494-
assert!(resolve_identity(&sandbox, "sha256:pinned", "root", passwd, groups).is_err());
530+
let error = resolve_identity(&sandbox, "sha256:pinned", "root", passwd, groups)
531+
.expect_err("a root image USER is rejected");
532+
let message = error.to_string();
533+
assert!(message.contains("sha256:pinned"));
534+
assert!(message.contains("the image's `USER`"));
535+
assert!(message.contains("UID 0"));
536+
assert!(message.contains("process.run_as_user"));
537+
assert!(!message.contains("descriptor error"));
495538
assert!(resolve_identity(&sandbox, "sha256:pinned", "2000", passwd, groups).is_err());
496539
}
497540

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

Lines changed: 155 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -187,6 +187,77 @@ impl ResolvedWorkloadIdentity {
187187
}
188188
}
189189

190+
/// Where a rejected workload-identity component's numeric value came from.
191+
///
192+
/// Used only to build an actionable diagnostic when a resolved identity
193+
/// contains UID or GID 0. It describes provenance for the error message and
194+
/// does not influence how identities are resolved or enforced.
195+
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
196+
pub enum IdentityComponentOrigin {
197+
/// Selected from the image's OCI `USER` directive.
198+
ImageUser,
199+
/// Resolved through the image's `/etc/passwd`.
200+
ImagePasswd,
201+
/// Resolved through the image's `/etc/group`.
202+
ImageGroup,
203+
/// Selected by the sandbox policy (`process.run_as_user` / `run_as_group`).
204+
Policy,
205+
}
206+
207+
/// Build an actionable error message when a resolved workload identity contains
208+
/// UID or GID 0.
209+
///
210+
/// The Docker and Podman drivers never run a workload as root, so they
211+
/// reject any resolved identity with a zero user, primary group, or
212+
/// supplementary group. That numeric rejection is the invariant enforced by
213+
/// [`ResolvedWorkloadIdentity::new`]; this helper changes nothing about it. It
214+
/// only explains an already-rejected identity in terms a user can act on,
215+
/// naming the image, which component is zero, and where its value came from.
216+
///
217+
/// Returns `None` when no component is zero.
218+
#[must_use]
219+
pub fn root_identity_rejection_message(
220+
image_reference: &str,
221+
uid: u32,
222+
uid_origin: IdentityComponentOrigin,
223+
gid: u32,
224+
gid_origin: IdentityComponentOrigin,
225+
supplementary_gids: &[u32],
226+
) -> Option<String> {
227+
use IdentityComponentOrigin::{ImageGroup, ImagePasswd, ImageUser, Policy};
228+
229+
let remediation = "OpenShell never runs a workload as root. Use an image with a non-root `USER`, \
230+
or set `process.run_as_user` and `process.run_as_group` to a non-root identity in the creation policy.";
231+
232+
if uid == 0 {
233+
let origin = match uid_origin {
234+
Policy => "the policy's `process.run_as_user`",
235+
_ => "the image's `USER`",
236+
};
237+
return Some(format!(
238+
"image '{image_reference}' resolves to a root workload: {origin} selects UID 0. {remediation}"
239+
));
240+
}
241+
if gid == 0 {
242+
let origin = match gid_origin {
243+
Policy => "the policy's `process.run_as_group`",
244+
ImageUser => "the image's `USER`",
245+
ImagePasswd => "the image's `/etc/passwd`",
246+
ImageGroup => "the image's `/etc/group`",
247+
};
248+
return Some(format!(
249+
"image '{image_reference}' resolves to a root primary group: {origin} selects GID 0. {remediation}"
250+
));
251+
}
252+
if supplementary_gids.contains(&0) {
253+
return Some(format!(
254+
"image '{image_reference}' lists the workload user in group 0 (root) through its `/etc/group`. \
255+
Overriding `process.run_as_group` alone does not remove this supplementary membership. {remediation}"
256+
));
257+
}
258+
None
259+
}
260+
190261
/// The trusted sandbox context, constructed by trusted common code after the
191262
/// control plane assigns the resource to the admitted sandbox.
192263
///
@@ -623,3 +694,87 @@ pub struct PendingDnsQuery {
623694
/// Single-use response channel owned by the backend adapter.
624695
pub response: oneshot::Sender<Result<Vec<u8>, BackendError>>,
625696
}
697+
698+
#[cfg(test)]
699+
mod root_identity_rejection_tests {
700+
use super::{IdentityComponentOrigin, root_identity_rejection_message};
701+
702+
#[test]
703+
fn image_user_root_names_image_and_remediation() {
704+
let message = root_identity_rejection_message(
705+
"nicolaka/netshoot:latest",
706+
0,
707+
IdentityComponentOrigin::ImageUser,
708+
0,
709+
IdentityComponentOrigin::ImageUser,
710+
&[],
711+
)
712+
.expect("root UID is rejected");
713+
assert!(message.contains("nicolaka/netshoot:latest"));
714+
assert!(message.contains("the image's `USER`"));
715+
assert!(message.contains("UID 0"));
716+
assert!(message.contains("process.run_as_user"));
717+
assert!(message.contains("process.run_as_group"));
718+
}
719+
720+
#[test]
721+
fn policy_user_zero_blames_policy() {
722+
let message = root_identity_rejection_message(
723+
"example:1.0",
724+
0,
725+
IdentityComponentOrigin::Policy,
726+
1000,
727+
IdentityComponentOrigin::Policy,
728+
&[],
729+
)
730+
.expect("root UID is rejected");
731+
assert!(message.contains("the policy's `process.run_as_user`"));
732+
}
733+
734+
#[test]
735+
fn primary_group_zero_reports_passwd_origin() {
736+
let message = root_identity_rejection_message(
737+
"example:1.0",
738+
1000,
739+
IdentityComponentOrigin::ImageUser,
740+
0,
741+
IdentityComponentOrigin::ImagePasswd,
742+
&[],
743+
)
744+
.expect("root primary GID is rejected");
745+
assert!(message.contains("root primary group"));
746+
assert!(message.contains("the image's `/etc/passwd`"));
747+
assert!(message.contains("GID 0"));
748+
}
749+
750+
#[test]
751+
fn supplementary_group_zero_mentions_etc_group_and_override_limit() {
752+
let message = root_identity_rejection_message(
753+
"example:1.0",
754+
1000,
755+
IdentityComponentOrigin::ImageUser,
756+
1000,
757+
IdentityComponentOrigin::ImagePasswd,
758+
&[0],
759+
)
760+
.expect("supplementary group 0 is rejected");
761+
assert!(message.contains("group 0 (root)"));
762+
assert!(message.contains("/etc/group"));
763+
assert!(message.contains("does not remove this supplementary membership"));
764+
}
765+
766+
#[test]
767+
fn non_root_identity_is_accepted() {
768+
assert!(
769+
root_identity_rejection_message(
770+
"example:1.0",
771+
1000,
772+
IdentityComponentOrigin::ImageUser,
773+
1000,
774+
IdentityComponentOrigin::ImagePasswd,
775+
&[10, 20],
776+
)
777+
.is_none()
778+
);
779+
}
780+
}

‎docs/how-it-works/sandboxes/runtimes.mdx‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -362,7 +362,7 @@ On Docker and Podman, set `process.run_as_user` and `process.run_as_group` in th
362362

363363
| Driver | Default identity |
364364
|---|---|
365-
| Docker, Podman | The image's `USER`, otherwise `1000`. |
365+
| Docker, Podman | The image's `USER`, otherwise `1000`. A root `USER` is rejected unless the policy sets a non-root `run_as_user` and `run_as_group`. |
366366
| Kubernetes | OpenShift SCC namespace annotations, otherwise `1000`. Override with `sandbox_uid` and `sandbox_gid`. |
367367
| MicroVM | The image's `sandbox` account, otherwise `1000`. Override with `sandbox_uid` and `sandbox_gid`. |
368368

0 commit comments

Comments
 (0)