Support low numeric UID and GID values.

[ebusto]

Problem Statement

Unfortunately many environments have Unix UID and GID values that are low numbers, well below 1000. For example, my primary group ID is 30.

Proposed Design

There are two obvious approaches. One is to simply relax the minimum values, perhaps to something 1 or greater. The other is to make it configurable, which is likely more sensible.

Alternatives Considered

There is no chance of renumbering IDs in enterprises that are decades old.

Agent Investigation

No response

Checklist

• I've reviewed existing issues and the architecture docs
• This is a design proposal, not a "please build this" request

[krishicks]

I did some analysis of this with my agent, captured below. This would be enhancing a recently-introduced ability to define some other UID/GID. As long as the operator has to opt in to allowing lower values, I think it's fine from a security perspective. cc @sjenning as the author of the configurable-UID feature.

Agent analysis:

---

Why the minimum is 1000

The limit was introduced in commit 6461677 (feat(policy): accept numeric UIDs for sandbox process identity (#1973)) on July 2, 2026, as part of issue #1959.

Before that change, OpenShell accepted only the literal sandbox identity. Numeric identities were added with this range:

  pub const MIN_SANDBOX_UID: u32 = 1000;
  pub const MAX_SANDBOX_UID: u32 = 2_000_000_000;

The associated comments and issue describe 1000 as a security boundary intended to reject “system users.” The implementation plan explicitly called the range a platform safety constant rather than a configurable value.

I did not find evidence of a specific vulnerability, platform requirement, or empirical analysis that selected exactly 1000. It appears to follow the common Linux convention that IDs below 1000 are reserved for system accounts, while regular login users begin at 1000. That convention is not universal and does not account for established enterprise identity ranges.

What the limit currently protects

Linux does not inherently grant capabilities or root privileges to UIDs between 1 and 999. UID 0 remains the special privileged identity. However, low IDs commonly correspond to privileged system accounts and groups inside images, including groups associated with logs, terminals, disks, serial devices, or other resources.

Rejecting IDs below 1000 reduces the chance that a configured sandbox identity will accidentally:

• Match ownership of sensitive files included in a container or VM image.
• Match a privileged group defined in the image’s /etc/group.
• Gain access to mounted volumes or devices based on existing numeric ownership.
• Collide with an OpenShell infrastructure identity, particularly the network proxy identity.
• Create duplicate or ambiguous /etc/passwd and /etc/group entries.

The limit therefore provides collision avoidance and defense in depth, rather than enforcing a kernel-level privilege boundary.

Impact of lowering it

Lowering the minimum while continuing to reject UID and GID 0 would not directly make a sandbox process root. The privilege-dropping code verifies that UID 0 and GID 0 are not
selected.

It would nevertheless expand the authority an operator can assign to a sandbox:

1. Image file access
   A low UID or GID could match existing ownership in the image. For example, selecting GID 30 gives the process every permission granted numerically to group 30, regardless of
   what that group is named.

2. Mounted storage and devices
   Kubernetes fsGroup, host mounts, shared PVCs, and device nodes use numeric ownership. A low ID could grant access to resources already owned by a system account or group.

3. Host identity collisions
   Rootful container deployments generally preserve numeric IDs unless user namespaces are enabled. A low container identity could therefore match a host system identity on
   host-mounted paths. Rootless Podman usually mitigates this through user-namespace mapping; VM identities generally remain guest-local.

4. Account database ambiguity
   OpenShell can create or rewrite a sandbox account using the injected IDs. The current code checks for an account named sandbox, but does not reject another account already using the requested UID or GID. Selecting a low ID could create duplicate entries such as both sandbox and an image system account mapping to the same numeric identity.

5. Kubernetes admission compatibility
   Cluster security policies or OpenShift SCCs may require IDs from an allocated range. Configuring a low ID could cause admission failures even if OpenShell accepts it.

6. Network proxy bypass risk if the constant is changed globally
   MIN_SANDBOX_UID is also used to validate the Kubernetes sidecar proxy UID and network-init IDs. That proxy UID is exempted from network interception rules. Simply changing the shared constant could allow the exempt identity to collide with a system account or sandbox workload identity.

Existing inconsistency

Docker and Podman OCI-image identity resolution already accept any nonzero UID or GID when it comes from the image’s USER declaration. The [1000, 2_000_000_000] restriction still applies to explicit process policy and driver-injected identities used by Kubernetes and VM paths.

The requested behavior is therefore partially supported today, but not consistently across identity sources and drivers.

Recommended design constraint

The implementation should not simply lower the shared MIN_SANDBOX_UID constant. Sandbox workload identities and OpenShell infrastructure identities should have separate
validation rules.

A safer user-facing design would:

• Keep UID 0 and GID 0 prohibited.
• Preserve 1000 as the default minimum.
• Allow operators to opt into lower workload UID and GID minimums independently.
• Apply the lower range only to sandbox workload identities, not proxy or other OpenShell infrastructure identities.
• Continue requiring the proxy identity to be dedicated and distinct from the workload identity.
• Detect or clearly warn about collisions with existing image passwd/group entries.
• Document that selecting a low ID grants access to every image, volume, or device permission associated with that numeric identity.
• Report cluster admission-policy failures clearly rather than implying that OpenShell configuration overrides Kubernetes or OpenShift restrictions.

This preserves the current safe default while enabling environments that intentionally rely on established low-numbered identities.

[ebusto]

Hi @krishicks, thanks for looking into this! I actually have a pull request almost ready to address this issue.