Docker / Compose and reliable runtime contracts / Lesson 10

Runtime identity and least privilege

Reduce the authority available to a compromised process while preserving the specific access it actually needs.

About 4 min readContent reviewed 2026-10-25

On this page

Lesson goals

Review user identity, capabilities, writable paths, and daemon access.
Build a restrictive runtime model without treating one setting as a complete security proof.

Start with the authority the workload requires

The synthetic API needs a high-numbered TCP listener and readable application files. It does not need host device access, host namespaces, a Docker socket, or permission to modify system files. Describe those requirements before adding runtime flags. A smaller permission set reduces consequences of compromise, but containers still share a kernel and depend on the engine, runtime, host policy, and application security. Privilege reduction complements rather than replaces updates and threat modeling.

A non-root user still needs correct data access

The earlier image selects numeric uid and gid 10001. That is an application identity decision, distinct from whether the daemon itself runs rootless. The filesystem must permit required reads and narrowly scoped writes. Naming a non-root user does not repair an inaccessible volume, and adding root authority to hide an ownership error weakens the design. Review mapped identities, mount permissions, and platform security labels explicitly.

yaml A restrictive fixture runtime model

services:
  api:
    image: parcel-api:lab
    user: "10001:10001"
    read_only: true
    tmpfs:
      - /tmp
    cap_drop:
      - ALL
    security_opt:
      - no-new-privileges:true

The API has a read-only root filesystem and a separate temporary writable /tmp. Dropping capabilities and blocking privilege escalation fit this simple workload; another application may require a reviewed subset. This model grants no persistent writable data path and makes no claim that all kernels or platforms enforce settings identically.

Avoid broad escape hatches

Linux capabilities divide some root powers into narrower privileges, but adding a capability still expands attack surface. privileged disables many protections and is not a normal fix for permission errors. Host networking, host PID sharing, device mounts, and writable host paths each change the trust boundary. A Docker socket mount lets a process ask a powerful daemon to act; read-only mounting of the socket file does not make the API itself read-only.

Inspect effective settings, not only intent

An image USER can be overridden at container creation. Compose files, override files, and platform policy can change the effective user, mounts, and security options. Inspect a known existing container through an authorized diagnostic connection and compare it with the approved model. Do not dump environment arrays or host paths into public reports; use a minimal redacted evidence set and preserve the distinction between configured restrictions and observed application behavior.

bash Read a narrow effective security view

docker container inspect parcel-api --format '{{json .Config.User}}'
docker container inspect parcel-api --format '{{json .HostConfig.CapDrop}}'
docker container inspect parcel-api --format '{{json .HostConfig.ReadonlyRootfs}}'

These queries expose selected settings without printing all environment values. Actual output depends on the existing container and may differ from image defaults. They do not verify every kernel enforcement detail or prove that the application is invulnerable; use them as one part of a reviewed security check.

Keep security compatible with operations

Read-only roots and minimal images can remove familiar debugging tools and writable caches. Plan logs, temporary files, health probes, certificate updates, and incident evidence before restricting them. Avoid installing tools interactively into a running release as an undocumented repair. Rebuild a reviewed image or use an approved diagnostic method with limited access. Test normal requests, shutdown, and failure paths under the final restricted identity so permissions are not discovered only during an incident.

Common errors and fixes

Permission denied is fixed by privileged: true.

Why it happens: The workload received broad host-related authority instead of a targeted storage correction.
How to fix it: Identify the exact denied resource and grant only its required reviewed access.
Prevent it next time: Treat privileged mode as a separate architectural exception, not a debugging default.

Read-only file system.

Why it happens: The application writes a cache or temporary file on the protected root filesystem.
How to fix it: Provide a narrow temporary or persistent writable path matching data lifetime.
Prevent it next time: List every required write path and test the restricted runtime.

A non-root container can still control the daemon.

Why it happens: The process has access to a Docker socket or equivalent powerful API credentials.
How to fix it: Remove unnecessary daemon access through the approved deployment design.
Prevent it next time: Review external control channels as well as the in-container user.

Check your understanding

1. Why is a read-only socket mount not a read-only Docker API?

Show worked solution

Filesystem mount mode governs changes to the mounted file path, not which requests can be sent through an open socket. A reachable daemon API may still accept powerful operations. Avoid granting the socket unless the workload is explicitly trusted and the access model has been independently reviewed.

2. How should a service retain logs with a read-only root?