> ## Documentation Index
> Fetch the complete documentation index at: https://tally.wharflab.com/llms.txt
> Use this file to discover all available pages before exploring further.

# tally/named-identity-in-passwdless-stage

> Named user/group in USER or --chown requires /etc/passwd which passwd-less stages lack.

Named user/group in USER or --chown requires /etc/passwd which passwd-less stages lack.

| Property | Value       |
| -------- | ----------- |
| Severity | Warning     |
| Category | Correctness |
| Default  | Enabled     |

## Description

Detects named (non-numeric) user or group references in `USER` instructions or `COPY`/`ADD --chown` flags
within stages that lack `/etc/passwd` or `/etc/group`. Named identity resolution requires these database
files; without them, the build will fail at `RUN` time or the runtime will reject the container.

This is a common pitfall in `scratch` and multi-stage builds that inherit from scratch without copying
the passwd/group databases from a builder stage.

Numeric UIDs/GIDs (e.g., `65532`, `1000:1000`) work without any passwd database and are the recommended
approach for minimal images.

The rule suppresses after a `SHELL` instruction, since the user may have bootstrapped tools that handle
identity resolution.

## Examples

### Bad

```dockerfile theme={null}
FROM scratch
COPY --from=builder /myapp /myapp
USER appuser
```

```dockerfile theme={null}
FROM scratch
COPY --chown=appuser:appgroup --from=builder /myapp /myapp
```

### Good (numeric IDs)

```dockerfile theme={null}
FROM scratch
COPY --from=builder /myapp /myapp
USER 65532:65532
```

```dockerfile theme={null}
FROM scratch
COPY --chown=1000:1000 --from=builder /myapp /myapp
```

### Good (passwd copied from builder)

```dockerfile theme={null}
FROM golang:1.22 AS builder
RUN useradd -r appuser

FROM scratch
COPY --from=builder /etc/passwd /etc/passwd
COPY --from=builder /etc/group /etc/group
COPY --from=builder /myapp /myapp
USER appuser
```

### Good (non-scratch base image)

```dockerfile theme={null}
FROM alpine:3.19
RUN adduser -D appuser
USER appuser
```

## Suggested fix

The rule suggests replacing named identities with the numeric UID/GID `65532` (the conventional
non-root ID used by distroless and Chainguard images). This fix uses `FixSuggestion` safety because
the numeric ID may not match the author's intended user.

Alternatively, copy `/etc/passwd` and `/etc/group` from a builder stage that has the desired user.

## Related rules

* [`tally/shell-run-in-scratch`](./shell-run-in-scratch) -- detects shell-form RUN in scratch
  stages (different concern: shell availability vs identity resolution)
* [`tally/copy-after-user-without-chown`](./copy-after-user-without-chown) -- detects missing
  `--chown` after `USER` (complementary: different condition)
* [`tally/user-created-but-never-used`](./user-created-but-never-used) -- detects created
  users that are never switched to (complementary: different condition)

## Configuration

```toml theme={null}
[rules.tally.named-identity-in-passwdless-stage]
severity = "warning"  # Options: "off", "error", "warning", "info", "style"
```