[apparmor] PATCH: apparmor.d man page

Thu Jun 9 07:47:30 UTC 2016

Add documentation of the profile flags and how to debug apparmor policy to the apparmor.d man page

v2. Added in most of Seth and Christians feedback

---

=== modified file 'parser/apparmor.d.pod'

--- parser/apparmor.d.pod	2016-06-01 20:55:14 +0000
+++ parser/apparmor.d.pod	2016-06-09 07:43:10 +0000
@@ -299,6 +299,91 @@
 written or modified to use change_profile(2) transition permanently to the
 specified profile. libvirt is one such application.
 
+=head2 Profile Flags
+
+The profile flags allow for quick global control over profile behavior
+and some override rule qualifiers allowing for quick global changes
+for profile debugging or development. While multiple profile flags can
+be specified some of the flags conflict (see below).
+
+If profile flags are not specified a the default flag set will be
+  flags=(enforce, namespace_relative, no_attach_disconnected)
+
+=over 8
+
+=head3 Profile Audit Flags
+
+=item B<audit>
+places the profile in audit mode which will cause all allowed accesses to
+be audited. This is equivalent to placing the audit qualifier on all
+allow rules in the profile.
+
+=item B<debug>
+removed in apparmor 2.5 and may result in a parse error (tested on 2.8),
+See below I<Debugging AppArmor Policy> for other options.
+
+
+=head3 Profile Mode Flags
+
+The profile mode flags conflict with each other, so you can't use more
+than one. If no profile mode flags the default value of I<enforce> will
+be used.
+
+=item B<complain> -- conflicts with allow, enforce, kill, stop
+places the profile in complain mode which will cause all unknown accesses
+to be audited and allowed. Complain mode is used for profile development
+so that unknown accesses can be logged without affecting program behavior
+as the default white listing behavior would.
+
+Note that deny rules will be enforced even in complain mode. The auditing
+and quieting of existing allow and deny rules will be applied, so known
+accesses and denials will not show up in the audit stream (unless the
+rule contains B<audit>).
+
+Note: there is a known bug where rules with a prefix with B<audit deny> will
+be treated as unknown accesses.
+
+=item B<enforce> DEFAULT -- conflicts with allow, complain, stop, kill
+The default profile mode, if no profile mode flag is specified. It puts
+the profile into a white listing mode that denies all unknown accesses.
+
+The use of the keyword is not currently supported but can be achieved by
+removing profile mode keywords for the profile flags.
+
+=head3 Profile Path Relative Flags
+
+The path relative flags control what file name resolution is relative to for
+the profile.
+
+=item B<chroot_relative> -- conflicts with namespace_relative
+Pathnames are relative to the base of the chroot and names outside of the
+chroot are determined by the path attach flags.
+
+=item B<namespace_relative> DEFAULT -- conflicts with chroot_relative
+Pathnames are relative to the namespace (not the chroot) and names outside
+of the namespace are determined by the path attach flags.
+
+=head3 Profile Path Attach Flags
+
+The attach flags control how disconnected paths are handled.
+
+=item B<attach_disconnect> -- conflicts with no_attach_disconnected
+Tells apparmor to attach disconnected paths to the disconnect_root (default is
+"/"). by prepending its value to the disconnected path.
+
+WARNING: it is not recommend that this option be used because it can result
+in disconnected paths aliasing real path names, which can result in security
+problems.
+
+The proper solution is almost always to uses delegation or disconnected
+path rules. If this option is used the disconnect_root should be set to a
+value other than the default of "/".
+
+=item B<no_attach_disconnected> DEFAULT -- conflicts with attach_disconnected
+
+Disconnected paths are not attached or mediated via file pathname rules.
+
+
 =head2 Access Modes
 
 File permission access modes consists of combinations of the following
@@ -318,6 +403,8 @@
 
 - append -- conflicts with write
 
+
+
 =item B<ux>
 
 - unconfined execute
@@ -1572,6 +1659,103 @@
 
 =back
 
+=head1 Debugging AppArmor Policy
+
+=over 4
+
+In addition to setting profile mode flags AppArmor provides a few global
+controls that can help in debugging how policy is being enforced. To use
+these controls the policy author must have sufficient privilege to
+manage policy for the namespace.
+
+The most useful are the I<noquiet> audit value, and turning on the
+debug parameters. These two values should suffice in most situations.
+The setting these values and the full set of possible parameters are
+documented below.
+
+=head2 /sys/module/apparmor/parameters/audit
+
+The audit paramenter allows controlling of how auditing is applied, it
+can be in any of the follow states.
+
+=item B<normal> - auditing behaves as specified in the profile
+=item B<quiet_denied> - there is no auditing of denials
+=item B<quiet> - auditing is disabled
+=item B<noquiet> - rule quieting is not used so explit denies will be logged
+=item B<all> - all access whether allowed or denied are logged. Warning this
+mode is very noisy and it is recommended to use the per profile flag instead.
+
+  Eg.
+     #cat /sys/module/apparmor/parameters/audit
+     normal
+     #echo -n "noquiet" E<gt> /sys/module/apparmor/parameters/audit
+     #cat /sys/module/apparmor/parameters/audit
+     noquiet
+
+=head2 /sys/module/apparmor/parameters/debug
+
+The boolean debug parameter turns on logging of extra information to the
+kernel ring buffer (dmesg). This primarily contains information for domain
+transitions like scrubbing of environment variables, clearing of unsafe
+personality bits and seccomp's no-new-privs mode.
+
+  Eg.
+     #cat /sys/module/apparmor/parameters/debug
+     N
+     #echo Y E<gt> /sys/module/apparmor/parameters/debug
+     #cat /sys/module/apparmor/parameters/debug
+     Y
+
+=head2 /sys/module/apparmor/parameters/enabled
+
+The boolean enabled parameter allows checking if the AppArmor kernel
+module is enabled. It is recommneded that the user uses aa-enabled(8)
+or the api aa_is_enabled(2) to do this check as they provide more
+information and other requirements (such as whether securityfs is
+mounted) for AppArmor policy to be enforced.
+ 
+=head2 /sys/module/apparmor/parameters/lock_policy
+
+The boolean lock_policy parameter allows checking if policy loads have
+been locked, thus preventing further changes to AppArmor policy. Once
+locked the flag can not be toggled back to an unlocked state.
+
+  Eg.
+     #cat /sys/module/apparmor/parameters/lock_policy
+     N
+     #echo Y E<gt> /sys/module/apparmor/parameters/lock_policy
+     #cat /sys/module/apparmor/parameters/lock_policy
+     Y
+
+=head2 sys/module/apparmor/parameters/mode
+
+The mode parameter allows overriding the profiles enforcement mode.
+
+=item B<enforce> - enfoce profile as specified by its flags
+=item B<complain> - put all profiles into complain mode
+=item B<kill> - put all profiles into kill mode
+=item B<unconfined> - put all profiles into unconfined mode
+
+  Eg.
+     #cat /sys/module/apparmor/parameters/mode
+     enforce
+     #echo -n "complain" E<gt> /sys/module/apparmor/parameters/mode
+     #cat /sys/module/apparmor/parameters/mode
+     complain
+
+=head2 /sys/module/apparmor/parameters/path_max
+
+The path_max parameter allows discovering the current maximum length
+for path name resolution. The path_max value can only be set on boot.
+Paths longer than the maximum value will result in access requests that
+are denied with ETOOLONG.
+
+  Eg.
+     #cat /sys/module/apparmor/parameters/path_max 
+     8192
+
+=back
+
 =head1 KNOWN BUGS
 
 =over 4



