fix(compute): explain the root-identity rejection instead of an opaque UID/GID error

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

@@ -58,7 +58,9 @@ use openshell_core::proto_struct::{
 use openshell_core::{
     AppArmorProfile, Error, ImagePullPolicy, Result as CoreResult, UpstreamProxyConfig,
 };
-use openshell_isolation_interface::contract::ResolvedWorkloadIdentity;
+use openshell_isolation_interface::contract::{
+    IdentityComponentOrigin, ResolvedWorkloadIdentity, root_identity_rejection_message,
+};
 use openshell_sandbox_backend::boundary_protocol::{
     BoundaryConfig, GatewayVerificationKey, SandboxRuntimeDescriptor, SandboxTlsClientConfig,
     SandboxTlsServerConfig, generate_sandbox_tls_material,
@@ -692,6 +694,39 @@ fn resolve_docker_identity_from_accounts(
     } else {
         "image"
     };
+    // Where each numeric component came from, for an actionable rejection
+    // message. This does not change which identity is resolved or enforced.
+    let uid_origin = if requested_user.is_empty() {
+        IdentityComponentOrigin::ImageUser
+    } else {
+        IdentityComponentOrigin::Policy
+    };
+    let gid_origin = if !requested_group.is_empty() {
+        IdentityComponentOrigin::Policy
+    } else if !group_selector.is_empty() {
+        // The group came from the image's `USER` in its `user:group` form.
+        IdentityComponentOrigin::ImageUser
+    } else {
+        // The group was inherited from the user's `/etc/passwd` entry.
+        IdentityComponentOrigin::ImagePasswd
+    };
+    let image_reference = sandbox
+        .spec
+        .as_ref()
+        .and_then(|spec| spec.template.as_ref())
+        .map(|template| template.image.trim())
+        .filter(|reference| !reference.is_empty())
+        .unwrap_or(image.id.as_str());
+    if let Some(message) = root_identity_rejection_message(
+        image_reference,
+        uid,
+        uid_origin,
+        gid,
+        gid_origin,
+        &supplementary_gids,
+    ) {
+        return Err(Status::failed_precondition(message));
+    }
     ResolvedWorkloadIdentity::new(
         uid,
         gid,

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

@@ -1711,7 +1711,95 @@ fn docker_identity_resolution_honors_policy_selectors_and_rejects_root() {
         b"root:x:0:\n",
     )
     .unwrap_err();
-    assert!(error.message().contains("UID or GID zero"));
+    let message = error.message();
+    assert!(!message.contains("descriptor error"));
+    assert!(message.contains("resolves to a root workload"));
+    assert!(message.contains("the policy's `process.run_as_user`"));
+    assert!(message.contains("nvcr.io/nvidia/base/ubuntu:24.04"));
+}
+
+#[test]
+fn docker_identity_resolution_rejects_image_user_root_with_actionable_error() {
+    // An off-the-shelf image that declares `USER root` and no policy identity.
+    let sandbox = test_sandbox();
+    let image = DockerImageMetadata {
+        id: "sha256:image".to_string(),
+        user: "root".to_string(),
+        working_dir: "/root".to_string(),
+        volumes: Vec::new(),
+    };
+    let error = resolve_docker_identity_from_accounts(
+        &sandbox,
+        &image,
+        b"root:x:0:0:root:/root:/bin/sh\n",
+        b"root:x:0:\n",
+    )
+    .unwrap_err();
+    let message = error.message();
+    // Names the image, blames the image USER, and gives a remediation path.
+    assert!(message.contains("nvcr.io/nvidia/base/ubuntu:24.04"));
+    assert!(message.contains("the image's `USER`"));
+    assert!(message.contains("UID 0"));
+    assert!(message.contains("non-root"));
+    assert!(message.contains("process.run_as_user"));
+    // The internal `descriptor error:` prefix must not leak to users.
+    assert!(!message.contains("descriptor error"));
+}
+
+#[test]
+fn docker_identity_resolution_rejects_supplementary_group_zero_from_etc_group() {
+    // A non-root user whose /etc/group membership puts it in group 0.
+    let sandbox = test_sandbox();
+    let image = DockerImageMetadata {
+        id: "sha256:image".to_string(),
+        user: "agent".to_string(),
+        working_dir: "/sandbox".to_string(),
+        volumes: Vec::new(),
+    };
+    let error = resolve_docker_identity_from_accounts(
+        &sandbox,
+        &image,
+        b"root:x:0:0:root:/root:/bin/sh\nagent:x:10001:10002::/sandbox:/bin/sh\n",
+        b"root:x:0:agent\nagent:x:10002:\n",
+    )
+    .unwrap_err();
+    let message = error.message();
+    assert!(message.contains("group 0 (root)"));
+    assert!(message.contains("/etc/group"));
+    // The user here has already set non-root `run_as_user`/`run_as_group`, yet
+    // the supplementary membership still grants GID 0. The advice must not tell
+    // them to set those fields again (doing so reproduces the error); it must
+    // explain the fields cannot drop a supplementary membership and point at a
+    // different user or image.
+    assert!(message.contains("do not drop supplementary group memberships"));
+    assert!(message.contains("user is not a member of the root group"));
+    assert!(!message.contains("descriptor error"));
+}
+
+#[test]
+fn docker_identity_resolution_rejects_primary_group_zero_with_group_scoped_advice() {
+    // A non-root user whose `/etc/passwd` primary group is 0.
+    let sandbox = test_sandbox();
+    let image = DockerImageMetadata {
+        id: "sha256:image".to_string(),
+        user: "app".to_string(),
+        working_dir: "/sandbox".to_string(),
+        volumes: Vec::new(),
+    };
+    let error = resolve_docker_identity_from_accounts(
+        &sandbox,
+        &image,
+        b"app:x:1001:0::/sandbox:/bin/sh\n",
+        b"root:x:0:\n",
+    )
+    .unwrap_err();
+    let message = error.message();
+    assert!(message.contains("root primary group"));
+    assert!(message.contains("GID 0"));
+    // A root primary group is remedied by `run_as_group`, not `run_as_user`.
+    assert!(message.contains("`process.run_as_group`"));
+    assert!(!message.contains("`process.run_as_user`"));
+    assert!(!message.contains("descriptor error"));
 }
 
 #[test]

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

@@ -11,7 +11,8 @@ use std::path::PathBuf;
 use openshell_core::ComputeDriverError;
 use openshell_core::proto::compute::v1::DriverSandbox;
 use openshell_isolation_interface::contract::{
-    OuterFenceGuarantee, OuterFenceGuarantees, ResolvedWorkloadIdentity,
+    IdentityComponentOrigin, OuterFenceGuarantee, OuterFenceGuarantees, ResolvedWorkloadIdentity,
+    root_identity_rejection_message,
 };
 use openshell_sandbox_backend::ALLOW_EXTRA_SUPPLEMENTARY_GROUPS_RESOURCE_CLAIM;
 use openshell_sandbox_backend::boundary_protocol::{
@@ -178,6 +179,39 @@ pub fn resolve_identity(
     } else {
         "policy"
     };
+    // Where each numeric component came from, for an actionable rejection
+    // message. This does not change which identity is resolved or enforced.
+    let uid_origin = if requested_user.is_empty() {
+        IdentityComponentOrigin::ImageUser
+    } else {
+        IdentityComponentOrigin::Policy
+    };
+    let gid_origin = if !requested_group.is_empty() {
+        IdentityComponentOrigin::Policy
+    } else if !group.is_empty() {
+        // The group came from the image's `USER` in its `user:group` form.
+        IdentityComponentOrigin::ImageUser
+    } else {
+        // The group was inherited from the user's `/etc/passwd` entry.
+        IdentityComponentOrigin::ImagePasswd
+    };
+    let image_reference = sandbox
+        .spec
+        .as_ref()
+        .and_then(|spec| spec.template.as_ref())
+        .map(|template| template.image.trim())
+        .filter(|reference| !reference.is_empty())
+        .unwrap_or(image_id);
+    if let Some(message) = root_identity_rejection_message(
+        image_reference,
+        uid,
+        uid_origin,
+        gid,
+        gid_origin,
+        &supplemental,
+    ) {
+        return Err(invalid(message));
+    }
     ResolvedWorkloadIdentity::new(uid, gid, supplemental, source.into(), image_id.into())
         .map_err(invalid)
 }
@@ -464,7 +498,14 @@ mod tests {
         assert_eq!((identity.uid, identity.gid), (1000, 1001));
         assert_eq!(identity.supplementary_gids, vec![2000]);
         assert_eq!(identity.resource_digest, "sha256:pinned");
-        assert!(resolve_identity(&sandbox, "sha256:pinned", "root", passwd, groups).is_err());
+        let error = resolve_identity(&sandbox, "sha256:pinned", "root", passwd, groups)
+            .expect_err("a root image USER is rejected");
+        let message = error.to_string();
+        assert!(message.contains("sha256:pinned"));
+        assert!(message.contains("the image's `USER`"));
+        assert!(message.contains("UID 0"));
+        assert!(message.contains("process.run_as_user"));
+        assert!(!message.contains("descriptor error"));
         assert!(resolve_identity(&sandbox, "sha256:pinned", "2000", passwd, groups).is_err());
     }