diff --git a/docs/security/apparmor.md b/docs/security/apparmor.md index b0998f84c7..bc80a24509 100644 --- a/docs/security/apparmor.md +++ b/docs/security/apparmor.md @@ -20,8 +20,8 @@ Docker automatically loads container profiles. The Docker binary installs a `docker-default` profile in the `/etc/apparmor.d/docker` file. This profile is used on containers, _not_ on the Docker Daemon. -A profile for the Docker Engine Daemon exists but it is not currently installed -with the deb packages. If you are interested in the source for the Daemon +A profile for the Docker Engine daemon exists but it is not currently installed +with the `deb` packages. If you are interested in the source for the daemon profile, it is located in [contrib/apparmor](https://github.com/docker/docker/tree/master/contrib/apparmor) in the Docker Engine source repository. @@ -72,15 +72,15 @@ explicitly specifies the default policy: $ docker run --rm -it --security-opt apparmor=docker-default hello-world ``` -## Loading and Unloading Profiles +## Load and unload profiles -To load a new profile into AppArmor, for use with containers: +To load a new profile into AppArmor for use with containers: -``` +```bash $ apparmor_parser -r -W /path/to/your_profile ``` -Then you can run the custom profile with `--security-opt` like so: +Then, run the custom profile with `--security-opt` like so: ```bash $ docker run --rm -it --security-opt apparmor=your_profile hello-world @@ -97,39 +97,174 @@ $ apparmor_parser -R /path/to/profile $ /etc/init.d/apparmor start ``` -## Debugging AppArmor +### Resources for writing profiles -### Using `dmesg` +The syntax for file globbing in AppArmor is a bit different than some other +globbing implementations. It is highly suggested you take a look at some of the +below resources with regard to AppArmor profile syntax. + +- [Quick Profile Language](http://wiki.apparmor.net/index.php/QuickProfileLanguage) +- [Globbing Syntax](http://wiki.apparmor.net/index.php/AppArmor_Core_Policy_Reference#AppArmor_globbing_syntax) + +## Nginx example profile + +In this example, you create a custom AppArmor profile for Nginx. Below is the +custom profile. + +``` +#include + + +profile docker-nginx flags=(attach_disconnected,mediate_deleted) { + #include + + network inet tcp, + network inet udp, + network inet icmp, + + deny network raw, + + deny network packet, + + file, + umount, + + deny /bin/** wl, + deny /boot/** wl, + deny /dev/** wl, + deny /etc/** wl, + deny /home/** wl, + deny /lib/** wl, + deny /lib64/** wl, + deny /media/** wl, + deny /mnt/** wl, + deny /opt/** wl, + deny /proc/** wl, + deny /root/** wl, + deny /sbin/** wl, + deny /srv/** wl, + deny /tmp/** wl, + deny /sys/** wl, + deny /usr/** wl, + + audit /** w, + + /var/run/nginx.pid w, + + /usr/sbin/nginx ix, + + deny /bin/dash mrwklx, + deny /bin/sh mrwklx, + deny /usr/bin/top mrwklx, + + + capability chown, + capability dac_override, + capability setuid, + capability setgid, + capability net_bind_service, + + 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, +} +``` + +1. Save the custom profile to disk in the +`/etc/apparmor.d/containers/docker-nginx` file. + + The file path in this example is not a requirement. In production, you could + use another. + +2. Load the profile. + + ```bash + $ sudo apparmor_parser -r -W /etc/apparmor.d/containers/docker-nginx + ``` + +3. Run a container with the profile. + + To run nginx in detached mode: + + ```bash + $ docker run --security-opt "apparmor=docker-nginx" \ + -p 80:80 -d --name apparmor-nginx nginx + ``` + +4. Exec into the running container + + ```bash + $ docker exec -it apparmor-nginx bash + ``` + +5. Try some operations to test the profile. + + ```bash + root@6da5a2a930b9:~# ping 8.8.8.8 + ping: Lacking privilege for raw socket. + + root@6da5a2a930b9:/# top + bash: /usr/bin/top: Permission denied + + root@6da5a2a930b9:~# touch ~/thing + touch: cannot touch 'thing': Permission denied + + root@6da5a2a930b9:/# sh + bash: /bin/sh: Permission denied + + root@6da5a2a930b9:/# dash + bash: /bin/dash: Permission denied + ``` + + +Congrats! You just deployed a container secured with a custom apparmor profile! + + +## Debug AppArmor + +You can use `demsg` to debug problems and `aa-status` check the loaded profiles. + +### Use dmesg Here are some helpful tips for debugging any problems you might be facing with regard to AppArmor. AppArmor sends quite verbose messaging to `dmesg`. Usually an AppArmor line -will look like the following: +looks like the following: ``` [ 5442.864673] audit: type=1400 audit(1453830992.845:37): apparmor="ALLOWED" operation="open" profile="/usr/bin/docker" name="/home/jessie/docker/man/man1/docker-attach.1" pid=10923 comm="docker" requested_mask="r" denied_mask="r" fsuid=1000 ouid=0 ``` -In the above example, the you can see `profile=/usr/bin/docker`. This means the +In the above example, you can see `profile=/usr/bin/docker`. This means the user has the `docker-engine` (Docker Engine Daemon) profile loaded. > **Note:** On version of Ubuntu > 14.04 this is all fine and well, but Trusty > users might run into some issues when trying to `docker exec`. -Let's look at another log line: +Look at another log line: ``` [ 3256.689120] type=1400 audit(1405454041.341:73): apparmor="DENIED" operation="ptrace" profile="docker-default" pid=17651 comm="docker" requested_mask="receive" denied_mask="receive" ``` This time the profile is `docker-default`, which is run on containers by -default unless in `privileged` mode. It is telling us, that apparmor has denied -`ptrace` in the container. This is great. +default unless in `privileged` mode. This line shows that apparmor has denied +`ptrace` in the container. This is exactly as expected. -### Using `aa-status` +### Use aa-status -If you need to check which profiles are loaded you can use `aa-status`. The +If you need to check which profiles are loaded, you can use `aa-status`. The output looks like: ```bash @@ -162,17 +297,17 @@ apparmor module is loaded. 0 processes are unconfined but have a profile defined. ``` -In the above output you can tell that the `docker-default` profile running on -various container PIDs is in `enforce` mode. This means AppArmor will actively -block and audit in `dmesg` anything outside the bounds of the `docker-default` +The above output shows that the `docker-default` profile running on various +container PIDs is in `enforce` mode. This means AppArmor is actively blocking +and auditing in `dmesg` anything outside the bounds of the `docker-default` profile. -The output above also shows the `/usr/bin/docker` (Docker Engine Daemon) -profile is running in `complain` mode. This means AppArmor will _only_ log to -`dmesg` activity outside the bounds of the profile. (Except in the case of -Ubuntu Trusty, where we have seen some interesting behaviors being enforced.) +The output above also shows the `/usr/bin/docker` (Docker Engine daemon) profile +is running in `complain` mode. This means AppArmor _only_ logs to `dmesg` +activity outside the bounds of the profile. (Except in the case of Ubuntu +Trusty, where some interesting behaviors are enforced.) -## Contributing to AppArmor code in Docker +## Contribute Docker's AppArmor code Advanced users and package managers can find a profile for `/usr/bin/docker` (Docker Engine Daemon) underneath