Docker Capabilities and Read Only

A secure container receives only the permissions it needs. Linux splits the power of the root account into small pieces called capabilities, and Docker lets you remove pieces that your application never uses. A read-only file system adds a second layer by blocking changes to the container itself.

What Are Linux Capabilities

Root power is not a single switch. Linux divides it into dozens of separate abilities, such as binding to low ports, changing file ownership, or loading kernel modules.

Capability          What it allows
------------------  ----------------------------------------
NET_BIND_SERVICE    open ports below 1024
CHOWN               change file owners
SETUID / SETGID     switch to another user
NET_RAW             craft raw network packets
SYS_ADMIN           broad system administration (very powerful)
SYS_MODULE          load kernel modules

Imagine a building manager with a ring of keys. A cleaner gets the key to the cleaning closet and not the master key. Capabilities let you hand out keys one at a time.

Docker's Default Set

Docker already removes many dangerous capabilities and grants a modest default set. Most applications need even fewer than the default.

Dropping Capabilities

The safest pattern drops every capability and adds back only the required ones.

docker run -d \
  --cap-drop ALL \
  --cap-add NET_BIND_SERVICE \
  nginx:alpine

This web server may bind to port 80 and holds no other special power. An attacker who breaks into this container finds very few tools to work with.

Compose Syntax

services:
  web:
    image: nginx:alpine
    cap_drop:
      - ALL
    cap_add:
      - NET_BIND_SERVICE

Finding the Needed Capabilities

  1. Start with --cap-drop ALL.
  2. Run the application and read the error messages.
  3. Add back one capability at a time until the application works.
  4. Record the final list in your Compose file.

Read-Only File System

A running container normally writes to a thin layer on top of the image. Malicious code uses that layer to drop new files. The --read-only flag locks the entire container file system.

docker run -d --read-only my-app

Any attempt to create or change a file inside the container now fails.

Allowing Specific Writable Folders

Applications still need places for temporary files. A tmpfs mount gives a small writable area in memory.

docker run -d \
  --read-only \
  --tmpfs /tmp:rw,size=64m \
  -v app-data:/var/lib/app \
  my-app
Container file system   read-only
/tmp                    writable, in memory, erased on stop
/var/lib/app            writable, stored in a named volume

Blocking Privilege Escalation

The flag --security-opt no-new-privileges stops a process from gaining more rights than it started with, even through special files that normally grant extra power.

docker run -d --security-opt no-new-privileges my-app

A Hardened Example

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

This one definition combines a non-root user, a locked file system, no extra capabilities, and no privilege escalation. Each setting covers a weakness the others miss.

Common Mistakes

  • Using --privileged to fix a permission problem instead of finding the one capability needed.
  • Enabling read-only mode without a tmpfs mount, which crashes programs that write temporary files.
  • Testing hardening only on a laptop. Run the same settings in a staging environment before production.

Real-World Scenario

A company runs a public API in a container with default settings. An attacker finds a flaw in a library and runs a command inside the container. The attacker tries to download a tool, write it to disk, and run it. A read-only file system blocks the write. The attacker tries to change network settings, and the missing capability blocks that step as well. The break-in leads nowhere, and the logs show the failed attempts for the security team to review.

Testing Your Restrictions

docker exec api touch /test.txt
touch: /test.txt: Read-only file system

docker exec api ping -c 1 8.8.8.8
ping: Operation not permitted

Failed commands like these prove that the restrictions work. Run a short test list after every change to the container definition so new settings do not weaken the defense by accident.