Add documentation of the profile flags and how to debug apparmor policy to the apparmor.d man page
--- === modified file 'parser/apparmor.d.pod' --- parser/apparmor.d.pod 2016-06-01 20:55:14 +0000 +++ parser/apparmor.d.pod 2016-06-07 20:45:20 +0000 @@ -299,6 +299,109 @@ 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> +obsoleted in apparmo 2.5 and may result in a parse error (tested on 2.8), +it will be reintroduced at some point in the future. See below I<Debugging + AppArmor Policy> for other options. + + +=head3 Profile Mode Flags + +=item B<allow> -- conflicts with complain, debug, enforce, kill +places the profile in allow mode which will cause all denied accesses +to be audited and allowed. Allow mode is similar to complain mode except +that explicitly denied accesses are also allowed. + +Not supported in versions before AppArmor 3.6 + +=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. It is important to note +that allow rules still auditing/quieting as specified and deny rules +and their auditing/quieting behavior is also still applied, so normally +known denials will not show up in the audit stream. + +Note: there is a known bug versions before AppArmor 4.0 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 user of the keyword is not supported in versions before AppArmor 4.0, +but can be achieved by removing profile mode keywords for the profile +flags. + +=item B<kill> -- conflicts with allow, complain, enforce, stop +Instead of logging denials, send a kill signal to the task. Note there +are some accesses where a task is not associated, in those cases no +kill signal will be sent. + +Not yet supported in versions before AppArmor 4.0 + +=item B<stop> -- conflicts with allow, complain, enforce, kill +A debug mode where a SIGSTOP or SIGSYS may be sent to the task for unknown +accesses. Note there are some accesses where a task is not associated, in +those case a signal will not be sent. + +Not yet supported in versions before AppArmor 4.0 + + +=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) with 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 +421,8 @@ - append -- conflicts with write + + =item B<ux> - unconfined execute @@ -1572,6 +1677,99 @@ =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 noise and it is recommended the per profile flag is used 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 > /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 other requirements 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 this preventing further changes to AppArmor policy. + + Eg. + $cat /sys/module/apparmor/parameters/lock_policy + N + $echo Y > /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 + + Eg. + $cat /sys/module/apparmor/parameters/path_max + 8192 + +=back + =head1 KNOWN BUGS =over 4 -- AppArmor mailing list [email protected] Modify settings or unsubscribe at: https://lists.ubuntu.com/mailman/listinfo/apparmor
