diff --git a/docs/installation/binaries.md b/docs/installation/binaries.md index 2f1d55d29b..b5f56d0f28 100644 --- a/docs/installation/binaries.md +++ b/docs/installation/binaries.md @@ -186,7 +186,7 @@ need to add `sudo` to all the client commands. > **Warning**: > The *docker* group (or the group specified with `-G`) is root-equivalent; -> see [*Docker Daemon Attack Surface*](../articles/security.md#docker-daemon-attack-surface) details. +> see [*Docker Daemon Attack Surface*](../security/security.md#docker-daemon-attack-surface) details. ## Upgrades diff --git a/docs/installation/centos.md b/docs/installation/centos.md index e447e21452..84a9b791ab 100644 --- a/docs/installation/centos.md +++ b/docs/installation/centos.md @@ -134,7 +134,7 @@ makes the ownership of the Unix socket read/writable by the `docker` group. >**Warning**: The `docker` group is equivalent to the `root` user; For details >on how this impacts security in your system, see [*Docker Daemon Attack ->Surface*](../articles/security.md#docker-daemon-attack-surface) for details. +>Surface*](../security/security.md#docker-daemon-attack-surface) for details. To create the `docker` group and add your user: diff --git a/docs/installation/debian.md b/docs/installation/debian.md index 154650f1c5..400db59822 100644 --- a/docs/installation/debian.md +++ b/docs/installation/debian.md @@ -133,7 +133,7 @@ use the `-G` flag to specify an alternative group. > **Warning**: > The `docker` group (or the group specified with the `-G` flag) is -> `root`-equivalent; see [*Docker Daemon Attack Surface*](../articles/security.md#docker-daemon-attack-surface) details. +> `root`-equivalent; see [*Docker Daemon Attack Surface*](../security/security.md#docker-daemon-attack-surface) details. **Example:** diff --git a/docs/installation/fedora.md b/docs/installation/fedora.md index 3e9dd5ddfa..b45a5de048 100644 --- a/docs/installation/fedora.md +++ b/docs/installation/fedora.md @@ -128,7 +128,7 @@ makes the ownership of the Unix socket read/writable by the `docker` group. >**Warning**: The `docker` group is equivalent to the `root` user; For details >on how this impacts security in your system, see [*Docker Daemon Attack ->Surface*](../articles/security.md#docker-daemon-attack-surface) for details. +>Surface*](../security/security.md#docker-daemon-attack-surface) for details. To create the `docker` group and add your user: diff --git a/docs/installation/oracle.md b/docs/installation/oracle.md index e189558a91..56c96aa902 100644 --- a/docs/installation/oracle.md +++ b/docs/installation/oracle.md @@ -99,7 +99,7 @@ makes the ownership of the Unix socket read/writable by the `docker` group. >**Warning**: The `docker` group is equivalent to the `root` user; For details >on how this impacts security in your system, see [*Docker Daemon Attack ->Surface*](../articles/security.md#docker-daemon-attack-surface) for details. +>Surface*](../security/security.md#docker-daemon-attack-surface) for details. To create the `docker` group and add your user: diff --git a/docs/installation/rhel.md b/docs/installation/rhel.md index 6c20f273b3..b550a3790d 100644 --- a/docs/installation/rhel.md +++ b/docs/installation/rhel.md @@ -126,7 +126,7 @@ makes the ownership of the Unix socket read/writable by the `docker` group. >**Warning**: The `docker` group is equivalent to the `root` user; For details >on how this impacts security in your system, see [*Docker Daemon Attack ->Surface*](../articles/security.md#docker-daemon-attack-surface) for details. +>Surface*](../security/security.md#docker-daemon-attack-surface) for details. To create the `docker` group and add your user: diff --git a/docs/installation/ubuntulinux.md b/docs/installation/ubuntulinux.md index 78731da621..e2eeb85364 100644 --- a/docs/installation/ubuntulinux.md +++ b/docs/installation/ubuntulinux.md @@ -225,7 +225,7 @@ makes the ownership of the Unix socket read/writable by the `docker` group. >**Warning**: The `docker` group is equivalent to the `root` user; For details >on how this impacts security in your system, see [*Docker Daemon Attack ->Surface*](../articles/security.md#docker-daemon-attack-surface) for details. +>Surface*](../security/security.md#docker-daemon-attack-surface) for details. To create the `docker` group and add your user: diff --git a/docs/reference/commandline/login.md b/docs/reference/commandline/login.md index b79c18b2c6..faf3615a00 100644 --- a/docs/reference/commandline/login.md +++ b/docs/reference/commandline/login.md @@ -30,7 +30,7 @@ adding the server name. `docker login` requires user to use `sudo` or be `root`, except when: 1. connecting to a remote daemon, such as a `docker-machine` provisioned `docker engine`. -2. user is added to the `docker` group. This will impact the security of your system; the `docker` group is `root` equivalent. See [Docker Daemon Attack Surface](https://docs.docker.com/articles/security/#docker-daemon-attack-surface) for details. +2. user is added to the `docker` group. This will impact the security of your system; the `docker` group is `root` equivalent. See [Docker Daemon Attack Surface](https://docs.docker.com/security/security/#docker-daemon-attack-surface) for details. You can log into any public or private repository for which you have credentials. When you log in, the command stores encoded credentials in diff --git a/docs/security/apparmor.md b/docs/security/apparmor.md index 07cd62c772..c33240dbfb 100644 --- a/docs/security/apparmor.md +++ b/docs/security/apparmor.md @@ -1,47 +1,74 @@ -AppArmor security profiles for Docker --------------------------------------- +# AppArmor security profiles for Docker -AppArmor (Application Armor) is a security module that allows a system -administrator to associate a security profile with each program. Docker +AppArmor (Application Armor) is a Linux security module that protects an +operating system and its applications from security threats. To use it, a system +administrator associates an AppArmor security profile with each program. Docker expects to find an AppArmor policy loaded and enforced. -Container profiles are loaded automatically by Docker. A profile -for the Docker Engine itself also exists and is installed -with the official *.deb* packages. Advanced users and package -managers may find the profile for */usr/bin/docker* underneath -[contrib/apparmor](https://github.com/docker/docker/tree/master/contrib/apparmor) -in the Docker Engine source repository. +Docker automatically loads container profiles. A profile for the Docker Engine +itself also exists and is installed with the official *.deb* packages in +`/etc/apparmor.d/docker` file. -Understand the policies ------------------------- +## Understand the policies -The `docker-default` profile the default for running -containers. It is moderately protective while -providing wide application compatibility. - -The system's standard `unconfined` profile inherits all -system-wide policies, applying path-based policies -intended for the host system inside of containers. -This was the default for privileged containers -prior to Docker 1.8. - - -Overriding the profile for a container ---------------------------------------- - -Users may override the AppArmor profile using the -`security-opt` option (per-container). - -For example, the following explicitly specifies the default policy: +The `docker-default` profile is the default for running containers. It is +moderately protective while providing wide application compatibility. The +profile is the following: ``` +#include + + +profile docker-default flags=(attach_disconnected,mediate_deleted) { + + #include + + + network, + capability, + file, + umount, + + deny @{PROC}/{*,**^[0-9*],sys/kernel/shm*} wkx, + deny @{PROC}/sysrq-trigger rwklx, + deny @{PROC}/mem rwklx, + deny @{PROC}/kmem rwklx, + deny @{PROC}/kcore rwklx, + + deny mount, + + deny /sys/[^f]*/** wklx, + deny /sys/f[^s]*/** wklx, + deny /sys/fs/[^c]*/** wklx, + deny /sys/fs/c[^g]*/** wklx, + deny /sys/fs/cg[^r]*/** wklx, + deny /sys/firmware/efi/efivars/** rwklx, + deny /sys/kernel/security/** rwklx, +} +``` + +When you run a container, it uses the `docker-default` policy unless you +override it with the `security-opt` option. For example, the following +explicitly specifies the default policy: + +```bash $ docker run --rm -it --security-opt apparmor:docker-default hello-world ``` +## Contributing to AppArmor code in Docker + +Advanced users and package managers can find a profile for `/usr/bin/docker` +underneath +[contrib/apparmor](https://github.com/docker/docker/tree/master/contrib/apparmor) +in the Docker Engine source repository. diff --git a/docs/security/index.md b/docs/security/index.md new file mode 100644 index 0000000000..6948b097f7 --- /dev/null +++ b/docs/security/index.md @@ -0,0 +1,20 @@ + + +# Work with Docker security + +This section discusses the security features you can configure and use within your Docker Engine installation. + +* You can configure Docker's trust features so that your users can push and pull trusted images. To learn how to do this, see [Use trusted images](trust/index.md) in this section. + +* You can configure secure computing mode (Seccomp) policies to secure system calls in a container. For more information, see [Seccomp security profiles for Docker](seccomp.md). + +* An AppArmor profile for Docker is installed with the official *.deb* packages. For information about this profile and overriding it, see [AppArmor security profiles for Docker](apparmor.md). diff --git a/docs/security/seccomp.md b/docs/security/seccomp.md index c8b7bde036..b683be026b 100644 --- a/docs/security/seccomp.md +++ b/docs/security/seccomp.md @@ -3,27 +3,26 @@ title = "Seccomp security profiles for Docker" description = "Enabling seccomp in Docker" keywords = ["seccomp, security, docker, documentation"] +[menu.main] +parent= "smn_secure_docker" +++ -Seccomp security profiles for Docker ------------------------------------- +# Seccomp security profiles for Docker -The seccomp() system call operates on the Secure Computing (seccomp) -state of the calling process. +Secure computing mode (Seccomp) is a Linux kernel feature. You can use it to +restrict the actions available within the container. The `seccomp()` system +call operates on the seccomp state of the calling process. You can use this +feature to restrict your application's access. -This operation is available only if the kernel is configured -with `CONFIG_SECCOMP` enabled. +This feature is available only if the kernel is configured with `CONFIG_SECCOMP` +enabled. -This allows for allowing or denying of certain syscalls in a container. +## Passing a profile for a container -Passing a profile for a container ---------------------------------- - -Users may pass a seccomp profile using the `security-opt` option -(per-container). - -The profile has layout in the following form: +The default seccomp profile provides a sane default for running containers with +seccomp. It is moderately protective while providing wide application +compatibility. The default Docker profile has layout in the following form: ``` { @@ -57,30 +56,14 @@ The profile has layout in the following form: } ``` -Then you can run with: +When you run a container, it uses the default profile unless you override +it with the `security-opt` option. For example, the following explicitly +specifies the default policy: ``` $ docker run --rm -it --security-opt seccomp:/path/to/seccomp/profile.json hello-world ``` -Default Profile ---------------- - -The default seccomp profile provides a sane default for running -containers with seccomp. It is moderately protective while -providing wide application compatibility. - - -### Overriding the default profile for a container - -You can pass `unconfined` to run a container without the default seccomp -profile. - -``` -$ docker run --rm -it --security-opt seccomp:unconfined debian:jessie \ - unshare --map-root-user --user sh -c whoami -``` - ### Syscalls blocked by the default profile Docker's default seccomp profile is a whitelist which specifies the calls that @@ -91,55 +74,65 @@ the reason each syscall is blocked rather than white-listed. | Syscall | Description | |---------------------|---------------------------------------------------------------------------------------------------------------------------------------| | `acct` | Accounting syscall which could let containers disable their own resource limits or process accounting. Also gated by `CAP_SYS_PACCT`. | -| `add_key` | Prevent containers from using the kernel keyring, which is not namespaced. | -| `adjtimex` | Similar to `clock_settime` and `settimeofday`, time/date is not namespaced. | -| `bpf` | Deny loading potentially persistent bpf programs into kernel, already gated by `CAP_SYS_ADMIN`. | -| `clock_adjtime` | Time/date is not namespaced. | -| `clock_settime` | Time/date is not namespaced. | -| `clone` | Deny cloning new namespaces. Also gated by `CAP_SYS_ADMIN` for CLONE_* flags, except `CLONE_USERNS`. | -| `create_module` | Deny manipulation and functions on kernel modules. | -| `delete_module` | Deny manipulation and functions on kernel modules. Also gated by `CAP_SYS_MODULE`. | -| `finit_module` | Deny manipulation and functions on kernel modules. Also gated by `CAP_SYS_MODULE`. | -| `get_kernel_syms` | Deny retrieval of exported kernel and module symbols. | -| `get_mempolicy` | Syscall that modifies kernel memory and NUMA settings. Already gated by `CAP_SYS_NICE`. | -| `init_module` | Deny manipulation and functions on kernel modules. Also gated by `CAP_SYS_MODULE`. | -| `ioperm` | Prevent containers from modifying kernel I/O privilege levels. Already gated by `CAP_SYS_RAWIO`. | -| `iopl` | Prevent containers from modifying kernel I/O privilege levels. Already gated by `CAP_SYS_RAWIO`. | -| `kcmp` | Restrict process inspection capabilities, already blocked by dropping `CAP_PTRACE`. | -| `kexec_file_load` | Sister syscall of `kexec_load` that does the same thing, slightly different arguments. | -| `kexec_load` | Deny loading a new kernel for later execution. | -| `keyctl` | Prevent containers from using the kernel keyring, which is not namespaced. | -| `lookup_dcookie` | Tracing/profiling syscall, which could leak a lot of information on the host. | -| `mbind` | Syscall that modifies kernel memory and NUMA settings. Already gated by `CAP_SYS_NICE`. | -| `modify_ldt` | Old syscall only used in 16-bit code and a potential information leak. | -| `mount` | Deny mounting, already gated by `CAP_SYS_ADMIN`. | -| `move_pages` | Syscall that modifies kernel memory and NUMA settings. | -| `name_to_handle_at` | Sister syscall to `open_by_handle_at`. Already gated by `CAP_SYS_NICE`. | -| `nfsservctl` | Deny interaction with the kernel nfs daemon. | -| `open_by_handle_at` | Cause of an old container breakout. Also gated by `CAP_DAC_READ_SEARCH`. | -| `perf_event_open` | Tracing/profiling syscall, which could leak a lot of information on the host. | -| `personality` | Prevent container from enabling BSD emulation. Not inherently dangerous, but poorly tested, potential for a lot of kernel vulns. | -| `pivot_root` | Deny `pivot_root`, should be privileged operation. | -| `process_vm_readv` | Restrict process inspection capabilities, already blocked by dropping `CAP_PTRACE`. | -| `process_vm_writev` | Restrict process inspection capabilities, already blocked by dropping `CAP_PTRACE`. | -| `ptrace` | Tracing/profiling syscall, which could leak a lot of information on the host. Already blocked by dropping `CAP_PTRACE`. | -| `query_module` | Deny manipulation and functions on kernel modules. | -| `quotactl` | Quota syscall which could let containers disable their own resource limits or process accounting. Also gated by `CAP_SYS_ADMIN`. | -| `reboot` | Don't let containers reboot the host. Also gated by `CAP_SYS_BOOT`. | +| `add_key` | Prevent containers from using the kernel keyring, which is not namespaced. | +| `adjtimex` | Similar to `clock_settime` and `settimeofday`, time/date is not namespaced. | +| `bpf` | Deny loading potentially persistent bpf programs into kernel, already gated by `CAP_SYS_ADMIN`. | +| `clock_adjtime` | Time/date is not namespaced. | +| `clock_settime` | Time/date is not namespaced. | +| `clone` | Deny cloning new namespaces. Also gated by `CAP_SYS_ADMIN` for CLONE_* flags, except `CLONE_USERNS`. | +| `create_module` | Deny manipulation and functions on kernel modules. | +| `delete_module` | Deny manipulation and functions on kernel modules. Also gated by `CAP_SYS_MODULE`. | +| `finit_module` | Deny manipulation and functions on kernel modules. Also gated by `CAP_SYS_MODULE`. | +| `get_kernel_syms` | Deny retrieval of exported kernel and module symbols. | +| `get_mempolicy` | Syscall that modifies kernel memory and NUMA settings. Already gated by `CAP_SYS_NICE`. | +| `init_module` | Deny manipulation and functions on kernel modules. Also gated by `CAP_SYS_MODULE`. | +| `ioperm` | Prevent containers from modifying kernel I/O privilege levels. Already gated by `CAP_SYS_RAWIO`. | +| `iopl` | Prevent containers from modifying kernel I/O privilege levels. Already gated by `CAP_SYS_RAWIO`. | +| `kcmp` | Restrict process inspection capabilities, already blocked by dropping `CAP_PTRACE`. | +| `kexec_file_load` | Sister syscall of `kexec_load` that does the same thing, slightly different arguments. | +| `kexec_load` | Deny loading a new kernel for later execution. | +| `keyctl` | Prevent containers from using the kernel keyring, which is not namespaced. | +| `lookup_dcookie` | Tracing/profiling syscall, which could leak a lot of information on the host. | +| `mbind` | Syscall that modifies kernel memory and NUMA settings. Already gated by `CAP_SYS_NICE`. | +| `modify_ldt` | Old syscall only used in 16-bit code and a potential information leak. | +| `mount` | Deny mounting, already gated by `CAP_SYS_ADMIN`. | +| `move_pages` | Syscall that modifies kernel memory and NUMA settings. | +| `name_to_handle_at` | Sister syscall to `open_by_handle_at`. Already gated by `CAP_SYS_NICE`. | +| `nfsservctl` | Deny interaction with the kernel nfs daemon. | +| `open_by_handle_at` | Cause of an old container breakout. Also gated by `CAP_DAC_READ_SEARCH`. | +| `perf_event_open` | Tracing/profiling syscall, which could leak a lot of information on the host. | +| `personality` | Prevent container from enabling BSD emulation. Not inherently dangerous, but poorly tested, potential for a lot of kernel vulns. | +| `pivot_root` | Deny `pivot_root`, should be privileged operation. | +| `process_vm_readv` | Restrict process inspection capabilities, already blocked by dropping `CAP_PTRACE`. | +| `process_vm_writev` | Restrict process inspection capabilities, already blocked by dropping `CAP_PTRACE`. | +| `ptrace` | Tracing/profiling syscall, which could leak a lot of information on the host. Already blocked by dropping `CAP_PTRACE`. | +| `query_module` | Deny manipulation and functions on kernel modules. | +| `quotactl` | Quota syscall which could let containers disable their own resource limits or process accounting. Also gated by `CAP_SYS_ADMIN`. | +| `reboot` | Don't let containers reboot the host. Also gated by `CAP_SYS_BOOT`. | | `restart_syscall` | Don't allow containers to restart a syscall. Possible seccomp bypass see: https://code.google.com/p/chromium/issues/detail?id=408827. | -| `request_key` | Prevent containers from using the kernel keyring, which is not namespaced. | -| `set_mempolicy` | Syscall that modifies kernel memory and NUMA settings. Already gated by `CAP_SYS_NICE`. | -| `setns` | Deny associating a thread with a namespace. Also gated by `CAP_SYS_ADMIN`. | -| `settimeofday` | Time/date is not namespaced. Also gated by `CAP_SYS_TIME`. | -| `stime` | Time/date is not namespaced. Also gated by `CAP_SYS_TIME`. | -| `swapon` | Deny start/stop swapping to file/device. Also gated by `CAP_SYS_ADMIN`. | -| `swapoff` | Deny start/stop swapping to file/device. Also gated by `CAP_SYS_ADMIN`. | -| `sysfs` | Obsolete syscall. | -| `_sysctl` | Obsolete, replaced by /proc/sys. | -| `umount` | Should be a privileged operation. Also gated by `CAP_SYS_ADMIN`. | -| `umount2` | Should be a privileged operation. | -| `unshare` | Deny cloning new namespaces for processes. Also gated by `CAP_SYS_ADMIN`, with the exception of `unshare --user`. | -| `uselib` | Older syscall related to shared libraries, unused for a long time. | -| `ustat` | Obsolete syscall. | -| `vm86` | In kernel x86 real mode virtual machine. Also gated by `CAP_SYS_ADMIN`. | -| `vm86old` | In kernel x86 real mode virtual machine. Also gated by `CAP_SYS_ADMIN`. | +| `request_key` | Prevent containers from using the kernel keyring, which is not namespaced. | +| `set_mempolicy` | Syscall that modifies kernel memory and NUMA settings. Already gated by `CAP_SYS_NICE`. | +| `setns` | Deny associating a thread with a namespace. Also gated by `CAP_SYS_ADMIN`. | +| `settimeofday` | Time/date is not namespaced. Also gated by `CAP_SYS_TIME`. | +| `stime` | Time/date is not namespaced. Also gated by `CAP_SYS_TIME`. | +| `swapon` | Deny start/stop swapping to file/device. Also gated by `CAP_SYS_ADMIN`. | +| `swapoff` | Deny start/stop swapping to file/device. Also gated by `CAP_SYS_ADMIN`. | +| `sysfs` | Obsolete syscall. | +| `_sysctl` | Obsolete, replaced by /proc/sys. | +| `umount` | Should be a privileged operation. Also gated by `CAP_SYS_ADMIN`. | +| `umount2` | Should be a privileged operation. | +| `unshare` | Deny cloning new namespaces for processes. Also gated by `CAP_SYS_ADMIN`, with the exception of `unshare --user`. | +| `uselib` | Older syscall related to shared libraries, unused for a long time. | +| `ustat` | Obsolete syscall. | +| `vm86` | In kernel x86 real mode virtual machine. Also gated by `CAP_SYS_ADMIN`. | +| `vm86old` | In kernel x86 real mode virtual machine. Also gated by `CAP_SYS_ADMIN`. | + +## Run without the default seccomp profile + +You can pass `unconfined` to run a container without the default seccomp +profile. + +``` +$ docker run --rm -it --security-opt seccomp:unconfined debian:jessie \ + unshare --map-root-user --user sh -c whoami +``` diff --git a/docs/articles/security.md b/docs/security/security.md similarity index 97% rename from docs/articles/security.md rename to docs/security/security.md index 92f02dc0ad..d6b11e466d 100644 --- a/docs/articles/security.md +++ b/docs/security/security.md @@ -1,11 +1,12 @@ @@ -277,8 +278,9 @@ containerization systems, these are simply kernels features that may be implemented in Docker as well. We welcome users to submit issues, pull requests, and communicate via the mailing list. -References: +## Related Information -* [Docker Containers: How Secure Are They? (2013)]( -http://blog.docker.com/2013/08/containers-docker-how-secure-are-they/). -* [On the Security of Containers (2014)](https://medium.com/@ewindisch/on-the-security-of-containers-2c60ffe25a9e). +* [Use trusted images](../security/trust/index.md) +* [Seccomp security profiles for Docker](../security/seccomp.md) +* [AppArmor security profiles for Docker](../security/apparmor.md) +* [On the Security of Containers (2014)](https://medium.com/@ewindisch/on-the-security-of-containers-2c60ffe25a9e)