zebra/docs/decisions/devops/0001-docker-high-uid.md

status	date	story
accepted	2025-02-28	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 - Demonstrates the risks of using UID 101 which overlaps with systemd-network user on Debian systems
• .NET Docker Issue on System Users - Details the problems with using --system flag and the SYS_UID_MAX warnings
• Docker Security Best Practices - General security recommendations for Docker containers