[apparmor] [PATCH] update man page for recent mount rule additions

[John Johansen]

On 04/09/2012 04:22 PM, Steve Beattie wrote:
> On Mon, Apr 09, 2012 at 05:13:32PM -0500, Jamie Strandboge wrote:
>> With all of the work that John did on mount rules, it is about time I
>> finally wrote the man page I promised I would. This is based on the
>> wiki[1][2] and conversations with John.
>>
>> [1]http://wiki.apparmor.net/index.php/AppArmor_Core_Policy_Reference#Mount_rules_.28AppArmor_2.8_and_later.29
>> [2]http://wiki.apparmor.net/index.php/TechnicalDoc_Mount_Flags
>>
>> -- 
>> Jamie Strandboge             | http://www.canonical.com
> 
>> @@ -305,7 +331,8 @@
>>  
>>  The only operations that cannot be controlled in this manner are mount(2),
>>  umount(2), and loading new AppArmor policy into the kernel, which are
>> -always denied to confined processes.
>> +always denied to confined processes unless explicit mount rules are
>> +specified in the policy.
> 
> Really, we ought to drop the reference to mount/umount here, as we have
> plenty of things that are not allowed to a confined process unless
> explicit rules are specified in the policy.
> 
yeah, that makes sense

> (Also, is apparmor policy loading restricted to CAP_MAC_ADMIN these
> days, or is the 'no confined process ever' rule still in effect?)
> 
CAP_MAC_ADMIN, though I am not sure exactly what we will do for user profiles

>>  
>>  =head2 Network Rules
>>  
> 
>> @@ -328,6 +355,248 @@
>>   network inet tcp,	#allow access to tcp only for inet4 addresses
>>   network inet6 tcp,	#allow access to tcp only for inet6 addresses
>>  
>> +=head2 Mount Rules
>> +
>> +AppArmor supports mount mediation and allows specifying filesystem types and
>> +mount flags. The syntax of mount rules in AppArmor is based on mount rule
>> +syntax. Mount rules must contain one of the mount, remount, umount or
>> +pivot_root keywords, but all mount conditions are optional. Unspecified
>> +optional conditionals are assumed to match all entries (eg, not specifying
>> +fstype means all fstypes are matched). Due to the complexity of the mount
>> +command and how options may be specified, AppArmor allows specifying
>> +conditionals two different ways:
>> +
>> +=item 1.
>> +
>> +If a conditional is specified using '=', then the rule only grants permission
>> +for mounts matching the exactly specified options. For example, an AppArmor
>> +policy with the following rule:
>> +
>> +=over 4
>> +
>> +mount options=ro /dev/foo -> /mnt/,
>> +
>> +=back
>> +
>> +Would match:
>> +
>> +=over 4
>> +
>> +$ mount -o ro /dev/foo /mnt
>> +
>> +=back
>> +
>> +but not either of these:
>> +
>> +=over 4
>> +
>> +$ mount -o ro,atime /dev/foo /mnt
>> +
>> +$ mount -o rw /dev/foo /mnt
>> +
>> +=back
>> +
>> +=item 2.
>> +
>> +If a conditional is specified using 'in', then the rule grants permission for
>> +mounts matching any combination of the specified options. This gets
>> +particularly interesting because the mount command sometimes has an inverse
>> +option and sometimes doesn't (eg, the inverse of 'ro' is 'rw' and the inverse
>> +of 'atime' is 'noatime', but 'slave' does not have an inverse). When creating
>> +or auditing policy and specifying 'in' for mount conditional, it is useful to
>> +remember that each option may be either 'on' or 'off' (regardless of the actual
>> +name of the mount option). For example, if an AppArmor policy has the following
>> +rule:
> 
> I must surely not be understanding the semantics of 'or'ing these,
> the option toggling, and the implications with what the default options
> are, because many of these, I do not understand why they are rejected
> or allowed. Can we explain why each one matches or doesn't match?
> 
Its complicated but it comes down to each mount flag has a positive and negative
(bit set/not set).  If you specify one, then the other can't be, or in the case
of in it basically means it can be either.

