1. docker
  2. Commit a6701790ee585c625c6a39413d2772dc7ecf80fd
Browse code

way better apparmor docs

Signed-off-by: Jessica Frazelle <acidburn@docker.com>

Jessica Frazelle authored on 2016/01/27 05:19:15
Showing 1 changed files
docs/security/apparmor.md
History View file @ a670179
... ... 
@@ -16,10 +16,15 @@ operating system and its applications from security threats. To use it, a system
16 16 
 administrator associates an AppArmor security profile with each program. Docker
17 17 
 expects to find an AppArmor policy loaded and enforced.
18 18
19 
-Docker automatically loads container profiles. A profile for the Docker Engine
20 
-itself also exists and is installed with the official *.deb* packages in
21 
-`/etc/apparmor.d/docker` file.
19 
+Docker automatically loads container profiles. The Docker binary installs
20 
+a `docker-default` profile in the `/etc/apparmor.d/docker` file. This profile
21 
+is used on containers, _not_ on the Docker Daemon.
22 22
23 
+A profile for the Docker Engine Daemon exists but it is not currently installed
24 
+with the deb packages. If you are interested in the source for the Daemon
25 
+profile, it is located in
26 
+[contrib/apparmor](https://github.com/docker/docker/tree/master/contrib/apparmor)
27 
+in the Docker Engine source repository.
23 28
24 29 
 ## Understand the policies
25 30
... ... 
@@ -67,9 +72,112 @@ explicitly specifies the default policy:
67 67 
 $ docker run --rm -it --security-opt apparmor:docker-default hello-world
68 68 
 ```
69 69
70 
+## Loading and Unloading Profiles
71 
+
72 
+To load a new profile into AppArmor, for use with containers:
73 
+
74 
+```
75 
+$ apparmor_parser -r -W /path/to/your_profile
76 
+```
77 
+
78 
+Then you can run the custom profile with `--security-opt` like so:
79 
+
80 
+```bash
81 
+$ docker run --rm -it --security-opt apparmor:your_profile hello-world
82 
+```
83 
+
84 
+To unload a profile from AppArmor:
85 
+
86 
+```bash
87 
+# stop apparmor
88 
+$ /etc/init.d/apparmor stop
89 
+# unload the profile
90 
+$ apparmor_parser -R /path/to/profile
91 
+# start apparmor
92 
+$ /etc/init.d/apparmor start
93 
+```
94 
+
95 
+## Debugging AppArmor
96 
+
97 
+### Using `dmesg`
98 
+
99 
+Here are some helpful tips for debugging any problems you might be facing with
100 
+regard to AppArmor.
101 
+
102 
+AppArmor sends quite verbose messaging to `dmesg`. Usually an AppArmor line
103 
+will look like the following:
104 
+
105 
+```
106 
+[ 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
107 
+```
108 
+
109 
+In the above example, the you can see `profile=/usr/bin/docker`. This means the
110 
+user has the `docker-engine` (Docker Engine Daemon) profile loaded.
111 
+
112 
+> **Note:** On version of Ubuntu > 14.04 this is all fine and well, but Trusty
113 
+> users might run into some issues when trying to `docker exec`.
114 
+
115 
+Let's look at another log line:
116 
+
117 
+```
118 
+[ 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"
119 
+```
120 
+
121 
+This time the profile is `docker-default`, which is run on containers by
122 
+default unless in `privileged` mode. It is telling us, that apparmor has denied
123 
+`ptrace` in the container. This is great.
124 
+
125 
+### Using `aa-status`
126 
+
127 
+If you need to check which profiles are loaded you can use `aa-status`. The
128 
+output looks like:
129 
+
130 
+```bash
131 
+$ sudo aa-status
132 
+apparmor module is loaded.
133 
+14 profiles are loaded.
134 
+1 profiles are in enforce mode.
135 
+   docker-default
136 
+13 profiles are in complain mode.
137 
+   /usr/bin/docker
138 
+   /usr/bin/docker///bin/cat
139 
+   /usr/bin/docker///bin/ps
140 
+   /usr/bin/docker///sbin/apparmor_parser
141 
+   /usr/bin/docker///sbin/auplink
142 
+   /usr/bin/docker///sbin/blkid
143 
+   /usr/bin/docker///sbin/iptables
144 
+   /usr/bin/docker///sbin/mke2fs
145 
+   /usr/bin/docker///sbin/modprobe
146 
+   /usr/bin/docker///sbin/tune2fs
147 
+   /usr/bin/docker///sbin/xtables-multi
148 
+   /usr/bin/docker///sbin/zfs
149 
+   /usr/bin/docker///usr/bin/xz
150 
+38 processes have profiles defined.
151 
+37 processes are in enforce mode.
152 
+   docker-default (6044)
153 
+   ...
154 
+   docker-default (31899)
155 
+1 processes are in complain mode.
156 
+   /usr/bin/docker (29756)
157 
+0 processes are unconfined but have a profile defined.
158 
+```
159 
+
160 
+In the above output you can tell that the `docker-default` profile running on
161 
+various container PIDs is in `enforce` mode. This means AppArmor will actively
162 
+block and audit in `dmesg` anything outside the bounds of the `docker-default`
163 
+profile.
164 
+
165 
+The output above also shows the `/usr/bin/docker` (Docker Engine Daemon)
166 
+profile is running in `complain` mode. This means AppArmor will _only_ log to
167 
+`dmesg` activity outside the bounds of the profile. (Except in the case of
168 
+Ubuntu Trusty, where we have seen some interesting behaviors being enforced.)
169 
+
70 170 
 ## Contributing to AppArmor code in Docker
71 171
72 172 
 Advanced users and package managers can find a profile for `/usr/bin/docker`
73 
-underneath
173 
+(Docker Engine Daemon) underneath
74 174 
 [contrib/apparmor](https://github.com/docker/docker/tree/master/contrib/apparmor)
75 175 
 in the Docker Engine source repository.
176 
+
177 
+The `docker-default` profile for containers lives in
178 
+[profiles/apparmor](https://github.com/docker/docker/tree/master/profiles/apparmor).