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
- Start with
--cap-drop ALL. - Run the application and read the error messages.
- Add back one capability at a time until the application works.
- 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
--privilegedto 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.
