Docker cap-add and cap-drop: How to Add Linux Capabilities Safely

Q: When should I use --privileged?

Almost never. The --privileged flag gives the container all capabilities and disables most of the security features of the container runtime. The right answer is to use the specific capabilities the container needs.

Linux capabilities are the fine-grained permissions a container has. cap-add and cap-drop are the Docker flags that control them. The right answer is to start from the default and add only what is needed; the wrong answer is to use —privileged, which gives the container all capabilities and most of the security risks of running on the host.

What capabilities are
The default capabilities
The cap-add flag
The cap-drop flag
When to add
When to use —privileged
FAQ

What capabilities are

Linux capabilities are the fine-grained permissions that a process can have. The full set of capabilities includes things like CAP_NET_ADMIN (manage network interfaces), CAP_SYS_ADMIN (mount file systems, perform other system administration operations), and CAP_NET_BIND_SERVICE (bind to a privileged port).

The traditional Unix model had only two states: root (with all capabilities) and non-root (with no capabilities). Linux capabilities split root into a set of individual permissions, so a process can have some of root’s permissions without having all of them.

The default capabilities

The default capabilities in Docker are a curated subset of the full set. The default is:

CHOWN, DAC_OVERRIDE, FSETID, FOWNER, MKNOD, NET_RAW, SETGID, SETUID, SETFCAP, SETPCAP, NET_BIND_SERVICE, SYS_CHROOT, KILL, AUDIT_WRITE

This default is enough for most containers. The container can do basic things (bind to a privileged port, change the user, set the hostname) without having the full root permissions of the host.

The cap-add flag

The cap-add flag adds a capability to the default set. The most common capabilities to add:

NET_ADMIN. Manage network interfaces. The right answer for a container that needs to configure the network (e.g., a network plugin, a service mesh sidecar).
SYS_PTRACE. Trace other processes. The right answer for a debugging tool or a performance profiler.
SYS_ADMIN. Mount file systems, perform system administration operations. The right answer for a container that needs to mount a file system (e.g., a backup tool).
NET_BIND_SERVICE. Bind to a privileged port. Already in the default, but the team that has stripped it (e.g., for security reasons) needs to add it back for a container that binds to port 80.

The cap-drop flag

The cap-drop flag removes a capability from the default set. The most common capabilities to drop:

All. Drop all capabilities. The right answer for a container that does not need any root permissions.
NET_RAW. Use raw sockets. The right answer for a container that does not need to use raw sockets (most containers do not).
SYS_ADMIN. Mount file systems. The right answer for a container that does not need to mount file systems.
CHOWN, SETUID, SETGID. Change file ownership and process user. The right answer for a container that does not need to change the file ownership.

When to add

The team that should add capabilities:

The team that has a container that needs a specific capability (e.g., a network plugin needs NET_ADMIN).
The team that is migrating from —privileged to a more restrictive configuration.
The team that has audited the default capabilities and identified the specific capability that is needed.

When to use —privileged

The team that should use —privileged:

Almost no one. The —privileged flag gives the container all capabilities and disables most of the security features of the container runtime. The right answer is to use the specific capabilities the container needs, not all of them.

The exceptions: a Docker-in-Docker container (the team needs to run Docker inside Docker), a container that needs to access the host’s hardware (e.g., a GPU), a debugging tool that needs full system access.

FAQ

What are Linux capabilities?

The fine-grained permissions that a process can have. The full set includes things like NET_ADMIN, SYS_ADMIN, and NET_BIND_SERVICE.

What are the default Docker capabilities?

CHOWN, DAC_OVERRIDE, FSETID, FOWNER, MKNOD, NET_RAW, SETGID, SETUID, SETFCAP, SETPCAP, NET_BIND_SERVICE, SYS_CHROOT, KILL, AUDIT_WRITE.

When should I use cap-add?

When the container needs a specific capability that is not in the default. The most common: NET_ADMIN for a network plugin, SYS_PTRACE for a debugging tool, SYS_ADMIN for a backup tool.

When should I use cap-drop?

When the container does not need a specific capability that is in the default. The most common: ALL for a container that does not need any root permissions, NET_RAW for a container that does not need raw sockets.

When should I use —privileged?

Almost never. The —privileged flag gives the container all capabilities and disables most of the security features of the container runtime. The right answer is to use the specific capabilities the container needs.

If you are sizing a container tier for a new project, the RunxBuild hosting calculator is the place to model the line items. The containers, the volumes, the CPU, the memory - each one is a separate number, and the team’s mental model for the platform is the sum of those numbers. The RunxBuild dashboard is where the team sees the actual container deployment in one place.