Description
Docker’sUSER reference
is explicit about an easy-to-miss behavior:
Note that when specifying a group for the user, the user will have only the specified group membership. Any other configured group memberships will be ignored.This applies to both Linux and Windows containers. Any supplementary group the Dockerfile adds the user to via one of these commands is silently dropped the moment
USER name:group takes effect:
The most common real-world symptom on Linux is a user added to the
docker
group then locked out of /var/run/docker.sock at runtime. On Windows, the
corresponding symptom is a user added to a local group (for example a
custom app-writers group) then unable to access files whose ACL only grants
that group.
Examples
Bad — Linux
docker and wheel supplementary groups are dropped at runtime.
Bad — Windows cmd
app is added to docker via net localgroup /add, but USER app:docker
restricts the process to only the docker token — any other local-group
membership is dropped.
Bad — Windows PowerShell
Good — drop the explicit group
/etc/passwd (or the Windows
token) plus every supplementary group that was added.
Suppression
The rule does not fire when:- The
USERinstruction uses no explicit group (USER apprather thanUSER app:group). - The user is root or UID 0.
- The user specifier is numeric (
USER 1000:1000). We do not correlate UIDs touseradd-created accounts; the rule targets named identities. - The stage is passwd-less (scratch-rooted without a copied
/etc/passwd). That case belongs totally/named-identity-in-passwdless-stage.
Suggested fix
The rule proposes aFixSuggestion that removes the :group portion so
the user’s supplementary groups survive. Run with --fix --fix-unsafe to
apply it.
Related rules
tally/named-identity-in-passwdless-stage— fires in scratch-rooted stages where/etc/passwdis missing. Passwd-less stages are explicitly skipped by this rule to avoid overlapping edits on the same operand.tally/user-created-but-never-used— fires when the final stage never switches to a non-root user. Complementary; our rule requires an explicit non-root USER.tally/copy-after-user-without-chown— targets COPY/ADD ownership, not USER. Complementary.
Configuration
References
- Docker Dockerfile reference: USER
setgroups(2)(Linux) — the syscall whose effects are described above- Microsoft Add-LocalGroupMember cmdlet
- Microsoft
net localgroupreference