~ubuntu-branches/ubuntu/precise/apparmor/precise-security

Origin: upstream, lp:apparmor
Subject  add mount rule syntax and usage.
revno: 2023 thorough 2026
committer: Jamie Strandboge <jamie@canonical.com>
branch nick: master
timestamp: Wed 2012-04-11 16:34:22 -0500
message:
  parser/apparmor.d.pod: add mount rule syntax and usage. Refinements and
  clarifications thanks to Steve Beattie.
  
  Acked-By: Jamie Strandboge <jamie@canonical.com>
  Acked-By: Steve Beattie <sbeattie@ubuntu.com>

also includes

  Attached is a patch to add --stderr to the common rules for generating
  manpages (and adjust it so that it's one rule instead of eight). It
  also fixes the above problem and a similar problem in the aa-exec
  manpage.

---
 common/Make.rules     |   25 ---
 parser/apparmor.d.pod |  332 +++++++++++++++++++++++++++++++++++++++++++++++++-
 utils/aa-exec.pod     |    2 
 3 files changed, 330 insertions(+), 29 deletions(-)

Index: b/common/Make.rules
===================================================================
--- a/common/Make.rules
+++ b/common/Make.rules
@@ -206,29 +206,8 @@ install_manpages: $(MANPAGES)
 
 MAN_RELEASE="AppArmor ${VERSION}"
 
-%.1: %.pod
-	$(POD2MAN) $< --release=$(MAN_RELEASE) --center=AppArmor --section=1 > $@
-
-%.2: %.pod
-	$(POD2MAN) $< --release=$(MAN_RELEASE) --center=AppArmor --section=2 > $@
-
-%.3: %.pod
-	$(POD2MAN) $< --release=$(MAN_RELEASE) --center=AppArmor --section=3 > $@
-
-%.4: %.pod
-	$(POD2MAN) $< --release=$(MAN_RELEASE) --center=AppArmor --section=4 > $@
-
-%.5: %.pod
-	$(POD2MAN) $< --release=$(MAN_RELEASE) --center=AppArmor --section=5 > $@
-
-%.6: %.pod
-	$(POD2MAN) $< --release=$(MAN_RELEASE) --center=AppArmor --section=6 > $@
-
-%.7: %.pod
-	$(POD2MAN) $< --release=$(MAN_RELEASE) --center=AppArmor --section=7 > $@
-
-%.8: %.pod
-	$(POD2MAN) $< --release=$(MAN_RELEASE) --center=AppArmor --section=8 > $@
+%.1 %.2 %.3 %.4 %.5 %.6 %.7 %.8: %.pod
+	$(POD2MAN) $< --release=$(MAN_RELEASE) --center=AppArmor --stderr --section=$(subst .,,$(suffix $@)) > $@
 
 %.1.html: %.pod
 	$(POD2HTML) --header --css apparmor.css --infile=$< --outfile=$@
Index: b/parser/apparmor.d.pod
===================================================================
--- a/parser/apparmor.d.pod
+++ b/parser/apparmor.d.pod
@@ -54,7 +54,7 @@ B<COMMENT> = '#' I<TEXT>
 
 B<TEXT> = any characters
 
-B<PROFILE> = [ I<COMMENT> ... ] [ I<VARIABLE ASSIGNMENT> ... ] ( '"' I<PROGRAM> '"' | I<PROGRAM> ) [ 'flags=(complain)' ]'{' [ ( I<RESOURCE RULE> | I<COMMENT> | I<INCLUDE> | I<SUBPROFILE> | 'capability ' I<CAPABILITY> | I<NETWORK RULE> | 'change_profile -> ' I<PROGRAMCHILD> ) ... ] '}'
+B<PROFILE> = [ I<COMMENT> ... ] [ I<VARIABLE ASSIGNMENT> ... ] ( '"' I<PROGRAM> '"' | I<PROGRAM> ) [ 'flags=(complain)' ]'{' [ ( I<RESOURCE RULE> | I<COMMENT> | I<INCLUDE> | I<SUBPROFILE> | 'capability ' I<CAPABILITY> | I<NETWORK RULE> | I<MOUNT RULE> | I<FILE RULE> | 'change_profile -> ' I<PROGRAMCHILD> ) ... ] '}'
 
 B<SUBPROFILE> = [ I<COMMENT> ... ] ( I<PROGRAMHAT> | 'profile ' I<PROGRAMCHILD> ) '{' [ ( I<FILE RULE> | I<COMMENT> | I<INCLUDE> ) ... ] '}'
 
@@ -75,11 +75,37 @@ B<PROGRAMHAT> = '^'  (non-whitespace cha
 
 B<PROGRAMCHILD> = I<SUBPROFILE> name
 
+B<MOUNT RULE> = ( I<MOUNT> | I<REMOUNT> | I<UMOUNT> | I<PIVOT ROOT> )
+
+B<MOUNT> = [ 'audit' ] [ 'deny' ] 'mount' [ I<MOUNT CONDITIONS> ] [ I<SOURCE FILEGLOB> ] [ -> [ I<MOUNTPOINT FILEGLOB> ]
+
+B<REMOUNT> = [ 'audit' ] [ 'deny' ] 'remount' [ I<MOUNT CONDITIONS> ] I<MOUNTPOINT FILEGLOB>
+
+B<UMOUNT> = [ 'audit' ] [ 'deny' ] 'umount' [ I<MOUNT CONDITIONS> ] I<MOUNTPOINT FILEGLOB>
+
+B<PIVOT ROOT> = [ 'audit' ] [ 'deny' ] pivot_root [ I<OLD ABS PATH> ] [ I<MOUNTPOINT ABS PATH> ] [ -> I<PROGRAMCHILD> ]
+
+B<MOUNT CONDITIONS> = [ ( 'fstype' | 'vfstype' ) ( '=' | 'in' ) I<MOUNT FSTYPE EXPRESSION> ] [ 'options' ( '=' | 'in' ) I<MOUNT FLAGS EXPRESSION> ]
+
+B<MOUNT FSTYPE EXPRESSION> = ( I<MOUNT FSTYPE LIST> | I<MOUNT EXPRESSION> )
+
+B<MOUNT FSTYPE LIST> = Comma separated list of valid filesystem and virtual filesystem types (eg ext4, debugfs, devfs, etc)
+
+B<MOUNT FLAGS EXPRESSION> = ( I<MOUNT FLAGS LIST> | I<MOUNT EXPRESSION> )
+
+B<MOUNT FLAGS LIST> = Comma separated list of I<MOUNT FLAGS>.
+
+B<MOUNT FLAGS> = ( 'ro' | 'rw' | 'nosuid' | 'suid' | 'nodev' | 'dev' | 'noexec' | 'exec' | 'sync' | 'async' | 'remount' | 'mand' | 'nomand' | 'dirsync' | 'nodirsync' | 'noatime' | 'atime' | 'nodiratime' | 'diratime' | 'bind' | 'move' | 'rec' | 'verbose' | 'silent' | 'load' | 'acl' | 'noacl' | 'unbindable' | 'private' | 'slave' | 'shared' | 'relative' | 'norelative' | 'iversion' | 'noiversion' | 'strictatime' | 'nouser' | 'user' )
+
+B<MOUNT EXPRESSION> = ( I<ALPHANUMERIC> | I<AARE> ) ...
+
+B<AARE> = B<?*[]{}^> (see below for meanings)
+
 B<FILE RULE> = I<RULE QUALIFIER> ( '"' I<FILEGLOB> '"' | I<FILEGLOB> ) I<ACCESS> ','
 
 B<RULE QUALIFIER> = [ 'audit' ] [ 'deny' ] [ 'owner' ]
 
-B<FILEGLOB> = (must start with '/' (after variable expansion), B<?*[]{}^> have special meanings; see below. May include I<VARIABLE>. Rules with embedded spaces or tabs must be quoted. Rules must end with '/' to apply to directories.)
+B<FILEGLOB> = (must start with '/' (after variable expansion), B<AARE> have special meanings; see below. May include I<VARIABLE>. Rules with embedded spaces or tabs must be quoted. Rules must end with '/' to apply to directories.)
 
 B<ACCESS> = ( 'r' | 'w' | 'l' | 'ix' | 'ux' | 'Ux' | 'px' | 'Px' | 'cx -> ' I<PROGRAMCHILD> | 'Cx -> ' I<PROGRAMCHILD> | 'm' ) [ I<ACCESS> ... ]  (not all combinations are allowed; see below.)
 
@@ -303,10 +329,6 @@ access is not granted, some capabilities
 arbitrary access to IPC, ability to bypass discretionary access controls,
 and other operations that are typically reserved for the root user.
 
-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.
-
 =head2 Network Rules
 
 AppArmor supports simple coarse grained network mediation.  The network
@@ -328,6 +350,281 @@ eg.
  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 the mount(8)
+command 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 three different ways:
+
+=over 4
+
+=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. For example, if an
+AppArmor policy has the following rule:
+
+=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 atime /dev/foo /mnt
+
+=back
+
+but none of these will:
+
+=over 4
+
+$ mount -o ro,sync /dev/foo /mnt
+
+$ mount -o ro,atime,sync /dev/foo /mnt
+
+$ mount -o rw /dev/foo /mnt
+
+$ mount -o rw,noatime /dev/foo /mnt
+
+$ mount /dev/foo /mnt
+
+=back
+
+=item 3.
+
+If multiple conditionals are specified in a single mount rule, then the rule
+grants permission for each set of options. This provides a shorthand when
+writing mount rules which might help to logically break up a conditional. For
+example, if an AppArmor policy has the following rule:
+
+=over 4
+
+mount options=ro options=atime
+
+=back
+
+both of these mount commands will match:
+
+=over 4
+
+$ mount -o ro /dev/foo /mnt
+
+$ mount -o atime /dev/foo /mnt
+
+=back
+
+but this one will not:
+
+=over 4
+
+$ mount -o ro,atime /dev/foo /mnt
+
+=back
+
+=back
+
+Note that separate mount rules are distinct and the options do not accumulate.
+For example, these AppArmor mount rules:
+
+=over 4
+
+mount options=ro,
+mount options=atime,
+
+=back
+
+are not equivalent to either of these mount rules:
+
+=over 4
+
+mount options=(ro,atime),
+
+mount options in (ro,atime),
+
+=back
+
+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 /dev/foo /mnt
+
+$ mount -o atime /dev/foo /some/where/else
+
+$ mount -o ro,atime /dev/foo /some/other/place
+
+=back
+
+=item B<mount options=ro /dev/foo, 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. 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 mounting /dev/foo on /mmt/ read only and using inode access times or
+allow mounting /dev/foo on /mnt/ with some combination of 'nodev' and 'user'.
+Matches only:
+
+=over 4
+
+$ mount -o ro,atime /dev/foo /mnt
+
+$ mount -o nodev /dev/foo /mnt
+
+$ mount -o user /dev/foo /mnt
+
+$ mount -o nodev,user /dev/foo /mnt
+
+=back
+
+=back
+
 =head2 Variables
 
 AppArmor's policy language allows embedding variables into file rules
@@ -605,6 +902,29 @@ An example AppArmor profile:
 
 =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.
+
+Mount rules with multiple 'options' conditionals are not applied as documented
+but instead merged such that 'options in (ro,nodev) options in (atime)' is
+equivalent to 'options in (ro,nodev,atime)'.
+
+When specifying mount options with the 'in' conditional, both the positive and
+negative values match when specifying one or the other. Eg, 'rw' matches when
+'ro' is specified and 'dev' matches when 'nodev' is specified such that
+'options in (ro,nodev)' is equivalent to 'options in (rw,dev)'.
+
+=back
+
 =head1 SEE ALSO
 
 apparmor(7), apparmor_parser(8), aa-complain(1),
Index: b/utils/aa-exec.pod
===================================================================
--- a/utils/aa-exec.pod
+++ b/utils/aa-exec.pod
@@ -82,6 +82,8 @@ arguments after the -- are treated as ar
 useful when passing arguments to the I<E<lt>commandE<gt>> being invoked by
 aa-exec.
 
+=back
+
 =head1 BUGS
 
 If you find any bugs, please report them at