WIP: Update security docs for seccomp/apparmor

Signed-off-by: Mary Anthony <mary@docker.com>

Updaing and slight re-arrangement of security information

Signed-off-by: Mary Anthony <mary@docker.com>

Updating security files

Signed-off-by: Mary Anthony <mary@docker.com>

Updating links to the security documentation

Signed-off-by: Mary Anthony <mary@docker.com>

removing some extra spaces

Signed-off-by: Mary Anthony <mary@docker.com>

Correcting spelling

Signed-off-by: Mary Anthony <mary@docker.com>

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
 

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:
 

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:**
 

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:
 

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:
 

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:
 

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:
 

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

docs/security/apparmor.md

@@ -1,47 +1,74 @@
 <!-- [metadata]>
 +++
-draft = true
+title = "AppArmor security profiles for Docker"
+description = "Enabling AppArmor in Docker"
+keywords = ["AppArmor, security, docker, documentation"]
+[menu.main]
+parent= "smn_secure_docker"
 +++
 <![end-metadata]-->
 
-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
+
+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 <tunables/global>
 
-Understand the policies
-------------------------
 
-The `docker-default` profile the default for running
-containers. It is moderately protective while
-providing wide application compatibility.
+profile docker-default flags=(attach_disconnected,mediate_deleted) {
 
-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.
+  #include <abstractions/base>
 
 
-Overriding the profile for a container
----------------------------------------
+  network,
+  capability,
+  file,
+  umount,
 
-Users may override the AppArmor profile using the
-`security-opt` option (per-container).
+  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,
 
-For example, the following explicitly specifies the default policy:
+  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.

docs/security/index.md

@@ -0,0 +1,20 @@
+<!-- [metadata]>
++++
+title = "Work with Docker security"
+description = "Sec"
+keywords = ["seccomp, security, docker, documentation"]
+[menu.main]
+identifier="smn_secure_docker"
+parent= "mn_use_docker"
++++
+<![end-metadata]-->
+
+# 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).

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"
 +++
 <![end-metadata]-->
 
-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
+```

docs/articles/security.md → docs/security/security.md

@@ -1,11 +1,12 @@
 <!--[metadata]>
 +++
+aliases = ["/engine/articles/security/"]
 title = "Docker security"
 description = "Review of the Docker Daemon attack surface"
 keywords = ["Docker, Docker documentation,  security"]
 [menu.main]
-parent = "smn_administrate"
-weight = 2
+parent = "smn_secure_docker"
+weight =-99
 +++
 <![end-metadata]-->
 
@@ -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)