It does make for confusing examples though

>> +
>> +=over 4
>> +
>> +mount options in (ro,atime) /dev/foo -> /mnt/,
>> +
>> +=back
>> +
>> +all of these mount commands will match:
>> +
>> +=over 4
>> +
>> +$ mount -o ro /dev/foo /mnt
>> +
>> +$ mount -o ro,atime /dev/foo /mnt
>> +
>> +$ mount -o ro,noatime /dev/foo /mnt
>> +
>> +$ mount -o rw /dev/foo /mnt
>> +
>> +$ mount -o rw,atime /dev/foo /mnt
>> +
>> +$ mount -o rw,noatime /dev/foo /mnt
> 
> How is this one allowed? Neither ro or atime are specified.
> rw is listed as the negative form of ro, and noatime is the negative
> form of atime, so neither should be matched?
> 

because we can't distinguish at least not in the backend.

options in (ro,atime) means any of the following sets

{ro, atime}
{ro}
{atime}
{}

but if an option is missing that implies it negative form (again bit set or unset)

so
{ro} implies noatime
{atime} implies rw
{} implies noatime, rw



>> +
>> +$ mount -o atime /dev/foo /mnt
>> +
>> +$ mount -o noatime /dev/foo /mnt
> 
> Again I'm confused why the above would match, assuming the default mode
> is 'rw'?
> 
>> +
>> +$ mount /dev/foo /mnt
> 
> I assume this matches because 'atime' is the default.
> 
>> +
>> +=back
>> +
>> +but none of these will:
>> +
>> +=over 4
>> +
>> +$ mount -o ro,sync /dev/foo /mnt
>> +
>> +$ mount -o ro,atime,sync /dev/foo /mnt
> 
> Why would these two not?
> 
because sync was added

