--- status: accepted date: 2025-02-28 story: Appropriate UID/GID values for container users --- # Use High UID/GID Values for Container Users ## Context & Problem Statement Docker containers share the host's user namespace by default. If container UIDs/GIDs overlap with privileged host accounts, this could lead to privilege escalation if a container escape vulnerability is exploited. Low UIDs (especially in the system user range of 100-999) are particularly risky as they often map to privileged system users on the host. Our previous approach used UID/GID 101 with the `--system` flag for user creation, which falls within the system user range and could potentially overlap with critical system users on the host. ## Priorities & Constraints * Enhance security by reducing the risk of container user namespace overlaps * Avoid warnings during container build related to system user ranges * Maintain compatibility with common Docker practices * Prevent potential privilege escalation in case of container escape ## Considered Options * Option 1: Keep using low UID/GID (101) with `--system` flag * Option 2: Use UID/GID (1000+) without `--system` flag * Option 3: Use high UID/GID (10000+) without `--system` flag ## Decision Outcome Chosen option: [Option 3: Use high UID/GID (10000+) without `--system` flag] We decided to: 1. Change the default UID/GID from 101 to 10001 2. Remove the `--system` flag from user/group creation commands 3. Document the security rationale for these changes This approach significantly reduces the risk of UID/GID collision with host system users while avoiding build-time warnings related to system user ranges. Using a very high UID/GID (10001) provides an additional security boundary in containers where user namespaces are shared with the host. ### Expected Consequences * Improved security posture by reducing the risk of container escapes leading to privilege escalation * Elimination of build-time warnings related to system user UID/GID ranges * Consistency with industry best practices for container security * No functional impact on container operation, as the internal user permissions remain the same ## More Information * [NGINX Docker User ID Issue](https://github.com/nginxinc/docker-nginx/issues/490) - Demonstrates the risks of using UID 101 which overlaps with `systemd-network` user on Debian systems * [.NET Docker Issue on System Users](https://github.com/dotnet/dotnet-docker/issues/4624) - Details the problems with using `--system` flag and the SYS_UID_MAX warnings * [Docker Security Best Practices](https://docs.docker.com/develop/security-best-practices/) - General security recommendations for Docker containers