>> +
>> +$ mount -o rw,sync /dev/foo /mnt
>> +
>> +$ mount -o sync /dev/foo /mnt
>> +
>> +=back
>> +
>> +=back
>> +
>> +In addition to the above, options may be specified multiple times in the same
>> +rule, which might help to logically break up a conditional. To help clarify the
>> +flexibility and complexity of mount rules, here are some example rules with
>> +accompanying matching commands:
>> +
>> +=over 4
>> +
>> +=item B<mount,>
>> +
>> +the 'mount' rule without any conditionals is the most generic and allows any
>> +mount. Equivalent to 'mount fstype=** options=** ** -> /**'.
>> +
>> +=item B<mount /dev/foo,>
>> +
>> +allow mounting of /dev/foo anywhere with any options. Some matching mount
>> +commands:
>> +
>> +=over 4
>> +
>> +$ mount /dev/foo /mnt
>> +
>> +$ mount -t ext3 /dev/foo /mnt
>> +
>> +$ mount -t vfat /dev/foo /mnt
>> +
>> +$ mount -o ro,atime,noexec,nodiratime /dev/foo /srv/some/mountpoint
>> +
>> +=back
>> +
>> +=item B<mount options=ro /dev/foo,>
>> +
>> +allow mounting of /dev/foo anywhere, as read only. Some matching mount
>> +commands:
>> +
>> +=over 4
>> +
>> +$ mount -o ro /dev/foo /mnt
>> +
>> +$ mount -o ro /dev/foo /some/where/else
>> +
>> +=back
>> +
>> +=item B<mount options=(ro,atime) /dev/foo,>
>> +
>> +allow mount of /dev/foo anywhere, as read only and using inode access times.
>> +Some matching mount commands:
>> +
>> +=over 4
>> +
>> +$ mount -o ro,atime /dev/foo /mnt
>> +
>> +$ mount -o ro,atime /dev/foo /some/where/else
>> +
>> +=back
>> +
>> +=item B<mount options in (ro,atime) /dev/foo,>
>> +
>> +allow mount of /dev/foo anywhere using some combination of 'ro' and 'atime'
>> +(see above). Some matching mount commands:
>> +
>> +=over 4
>> +
>> +$ mount -o ro,atime /dev/foo /mnt
>> +
>> +$ mount -o ro,noatime /dev/foo /some/where/else
>> +
>> +$ mount -o rw /dev/foo /some/other/place
>> +
>> +$ mount /dev/foo /mnt
>> +
>> +=back
>> +
>> +=item B<mount options=ro, mount options=atime /dev/foo,>
>> +
>> +allow mount of /dev/foo anywhere as read only, and allow mount of /dev/foo
>> +anywhere using inode access times. Note this is expressed as two different
>> +rules and is not the equivalent of 'options=(ro,atime)' or 'options in
>> +(ro,atime)'. Matches:
>> +
>> +=over 4
>> +
>> +$ mount -o ro /dev/foo /mnt/1
>> +
>> +$ mount -o atime /dev/foo /mnt/2
>> +
>> +=back
>> +
>> +=item B<< mount -> /mnt/**, >>
>> +
>> +allow mounting anything under a directory in /mnt/**. Some matching mount
>> +commands:
>> +
>> +=over 4
>> +
>> +$ mount /dev/foo1 /mnt/1
>> +
>> +$ mount -o ro,atime,noexec,nodiratime /dev/foo2 /mnt/deep/path/foo2
>> +
>> +=back
>> +
>> +=item B<< mount options=ro -> /mnt/**, >>
>> +
>> +allow mounting anything under /mnt/**, as read only. Some matching mount
>> +commands:
>> +
>> +=over 4
>> +
>> +$ mount -o ro /dev/foo1 /mnt/1
>> +
>> +$ mount -o ro /dev/foo2 /mnt/deep/path/foo2
>> +
>> +=back
>> +
>> +=item B<< mount fstype=ext3 options=(rw,atime) /dev/sdb1 -> /mnt/stick/, >>
>> +
>> +allow mounting an ext3 filesystem in /dev/sdb1 on /mnt/stick as read/write and
>> +using inode access times. Matches only:
>> +
>> +=over 4
>> +
>> +$ mount -o rw,atime /dev/sdb1 /mnt/stick
>> +
>> +=back
>> +
>> +=item B<< mount options=(ro, atime) options in (nodev, user) /dev/foo -> /mnt/, >>
>> +
>> +allow mount /dev/foo read only and using inode access times, with some
>> +combination of 'nodev' and 'user'. Some matching mount commands:
>> +
>> +=over 4
>> +
>> +$ mount -o ro,atime,nodev,user /dev/foo /mnt
>> +
>> +$ mount -o ro,atime /dev/foo /mnt
>> +
>> +$ mount -o ro,atime,dev,user /dev/foo /mnt
>> +
>> +$ mount -o ro,atime,nouser /dev/foo /mnt
>> +
>> +=back
>> +
>> +=back
>> +
>>  =head2 Variables
>>  
>>  AppArmor's policy language allows embedding variables into file rules
>> @@ -605,6 +874,20 @@
>>  
>>  =back
>>  
>> +=head1 KNOWN BUGS
>> +
>> +=over 4
>> +
>> +Mount options support the use of pattern matching but mount flags are not
>> +correctly intersected against specified patterns. Eg, 'mount options=**,'
>> +should be equivalent to 'mount,', but it is not. (LP: #965690)
>> +
>> +The fstype may not be matched against when certain mount command flags are
>> +used. Specifically fstype matching currently only works when creating a new
>> +mount and not remount, bind, etc.
>> +
>> +=back
>> +
>>  =head1 SEE ALSO
>>  
>>  apparmor(7), apparmor_parser(8), aa-complain(1),
>>
> 
> 
> 
> 
>> -- 
>> AppArmor mailing list
>> AppArmor at lists.ubuntu.com
>> Modify settings or unsubscribe at: https://lists.ubuntu.com/mailman/listinfo/apparmor
> 
> 
> 
>